diff options
Diffstat (limited to 'man/systemd-machined.service.xml')
| -rw-r--r-- | man/systemd-machined.service.xml | 139 |
1 files changed, 139 insertions, 0 deletions
diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml new file mode 100644 index 0000000..48bf6c5 --- /dev/null +++ b/man/systemd-machined.service.xml @@ -0,0 +1,139 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1-or-later --> + +<refentry id="systemd-machined.service" conditional='ENABLE_MACHINED'> + + <refentryinfo> + <title>systemd-machined.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-machined.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-machined.service</refname> + <refname>systemd-machined</refname> + <refpurpose>Virtual machine and container registration manager</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-machined.service</filename></para> + <para><filename>/usr/lib/systemd/systemd-machined</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><command>systemd-machined</command> is a system service that keeps track of locally running virtual + machines and containers.</para> + + <para><command>systemd-machined</command> is useful for registering and keeping track of both OS + containers (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) and full virtual + machines (virtualized hardware running normal operating systems and possibly different kernels).</para> + + <para><command>systemd-machined</command> should <emphasis>not</emphasis> be used for registering/keeping + track of application sandbox containers. A <emphasis>machine</emphasis> in the context of + <command>systemd-machined</command> is supposed to be an abstract term covering both OS containers and + full virtual machines, but not application sandboxes.</para> + + <para>Machines registered with machined are exposed in various ways in the system. For example: + <itemizedlist> + <listitem><para>Tools like + <citerefentry project='man-pages'><refentrytitle>ps</refentrytitle><manvolnum>1</manvolnum></citerefentry> + will show to which machine a specific process belongs in a column of + its own, and so will + <ulink url="https://help.gnome.org/users/gnome-system-monitor/">gnome-system-monitor</ulink> or + <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para> + </listitem> + + <listitem><para>systemd's various tools + (<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>hostnamectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>timedatectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>localectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, ...) + support the <option>-M</option> switch to operate on local containers instead of the host system. + </para></listitem> + + <listitem><para><command>systemctl list-machines</command> will show the system state of all local + containers, connecting to the container's init system for that.</para></listitem> + + <listitem><para>systemctl's <option>--recursive</option> switch has the effect of not only showing the + locally running services, but recursively showing the services of all registered containers.</para></listitem> + + <listitem><para>The <command>machinectl</command> command provides access to a number of useful + operations on registered containers, such as introspecting them, rebooting, shutting them down, and + getting a login prompt on them.</para></listitem> + + <listitem><para>The + <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry> library + exposes the + <citerefentry><refentrytitle>sd_bus_open_system_machine</refentrytitle><manvolnum>3</manvolnum></citerefentry> + call to connect to the system bus of any registered container.</para></listitem> + + <listitem><para>The + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> + module makes sure all registered containers can be resolved via normal glibc + <citerefentry project='man-pages'><refentrytitle>gethostbyname</refentrytitle><manvolnum>3</manvolnum></citerefentry> + or + <citerefentry project='man-pages'><refentrytitle>getaddrinfo</refentrytitle><manvolnum>3</manvolnum></citerefentry> + calls.</para></listitem> + </itemizedlist></para> + + <para>See + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for some examples on how to run containers with OS tools.</para> + + <para>If you are interested in writing a VM or container manager that makes use of machined, please have + look at <ulink url="https://www.freedesktop.org/wiki/Software/systemd/writing-vm-managers">Writing + Virtual Machine or Container Managers</ulink>. Also see the <ulink + url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface">New Control Group + Interfaces</ulink>.</para> + + <para>The daemon provides both a C library interface + (which is shared with <citerefentry><refentrytitle>systemd-logind.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>) + 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 + <citerefentry><refentrytitle>sd-login</refentrytitle><manvolnum>3</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry> + and + <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + + <para>A small companion daemon + <citerefentry><refentrytitle>systemd-importd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is also available, which implements importing, exporting, and downloading of container and VM images. + </para> + + <para>For each container registered with <filename>systemd-machined.service</filename> that employs user + namespacing, users/groups are synthesized for the used UIDs/GIDs. These are made available to the system + using the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via + Varlink</ulink>, and thus may be resolved with + <citerefentry><refentrytitle>userdbctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> or the + usual glibc NSS calls.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> |