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