man/nss-systemd.xml

   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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="nss-systemd" conditional='ENABLE_NSS_SYSTEMD'>
   7
   8   <refentryinfo>
   9     <title>nss-systemd</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>nss-systemd</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>nss-systemd</refname>
  20     <refname>libnss_systemd.so.2</refname>
  21     <refpurpose>UNIX user and group name resolution for user/group lookup via Varlink</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>libnss_systemd.so.2</filename></para>
  26   </refsynopsisdiv>
  27
  28   <refsect1>
  29     <title>Description</title>
  30
  31     <para><command>nss-systemd</command> is a plug-in module for the GNU Name Service Switch (NSS)
  32     functionality of the GNU C Library (<command>glibc</command>), providing UNIX user and group name
  33     resolution for services implementing the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record
  34     Lookup API via Varlink</ulink>, such as the system and service manager
  35     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> (for its
  36     <varname>DynamicUser=</varname> feature, see
  37     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
  38     details),
  39     <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, or <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
  40
  41     <para>This module also ensures that the root and nobody users and groups (i.e. the users/groups with the UIDs/GIDs
  42     0 and 65534) remain resolvable at all times, even if they are not listed in <filename>/etc/passwd</filename> or
  43     <filename>/etc/group</filename>, or if these files are missing.</para>
  44
  45     <para>This module preferably utilizes
  46     <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  47     for resolving users and groups, but also works without the service running.</para>
  48
  49     <para>To activate the NSS module, add <literal>systemd</literal> to the lines starting with
  50     <literal>passwd:</literal>, <literal>group:</literal>, <literal>shadow:</literal> and
  51     <literal>gshadow:</literal> in <filename>/etc/nsswitch.conf</filename>.</para>
  52
  53     <para>It is recommended to place <literal>systemd</literal> after the <literal>files</literal> entry of
  54     the <filename>/etc/nsswitch.conf</filename> lines so that <filename>/etc/passwd</filename>,
  55     <filename>/etc/group</filename>, <filename>/etc/shadow</filename> and <filename>/etc/gshadow</filename>
  56     based mappings take precedence.</para>
  57   </refsect1>
  58
  59   <refsect1>
  60     <title>Static Drop-In JSON User/Group Records</title>
  61
  62     <para>Besides user/group records acquired via the aforementioned Varlink IPC interfaces and the
  63     synthesized root and nobody accounts, this module also makes user and group accounts available to the
  64     system that are defined in static drop-in files in the <filename>/etc/userdb/</filename>,
  65     <filename>/run/userdb/</filename>, <filename>/run/host/userdb/</filename> and
  66     <filename>/usr/lib/userdb/</filename> directories.</para>
  67
  68     <para>This is a simple mechanism to provide static user and group records via JSON drop-in files. Such
  69     user records should be defined in the format described by the <ulink
  70     url="https://systemd.io/USER_RECORD">JSON User Records</ulink> specification and be placed in one of the
  71     aforementioned directories under a file name composed of the user name suffixed with
  72     <filename>.user</filename>, with a world-readable access mode. A symlink named after the user record's
  73     UID formatted in decimal and suffixed with <filename>.user</filename> pointing to the primary record file
  74     should be created as well, in order to allow both lookups by username and by UID. Privileged user record
  75     data (e.g. hashed UNIX passwords) may optionally be provided as well, in a pair of separate companion
  76     files with the <filename>.user-privileged</filename> suffix. The data should be stored in a regular file
  77     named after the user name, suffixed with <filename>.user-privileged</filename>, and a symlink pointing to
  78     it, named after the used numeric UID formatted in decimal with the same suffix. These companion files
  79     should not be readable to anyone but root. Example:</para>
  80
  81     <programlisting>-rw-r--r--. 1 root root  723 May 10 foobar.user
  82 -rw-------. 1 root root  123 May 10 foobar.user-privileged
  83 lrwxrwxrwx. 1 root root   19 May 10 4711.user -> foobar.user
  84 lrwxrwxrwx. 1 root root   19 May 10 4711.user-privileged -> foobar.user-privileged</programlisting>
  85
  86     <para>Similarly, group records following the format described in <ulink
  87     url="https://systemd.io/GROUP_RECORD">JSON Group Record</ulink> may be defined, using the file suffixes
  88     <filename>.group</filename> and <filename>.group-privileged</filename>.</para>
  89
  90     <para>The primary user/group record files (i.e. those with the <filename>.user</filename> and
  91     <filename>.group</filename> suffixes) should not contain the <literal>privileged</literal> section as
  92     described in the specifications. The privileged user/group record files (i.e. those with the
  93     <filename>.user-privileged</filename> and <filename>.group-privileged</filename> suffixes) should
  94     contain this section, exclusively.</para>
  95
  96     <para>In addition to the two types of user record files and the two types of group record files there's a
  97     fifth type of file that may be placed in the searched directories: files that indicate membership of
  98     users in groups. Specifically, for every pair of user/group where the user shall be a member of a group a
  99     file named
 100     <literal><replaceable>username</replaceable>:<replaceable>groupname</replaceable>.membership</literal>
 101     should be created, i.e. the textual UNIX user name, followed by a colon, followed by the textual UNIX
 102     group name, suffixed by <literal>.membership</literal>. The contents of these files are currently not
 103     read, and the files should be created empty. The mere existence of these files is enough to effect a
 104     user/group membership. If a program provides user and/or group record files in the searched directories,
 105     it should always also create such files, both for primary and auxiliary group memberships.</para>
 106
 107     <para>Note that static user/group records generally do not override conflicting records in
 108     <filename>/etc/passwd</filename> or <filename>/etc/group</filename> or other account databases. In fact,
 109     before dropping in these files a reasonable level of care should be taken to avoid user/group name and
 110     UID/GID conflicts.</para>
 111   </refsect1>
 112
 113   <refsect1>
 114     <title>Configuration in <filename>/etc/nsswitch.conf</filename></title>
 115
 116     <para>Here is an example <filename>/etc/nsswitch.conf</filename> file that enables
 117     <command>nss-systemd</command> correctly:</para>
 118
 119     <!-- synchronize with other nss-* man pages and factory/etc/nsswitch.conf -->
 120     <programlisting>passwd:         files <command>systemd</command>
 121 group:          files <command>[SUCCESS=merge] systemd</command>
 122 shadow:         files <command>systemd</command>
 123 gshadow:        files <command>systemd</command>
 124
 125 hosts:          mymachines resolve [!UNAVAIL=return] files myhostname dns
 126 networks:       files
 127
 128 protocols:      db files
 129 services:       db files
 130 ethers:         db files
 131 rpc:            db files
 132
 133 netgroup:       nis</programlisting>
 134
 135   </refsect1>
 136
 137   <refsect1>
 138     <title>Example: Mappings provided by <filename>systemd-machined.service</filename></title>
 139
 140     <para>The container <literal>rawhide</literal> is spawned using
 141     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>:
 142     </para>
 143
 144     <programlisting># systemd-nspawn -M rawhide --boot --network-veth --private-users=pick
 145 Spawning container rawhide on /var/lib/machines/rawhide.
 146 Selected user namespace base 20119552 and range 65536.
 147 ...
 148
 149 $ machinectl --max-addresses=3
 150 MACHINE CLASS     SERVICE        OS     VERSION ADDRESSES
 151 rawhide container systemd-nspawn fedora 30      169.254.40.164 fe80::94aa:3aff:fe7b:d4b9
 152
 153 $ getent passwd vu-rawhide-0 vu-rawhide-81
 154 vu-rawhide-0:*:20119552:65534:vu-rawhide-0:/:/usr/sbin/nologin
 155 vu-rawhide-81:*:20119633:65534:vu-rawhide-81:/:/usr/sbin/nologin
 156
 157 $ getent group vg-rawhide-0 vg-rawhide-81
 158 vg-rawhide-0:*:20119552:
 159 vg-rawhide-81:*:20119633:
 160
 161 $ ps -o user:15,pid,tty,command -e|grep '^vu-rawhide'
 162 vu-rawhide-0      692 ?        /usr/lib/systemd/systemd
 163 vu-rawhide-0      731 ?        /usr/lib/systemd/systemd-journald
 164 vu-rawhide-192    734 ?        /usr/lib/systemd/systemd-networkd
 165 vu-rawhide-193    738 ?        /usr/lib/systemd/systemd-resolved
 166 vu-rawhide-0      742 ?        /usr/lib/systemd/systemd-logind
 167 vu-rawhide-81     744 ?        /usr/bin/dbus-daemon --system --address=systemd: --nofork --nopidfile --systemd-activation --syslog-only
 168 vu-rawhide-0      746 ?        /usr/sbin/sshd -D ...
 169 vu-rawhide-0      752 ?        /usr/lib/systemd/systemd --user
 170 vu-rawhide-0      753 ?        (sd-pam)
 171 vu-rawhide-0     1628 ?        login -- zbyszek
 172 vu-rawhide-1000  1630 ?        /usr/lib/systemd/systemd --user
 173 vu-rawhide-1000  1631 ?        (sd-pam)
 174 vu-rawhide-1000  1637 pts/8    -zsh
 175 </programlisting>
 176   </refsect1>
 177
 178   <refsect1>
 179     <title>See Also</title>
 180     <para><simplelist type="inline">
 181       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 182       <member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 183       <member><citerefentry><refentrytitle>nss-resolve</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 184       <member><citerefentry><refentrytitle>nss-myhostname</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 185       <member><citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 186       <member><citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 187       <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 188       <member><citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 189       <member><citerefentry project='man-pages'><refentrytitle>nsswitch.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
 190       <member><citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 191     </simplelist></para>
 192   </refsect1>
 193
 194 </refentry>