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.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   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 Records</ulink> and <ulink
  40     url="https://systemd.io/GROUP_RECORD">JSON Group Records</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>, and may also
  43     pick up drop-in JSON user and group records from <filename>/etc/userdb/</filename>,
  44     <filename>/run/userdb/</filename>, <filename>/run/host/userdb/</filename>,
  45     <filename>/usr/lib/userdb/</filename>.</para>
  46   </refsect1>
  47
  48   <refsect1>
  49     <title>Options</title>
  50
  51     <para>The following options are understood:</para>
  52
  53     <variablelist>
  54
  55       <varlistentry>
  56         <term><option>--output=<replaceable>MODE</replaceable></option></term>
  57
  58         <listitem><para>Choose the output mode, takes one of <literal>classic</literal>,
  59         <literal>friendly</literal>, <literal>table</literal>, <literal>json</literal>. If
  60         <literal>classic</literal>, an output very close to the format of <filename>/etc/passwd</filename> or
  61         <filename>/etc/group</filename> is generated. If <literal>friendly</literal> a more comprehensive and
  62         user friendly, human readable output is generated; if <literal>table</literal> a minimal, tabular
  63         output is generated; if <literal>json</literal> a JSON formatted output is generated. Defaults to
  64         <literal>friendly</literal> if a user/group is specified on the command line,
  65         <literal>table</literal> otherwise.</para>
  66
  67         <para>Note that most output formats do not show all available information. In particular,
  68         <literal>classic</literal> and <literal>table</literal> show only the most important fields. Various
  69         modes also do not show password hashes. Use <literal>json</literal> to view all fields, including
  70         any authentication fields.</para>
  71
  72         <xi:include href="version-info.xml" xpointer="v245"/>
  73         </listitem>
  74       </varlistentry>
  75
  76       <varlistentry>
  77         <term><option>--json=<replaceable>FORMAT</replaceable></option></term>
  78
  79         <listitem><para>Selects JSON output mode (like <option>--output=json</option>) and selects the
  80         precise display mode. Takes one of <literal>pretty</literal> or <literal>short</literal>. If
  81         <literal>pretty</literal>, human-friendly whitespace and newlines are inserted in the output to make
  82         the JSON data more readable. If <literal>short</literal>, all superfluous whitespace is
  83         suppressed.</para>
  84
  85         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><option>--service=<replaceable>SERVICE</replaceable><optional>:<replaceable>SERVICE…</replaceable></optional></option></term>
  90         <term><option>-s</option> <replaceable>SERVICE</replaceable>:<replaceable>SERVICE…</replaceable></term>
  91
  92         <listitem><para>Controls which services to query for users/groups. Takes a list of one or more
  93         service names, separated by <literal>:</literal>. See below for a list of well-known service
  94         names. If not specified all available services are queried at once.</para>
  95
  96         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><option>--with-nss=<replaceable>BOOL</replaceable></option></term>
 101
 102         <listitem><para>Controls whether to include classic glibc/NSS user/group lookups in the output. If
 103         <option>--with-nss=no</option> is used any attempts to resolve or enumerate users/groups provided
 104         only via glibc NSS is suppressed. If <option>--with-nss=yes</option> is specified such users/groups
 105         are included in the output (which is the default).</para>
 106
 107         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 108       </varlistentry>
 109
 110       <varlistentry>
 111         <term><option>--with-varlink=<replaceable>BOOL</replaceable></option></term>
 112
 113         <listitem><para>Controls whether to include Varlink user/group lookups in the output, i.e. those done
 114         via the <ulink url="https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via
 115         Varlink</ulink>. If <option>--with-varlink=no</option> is used any attempts to resolve or enumerate
 116         users/groups provided only via Varlink are suppressed. If <option>--with-varlink=yes</option> is
 117         specified such users/groups are included in the output (which is the default).</para>
 118
 119         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><option>--with-dropin=<replaceable>BOOL</replaceable></option></term>
 124
 125         <listitem><para>Controls whether to include user/group lookups in the output that are defined using
 126         drop-in files in <filename>/etc/userdb/</filename>, <filename>/run/userdb/</filename>,
 127         <filename>/run/host/userdb/</filename>, <filename>/usr/lib/userdb/</filename>. If
 128         <option>--with-dropin=no</option> is used these records are suppressed. If
 129         <option>--with-dropin=yes</option> is specified such users/groups are included in the output (which
 130         is the default).</para>
 131
 132         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><option>--synthesize=<replaceable>BOOL</replaceable></option></term>
 137
 138         <listitem><para>Controls whether to synthesize records for the root and nobody users/groups if they
 139         aren't defined otherwise. By default (or <literal>yes</literal>) such records are implicitly
 140         synthesized if otherwise missing since they have special significance to the OS. When
 141         <literal>no</literal> this synthesizing is turned off.</para>
 142
 143         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>-N</option></term>
 148
 149         <listitem><para>This option is short for <option>--with-nss=no</option>
 150         <option>--synthesize=no</option>. Use this option to show only records that are natively defined as
 151         JSON user or group records, with all NSS/glibc compatibility and all implicit synthesis turned
 152         off.</para>
 153
 154         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 155       </varlistentry>
 156
 157       <varlistentry>
 158         <term><option>--multiplexer=<replaceable>BOOL</replaceable></option></term>
 159
 160         <listitem><para>Controls whether to do lookups via the multiplexer service (if specified as true, the
 161         default) or do lookups in the client (if specified as false). Using the multiplexer service is
 162         typically preferable, since it runs in a locked down sandbox.</para>
 163
 164         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><option>--chain</option></term>
 169
 170         <listitem><para>When used with the <command>ssh-authorized-keys</command> command, this will allow
 171         passing an additional command line after the user name that is chain executed after the lookup
 172         completed. This allows chaining multiple tools that show SSH authorized keys.</para>
 173
 174         <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 175       </varlistentry>
 176
 177       <xi:include href="standard-options.xml" xpointer="no-pager" />
 178       <xi:include href="standard-options.xml" xpointer="no-legend" />
 179       <xi:include href="standard-options.xml" xpointer="help" />
 180       <xi:include href="standard-options.xml" xpointer="version" />
 181     </variablelist>
 182   </refsect1>
 183
 184   <refsect1>
 185     <title>Commands</title>
 186
 187     <para>The following commands are understood:</para>
 188
 189     <variablelist>
 190
 191       <varlistentry>
 192         <term><command>user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 193
 194         <listitem><para>List all known users records or show details of one or more specified user
 195         records. Use <option>--output=</option> to tweak output mode.</para>
 196
 197         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><command>group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 202
 203         <listitem><para>List all known group records or show details of one or more specified group
 204         records. Use <option>--output=</option> to tweak output mode.</para>
 205
 206         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 207       </varlistentry>
 208
 209       <varlistentry>
 210         <term><command>users-in-group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 211
 212         <listitem><para>List users that are members of the specified groups. If no groups are specified list
 213         all user/group memberships defined. Use <option>--output=</option> to tweak output
 214         mode.</para>
 215
 216         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><command>groups-of-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 221
 222         <listitem><para>List groups that the specified users are members of. If no users are specified list
 223         all user/group memberships defined (in this case <command>groups-of-user</command> and
 224         <command>users-in-group</command> are equivalent). Use <option>--output=</option> to tweak output
 225         mode.</para>
 226
 227         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><command>services</command></term>
 232
 233         <listitem><para>List all services currently providing user/group definitions to the system. See below
 234         for a list of well-known services providing user information.</para>
 235
 236         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 237       </varlistentry>
 238
 239       <varlistentry>
 240         <term><command>ssh-authorized-keys</command></term>
 241
 242         <listitem><para>Show SSH authorized keys for this account. This command is intended to be used to
 243         allow the SSH daemon to pick up authorized keys from user records, see below.</para>
 244
 245         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 246       </varlistentry>
 247     </variablelist>
 248   </refsect1>
 249
 250   <refsect1>
 251     <title>Well-Known Services</title>
 252
 253     <para>The <command>userdbctl services</command> command will list all currently running services that
 254     provide user or group definitions to the system. The following well-known services are shown among
 255     this list:</para>
 256
 257     <variablelist>
 258       <varlistentry>
 259         <term><constant>io.systemd.DynamicUser</constant></term>
 260
 261         <listitem><para>This service is provided by the system service manager itself (i.e. PID 1) and
 262         makes all users (and their groups) synthesized through the <varname>DynamicUser=</varname> setting in
 263         service unit files available to the system (see
 264         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 265         details about this setting).</para>
 266
 267         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 268       </varlistentry>
 269
 270       <varlistentry>
 271         <term><constant>io.systemd.Home</constant></term>
 272
 273         <listitem><para>This service is provided by
 274         <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 275         and makes all users (and their groups) belonging to home directories managed by that service
 276         available to the system.</para>
 277
 278         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 279       </varlistentry>
 280
 281       <varlistentry>
 282         <term><constant>io.systemd.Machine</constant></term>
 283
 284         <listitem><para>This service is provided by
 285         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 286         and synthesizes records for all users/groups used by a container that employs user
 287         namespacing.</para>
 288
 289         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 290       </varlistentry>
 291
 292       <varlistentry>
 293         <term><constant>io.systemd.Multiplexer</constant></term>
 294
 295         <listitem><para>This service is provided by
 296         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 297         and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point
 298         for user/group record clients, as it simplifies client side implementation substantially since they
 299         can ask a single service for lookups instead of asking all running services in parallel.
 300         <command>userdbctl</command> uses this service preferably, too, unless <option>--with-nss=</option>
 301         or <option>--service=</option> are used, in which case finer control over the services to talk to is
 302         required.</para>
 303
 304         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 305       </varlistentry>
 306
 307       <varlistentry>
 308         <term><constant>io.systemd.NameServiceSwitch</constant></term>
 309
 310         <listitem><para>This service is (also) provided by
 311         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 312         and converts classic NSS/glibc user and group records to JSON user/group records, providing full
 313         backwards compatibility. Use <option>--with-nss=no</option> to disable this compatibility, see
 314         above. Note that compatibility is actually provided in both directions:
 315         <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
 316         automatically synthesize classic NSS/glibc user/group records from all JSON user/group records
 317         provided to the system, thus using both APIs is mostly equivalent and provides access to the same
 318         data, however the NSS/glibc APIs necessarily expose a more reduced set of fields
 319         only.</para>
 320
 321         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 322       </varlistentry>
 323
 324       <varlistentry>
 325         <term><constant>io.systemd.DropIn</constant></term>
 326
 327         <listitem><para>This service is (also) provided by
 328         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 329         and picks up JSON user/group records from <filename>/etc/userdb/</filename>,
 330         <filename>/run/userdb/</filename>, <filename>/run/host/userdb/</filename>,
 331         <filename>/usr/lib/userdb/</filename>.</para>
 332
 333         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 334       </varlistentry>
 335
 336     </variablelist>
 337
 338     <para>Note that <command>userdbctl</command> has internal support for NSS-based lookups too. This means
 339     that if neither <constant>io.systemd.Multiplexer</constant> nor
 340     <constant>io.systemd.NameServiceSwitch</constant> are running look-ups into the basic user/group
 341     databases will still work.</para>
 342   </refsect1>
 343
 344   <refsect1>
 345     <title>Integration with SSH</title>
 346
 347     <para>The <command>userdbctl</command> tool may be used to make the list of SSH authorized keys possibly
 348     contained in a user record available to the SSH daemon for authentication. For that configure the
 349     following in <citerefentry
 350     project='die-net'><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>:</para>
 351
 352     <programlisting>…
 353 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
 354 AuthorizedKeysCommandUser root
 355 …</programlisting>
 356
 357     <para>Sometimes it's useful to allow chain invocation of another program to list SSH authorized keys. By
 358     using the <option>--chain</option> such a tool may be chain executed by <command>userdbctl
 359     ssh-authorized-keys</command> once a lookup completes (regardless if an SSH key was found or
 360     not). Example:</para>
 361
 362     <programlisting>…
 363 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u
 364 AuthorizedKeysCommandUser root
 365 …</programlisting>
 366
 367     <para>The above will first query the userdb database for SSH keys, and then chain execute
 368     <command>/usr/bin/othertool</command> to also be queried.</para>
 369   </refsect1>
 370
 371   <refsect1>
 372     <title>Exit status</title>
 373
 374     <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
 375   </refsect1>
 376
 377   <xi:include href="common-variables.xml" />
 378
 379   <refsect1>
 380     <title>See Also</title>
 381     <para><simplelist type="inline">
 382       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 383       <member><citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 384       <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 385       <member><citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 386       <member><citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 387     </simplelist></para>
 388   </refsect1>
 389
 390 </refentry>