From de2efb75f72a732c82d36b015b190a4fe892672e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 7 Apr 2020 21:22:13 +0200 Subject: man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. org.foo.bar is used for interface names, function() for methods, and signal (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them. --- man/org.freedesktop.machine1.xml | 406 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 406 insertions(+) create mode 100644 man/org.freedesktop.machine1.xml (limited to 'man/org.freedesktop.machine1.xml') diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml new file mode 100644 index 0000000000..d089081a45 --- /dev/null +++ b/man/org.freedesktop.machine1.xml @@ -0,0 +1,406 @@ + + + + + + + org.freedesktop.machine1 + systemd + + + + org.freedesktop.machine1 + 5 + + + + org.freedesktop.machine1 + The D-Bus interface of systemd-machined + + + + Introduction + + + systemd-machined.service8 + is a system service that keeps track of locally running virtual machines and containers. + This page describes the D-Bus interface. + + + + The Manager Object + + The service exposes the following interfaces on the Manager object on the bus: + + +$ gdbus introspect --system \ + --dest org.freedesktop.machine1 \ + --object-path /org/freedesktop/machine1 + +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) machines); + 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); + 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); + RegisterMachine(in s name, + in ay id, + in s service, + in s class, + in u leader, + in s root_directory, + out o path); + 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); + KillMachine(in s name, + in s who, + in s signal); + TerminateMachine(in s id); + GetMachineAddresses(in s name, + out a(iay) addresses); + GetMachineOSRelease(in s name, + out a{ss} fields); + 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); + 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); + SetPoolLimit(in t size); + SetImageLimit(in s name, + in t size); + 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: + readonly s PoolPath = '/var/lib/machines'; + readonly t PoolUsage = 18446744070652059648; + readonly t PoolLimit = 2160721920; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + GetMachine() may be used to get the machine object path for the machine with + the specified name. Similarly, GetMachineByPID() get the machine object the + specified PID belongs to if there is any. + + GetImage() may be used to the the image object path for the image with the + specified name. + + ListMachines() returns an array with 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. + + ListImages() returns an array with 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, image object path. + + CreateMachine() may be used to register a new virtual machine or container + with systemd-machined, creating a scope unit for it. This takes as arguments: a + machine name chosen by the registrar, an optional UUID as 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 hostname, and hence should follow the usual + DNS hostname rules, as well as 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 + nss-mymachines8. 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 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 one as + /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's hierarchy, it should be passed, otherwise use the empty string. Finally, the + scope properties are passed as array in the same way as to PID1's + StartTransientUnit(). This method call will internally register a transient scope + unit for the calling client (utilizing the passed scope_properties), and move the leader PID into + it. The call returns an object path for the registered machine object, implementing the + org.freedesktop.machine1.Machine interface (see below). Also see the + New Control Group + Interfaces for details about scope units, and how to alter resource control settings on the + created machine at runtime. + + RegisterMachine() is similar to CreateMachine(), + however only registers a machine, but does not create a scope unit for it. The caller's unit will be + registered instead. This call is only recommended to be used for container or VM managers that are run + multiple times, one instance for each container/VM they manage, and are invoked as system + services. + + CreateMachineWithNetwork() and + RegisterMachineWithNetwork() are similar to CreateMachine() + and RegisterMachine() but take an extra argument: an array of network interface + indexes that point towards the virtual machine or container. The interface indexes 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), or 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. + nss-mymachines8 + makes use of this information. + + KillMachine() sends a UNIX signal to the machine's processes. It takes a + machine name (as originally passed to CreateMachine() or returned by + ListMachines()). An identifier what precisely to send the signal to being either + leader or all, plus a numeric UNIX signal integer. + + TerminateMachine() terminates a virtual machine, killing its processes. It + takes a machine name as argument. + + GetMachineAddresses() retrieves the IP addresses of a container. This call + returns an array of pairs consisting of an address family specifier (AF_INET or + AF_INET6) and a byte array containing the addresses. This is only supported for + containers that make use of network namespacing. + + GetMachineOSRelease() retrieves the OS release information of a + container. This call returns an array of key value pairs read from the + os-release5 file in + the container, and is useful to identify the operating system used in a container. + + OpenMachinePTY() 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 + posix_openpt3. + + OpenMachineLogin() allocates a pseudo TTY in the container and ensures that + a getty loging prompt of the container is running on the other end. It returns the file descriptor of + the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the + container. + + OpenMachineShell() allocates a pseudo TTY in the container, as the specified + user, and invokes an executable of 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 plus the PTY + path. + + BindMountMachine() bind mounts a file or directory from the host into the + container. Takes a machine name, the source directory on the host, and the destination directory in the + container as argument. Also takes 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. + + CopyFromMachine() copies files or directories from a container into the + host. Takes a container name, a source directory in the container and a destination directory on the + host as argument. CopyToMachine() does the opposite and copies files from a source + directory on the host into a destination directory in the container. + + RemoveImage() removes the image by the specified name. + + RenameImage() renames the specified image to a new name. + + CloneImage() clones the specified image under a new name. Also takes a + boolean argument indicating whether the resuling image shall be read-only or not. + + MarkImageReadOnly() toggles the read-only flag of an image. + + SetPoolLimit() sets an overall quota limit on the pool of images. + + SetImageLimit() sets a per-image quota limit. + + MapFromMachineUser(), MapToMachineUser(), + MapFromMachineGroup(), MapToMachineGroup() may be used to map + UIDs/GIDs from the host user namespace to a container namespace or back. + + + + Signals + + MachineNew and MachineRemoved are sent whenever a new + machine is registered or removed. These signals carry the machine name plus the object path to the + org.freedesktop.machine1.Machine interface (see below). + + + + Properties + + PoolPath specifies the file system path where images are written to. + + PoolUsage specifies the current usage size of the image pool in bytes. + + PoolLimit specifies the size limit of the image pool in bytes. + + + + + Machine Objects + + +$ gdbus introspect --system \ + --dest org.freedesktop.machine1 \ + --object-path /org/freedesktop/machine1/machine/rawhide + +node /org/freedesktop/machine1/machine/fedora_2dtree { + interface org.freedesktop.machine1.Machine { + methods: + Terminate(); + Kill(in s who, + in s signal); + GetAddresses(out a(iay) addresses); + GetOSRelease(out a{ss} fields); + signals: + properties: + readonly s Name = 'fedora-tree'; + readonly ay Id = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]; + readonly t Timestamp = 1374193370484284; + readonly t TimestampMonotonic = 128247251308; + readonly s Service = 'nspawn'; + readonly s Unit = 'machine-fedora\\x2dtree.scope'; + readonly u Leader = 30046; + readonly s Class = 'container'; + readonly s RootDirectory = '/home/lennart/fedora-tree'; + readonly ai NetworkInterfaces = [7]; + readonly s State = 'running'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; + + + + Methods + + Terminate() and Kill() terminate/kill the machine, and + take the same arguments as TerminateMachine() and + KillMachine() on the Manager interface. + + GetAddresses() and GetOSRelease() get IP address and OS + release information from the machine, and take the same arguments as + GetMachineAddresses() and GetMachineOSRelease() of the + Manager interface, described above. + + + + Properties + + Name is the machine name, as it was passed in during registration with + CreateMachine() on the manager object. + + Id is the machine UUID. + + Timestamp and TimestampMonotonic are the realtime and + monotonic timestamps when the virtual machines where created. + + Service contains a short string identifying the registering service, as passed + in during registration of the machine. + + Unit is the systemd scope or service unit name for the machine. + + Leader is the PID of the leader process of the machine. + + Class is the class of the machine and 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). + + RootDirectory is the root directory of the container if that is known and + applicable, or the empty string. + + NetworkInterfaces contains an array of network interface indexes that point + towards the container or VM or the host. For details about this information see the description of + CreateMachineWithNetwork() above. + + State is the state of the machine, and one of opening, + running, 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. + + + + + + Versioning + + These D-Bus interfaces follow + the usual interface versioning guidelines. + + -- cgit v1.2.1