1 <?xml version='
1.0'
?> <!--*-nxml-*-->
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-or-later -->
6 <refentry id=
"systemd-machined.service" conditional='ENABLE_MACHINED'
>
9 <title>systemd-machined.service
</title>
10 <productname>systemd
</productname>
14 <refentrytitle>systemd-machined.service
</refentrytitle>
15 <manvolnum>8</manvolnum>
19 <refname>systemd-machined.service
</refname>
20 <refname>systemd-machined
</refname>
21 <refpurpose>Virtual machine and container registration manager
</refpurpose>
25 <para><filename>systemd-machined.service
</filename></para>
26 <para><filename>/usr/lib/systemd/systemd-machined
</filename></para>
30 <title>Description
</title>
32 <para><command>systemd-machined
</command> is a system service that keeps track of locally running virtual
33 machines and containers.
</para>
35 <para><command>systemd-machined
</command> is useful for registering and keeping track of both OS
36 containers (containers that share the host kernel but run a full init system of their own and behave in
37 most regards like a full virtual operating system rather than just one virtualized app) and full virtual
38 machines (virtualized hardware running normal operating systems and possibly different kernels).
</para>
40 <para><command>systemd-machined
</command> should
<emphasis>not
</emphasis> be used for registering/keeping
41 track of application sandbox containers. A
<emphasis>machine
</emphasis> in the context of
42 <command>systemd-machined
</command> is supposed to be an abstract term covering both OS containers and
43 full virtual machines, but not application sandboxes.
</para>
45 <para>Machines registered with machined are exposed in various ways in the system. For example:
47 <listitem><para>Tools like
48 <citerefentry project='man-pages'
><refentrytitle>ps
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
49 will show to which machine a specific process belongs in a column of
51 <ulink url=
"https://help.gnome.org/users/gnome-system-monitor/">gnome-system-monitor
</ulink> or
52 <citerefentry><refentrytitle>systemd-cgls
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
55 <listitem><para>systemd's various tools
56 (
<citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
57 <citerefentry><refentrytitle>journalctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
58 <citerefentry><refentrytitle>loginctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
59 <citerefentry><refentrytitle>hostnamectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
60 <citerefentry><refentrytitle>timedatectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
61 <citerefentry><refentrytitle>localectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
62 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>, ...)
63 support the
<option>-M
</option> switch to operate on local containers instead of the host system.
66 <listitem><para><command>systemctl list-machines
</command> will show the system state of all local
67 containers, connecting to the container's init system for that.
</para></listitem>
69 <listitem><para>systemctl's
<option>--recursive
</option> switch has the effect of not only showing the
70 locally running services, but recursively showing the services of all registered containers.
</para></listitem>
72 <listitem><para>The
<command>machinectl
</command> command provides access to a number of useful
73 operations on registered containers, such as introspecting them, rebooting, shutting them down, and
74 getting a login prompt on them.
</para></listitem>
77 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry> library
79 <citerefentry><refentrytitle>sd_bus_open_system_machine
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
80 call to connect to the system bus of any registered container.
</para></listitem>
83 <citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
84 module makes sure all registered containers can be resolved via normal glibc
85 <citerefentry project='man-pages'
><refentrytitle>gethostbyname
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
87 <citerefentry project='man-pages'
><refentrytitle>getaddrinfo
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
88 calls.
</para></listitem>
89 </itemizedlist></para>
92 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
93 for some examples on how to run containers with OS tools.
</para>
95 <para>If you are interested in writing a VM or container manager that makes use of machined, please have
96 look at
<ulink url=
"https://www.freedesktop.org/wiki/Software/systemd/writing-vm-managers">Writing
97 Virtual Machine or Container Managers
</ulink>. Also see the
<ulink
98 url=
"https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
99 Interfaces
</ulink>.
</para>
101 <para>The daemon provides both a C library interface
102 (which is shared with
<citerefentry><refentrytitle>systemd-logind.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>)
103 as well as a D-Bus interface.
104 The library interface may be used to introspect and watch the state of virtual machines/containers.
105 The bus interface provides the same but in addition may also be used to register or terminate
107 For more information please consult
108 <citerefentry><refentrytitle>sd-login
</refentrytitle><manvolnum>3</manvolnum></citerefentry>
110 <citerefentry><refentrytitle>org.freedesktop.machine1
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
112 <citerefentry><refentrytitle>org.freedesktop.LogControl1
</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
115 <para>A small companion daemon
116 <citerefentry><refentrytitle>systemd-importd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
117 is also available, which implements importing, exporting, and downloading of container and VM images.
120 <para>For each container registered with
<filename>systemd-machined.service
</filename> that employs user
121 namespacing, users/groups are synthesized for the used UIDs/GIDs. These are made available to the system
122 using the
<ulink url=
"https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via
123 Varlink
</ulink>, and thus may be resolved with
124 <citerefentry><refentrytitle>userdbctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the
125 usual glibc NSS calls.
</para>
129 <title>See Also
</title>
131 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
132 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
133 <citerefentry><refentrytitle>systemd-nspawn
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
134 <citerefentry><refentrytitle>nss-mymachines
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
135 <citerefentry><refentrytitle>systemd.special
</refentrytitle><manvolnum>7</manvolnum></citerefentry>