Merge pull request #33334 from poettering/machined-more-pidfd

[thirdparty/systemd.git] / man / systemd-machined.service.xml

diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml
index 5172f6511a91306d5e5b18266ecc0d825d781b8b..bb931ac50be55663a464a5119c52e69bf7bdc87d 100644 (file)
--- a/man/systemd-machined.service.xml
+++ b/man/systemd-machined.service.xml
@@ -1,7 +1,7 @@
 <?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+ -->
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="systemd-machined.service" conditional='ENABLE_MACHINED'>
 
@@ -93,40 +93,49 @@
     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
+    look at <ulink url="https://systemd.io/WRITING_VM_AND_CONTAINER_MANAGERS">Writing
     Virtual Machine or Container Managers</ulink>. Also see the <ulink
-    url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
+    url="https://systemd.io/CONTROL_GROUP_INTERFACE">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.
+    as well as a D-Bus interface and a Varlink 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.
+    machines. The Varlink interface may be used to register machines with optional extensions, e.g. with an
+    SSH key / address; it can be queried with
+    <command>varlinkctl introspect /run/systemd/machine/io.systemd.Machine io.systemd.Machine</command>.
     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>.
+    <citerefentry><refentrytitle>org.freedesktop.machine1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
     and
-    <citerefentry><refentrytitle>org.freedesktop.LogControl1</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    <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>
+    <para><simplelist type="inline">
+      <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
+      <member><citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
+    </simplelist></para>
   </refsect1>
 
 </refentry>