diff options
Diffstat (limited to 'upstream/debian-unstable/man5/org.freedesktop.machine1.5')
| -rw-r--r-- | upstream/debian-unstable/man5/org.freedesktop.machine1.5 | 587 |
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 |