man/userdbctl.xml

   1 <?xml version='1.0'?>
   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+ -->
   5
   6 <refentry id="userdbctl" conditional='ENABLE_USERDB'
   7     xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>userdbctl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>userdbctl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>userdbctl</refname>
  21     <refpurpose>Inspect users, groups and group memberships</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>userdbctl</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="req">COMMAND</arg>
  29       <arg choice="opt" rep="repeat">NAME</arg>
  30     </cmdsynopsis>
  31   </refsynopsisdiv>
  32
  33   <refsect1>
  34     <title>Description</title>
  35
  36     <para><command>userdbctl</command> may be used to inspect user and groups (as well as group memberships)
  37     of the system. This client utility inquires user/group information provided by various system services,
  38     both operating on JSON user/group records (as defined by the <ulink
  39     url="https://systemd.io/USER_RECORD">JSON User Record</ulink> and <ulink
  40     url="https://systemd.io/GROUP_RECORD">JSON Group Record</ulink> definitions), and classic UNIX NSS/glibc
  41     user and group records. This tool is primarily a client to the <ulink
  42     url="https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via Varlink</ulink>.</para>
  43   </refsect1>
  44
  45   <refsect1>
  46     <title>Options</title>
  47
  48     <para>The following options are understood:</para>
  49
  50     <variablelist>
  51
  52       <varlistentry>
  53         <term><option>--output=</option><replaceable>MODE</replaceable></term>
  54
  55         <listitem><para>Choose the output mode, takes one of <literal>classic</literal>,
  56         <literal>friendly</literal>, <literal>table</literal>, <literal>json</literal>. If
  57         <literal>classic</literal>, an output very close to the format of <filename>/etc/passwd</filename> or
  58         <filename>/etc/group</filename> is generated. If <literal>friendly</literal> a more comprehensive and
  59         user friendly, human readable output is generated; if <literal>table</literal> a minimal, tabular
  60         output is generated; if <literal>json</literal> a JSON formatted output is generated. Defaults to
  61         <literal>friendly</literal> if a user/group is specified on the command line,
  62         <literal>table</literal> otherwise.</para></listitem>
  63       </varlistentry>
  64
  65       <varlistentry>
  66         <term><option>--service=</option><replaceable>SERVICE</replaceable><optional>:<replaceable>SERVICE…</replaceable></optional></term>
  67         <term><option>-s</option> <replaceable>SERVICE</replaceable>:<replaceable>SERVICE…</replaceable></term>
  68
  69         <listitem><para>Controls which services to query for users/groups. Takes a list of one or more
  70         service names, separated by <literal>:</literal>. See below for a list of well-known service
  71         names. If not specified all available services are queried at once.</para></listitem>
  72       </varlistentry>
  73
  74       <varlistentry>
  75         <term><option>--with-nss=</option><replaceable>BOOL</replaceable></term>
  76
  77         <listitem><para>Controls whether to include classic glibc/NSS user/group lookups in the output. If
  78         <option>--with-nss=no</option> is used any attempts to resolve or enumerate users/groups provided
  79         only via glibc NSS is suppressed. If <option>--with-nss=yes</option> is specified such users/groups
  80         are included in the output (which is the default).</para></listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term><option>--synthesize=</option><replaceable>BOOL</replaceable></term>
  85
  86         <listitem><para>Controls whether to synthesize records for the root and nobody users/groups if they
  87         aren't defined otherwise. By default (or <literal>yes</literal>) such records are implicitly
  88         synthesized if otherwise missing since they have special significance to the OS. When
  89         <literal>no</literal> this synthesizing is turned off.</para></listitem>
  90       </varlistentry>
  91
  92       <varlistentry>
  93         <term><option>-N</option></term>
  94
  95         <listitem><para>This option is short for <option>--with-nss=no</option>
  96         <option>--synthesize=no</option>. Use this option to show only records that are natively defined as
  97         JSON user or group records, with all NSS/glibc compatibility and all implicit synthesis turned
  98         off.</para></listitem>
  99       </varlistentry>
 100
 101       <xi:include href="standard-options.xml" xpointer="no-pager" />
 102       <xi:include href="standard-options.xml" xpointer="no-legend" />
 103       <xi:include href="standard-options.xml" xpointer="help" />
 104       <xi:include href="standard-options.xml" xpointer="version" />
 105     </variablelist>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Commands</title>
 110
 111     <para>The following commands are understood:</para>
 112
 113     <variablelist>
 114
 115       <varlistentry>
 116         <term><command>user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 117
 118         <listitem><para>List all known users records or show details of one or more specified user
 119         records. Use <option>--output=</option> to tweak output mode.</para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><command>group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 124
 125         <listitem><para>List all known group records or show details of one or more specified group
 126         records. Use <option>--output=</option> to tweak output mode.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><command>users-in-group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 131
 132         <listitem><para>List users that are members of the specified groups. If no groups are specified list
 133         all user/group memberships defined. Use <option>--output=</option> to tweak output
 134         mode.</para></listitem>
 135       </varlistentry>
 136
 137       <varlistentry>
 138         <term><command>groups-of-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 139
 140         <listitem><para>List groups that the specified users are members of. If no users are specified list
 141         all user/group memberships defined (in this case <command>groups-of-user</command> and
 142         <command>users-in-group</command> are equivalent). Use <option>--output=</option> to tweak output
 143         mode.</para></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><command>services</command></term>
 148
 149         <listitem><para>List all services currently providing user/group definitions to the system. See below
 150         for a list of well-known services providing user information.</para></listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term><command>ssh-authorized-keys</command></term>
 155
 156         <listitem><para>This operation is not a public, user-facing interface. It is used to allow the SSH daemon to pick
 157         up authorized keys from user records, see below.</para></listitem>
 158       </varlistentry>
 159     </variablelist>
 160   </refsect1>
 161
 162   <refsect1>
 163     <title>Well-Known Services</title>
 164
 165     <para>The <command>userdbctl services</command> command will list all currently running services that
 166     provide user or group definitions to the system. The following well-known services are shown among
 167     this list:</para>
 168
 169     <variablelist>
 170       <varlistentry>
 171         <term><constant>io.systemd.DynamicUser</constant></term>
 172
 173         <listitem><para>This service is provided by the system service manager itself (i.e. PID 1) and
 174         makes all users (and their groups) synthesized through the <varname>DynamicUser=</varname> setting in
 175         service unit files available to the system (see
 176         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 177         details about this setting).</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><constant>io.systemd.Home</constant></term>
 182
 183         <listitem><para>This service is provided by
 184         <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 185         and makes all users (and their groups) belonging to home directories managed by that service
 186         available to the system.</para></listitem>
 187       </varlistentry>
 188
 189       <varlistentry>
 190         <term><constant>io.systemd.Machine</constant></term>
 191
 192         <listitem><para>This service is provided by
 193         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 194         and synthesizes records for all users/groups used by a container that employs user
 195         namespacing.</para></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><constant>io.systemd.Multiplexer</constant></term>
 200
 201         <listitem><para>This service is provided by
 202         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 203         and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point
 204         for user/group record clients, as it simplifies client side implementation substantially since they
 205         can ask a single service for lookups instead of asking all running services in parallel.
 206         <command>userdbctl</command> uses this service preferably, too, unless <option>--with-nss=</option>
 207         or <option>--service=</option> are used, in which case finer control over the services to talk to is
 208         required.</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term><constant>io.systemd.NameSeviceSwitch</constant></term>
 213
 214         <listitem><para>This service is (also) provided by
 215         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 216         and converts classic NSS/glibc user and group records to JSON user/group records, providing full
 217         backwards compatibility. Use <option>--with-nss=no</option> to disable this compatibility, see
 218         above. Note that compatibility is actually provided in both directions:
 219         <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
 220         automatically synthesize classic NSS/glibc user/group records from all JSON user/group records
 221         provided to the system, thus using both APIs is mostly equivalent and provides access to the same
 222         data, however the NSS/glibc APIs necessarily expose a more reduced set of fields
 223         only.</para></listitem>
 224       </varlistentry>
 225     </variablelist>
 226
 227     <para>Note that <command>userdbctl</command> has internal support for NSS-based lookups too. This means
 228     that if neither <constant>io.systemd.Multiplexer</constant> nor
 229     <constant>io.systemd.NameSeviceSwitch</constant> are running look-ups into the basic user/group
 230     databases will still work.</para>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>Integration with SSH</title>
 235
 236     <para>The <command>userdbctl</command> tool may be used to make the list of SSH authorized keys possibly
 237     contained in a user record available to the SSH daemon for authentication. For that configure the
 238     following in <citerefentry
 239     project='die-net'><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>:</para>
 240
 241     <programlisting>…
 242 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
 243 AuthorizedKeysCommandUser root
 244 …</programlisting>
 245   </refsect1>
 246
 247   <refsect1>
 248     <title>Exit status</title>
 249
 250     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 251   </refsect1>
 252
 253   <xi:include href="less-variables.xml" />
 254
 255   <refsect1>
 256     <title>See Also</title>
 257     <para>
 258       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 259       <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 260       <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 261       <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 262       <citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 263     </para>
 264   </refsect1>
 265
 266 </refentry>