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+ -->
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></listitem>
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>
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>
75 <term><option>--with-nss=
</option><replaceable>BOOL
</replaceable></term>
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>
84 <term><option>--synthesize=
</option><replaceable>BOOL
</replaceable></term>
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>
93 <term><option>-N
</option></term>
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>
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" />
109 <title>Commands
</title>
111 <para>The following commands are understood:
</para>
116 <term><command>user
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
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>
123 <term><command>group
</command> <optional><replaceable>GROUP
</replaceable>…
</optional></term>
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>
130 <term><command>users-in-group
</command> <optional><replaceable>GROUP
</replaceable>…
</optional></term>
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>
138 <term><command>groups-of-user
</command> <optional><replaceable>USER
</replaceable>…
</optional></term>
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>
147 <term><command>services
</command></term>
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>
154 <term><command>ssh-authorized-keys
</command></term>
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>
163 <title>Well-Known Services
</title>
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
171 <term><constant>io.systemd.DynamicUser
</constant></term>
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>
181 <term><constant>io.systemd.Home
</constant></term>
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>
190 <term><constant>io.systemd.Multiplexer
</constant></term>
192 <listitem><para>This service is provided by
193 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
194 and multiplexes user/group look-ups to all other running lookup services. This is the primary entry point
195 for user/group record clients, as it simplifies client side implementation substantially since they
196 can ask a single service for lookups instead of asking all running services in parallel.
197 <command>userdbctl
</command> uses this service preferably, too, unless
<option>--with-nss=
</option>
198 or
<option>--service=
</option> are used, in which case finer control over the services to talk to is
199 required.
</para></listitem>
203 <term><constant>io.systemd.NameSeviceSwitch
</constant></term>
205 <listitem><para>This service is (also) provided by
206 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>
207 and converts classic NSS/glibc user and group records to JSON user/group records, providing full
208 backwards compatibility. Use
<option>--with-nss=no
</option> to disable this compatibility, see
209 above. Note that compatibility is actually provided in both directions:
210 <citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry> will
211 automatically synthesize classic NSS/glibc user/group records from all JSON user/group records
212 provided to the system, thus using both APIs is mostly equivalent and provides access to the same
213 data, however the NSS/glibc APIs necessarily expose a more reduced set of fields
214 only.
</para></listitem>
218 <para>Note that
<command>userdbctl
</command> has internal support for NSS-based lookups too. This means
219 that if neither
<constant>io.systemd.Multiplexer
</constant> nor
220 <constant>io.systemd.NameSeviceSwitch
</constant> are running look-ups into the basic user/group
221 databases will still work.
</para>
225 <title>Integration with SSH
</title>
227 <para>The
<command>userdbctl
</command> tool may be used to make the list of SSH authorized keys possibly
228 contained in a user record available to the SSH daemon for authentication. For that configure the
229 following in
<citerefentry
230 project='die-net'
><refentrytitle>sshd_config
</refentrytitle><manvolnum>5</manvolnum></citerefentry>:
</para>
233 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
234 AuthorizedKeysCommandUser root
239 <title>Exit status
</title>
241 <para>On success,
0 is returned, a non-zero failure code otherwise.
</para>
244 <xi:include href=
"less-variables.xml" />
247 <title>See Also
</title>
249 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
250 <citerefentry><refentrytitle>systemd-userdbd.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
251 <citerefentry><refentrytitle>systemd-homed.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
252 <citerefentry><refentrytitle>nss-systemd
</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
253 <citerefentry project='man-pages'
><refentrytitle>getent
</refentrytitle><manvolnum>1</manvolnum></citerefentry>