man: document new varlink service

poettering · poettering · commit 4c2cf15751e7 · 2020-07-14T17:08:12.000+02:00
diff --git a/docs/USER_GROUP_API.md b/docs/USER_GROUP_API.md
@@ -108,7 +108,7 @@ example, introspection is not available, and the resolver logic is not used.
 
 ## Other Services
 
-The `systemd` project provides two other services implementing this
+The `systemd` project provides three other services implementing this
 interface. Specifically:
 
 1. `io.systemd.DynamicUser` → This service is implemented by the service
@@ -119,6 +119,10 @@ interface. Specifically:
    and provides records for the users and groups defined by the home
    directories it manages.
 
+3. `io.systemd.Machine` → This service is implemented by
+   `systemd-machined.service` and provides records for the users and groups used
+   by local containers that use user namespacing.
+
 Other projects are invited to implement these services too. For example it
 would make sense for LDAP/ActiveDirectory projects to implement these
 interfaces, which would provide them a way to do per-user resource management
diff --git a/man/nss-systemd.xml b/man/nss-systemd.xml
@@ -35,8 +35,8 @@
     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> (for its
     <varname>DynamicUser=</varname> feature, see
     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
-    details) or
-    <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
+    details),
+    <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
 
     <para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs
     0 and 65534) remain resolvable at all times, even if they aren't listed in <filename>/etc/passwd</filename> or
@@ -55,7 +55,7 @@
   </refsect1>
 
   <refsect1>
-    <title>Example</title>
+    <title>Configuration in <filename>/etc/nsswitch.conf</filename></title>
 
     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
     <command>nss-systemd</command> correctly:</para>
@@ -77,6 +77,47 @@ netgroup:       nis</programlisting>
 
   </refsect1>
 
+  <refsect1>
+    <title>Example: Mappings provided by <filename>systemd-machined.service</filename></title>
+
+    <para>The container <literal>rawhide</literal> is spawned using
+    <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>:
+    </para>
+
+    <programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick
+Spawning container rawhide on /var/lib/machines/rawhide.
+Selected user namespace base 20119552 and range 65536.
+...
+
+$ machinectl --max-addresses=3
+MACHINE CLASS     SERVICE        OS     VERSION ADDRESSES
+rawhide container systemd-nspawn fedora 30      169.254.40.164 fe80::94aa:3aff:fe7b:d4b9
+
+$ getent passwd vu-rawhide-0 vu-rawhide-81
+vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
+vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin
+
+$ getent group vg-rawhide-0 vg-rawhide-81
+vg-rawhide-0:*:20119552:
+vg-rawhide-81:*:20119633:
+
+$ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
+vu-rawhide-0      692 ?        /usr/lib/systemd/systemd
+vu-rawhide-0      731 ?        /usr/lib/systemd/systemd-journald
+vu-rawhide-192    734 ?        /usr/lib/systemd/systemd-networkd
+vu-rawhide-193    738 ?        /usr/lib/systemd/systemd-resolved
+vu-rawhide-0      742 ?        /usr/lib/systemd/systemd-logind
+vu-rawhide-81     744 ?        /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
+vu-rawhide-0      746 ?        /usr/sbin/sshd -D ...
+vu-rawhide-0      752 ?        /usr/lib/systemd/systemd --user
+vu-rawhide-0      753 ?        (sd-pam)
+vu-rawhide-0     1628 ?        login -- zbyszek
+vu-rawhide-1000  1630 ?        /usr/lib/systemd/systemd --user
+vu-rawhide-1000  1631 ?        (sd-pam)
+vu-rawhide-1000  1637 pts/8    -zsh
+</programlisting>
+  </refsect1>
+
   <refsect1>
     <title>See Also</title>
     <para>
@@ -85,6 +126,9 @@ netgroup:       nis</programlisting>
       <citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
     </para>
diff --git a/man/systemd-machined.service.xml b/man/systemd-machined.service.xml
@@ -116,6 +116,13 @@
     <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>
diff --git a/man/userdbctl.xml b/man/userdbctl.xml
@@ -186,6 +186,15 @@
         available to the system.</para></listitem>
       </varlistentry>
 
+      <varlistentry>
+        <term><constant>io.systemd.Machine</constant></term>
+
+        <listitem><para>This service is provided by
+        <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+        and synthesizes records for all users/groups used by a container that employs user
+        namespacing.</para></listitem>
+      </varlistentry>
+
       <varlistentry>
         <term><constant>io.systemd.Multiplexer</constant></term>
 
