org.freedesktop.machine1(5) — Linux manual page

NAME | INTRODUCTION | THE MANAGER OBJECT | MACHINE OBJECTS | EXAMPLES | VERSIONING | NOTES | COLOPHON

ORG.FREEDESKTOP.MACHINE1(5)rg.freedesktop.machine1RG.FREEDESKTOP.MACHINE1(5)

NAME         top

       org.freedesktop.machine1 - The D-Bus interface of systemd-machined

INTRODUCTION         top

       systemd-machined.service(8) is a system service that keeps track of
       locally running virtual machines and containers. This page describes
       the D-Bus interface.

THE MANAGER OBJECT         top

       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);
                 GetImage(in  s name,
                          out o image);
                 GetMachineByPID(in  u pid,
                                 out o machine);
                 ListMachines(out a(ssso) machines);
                 ListImages(out a(ssbttto) images);
                 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);
                 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);
                 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);
                 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 = '...';
                 @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 { ... };
           };

   Methods
       GetMachine() may be used to get the machine object path for the
       machine with the specified name. Similarly, GetMachineByPID() gets
       the machine object the specified PID belongs to if there is any.

       GetImage() may be used to get the image object path of the image with
       the specified name.

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

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

       CreateMachine() may be used to register a new virtual machine or
       container with systemd-machined, 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 nss-mymachines(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's
       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's StartTransientUnit() 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
       New Control Group Interfaces[1] for details about scope units and how
       to alter resource control settings on the created machine at runtime.

       RegisterMachine() is similar to CreateMachine(). However, it only
       registers a machine and does not create a scope unit for it. Instead,
       the caller's 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.

       CreateMachineWithNetwork() and RegisterMachineWithNetwork() are
       similar to CreateMachine() and RegisterMachine() 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.
       nss-mymachines(8) makes use of this information.

       KillMachine() sends a UNIX signal to the machine's processes. As its
       arguments, it takes a machine name (as originally passed to
       CreateMachine() or returned by ListMachines()), an identifier that
       specifies what precisely to send the signal to (either "leader" or
       "all"), and a numeric UNIX signal integer.

       TerminateMachine() terminates a virtual machine, killing its
       processes. It takes a machine name as its only argument.

       GetMachineAddresses() retrieves the IP addresses of a container. This
       method 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 method returns an array of key value pairs read from
       the os-release(5) 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_openpt(3).

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

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

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

       CopyFromMachine() 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.
       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 with the specified name.

       RenameImage() renames the specified image.

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

       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(), and
       MapToMachineGroup() may be used to map UIDs/GIDs from the host user
       namespace to a container user namespace or vice versa.

   Signals
       MachineNew and MachineRemoved 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).

   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         top

           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);
                 OpenRootDirectory(out h fd);
               properties:
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s Name = '...';
                 @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 = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s Unit = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly u Leader = ...;
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s Class = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly s RootDirectory = '...';
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                 readonly ai NetworkInterfaces = [...];
                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
                 readonly s State = '...';
             };
             interface org.freedesktop.DBus.Peer { ... };
             interface org.freedesktop.DBus.Introspectable { ... };
             interface org.freedesktop.DBus.Properties { ... };
           };

   Methods
       Terminate() and Kill() terminate/kill the machine. These methods take
       the same arguments as TerminateMachine() and KillMachine() on the
       Manager interface, respectively.

       GetAddresses() and GetOSRelease() get the IP address and OS release
       information from the machine. These methods take the same arguments
       as GetMachineAddresses() and GetMachineOSRelease() of the Manager
       interface, respectively.

   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 in microseconds
       since the epoch.

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

       RootDirectory is the root directory of the container if it is known
       and applicable or the empty string.

       NetworkInterfaces 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 CreateMachineWithNetwork()
       above.

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

EXAMPLES         top

       Example 1. Introspect org.freedesktop.machine1.Manager on the bus

           $ gdbus introspect --system \
             --dest org.freedesktop.machine1 \
             --object-path /org/freedesktop/machine1

       Example 2. Introspect org.freedesktop.machine1.Machine on the bus

           $ gdbus introspect --system \
             --dest org.freedesktop.machine1 \
             --object-path /org/freedesktop/machine1/machine/rawhide

VERSIONING         top

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

NOTES         top

        1. New Control Group Interfaces
           https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/

        2. the usual interface versioning guidelines
           http://0pointer.de/blog/projects/versioning-dbus.html

COLOPHON         top

       This page is part of the systemd (systemd system and service manager)
       project.  Information about the project can be found at 
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a bug
       report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2020-08-13.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-08-11.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not part
       of the original manual page), send a mail to man-pages@man7.org

systemd 246                                      ORG.FREEDESKTOP.MACHINE1(5)

Pages that refer to this page: org.freedesktop.import1(5)30-systemd-environment-d-generator(7)systemd.directives(7)systemd.index(7)systemd-machined(8)systemd-machined.service(8)