Back to systemd

machined

systemd 205 and newer include systemd-machined. This is a tiny daemon that tracks locally running Virtual Machines and Containers in various ways.

See systemd-machined(8).service for more information.

The daemon provides both a C library interface (which is shared with logind) 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 the man pages: sd-login(7)

machined is useful for registering and keeping track of both OS containers (i.e. 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 or similar) and full virtual machines (i.e. virtualized hardware running normal operating systems and possibly different kernels).

machined should not be used for registering/keeping track of application sandbox containers. A machine in the context of 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 "ps" will show to which machine a specific process belongs in a column of its own, and so will "gnome-system-monitor" or "systemd-cgls".
  • systemd's various tools (systemctl, journalctl, loginctl, hostnamectl, timedatectl, localectl, machinectl, ...) support the "-M" switch to operate on local containers instead of the host system.
  • systemctl's "list-machines" command will show the system state of all local containers, connecting to the container's init system for that.
  • systemctl's "--recursive" 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 or shutting them down, or getting a login prompt on them.
  • The sd-bus API exposes the sd_bus_open_system_container() call to connect to the system bus of any registered container
  • The nss-mymachines module makes sure all registered containers can be resolved via normal glibc gethostbyname() or getaddrinfo()

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.

The Manager Object

The service exposes the following interfaces on the Manager object on the bus:

node /org/freedesktop/machine1 {
  interface org.freedesktop.machine1.Manager {
    methods:
      GetMachine(in  s name,
                 out o machine);
      GetMachineByPID(in  u pid,
                      out o machine);
      ListMachines(out a(ssso) 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);
    signals:
      MachineNew(s machine,
                 o path);
      MachineRemoved(s machine,
                     o path);
    properties:
  };
  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. Similar, GetMachineByPID() get the machine object the specified PID belongs to if there is any.

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.

CreateMachine() may be used to register a new virtual machine or container with 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 a file name, and hence not contain any slashes, nor be the empty string, nor single/double full stops. Only 7 Bit ASCII is permitted. 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, if that's possible. The service string can be free-form, but it is recommended to parse a short lowercase identifier like "systemd-nspawn", "libvirt-lxc" or suchlike. 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 PID1's StartTransientUnit() accepts it. 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 Countrol 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-mymachines 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 specfier (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 /usr/lib/os-release from the container, and useful to identify the operating system used in a container. See os-release(5) for details.

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).

Machine Objects

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.


These D-Bus interfaces follow the usual interface versioning guidelines.