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 -->
6 <refentry id=
"userdbctl" conditional='ENABLE_USERDB'
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>userdbctl
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>userdbctl
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>userdbctl
</refname>
21 <refpurpose>Inspect users, groups and group memberships
</refpurpose>
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>
34 <title>Description
</title>
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>
46 <title>Options
</title>
48 <para>The following options are understood:
</para>
53 <term><option>--output=
</option><replaceable>MODE
</replaceable></term>
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>
64 <para>Note that most output formats do not show all available information. In particular,
65 <literal>classic
</literal> and
<literal>table
</literal> show only the most important fields. Various
66 modes also do not show password hashes. Use
<literal>json
</literal> to view all fields, including
67 any authentication fields.
</para>
72 <term><option>--service=
</option><replaceable>SERVICE
</replaceable><optional>:
<replaceable>SERVICE…
</replaceable></optional></term>
73 <term><option>-s
</option> <replaceable>SERVICE
</replaceable>:
<replaceable>SERVICE…
</replaceable></term>
75 <listitem><para>Controls which services to query for users/groups. Takes a list of one or more
76 service names, separated by
<literal>:
</literal>. See below for a list of well-known service
77 names. If not specified all available services are queried at once.
</para></listitem>
81 <term><option>--with-nss=
</option><replaceable>BOOL
</replaceable></term>
83 <listitem><para>Controls whether to include classic glibc/NSS user/group lookups in the output. If
84 <option>--with-nss=no
</option> is used any attempts to resolve or enumerate users/groups provided
85 only via glibc NSS is suppressed. If
<option>--with-nss=yes
</option> is specified such users/groups
86 are included in the output (which is the default).
</para></listitem>
90 <term><option>--synthesize=
</option><replaceable>BOOL
</replaceable></term>
92 <listitem><para>Controls whether to synthesize records for the root and nobody users/groups if they
93 aren't defined otherwise. By default (or
<literal>yes
</literal>) such records are implicitly
94 synthesized if otherwise missing since they have special significance to the OS. When
95 <literal>no
</literal> this synthesizing is turned off.
</para></listitem>
99 <term><option>-N
</option></term>
101 <listitem><para>This option is short for
<option>--with-nss=no
</option>
102 <option>--synthesize=no
</option>. Use this option to show only records that are natively defined as
103 JSON user or group records, with all NSS/glibc compatibility and all implicit synthesis turned
104 off.
</para></listitem>
107 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
108 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
109 <xi:include href=
"standard-options.xml" xpointer=
"help" />
110 <xi:include href=
"standard-options.xml" xpointer=
"version" />
115 <title>Commands
</title>
117 <para>The following commands are understood:
</para>
122 <term><command>user
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
124 <listitem><para>List all known users records or show details of one or more specified user
125 records. Use
<option>--output=
</option> to tweak output mode.
</para></listitem>
129 <term><command>group
</command> <optional><replaceable>GROUP
</replaceable>…
</optional></term>
131 <listitem><para>List all known group records or show details of one or more specified group
132 records. Use
<option>--output=
</option> to tweak output mode.
</para></listitem>
136 <term><command>users-in-group
</command> <optional><replaceable>GROUP
</replaceable>…
</optional></term>
138 <listitem><para>List users that are members of the specified groups. If no groups are specified list
139 all user/group memberships defined. Use
<option>--output=
</option> to tweak output
140 mode.
</para></listitem>
144 <term><command>groups-of-user
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
146 <listitem><para>List groups that the specified users are members of. If no users are specified list
147 all user/group memberships defined (in this case
<command>groups-of-user
</command> and
148 <command>users-in-group
</command> are equivalent). Use
<option>--output=
</option> to tweak output
149 mode.
</para></listitem>
153 <term><command>services
</command></term>
155 <listitem><para>List all services currently providing user/group definitions to the system. See below
156 for a list of well-known services providing user information.
</para></listitem>
160 <term><command>ssh-authorized-keys
</command></term>
162 <listitem><para>This operation is not a public, user-facing interface. It is used to allow the SSH daemon to pick
163 up authorized keys from user records, see below.
</para></listitem>
169 <title>Well-Known Services
</title>
171 <para>The
<command>userdbctl services
</command> command will list all currently running services that
172 provide user or group definitions to the system. The following well-known services are shown among
177 <term><constant>io.systemd.DynamicUser
</constant></term>
179 <listitem><para>This service is provided by the system service manager itself (i.e. PID
1) and
180 makes all users (and their groups) synthesized through the
<varname>DynamicUser=
</varname> setting in
181 service unit files available to the system (see
182 <citerefentry><refentrytitle>systemd.exec
</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
183 details about this setting).
</para></listitem>
187 <term><constant>io.systemd.Home
</constant></term>
189 <listitem><para>This service is provided by
190 <citerefentry><refentrytitle>systemd-homed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
191 and makes all users (and their groups) belonging to home directories managed by that service
192 available to the system.
</para></listitem>
196 <term><constant>io.systemd.Machine
</constant></term>
198 <listitem><para>This service is provided by
199 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
200 and synthesizes records for all users/groups used by a container that employs user
201 namespacing.
</para></listitem>
205 <term><constant>io.systemd.Multiplexer
</constant></term>
207 <listitem><para>This service is provided by
208 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
209 and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point
210 for user/group record clients, as it simplifies client side implementation substantially since they
211 can ask a single service for lookups instead of asking all running services in parallel.
212 <command>userdbctl
</command> uses this service preferably, too, unless
<option>--with-nss=
</option>
213 or
<option>--service=
</option> are used, in which case finer control over the services to talk to is
214 required.
</para></listitem>
218 <term><constant>io.systemd.NameSeviceSwitch
</constant></term>
220 <listitem><para>This service is (also) provided by
221 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
222 and converts classic NSS/glibc user and group records to JSON user/group records, providing full
223 backwards compatibility. Use
<option>--with-nss=no
</option> to disable this compatibility, see
224 above. Note that compatibility is actually provided in both directions:
225 <citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
226 automatically synthesize classic NSS/glibc user/group records from all JSON user/group records
227 provided to the system, thus using both APIs is mostly equivalent and provides access to the same
228 data, however the NSS/glibc APIs necessarily expose a more reduced set of fields
229 only.
</para></listitem>
233 <para>Note that
<command>userdbctl
</command> has internal support for NSS-based lookups too. This means
234 that if neither
<constant>io.systemd.Multiplexer
</constant> nor
235 <constant>io.systemd.NameSeviceSwitch
</constant> are running look-ups into the basic user/group
236 databases will still work.
</para>
240 <title>Integration with SSH
</title>
242 <para>The
<command>userdbctl
</command> tool may be used to make the list of SSH authorized keys possibly
243 contained in a user record available to the SSH daemon for authentication. For that configure the
244 following in
<citerefentry
245 project='die-net'
><refentrytitle>sshd_config
</refentrytitle><manvolnum>5</manvolnum></citerefentry>:
</para>
248 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
249 AuthorizedKeysCommandUser root
254 <title>Exit status
</title>
256 <para>On success,
0 is returned, a non-zero failure code otherwise.
</para>
259 <xi:include href=
"less-variables.xml" />
262 <title>See Also
</title>
264 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
265 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
266 <citerefentry><refentrytitle>systemd-homed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
267 <citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
268 <citerefentry project='man-pages'
><refentrytitle>getent
</refentrytitle><manvolnum>1</manvolnum></citerefentry>