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>Chooses the output mode. Takes one of <literal>classic</literal>,
  59         <literal>friendly</literal>, <literal>table</literal> or <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         are not defined otherwise, as well as the user/groups for the "foreign" UID range. By default (or with
 140         <literal>yes</literal>), such records are implicitly synthesized if otherwise missing since they have
 141         special significance to the OS. When <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       <varlistentry>
 178         <term><option>--fuzzy</option></term>
 179         <term><option>-z</option></term>
 180
 181         <listitem><para>When used with the <command>user</command> or <command>group</command> command, do a
 182         fuzzy string search. Any specified arguments will be matched against the user name, the real name of
 183         the user record, the email address, and other descriptive strings of the user or group
 184         record. Moreover, instead of precise matching, a substring match or a match allowing slight
 185         deviations in spelling is applied.</para>
 186
 187         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><option>--disposition=</option></term>
 192
 193         <listitem><para>When used with the <command>user</command> or <command>group</command> command,
 194         filters by disposition of the record. Takes one of <literal>intrinsic</literal>,
 195         <literal>system</literal>, <literal>regular</literal>, <literal>dynamic</literal>,
 196         <literal>container</literal>. May be used multiple times, in which case only users matching any of
 197         the specified dispositions are shown.</para>
 198
 199         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 200       </varlistentry>
 201
 202       <varlistentry>
 203         <term><option>-I</option></term>
 204         <term><option>-S</option></term>
 205         <term><option>-R</option></term>
 206
 207         <listitem><para>Shortcuts for <option>--disposition=intrinsic</option>,
 208         <option>--disposition=system</option>, <option>--disposition=regular</option>,
 209         respectively.</para>
 210
 211         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>--uid-min=</option></term>
 216         <term><option>--uid-max=</option></term>
 217
 218         <listitem><para>When used with the <command>user</command> or <command>group</command> command,
 219         filters the output by UID/GID ranges. Takes numeric minimum or maximum UID/GID values, respectively. Shows only
 220         records within the specified range. When applied to the <command>user</command> command, it matches
 221         against UIDs. When applied to the <command>group</command> command, matches against GIDs (despite the name of
 222         the switch). If unspecified, defaults to 0 (for the minimum) and 4294967294 (for the maximum), i.e. by
 223         default, no filtering is applied, as the whole UID/GID range is covered.</para>
 224
 225         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 226       </varlistentry>
 227
 228       <varlistentry>
 229         <term><option>--boundaries=</option></term>
 230
 231         <listitem><para>When used with the <command>user</command> or <command>group</command> command,
 232         controls whether to show relevant UID/GID range boundary information in the tabular output. Takes a
 233         boolean. Defaults to true.</para>
 234
 235         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 236       </varlistentry>
 237
 238       <varlistentry>
 239         <term><option>-B</option></term>
 240
 241         <listitem><para>Shortcut for <option>--boundaries=no</option>.</para>
 242
 243         <xi:include href="version-info.xml" xpointer="v257"/></listitem>
 244       </varlistentry>
 245
 246       <xi:include href="standard-options.xml" xpointer="no-pager" />
 247       <xi:include href="standard-options.xml" xpointer="no-legend" />
 248       <xi:include href="standard-options.xml" xpointer="help" />
 249       <xi:include href="standard-options.xml" xpointer="version" />
 250     </variablelist>
 251   </refsect1>
 252
 253   <refsect1>
 254     <title>Commands</title>
 255
 256     <para>The following commands are understood:</para>
 257
 258     <variablelist>
 259
 260       <varlistentry>
 261         <term><command>user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 262
 263         <listitem><para>List all known users records or show details of one or more specified user
 264         records. Use <option>--output=</option> to tweak output mode.</para>
 265
 266         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 267       </varlistentry>
 268
 269       <varlistentry>
 270         <term><command>group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 271
 272         <listitem><para>List all known group records or show details of one or more specified group
 273         records. Use <option>--output=</option> to tweak the output mode.</para>
 274
 275         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 276       </varlistentry>
 277
 278       <varlistentry>
 279         <term><command>users-in-group</command> <optional><replaceable>GROUP</replaceable>…</optional></term>
 280
 281         <listitem><para>List users that are members of the specified groups. If no groups are specified, list
 282         all user/group memberships defined. Use <option>--output=</option> to tweak the output
 283         mode.</para>
 284
 285         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><command>groups-of-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
 290
 291         <listitem><para>Lists groups that the specified users are members of. If no users are specified, lists
 292         all user/group memberships defined (in this case, <command>groups-of-user</command> and
 293         <command>users-in-group</command> are equivalent). Use <option>--output=</option> to tweak the output
 294         mode.</para>
 295
 296         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><command>services</command></term>
 301
 302         <listitem><para>List all services currently providing user/group definitions to the system. See below
 303         for a list of well-known services providing user information.</para>
 304
 305         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 306       </varlistentry>
 307
 308       <varlistentry>
 309         <term><command>ssh-authorized-keys</command></term>
 310
 311         <listitem><para>Show SSH authorized keys for this account. This command is intended to be used to
 312         allow the SSH daemon to pick up authorized keys from user records, see below.</para>
 313
 314         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 315       </varlistentry>
 316     </variablelist>
 317   </refsect1>
 318
 319   <refsect1>
 320     <title>Well-Known Services</title>
 321
 322     <para>The <command>userdbctl services</command> command will list all currently running services that
 323     provide user or group definitions to the system. The following well-known services are shown among
 324     this list:</para>
 325
 326     <variablelist>
 327       <varlistentry>
 328         <term><constant>io.systemd.DynamicUser</constant></term>
 329
 330         <listitem><para>This service is provided by the system service manager itself (i.e. PID 1) and
 331         makes all users (and their groups) synthesized through the <varname>DynamicUser=</varname> setting in
 332         service unit files available to the system (see
 333         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 334         details about this setting).</para>
 335
 336         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 337       </varlistentry>
 338
 339       <varlistentry>
 340         <term><constant>io.systemd.Home</constant></term>
 341
 342         <listitem><para>This service is provided by
 343         <citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 344         and makes all users (and their groups) belonging to home directories managed by that service
 345         available to the system.</para>
 346
 347         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 348       </varlistentry>
 349
 350       <varlistentry>
 351         <term><constant>io.systemd.Machine</constant></term>
 352
 353         <listitem><para>This service is provided by
 354         <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 355         and synthesizes records for all users/groups used by a container that employs user
 356         namespacing.</para>
 357
 358         <xi:include href="version-info.xml" xpointer="v246"/></listitem>
 359       </varlistentry>
 360
 361       <varlistentry>
 362         <term><constant>io.systemd.Multiplexer</constant></term>
 363
 364         <listitem><para>This service is provided by
 365         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 366         and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point
 367         for user/group record clients, as it simplifies client side implementation substantially, since they
 368         can ask a single service for lookups instead of asking all running services in parallel.
 369         <command>userdbctl</command> uses this service preferably, too, unless <option>--with-nss=</option>
 370         or <option>--service=</option> are used, in which case finer control over the services to talk to is
 371         required.</para>
 372
 373         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 374       </varlistentry>
 375
 376       <varlistentry>
 377         <term><constant>io.systemd.NameServiceSwitch</constant></term>
 378
 379         <listitem><para>This service is (also) provided by
 380         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 381         and converts classic NSS/glibc user and group records to JSON user/group records, providing full
 382         backwards compatibility. Use <option>--with-nss=no</option> to disable this compatibility, see
 383         above. Note that compatibility is actually provided in both directions:
 384         <citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
 385         automatically synthesize classic NSS/glibc user/group records from all JSON user/group records
 386         provided to the system, thus using both APIs is mostly equivalent and provides access to the same
 387         data, however the NSS/glibc APIs necessarily expose a more reduced set of fields
 388         only.</para>
 389
 390         <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 391       </varlistentry>
 392
 393       <varlistentry>
 394         <term><constant>io.systemd.DropIn</constant></term>
 395
 396         <listitem><para>This service is (also) provided by
 397         <citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 398         and picks up JSON user/group records from <filename>/etc/userdb/</filename>,
 399         <filename>/run/userdb/</filename>, <filename>/run/host/userdb/</filename>,
 400         <filename>/usr/lib/userdb/</filename>.</para>
 401
 402         <xi:include href="version-info.xml" xpointer="v249"/></listitem>
 403       </varlistentry>
 404
 405     </variablelist>
 406
 407     <para>Note that <command>userdbctl</command> has internal support for NSS-based lookups too. This means
 408     that if neither <constant>io.systemd.Multiplexer</constant> nor
 409     <constant>io.systemd.NameServiceSwitch</constant> are running, look-ups into the basic user/group
 410     databases will still work.</para>
 411   </refsect1>
 412
 413   <refsect1>
 414     <title>Integration with SSH</title>
 415
 416     <para>The <command>userdbctl</command> tool may be used to make the list of SSH authorized keys possibly
 417     contained in a user record available to the SSH daemon for authentication. For that, configure the
 418     following in <citerefentry
 419     project='man-pages'><refentrytitle>sshd_config</refentrytitle><manvolnum>5</manvolnum></citerefentry>:</para>
 420
 421     <programlisting>…
 422 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
 423 AuthorizedKeysCommandUser root
 424 …</programlisting>
 425
 426     <para>Sometimes, it is useful to allow chain invocation of another program to list SSH authorized keys. By
 427     using the <option>--chain</option> option, such a tool may be chain executed by <command>userdbctl
 428     ssh-authorized-keys</command> once a lookup completes, regardless of whether an SSH key was found or
 429     not. Example:</para>
 430
 431     <programlisting>…
 432 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u
 433 AuthorizedKeysCommandUser root
 434 …</programlisting>
 435
 436     <para>The above will first query the userdb database for SSH keys, and then chain execute
 437     <command>/usr/bin/othertool</command> to also be queried.</para>
 438   </refsect1>
 439
 440   <refsect1>
 441     <title>Exit status</title>
 442
 443     <para>On success, 0 is returned, and a non-zero failure code otherwise.</para>
 444   </refsect1>
 445
 446   <xi:include href="common-variables.xml" />
 447
 448   <refsect1>
 449     <title>See Also</title>
 450     <para><simplelist type="inline">
 451       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 452       <member><citerefentry><refentrytitle>systemd-userdbd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 453       <member><citerefentry><refentrytitle>systemd-homed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 454       <member><citerefentry><refentrytitle>nss-systemd</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 455       <member><citerefentry project='man-pages'><refentrytitle>getent</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 456     </simplelist></para>
 457   </refsect1>
 458
 459 </refentry>