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.
+
+
diff --git a/man/rules/meson.build b/man/rules/meson.build
index 4e57b94bbf..c6baedcf6c 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -45,6 +45,7 @@ manpages = [
['nss-resolve', '8', ['libnss_resolve.so.2'], 'ENABLE_NSS_RESOLVE'],
['nss-systemd', '8', ['libnss_systemd.so.2'], 'ENABLE_NSS_SYSTEMD'],
['org.freedesktop.login1', '5', [], 'ENABLE_LOGIND'],
+ ['org.freedesktop.machine1', '5', [], 'ENABLE_MACHINED'],
['os-release', '5', [], ''],
['pam_systemd', '8', [], 'HAVE_PAM'],
['pam_systemd_home', '8', [], 'ENABLE_PAM_HOME'],
diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml
index 8771434e5a..b5fad154e7 100644
--- a/man/systemd-machined.service.xml
+++ b/man/systemd-machined.service.xml
@@ -29,24 +29,91 @@
Description
- systemd-machined is a system service that
- keeps track of virtual machines and containers, and processes
- belonging to them.
+ systemd-machined is a system service that keeps track of locally running virtual
+ machines and containers.
+
+ systemd-machined is useful for registering and keeping track of both OS
+ containers (containers that share the host kernel but run a full init system of their own and behave in
+ most regards like a full virtual operating system rather than just one virtualized app) and full virtual
+ machines (virtualized hardware running normal operating systems and possibly different kernels).
+
+ systemd-machined should not be used for registering/keeping
+ track of application sandbox containers. A machine in the context of
+ systemd-machined is supposed to be an abstract term covering both OS containers and
+ full virtual machines, but not application sandboxes.
+
+ Machines registered with machined are exposed in various ways in the system. For example:
+
+ Tools like
+ ps1
+ will show to which machine a specific process belongs in a column of
+ its own, and so will
+ gnome-system-monitor or
+ systemd-cgls1.
+
+
+ systemd's various tools
+ (systemctl1,
+ journalctl1,
+ loginctl1,
+ hostnamectl1,
+ timedatectl1,
+ localectl1,
+ machinectl1, ...)
+ support the switch to operate on local containers instead of the host system.
+
+
+ systemctl list-machines will show the system state of all local
+ containers, connecting to the container's init system for that.
+
+ systemctl's switch has the effect of not only showing the
+ locally running services, but recursively the services of all registered containers.
+
+ The machinectl command provides access to a number of useful
+ operations on registered containers, such as introspecting them, rebooting, shutting them down, and
+ getting a login prompt on them.
+
+ The
+ sd-bus3 library
+ exposes the
+ sd_bus_open_system_container3
+ call to connect to the system bus of any registered container.
+
+ The
+ nss-mymachines8
+ module makes sure all registered containers can be resolved via normal glibc
+ gethostbyname3
+ or
+ getaddrinfo3
+ calls.
+ See
systemd-nspawn1
for some examples on how to run containers with OS tools.
- Use
- nss-mymachines8
- to make the names of local containers known to
- systemd-machined locally resolvable as host
- names.
+ If you are interested in writing a VM or container manager that makes use of machined, please have
+ look at Writing
+ Virtual Machine or Container Managers. Also see the New Control Group
+ Interfaces.
- See the
-
- machined D-Bus API Documentation for information about the
- APIs systemd-machined provides.
+ The daemon provides both a C library interface
+ (which is shared with systemd-logind.service8)
+ as well as a D-Bus interface.
+ The library interface may be used to introspect and watch the state of virtual machines/containers.
+ The bus interface provides the same but in addition may also be used to register or terminate
+ machines.
+ For more information please consult
+ sd-login3
+ and
+ org.freedesktop.machine13.
+
+
+ A small companion daemon
+ systemd-importd.service8
+ is also available, which implements importing, exporting, and downloading of container and VM images.
+