Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 587 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man5/org.freedesktop.machine1.5 b/upstream/debian-unstable/man5/org.freedesktop.machine1.5
new file mode 100644
index 00000000..a63a4960
--- /dev/null
+++ b/upstream/debian-unstable/man5/org.freedesktop.machine1.5
@@ -0,0 +1,587 @@
+'\" t
+.TH "ORG\&.FREEDESKTOP\&.MACHINE1" "5" "" "systemd 255" "org.freedesktop.machine1"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+org.freedesktop.machine1 \- The D\-Bus interface of systemd\-machined
+.SH "INTRODUCTION"
+.PP
+\fBsystemd-machined.service\fR(8)
+is a system service that keeps track of locally running virtual machines and containers\&. This page describes the D\-Bus interface\&.
+.SH "THE MANAGER OBJECT"
+.PP
+The service exposes the following interfaces on the Manager object on the bus:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+node /org/freedesktop/machine1 {
+  interface org\&.freedesktop\&.machine1\&.Manager {
+    methods:
+      GetMachine(in  s name,
+                 out o machine);
+      GetImage(in  s name,
+               out o image);
+      GetMachineByPID(in  u pid,
+                      out o machine);
+      ListMachines(out a(ssso) machines);
+      ListImages(out a(ssbttto) images);
+      @org\&.freedesktop\&.systemd1\&.Privileged("true")
+      CreateMachine(in  s name,
+                    in  ay id,
+                    in  s service,
+                    in  s class,
+                    in  u leader,
+                    in  s root_directory,
+                    in  a(sv) scope_properties,
+                    out o path);
+      @org\&.freedesktop\&.systemd1\&.Privileged("true")
+      CreateMachineWithNetwork(in  s name,
+                               in  ay id,
+                               in  s service,
+                               in  s class,
+                               in  u leader,
+                               in  s root_directory,
+                               in  ai ifindices,
+                               in  a(sv) scope_properties,
+                               out o path);
+      @org\&.freedesktop\&.systemd1\&.Privileged("true")
+      RegisterMachine(in  s name,
+                      in  ay id,
+                      in  s service,
+                      in  s class,
+                      in  u leader,
+                      in  s root_directory,
+                      out o path);
+      @org\&.freedesktop\&.systemd1\&.Privileged("true")
+      RegisterMachineWithNetwork(in  s name,
+                                 in  ay id,
+                                 in  s service,
+                                 in  s class,
+                                 in  u leader,
+                                 in  s root_directory,
+                                 in  ai ifindices,
+                                 out o path);
+      UnregisterMachine(in  s name);
+      TerminateMachine(in  s id);
+      KillMachine(in  s name,
+                  in  s who,
+                  in  i signal);
+      GetMachineAddresses(in  s name,
+                          out a(iay) addresses);
+      GetMachineOSRelease(in  s name,
+                          out a{ss} fields);
+      @org\&.freedesktop\&.systemd1\&.Privileged("true")
+      OpenMachinePTY(in  s name,
+                     out h pty,
+                     out s pty_path);
+      OpenMachineLogin(in  s name,
+                       out h pty,
+                       out s pty_path);
+      OpenMachineShell(in  s name,
+                       in  s user,
+                       in  s path,
+                       in  as args,
+                       in  as environment,
+                       out h pty,
+                       out s pty_path);
+      BindMountMachine(in  s name,
+                       in  s source,
+                       in  s destination,
+                       in  b read_only,
+                       in  b mkdir);
+      CopyFromMachine(in  s name,
+                      in  s source,
+                      in  s destination);
+      CopyToMachine(in  s name,
+                    in  s source,
+                    in  s destination);
+      CopyFromMachineWithFlags(in  s name,
+                               in  s source,
+                               in  s destination,
+                               in  t flags);
+      CopyToMachineWithFlags(in  s name,
+                             in  s source,
+                             in  s destination,
+                             in  t flags);
+      OpenMachineRootDirectory(in  s name,
+                               out h fd);
+      GetMachineUIDShift(in  s name,
+                         out u shift);
+      RemoveImage(in  s name);
+      RenameImage(in  s name,
+                  in  s new_name);
+      CloneImage(in  s name,
+                 in  s new_name,
+                 in  b read_only);
+      MarkImageReadOnly(in  s name,
+                        in  b read_only);
+      GetImageHostname(in  s name,
+                       out s hostname);
+      GetImageMachineID(in  s name,
+                        out ay id);
+      GetImageMachineInfo(in  s name,
+                          out a{ss} machine_info);
+      GetImageOSRelease(in  s name,
+                        out a{ss} os_release);
+      SetPoolLimit(in  t size);
+      SetImageLimit(in  s name,
+                    in  t size);
+      CleanPool(in  s mode,
+                out a(st) images);
+      MapFromMachineUser(in  s name,
+                         in  u uid_inner,
+                         out u uid_outer);
+      MapToMachineUser(in  u uid_outer,
+                       out s machine_name,
+                       out o machine_path,
+                       out u uid_inner);
+      MapFromMachineGroup(in  s name,
+                          in  u gid_inner,
+                          out u gid_outer);
+      MapToMachineGroup(in  u gid_outer,
+                        out s machine_name,
+                        out o machine_path,
+                        out u gid_inner);
+    signals:
+      MachineNew(s machine,
+                 o path);
+      MachineRemoved(s machine,
+                     o path);
+    properties:
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
+      readonly s PoolPath = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
+      readonly t PoolUsage = \&.\&.\&.;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
+      readonly t PoolLimit = \&.\&.\&.;
+  };
+  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
+  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
+  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
+};
+    
+.fi
+.if n \{\
+.RE
+.\}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.SS "Methods"
+.PP
+\fBGetMachine()\fR
+may be used to get the machine object path for the machine with the specified name\&. Similarly,
+\fBGetMachineByPID()\fR
+gets the machine object the specified PID belongs to if there is any\&.
+.PP
+\fBGetImage()\fR
+may be used to get the image object path of the image with the specified name\&.
+.PP
+\fBListMachines()\fR
+returns an array of all currently registered machines\&. The structures in the array consist of the following fields: machine name, machine class, an identifier for the service that registered the machine and the machine object path\&.
+.PP
+\fBListImages()\fR
+returns an array of all currently known images\&. The structures in the array consist of the following fields: image name, type, read\-only flag, creation time, modification time, current disk space, and image object path\&.
+.PP
+\fBCreateMachine()\fR
+may be used to register a new virtual machine or container with
+\fBsystemd\-machined\fR, creating a scope unit for it\&. It accepts the following arguments: a machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the service that registers the machine, a class string, the PID of the leader process of the machine, an optional root directory of the container, and an array of additional properties to use for the scope registration\&. The virtual machine name must be suitable as a hostname, and hence should follow the usual DNS hostname rules, as well as the Linux hostname restrictions\&. Specifically, only 7 bit ASCII is permitted, a maximum length of 64 characters is enforced, only characters from the set
+"a\-zA\-Z0\-9\-_\&."
+are allowed, the name may not begin with a dot, and it may not contain two dots immediately following each other\&. Container and VM managers should ideally use the hostname used internally in the machine for this parameter\&. This recommendation is made in order to make the machine name naturally resolvable using
+\fBnss-mymachines\fR(8)\&. If a container manager needs to embed characters outside of the indicated range, escaping is required, possibly using
+"_"
+as the escape character\&. Another (somewhat natural) option would be to utilize Internet IDNA encoding\&. The UUID is passed as a 32 byte array or, if no suitable UUID is available, an empty array (zero length) or zeroed out array shall be passed\&. The UUID should identify the virtual machine/container uniquely and should ideally be the same UUID that
+/etc/machine\-id
+in the VM/container is initialized from\&. The service string can be free\-form, but it is recommended to pass a short lowercase identifier like
+"systemd\-nspawn",
+"libvirt\-lxc"
+or similar\&. The class string should be either
+"container"
+or
+"vm"
+indicating whether the machine to register is of the respective class\&. The leader PID should be the host PID of the init process of the container or the encapsulating process of the VM\&. If the root directory of the container is known and available in the host\*(Aqs hierarchy, it should be passed\&. Otherwise, pass the empty string instead\&. Finally, the scope properties are passed as array in the same way as to PID1\*(Aqs
+\fBStartTransientUnit()\fR
+method\&. Calling this method will internally register a transient scope unit for the calling client (utilizing the passed scope_properties) and move the leader PID into it\&. The method returns an object path for the registered machine object that implements the
+org\&.freedesktop\&.machine1\&.Machine
+interface (see below)\&. Also see the
+\m[blue]\fBNew Control Group Interfaces\fR\m[]\&\s-2\u[1]\d\s+2
+for details about scope units and how to alter resource control settings on the created machine at runtime\&.
+.PP
+\fBRegisterMachine()\fR
+is similar to
+\fBCreateMachine()\fR\&. However, it only registers a machine and does not create a scope unit for it\&. Instead, the caller\*(Aqs unit is registered\&. We recommend to only use this method for container or VM managers that are run multiple times, one instance for each container/VM they manage, and are invoked as system services\&.
+.PP
+\fBCreateMachineWithNetwork()\fR
+and
+\fBRegisterMachineWithNetwork()\fR
+are similar to
+\fBCreateMachine()\fR
+and
+\fBRegisterMachine()\fR
+but take an extra argument: an array of network interface indices that point towards the virtual machine or container\&. The interface indices should reference one or more network interfaces on the host that can be used to communicate with the guest\&. Commonly, the passed interface index refers to the host side of a "veth" link (in case of containers), a "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the VM/container interfaces\&. Specifying this information is useful to enable support for link\-local IPv6 communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex\&.
+\fBnss-mymachines\fR(8)
+makes use of this information\&.
+.PP
+\fBKillMachine()\fR
+sends a UNIX signal to the machine\*(Aqs processes\&. As its arguments, it takes a machine name (as originally passed to
+\fBCreateMachine()\fR
+or returned by
+\fBListMachines()\fR), an identifier that specifies what precisely to send the signal to (either
+"leader"
+or
+"all"), and a numeric UNIX signal integer\&.
+.PP
+\fBTerminateMachine()\fR
+terminates a virtual machine, killing its processes\&. It takes a machine name as its only argument\&.
+.PP
+\fBGetMachineAddresses()\fR
+retrieves the IP addresses of a container\&. This method returns an array of pairs consisting of an address family specifier (\fBAF_INET\fR
+or
+\fBAF_INET6\fR) and a byte array containing the addresses\&. This is only supported for containers that make use of network namespacing\&.
+.PP
+\fBGetMachineOSRelease()\fR
+retrieves the OS release information of a container\&. This method returns an array of key value pairs read from the
+\fBos-release\fR(5)
+file in the container and is useful to identify the operating system used in a container\&.
+.PP
+\fBOpenMachinePTY()\fR
+allocates a pseudo TTY in the container and returns a file descriptor and its path\&. This is equivalent to transitioning into the container and invoking
+\fBposix_openpt\fR(3)\&.
+.PP
+\fBOpenMachineLogin()\fR
+allocates a pseudo TTY in the container and ensures that a getty login prompt of the container is running on the other end\&. It returns the file descriptor of the PTY and the PTY path\&. This is useful for acquiring a pty with a login prompt from the container\&.
+.PP
+\fBOpenMachineShell()\fR
+allocates a pseudo TTY in the container, as the specified user, and invokes the executable at the specified path with a list of arguments (starting from argv[0]) and an environment block\&. It then returns the file descriptor of the PTY and the PTY path\&.
+.PP
+\fBBindMountMachine()\fR
+bind mounts a file or directory from the host into the container\&. Its arguments consist of a machine name, the source directory on the host, the destination directory in the container, and two booleans, one indicating whether the bind mount shall be read\-only, the other indicating whether the destination mount point shall be created first, if it is missing\&.
+.PP
+\fBCopyFromMachine()\fR
+copies files or directories from a container into the host\&. It takes a container name, a source directory in the container and a destination directory on the host as arguments\&.
+\fBCopyToMachine()\fR
+does the opposite and copies files from a source directory on the host into a destination directory in the container\&.
+\fBCopyFromMachineWithFlags()\fR
+and
+\fBCopyToMachineWithFlags\fR
+do the same but take an additional flags argument\&.
+.PP
+\fBRemoveImage()\fR
+removes the image with the specified name\&.
+.PP
+\fBRenameImage()\fR
+renames the specified image\&.
+.PP
+\fBCloneImage()\fR
+clones the specified image under a new name\&. It also takes a boolean argument indicating whether the resulting image shall be read\-only or not\&.
+.PP
+\fBMarkImageReadOnly()\fR
+toggles the read\-only flag of an image\&.
+.PP
+\fBSetPoolLimit()\fR
+sets an overall quota limit on the pool of images\&.
+.PP
+\fBSetImageLimit()\fR
+sets a per\-image quota limit\&.
+.PP
+\fBMapFromMachineUser()\fR,
+\fBMapToMachineUser()\fR,
+\fBMapFromMachineGroup()\fR, and
+\fBMapToMachineGroup()\fR
+may be used to map UIDs/GIDs from the host user namespace to a container user namespace or vice versa\&.
+.SS "Signals"
+.PP
+\fBMachineNew\fR
+and
+\fBMachineRemoved\fR
+are sent whenever a new machine is registered or removed\&. These signals carry the machine name and the object path to the corresponding
+org\&.freedesktop\&.machine1\&.Machine
+interface (see below)\&.
+.SS "Properties"
+.PP
+\fIPoolPath\fR
+specifies the file system path where images are written to\&.
+.PP
+\fIPoolUsage\fR
+specifies the current usage size of the image pool in bytes\&.
+.PP
+\fIPoolLimit\fR
+specifies the size limit of the image pool in bytes\&.
+.SH "MACHINE OBJECTS"
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+node /org/freedesktop/machine1/machine/rawhide {
+  interface org\&.freedesktop\&.machine1\&.Machine {
+    methods:
+      Terminate();
+      Kill(in  s who,
+           in  i signal);
+      GetAddresses(out a(iay) addresses);
+      GetOSRelease(out a{ss} fields);
+      GetUIDShift(out u shift);
+      OpenPTY(out h pty,
+              out s pty_path);
+      OpenLogin(out h pty,
+                out s pty_path);
+      OpenShell(in  s user,
+                in  s path,
+                in  as args,
+                in  as environment,
+                out h pty,
+                out s pty_path);
+      BindMount(in  s source,
+                in  s destination,
+                in  b read_only,
+                in  b mkdir);
+      CopyFrom(in  s source,
+               in  s destination);
+      CopyTo(in  s source,
+             in  s destination);
+      CopyFromWithFlags(in  s source,
+                        in  s destination,
+                        in  t flags);
+      CopyToWithFlags(in  s source,
+                      in  s destination,
+                      in  t flags);
+      OpenRootDirectory(out h fd);
+    properties:
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly s Name = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly ay Id = [\&.\&.\&.];
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly t Timestamp = \&.\&.\&.;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly t TimestampMonotonic = \&.\&.\&.;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly s Service = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly s Unit = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly u Leader = \&.\&.\&.;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly s Class = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly s RootDirectory = \*(Aq\&.\&.\&.\*(Aq;
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
+      readonly ai NetworkInterfaces = [\&.\&.\&.];
+      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
+      readonly s State = \*(Aq\&.\&.\&.\*(Aq;
+  };
+  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
+  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
+  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
+};
+    
+.fi
+.if n \{\
+.RE
+.\}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+.SS "Methods"
+.PP
+\fBTerminate()\fR
+and
+\fBKill()\fR
+terminate/kill the machine\&. These methods take the same arguments as
+\fBTerminateMachine()\fR
+and
+\fBKillMachine()\fR
+on the Manager interface, respectively\&.
+.PP
+\fBGetAddresses()\fR
+and
+\fBGetOSRelease()\fR
+get the IP address and OS release information from the machine\&. These methods take the same arguments as
+\fBGetMachineAddresses()\fR
+and
+\fBGetMachineOSRelease()\fR
+of the Manager interface, respectively\&.
+.SS "Properties"
+.PP
+\fIName\fR
+is the machine name as it was passed in during registration with
+\fBCreateMachine()\fR
+on the manager object\&.
+.PP
+\fIId\fR
+is the machine UUID\&.
+.PP
+\fITimestamp\fR
+and
+\fITimestampMonotonic\fR
+are the realtime and monotonic timestamps when the virtual machines where created in microseconds since the epoch\&.
+.PP
+\fIService\fR
+contains a short string identifying the registering service as passed in during registration of the machine\&.
+.PP
+\fIUnit\fR
+is the systemd scope or service unit name for the machine\&.
+.PP
+\fILeader\fR
+is the PID of the leader process of the machine\&.
+.PP
+\fIClass\fR
+is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for light\-weight userspace virtualization sharing the same kernel as the host)\&.
+.PP
+\fIRootDirectory\fR
+is the root directory of the container if it is known and applicable or the empty string\&.
+.PP
+\fINetworkInterfaces\fR
+contains an array of network interface indices that point towards the container, the VM or the host\&. For details about this information see the description of
+\fBCreateMachineWithNetwork()\fR
+above\&.
+.PP
+\fIState\fR
+is the state of the machine and is one of
+"opening",
+"running", or
+"closing"\&. Note that the state machine is not considered part of the API and states might be removed or added without this being considered API breakage\&.
+.SH "EXAMPLES"
+.PP
+\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.machine1\&.Manager on the bus\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ gdbus introspect \-\-system \e
+  \-\-dest org\&.freedesktop\&.machine1 \e
+  \-\-object\-path /org/freedesktop/machine1
+      
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.machine1\&.Machine on the bus\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+$ gdbus introspect \-\-system \e
+  \-\-dest org\&.freedesktop\&.machine1 \e
+  \-\-object\-path /org/freedesktop/machine1/machine/rawhide
+      
+.fi
+.if n \{\
+.RE
+.\}
+.SH "VERSIONING"
+.PP
+These D\-Bus interfaces follow
+\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[2]\d\s+2\&.
+.SH "HISTORY"
+.SS "The Manager Object"
+.PP
+\fBCopyFromMachineWithFlags()\fR
+and
+\fBCopyToMachineWithFlags()\fR
+were added in version 252\&.
+.SS "Machine Objects"
+.PP
+\fBCopyFromWithFlags()\fR
+and
+\fBCopyToWithFlags()\fR
+were added in version 252\&.
+.SH "NOTES"
+.IP " 1." 4
+New Control Group Interfaces
+.RS 4
+\%https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface
+.RE
+.IP " 2." 4
+the usual interface versioning guidelines
+.RS 4
+\%https://0pointer.de/blog/projects/versioning-dbus.html
+.RE