2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
6 <refentry id=
"org.freedesktop.machine1" conditional='ENABLE_MACHINED'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
9 <title>org.freedesktop.machine1
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>org.freedesktop.machine1
</refentrytitle>
15 <manvolnum>5</manvolnum>
19 <refname>org.freedesktop.machine1
</refname>
20 <refpurpose>The D-Bus interface of systemd-machined
</refpurpose>
24 <title>Introduction
</title>
27 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
28 is a system service that keeps track of locally running virtual machines and containers.
29 This page describes the D-Bus interface.
</para>
33 <title>The Manager Object
</title>
35 <para>The service exposes the following interfaces on the Manager object on the bus:
</para>
38 $ gdbus introspect --system \
39 --dest org.freedesktop.machine1 \
40 --object-path /org/freedesktop/machine1
42 node /org/freedesktop/machine1 {
43 interface org.freedesktop.machine1.Manager {
49 GetMachineByPID(in u pid,
51 ListMachines(out a(ssso) machines);
52 ListImages(out a(ssbttto) images);
53 CreateMachine(in s name,
59 in a(sv) scope_properties,
61 CreateMachineWithNetwork(in s name,
68 in a(sv) scope_properties,
70 RegisterMachine(in s name,
77 RegisterMachineWithNetwork(in s name,
85 UnregisterMachine(in s name);
86 TerminateMachine(in s id);
87 KillMachine(in s name,
90 GetMachineAddresses(in s name,
91 out a(iay) addresses);
92 GetMachineOSRelease(in s name,
94 OpenMachinePTY(in s name,
97 OpenMachineLogin(in s name,
100 OpenMachineShell(in s name,
107 BindMountMachine(in s name,
112 CopyFromMachine(in s name,
115 CopyToMachine(in s name,
118 OpenMachineRootDirectory(in s name,
120 GetMachineUIDShift(in s name,
122 RemoveImage(in s name);
123 RenameImage(in s name,
125 CloneImage(in s name,
128 MarkImageReadOnly(in s name,
130 GetImageHostname(in s name,
132 GetImageMachineID(in s name,
134 GetImageMachineInfo(in s name,
135 out a{ss} machine_info);
136 GetImageOSRelease(in s name,
137 out a{ss} os_release);
138 SetPoolLimit(in t size);
139 SetImageLimit(in s name,
143 MapFromMachineUser(in s name,
146 MapToMachineUser(in u uid_outer,
150 MapFromMachineGroup(in s name,
153 MapToMachineGroup(in u gid_outer,
158 MachineNew(s machine,
160 MachineRemoved(s machine,
163 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
164 readonly s PoolPath = '...';
165 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
166 readonly t PoolUsage = ...;
167 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
168 readonly t PoolLimit = ...;
170 interface org.freedesktop.DBus.Peer { ... };
171 interface org.freedesktop.DBus.Introspectable { ... };
172 interface org.freedesktop.DBus.Properties { ... };
177 <title>Methods
</title>
179 <para><function>GetMachine()
</function> may be used to get the machine object path for the machine with
180 the specified name. Similarly,
<function>GetMachineByPID()
</function> gets the machine object the
181 specified PID belongs to if there is any.
</para>
183 <para><function>GetImage()
</function> may be used to get the image object path of the image with the
184 specified name.
</para>
186 <para><function>ListMachines()
</function> returns an array of all currently registered machines. The
187 structures in the array consist of the following fields: machine name, machine class, an identifier for
188 the service that registered the machine and the machine object path.
</para>
190 <para><function>ListImages()
</function> returns an array of all currently known images. The
191 structures in the array consist of the following fields: image name, type, read-only flag, creation
192 time, modification time, current disk space, and image object path.
</para>
194 <para><function>CreateMachine()
</function> may be used to register a new virtual machine or container
195 with
<command>systemd-machined
</command>, creating a scope unit for it. It accepts the following arguments: a
196 machine name chosen by the registrar, an optional UUID as a
32 byte array, a string that identifies the
197 service that registers the machine, a class string, the PID of the leader process of the machine, an
198 optional root directory of the container, and an array of additional properties to use for the scope
199 registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual
200 DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only
7 bit ASCII is
201 permitted, a maximum length of
64 characters is enforced, only characters from the set
202 <literal>a-zA-Z0-
9-_.
</literal> are allowed, the name may not begin with a dot, and it may not contain
203 two dots immediately following each other. Container and VM managers should ideally use the hostname
204 used internally in the machine for this parameter. This recommendation is made in order to make the
205 machine name naturally resolvable using
206 <citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If
207 a container manager needs to embed characters outside of the indicated range, escaping is required,
208 possibly using
<literal>_
</literal> as the escape character. Another (somewhat natural) option would be
209 to utilize Internet IDNA encoding. The UUID is passed as a
32 byte array or, if no suitable UUID is
210 available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify
211 the virtual machine/container uniquely and should ideally be the same UUID that
212 <filename>/etc/machine-id
</filename> in the VM/container is initialized from. The service string can be
213 free-form, but it is recommended to pass a short lowercase identifier like
214 <literal>systemd-nspawn
</literal>,
<literal>libvirt-lxc
</literal> or similar. The class string should
215 be either
<literal>container
</literal> or
<literal>vm
</literal> indicating whether the machine to
216 register is of the respective class. The leader PID should be the host PID of the init process of the
217 container or the encapsulating process of the VM. If the root directory of the container is known and
218 available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the
219 scope properties are passed as array in the same way as to PID1's
220 <function>StartTransientUnit()
</function> method. Calling this method will internally register a transient scope
221 unit for the calling client (utilizing the passed scope_properties) and move the leader PID into
222 it. The call returns an object path for the registered machine object that implements the
223 <interfacename>org.freedesktop.machine1.Machine
</interfacename> interface (see below). Also see the
224 <ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
225 Interfaces
</ulink> for details about scope units and how to alter resource control settings on the
226 created machine at runtime.
</para>
228 <para><function>RegisterMachine()
</function> is similar to
<function>CreateMachine()
</function>.
229 However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is
230 registered. We recommend to only use this method for container or VM managers that are run
231 multiple times, one instance for each container/VM they manage, and are invoked as system
234 <para><function>CreateMachineWithNetwork()
</function> and
235 <function>RegisterMachineWithNetwork()
</function> are similar to
<function>CreateMachine()
</function>
236 and
<function>RegisterMachine()
</function> but take an extra argument: an array of network interface
237 indices that point towards the virtual machine or container. The interface indices should reference one
238 or more network interfaces on the host that can be used to communicate with the guest. Commonly, the
239 passed interface index refers to the host side of a
"veth" link (in case of containers), a
240 "tun"/
"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the
241 VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6
242 communication to the machines since the scope field of sockaddr_in6 can be initialized by the
244 <citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
245 makes use of this information.
</para>
247 <para><function>KillMachine()
</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a
248 machine name (as originally passed to
<function>CreateMachine()
</function> or returned by
249 <function>ListMachines()
</function>), an identifier that specifies what precisely to send the signal to (either
250 <literal>leader
</literal> or
<literal>all
</literal>), and a numeric UNIX signal integer.
</para>
252 <para><function>TerminateMachine()
</function> terminates a virtual machine, killing its processes. It
253 takes a machine name as its only argument.
</para>
255 <para><function>GetMachineAddresses()
</function> retrieves the IP addresses of a container. This call
256 returns an array of pairs consisting of an address family specifier (
<constant>AF_INET
</constant> or
257 <constant>AF_INET6
</constant>) and a byte array containing the addresses. This is only supported for
258 containers that make use of network namespacing.
</para>
260 <para><function>GetMachineOSRelease()
</function> retrieves the OS release information of a
261 container. This method returns an array of key value pairs read from the
262 <citerefentry><refentrytitle>os-release
</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
263 the container and is useful to identify the operating system used in a container.
</para>
265 <para><function>OpenMachinePTY()
</function> allocates a pseudo TTY in the container and returns a file
266 descriptor and its path. This is equivalent to transitioning into the container and invoking
267 <citerefentry><refentrytitle>posix_openpt
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
</para>
269 <para><function>OpenMachineLogin()
</function> allocates a pseudo TTY in the container and ensures that
270 a getty login prompt of the container is running on the other end. It returns the file descriptor of
271 the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the
274 <para><function>OpenMachineShell()
</function> allocates a pseudo TTY in the container, as the specified
275 user, and invokes the executable at the specified path with a list of arguments (starting from
276 argv[
0]) and an environment block. It then returns the file descriptor of the PTY and the PTY
279 <para><function>BindMountMachine()
</function> bind mounts a file or directory from the host into the
280 container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the
281 container, and two booleans, one indicating whether the bind mount shall be
282 read-only, the other indicating whether the destination mount point shall be created first, if it is
285 <para><function>CopyFromMachine()
</function> copies files or directories from a container into the
286 host. It takes a container name, a source directory in the container and a destination directory on the
287 host as arguments.
<function>CopyToMachine()
</function> does the opposite and copies files from a source
288 directory on the host into a destination directory in the container.
</para>
290 <para><function>RemoveImage()
</function> removes the image with the specified name.
</para>
292 <para><function>RenameImage()
</function> renames the specified image.
</para>
294 <para><function>CloneImage()
</function> clones the specified image under a new name. It also takes a
295 boolean argument indicating whether the resulting image shall be read-only or not.
</para>
297 <para><function>MarkImageReadOnly()
</function> toggles the read-only flag of an image.
</para>
299 <para><function>SetPoolLimit()
</function> sets an overall quota limit on the pool of images.
</para>
301 <para><function>SetImageLimit()
</function> sets a per-image quota limit.
</para>
303 <para><function>MapFromMachineUser()
</function>,
<function>MapToMachineUser()
</function>,
304 <function>MapFromMachineGroup()
</function>, and
<function>MapToMachineGroup()
</function> may be used to map
305 UIDs/GIDs from the host user namespace to a container user namespace or vice versa.
</para>
309 <title>Signals
</title>
311 <para><function>MachineNew
</function> and
<function>MachineRemoved
</function> are sent whenever a new
312 machine is registered or removed. These signals carry the machine name and the object path to the corresponding
313 <interfacename>org.freedesktop.machine1.Machine
</interfacename> interface (see below).
</para>
317 <title>Properties
</title>
319 <para><varname>PoolPath
</varname> specifies the file system path where images are written to.
</para>
321 <para><varname>PoolUsage
</varname> specifies the current usage size of the image pool in bytes.
</para>
323 <para><varname>PoolLimit
</varname> specifies the size limit of the image pool in bytes.
</para>
328 <title>Machine Objects
</title>
331 $ gdbus introspect --system \
332 --dest org.freedesktop.machine1 \
333 --object-path /org/freedesktop/machine1/machine/rawhide
335 node /org/freedesktop/machine1/machine/rawhide {
336 interface org.freedesktop.machine1.Machine {
341 GetAddresses(out a(iay) addresses);
342 GetOSRelease(out a{ss} fields);
343 GetUIDShift(out u shift);
354 BindMount(in s source,
358 CopyFrom(in s source,
362 OpenRootDirectory(out h fd);
364 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
365 readonly s Name = '...';
366 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
367 readonly ay Id = [...];
368 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
369 readonly t Timestamp = ...;
370 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
371 readonly t TimestampMonotonic = ...;
372 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
373 readonly s Service = '...';
374 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
375 readonly s Unit = '...';
376 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
377 readonly u Leader = ...;
378 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
379 readonly s Class = '...';
380 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
381 readonly s RootDirectory = '...';
382 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"const")
383 readonly ai NetworkInterfaces = [...];
384 @org.freedesktop.DBus.Property.EmitsChangedSignal(
"false")
385 readonly s State = '...';
387 interface org.freedesktop.DBus.Peer { ... };
388 interface org.freedesktop.DBus.Introspectable { ... };
389 interface org.freedesktop.DBus.Properties { ... };
394 <title>Methods
</title>
396 <para><function>Terminate()
</function> and
<function>Kill()
</function> terminate/kill the machine. These methods
397 take the same arguments as
<function>TerminateMachine()
</function> and
398 <function>KillMachine()
</function> on the Manager interface, respectively.
</para>
400 <para><function>GetAddresses()
</function> and
<function>GetOSRelease()
</function> get the IP address and OS
401 release information from the machine. These methods take the same arguments as
402 <function>GetMachineAddresses()
</function> and
<function>GetMachineOSRelease()
</function> of the
403 Manager interface, respectively.
</para>
407 <title>Properties
</title>
409 <para><varname>Name
</varname> is the machine name as it was passed in during registration with
410 <function>CreateMachine()
</function> on the manager object.
</para>
412 <para><varname>Id
</varname> is the machine UUID.
</para>
414 <para><varname>Timestamp
</varname> and
<varname>TimestampMonotonic
</varname> are the realtime and
415 monotonic timestamps when the virtual machines where created in microseconds since the epoch.
</para>
417 <para><varname>Service
</varname> contains a short string identifying the registering service as passed
418 in during registration of the machine.
</para>
420 <para><varname>Unit
</varname> is the systemd scope or service unit name for the machine.
</para>
422 <para><varname>Leader
</varname> is the PID of the leader process of the machine.
</para>
424 <para><varname>Class
</varname> is the class of the machine and is either the string
"vm" (for real VMs
425 based on virtualized hardware) or
"container" (for light-weight userspace virtualization sharing the
426 same kernel as the host).
</para>
428 <para><varname>RootDirectory
</varname> is the root directory of the container if it is known and
429 applicable or the empty string.
</para>
431 <para><varname>NetworkInterfaces
</varname> contains an array of network interface indices that point
432 towards the container, the VM or the host. For details about this information see the description of
433 <function>CreateMachineWithNetwork()
</function> above.
</para>
435 <para><varname>State
</varname> is the state of the machine and is one of
<literal>opening
</literal>,
436 <literal>running
</literal>, or
<literal>closing
</literal>. Note that the state machine is not considered
437 part of the API and states might be removed or added without this being considered API breakage.
443 <title>Versioning
</title>
445 <para>These D-Bus interfaces follow
<ulink url=
"http://0pointer.de/blog/projects/versioning-dbus.html">
446 the usual interface versioning guidelines
</ulink>.
</para>