# org.freedesktop.machine1

## NAME



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


## INTRODUCTION



           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



           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 whom,
                                 in  i signal);
                     GetMachineAddresses(in  s name,
                                         out a(iay) addresses);
                     GetMachineSSHInfo(in  s name,
                                       out s ssh_address,
                                       out s ssh_private_key_path);
                     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);
                     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 = '...';
                     @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.
    
           **GetMachineSSHInfo()** retrieves the SSH information of a machine.
           This method returns two strings, the SSH address which can be used
           to tell SSH where to connect, and the path to the SSH private key
           required for the connection to succeed.
    
           **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.  **CopyFromMachineWithFlags()** and
           **CopyToMachineWithFlags()** do the same but take an additional flags
           argument.
    
           **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



               node /org/freedesktop/machine1/machine/rawhide {
                 interface org.freedesktop.machine1.Machine {
                   methods:
                     Terminate();
                     Kill(in  s whom,
                          in  i signal);
                     GetAddresses(out a(iay) addresses);
                     GetSSHInfo(out s ssh_address,
                                out s ssh_private_key_path);
                     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 = '...';
                     @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 s Subgroup = '...';
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly u Leader = ...;
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly t LeaderPIDFDId = ...;
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly u Supervisor = ...;
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly t SupervisorPIDFDId = ...;
                     @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("const")
                     readonly u VSockCID = ...;
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly s SSHAddress = '...';
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly s SSHPrivateKeyPath = '...';
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
                     readonly s State = '...';
                     @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
                     readonly u UID = ...;
                 };
                 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()** , **GetSSHInfo()** and **GetOSRelease()** get the IP
           address, SSH connection and OS release information from the
           machine. These methods take the same arguments as
           **GetMachineAddresses()** , **GetMachineSSHInfo()** 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. (The
           leader process is the top-level process of the payload of the
           machine, i.e. for containers PID 1 inside the container, and for
           VMs the process encapsulating the VM. Its lifetime defines the
           lifetime of the machine.)
    
           _LeaderPIDFDId_ encodes the Linux pidfd inode ID of the leader
           process of the machine.
    
           _Supervisor_ is the PID of the supervisor process of the machine.
           (The supervisor process is the process that manages the machine,
           if there's a separate one for it. A supervisor process is not
           always defined, and does not define the machine's lifetime.)
    
           _SupervisorPIDFDId_ encodes the Linux pidfd inode ID of the
           supervisor 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
           lightweight 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.
    
           _VSockCID_ is the VSOCK CID of the VM if it is known, or
           **VMADDR_CID_ANY** otherwise.
    
           _SSHAddress_ is the address of the VM in a format **ssh** can understand
           if it is known or the empty string.
    
           _SSHPrivateKeyPath_ is the path to the SSH private key of the VM if
           it is known or the empty string.
    
           _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.
    
           _Subgroup_ contains the sub-control-group path this machine's
           processes reside in, relative to the specified unit's control
           group.
    
           _UID_ contains the numeric UNIX UID of the user who registered the
           machine.
    


## EXAMPLES



           **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



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


## NOTES



            1. New Control Group Interfaces
               https://systemd.io/CONTROL_GROUP_INTERFACE
    
            2. the usual interface versioning guidelines
               https://0pointer.de/blog/projects/versioning-dbus.html
    


* * *