1USERDBCTL(1)                       userdbctl                      USERDBCTL(1)
2
3
4

NAME

6       userdbctl - Inspect users, groups and group memberships
7

SYNOPSIS

9       userdbctl [OPTIONS...] {COMMAND} [NAME...]
10

DESCRIPTION

12       userdbctl may be used to inspect user and groups (as well as group
13       memberships) of the system. This client utility inquires user/group
14       information provided by various system services, both operating on JSON
15       user/group records (as defined by the JSON User Records[1] and JSON
16       Group Records[2] definitions), and classic UNIX NSS/glibc user and
17       group records. This tool is primarily a client to the User/Group Record
18       Lookup API via Varlink[3], and may also pick up drop-in JSON user and
19       group records from /etc/userdb/, /run/userdb/, /run/host/userdb/,
20       /usr/lib/userdb/.
21

OPTIONS

23       The following options are understood:
24
25       --output=MODE
26           Choose the output mode, takes one of "classic", "friendly",
27           "table", "json". If "classic", an output very close to the format
28           of /etc/passwd or /etc/group is generated. If "friendly" a more
29           comprehensive and user friendly, human readable output is
30           generated; if "table" a minimal, tabular output is generated; if
31           "json" a JSON formatted output is generated. Defaults to "friendly"
32           if a user/group is specified on the command line, "table"
33           otherwise.
34
35           Note that most output formats do not show all available
36           information. In particular, "classic" and "table" show only the
37           most important fields. Various modes also do not show password
38           hashes. Use "json" to view all fields, including any authentication
39           fields.
40
41       --json=FORMAT
42           Selects JSON output mode (like --output=json) and selects the
43           precise display mode. Takes one of "pretty" or "short". If
44           "pretty", human-friendly whitespace and newlines are inserted in
45           the output to make the JSON data more readable. If "short", all
46           superfluous whitespace is suppressed.
47
48       --service=SERVICE[:SERVICE...], -s SERVICE:SERVICE...
49           Controls which services to query for users/groups. Takes a list of
50           one or more service names, separated by ":". See below for a list
51           of well-known service names. If not specified all available
52           services are queried at once.
53
54       --with-nss=BOOL
55           Controls whether to include classic glibc/NSS user/group lookups in
56           the output. If --with-nss=no is used any attempts to resolve or
57           enumerate users/groups provided only via glibc NSS is suppressed.
58           If --with-nss=yes is specified such users/groups are included in
59           the output (which is the default).
60
61       --with-varlink=BOOL
62           Controls whether to include Varlink user/group lookups in the
63           output, i.e. those done via the User/Group Record Lookup API via
64           Varlink[3]. If --with-varlink=no is used any attempts to resolve or
65           enumerate users/groups provided only via Varlink are suppressed. If
66           --with-varlink=yes is specified such users/groups are included in
67           the output (which is the default).
68
69       --with-dropin=BOOL
70           Controls whether to include user/group lookups in the output that
71           are defined using drop-in files in /etc/userdb/, /run/userdb/,
72           /run/host/userdb/, /usr/lib/userdb/. If --with-dropin=no is used
73           these records are suppressed. If --with-dropin=yes is specified
74           such users/groups are included in the output (which is the
75           default).
76
77       --synthesize=BOOL
78           Controls whether to synthesize records for the root and nobody
79           users/groups if they aren't defined otherwise. By default (or
80           "yes") such records are implicitly synthesized if otherwise missing
81           since they have special significance to the OS. When "no" this
82           synthesizing is turned off.
83
84       -N
85           This option is short for --with-nss=no --synthesize=no. Use this
86           option to show only records that are natively defined as JSON user
87           or group records, with all NSS/glibc compatibility and all implicit
88           synthesis turned off.
89
90       --multiplexer=BOOL
91           Controls whether to do lookups via the multiplexer service (if
92           specified as true, the default) or do lookups in the client (if
93           specified as false). Using the multiplexer service is typically
94           preferable, since it runs in a locked down sandbox.
95
96       --chain
97           When used with the ssh-authorized-keys command, this will allow
98           passing an additional command line after the user name that is
99           chain executed after the lookup completed. This allows chaining
100           multiple tools that show SSH authorized keys.
101
102       --no-pager
103           Do not pipe output into a pager.
104
105       --no-legend
106           Do not print the legend, i.e. column headers and the footer with
107           hints.
108
109       -h, --help
110           Print a short help text and exit.
111
112       --version
113           Print a short version string and exit.
114

COMMANDS

116       The following commands are understood:
117
118       user [USER...]
119           List all known users records or show details of one or more
120           specified user records. Use --output= to tweak output mode.
121
122       group [GROUP...]
123           List all known group records or show details of one or more
124           specified group records. Use --output= to tweak output mode.
125
126       users-in-group [GROUP...]
127           List users that are members of the specified groups. If no groups
128           are specified list all user/group memberships defined. Use
129           --output= to tweak output mode.
130
131       groups-of-user [USER...]
132           List groups that the specified users are members of. If no users
133           are specified list all user/group memberships defined (in this case
134           groups-of-user and users-in-group are equivalent). Use --output= to
135           tweak output mode.
136
137       services
138           List all services currently providing user/group definitions to the
139           system. See below for a list of well-known services providing user
140           information.
141
142       ssh-authorized-keys
143           Show SSH authorized keys for this account. This command is intended
144           to be used to allow the SSH daemon to pick up authorized keys from
145           user records, see below.
146

WELL-KNOWN SERVICES

148       The userdbctl services command will list all currently running services
149       that provide user or group definitions to the system. The following
150       well-known services are shown among this list:
151
152       io.systemd.DynamicUser
153           This service is provided by the system service manager itself (i.e.
154           PID 1) and makes all users (and their groups) synthesized through
155           the DynamicUser= setting in service unit files available to the
156           system (see systemd.exec(5) for details about this setting).
157
158       io.systemd.Home
159           This service is provided by systemd-homed.service(8) and makes all
160           users (and their groups) belonging to home directories managed by
161           that service available to the system.
162
163       io.systemd.Machine
164           This service is provided by systemd-machined.service(8) and
165           synthesizes records for all users/groups used by a container that
166           employs user namespacing.
167
168       io.systemd.Multiplexer
169           This service is provided by systemd-userdbd.service(8) and
170           multiplexes user/group look-ups to all other running lookup
171           services. This is the primary entry point for user/group record
172           clients, as it simplifies client side implementation substantially
173           since they can ask a single service for lookups instead of asking
174           all running services in parallel.  userdbctl uses this service
175           preferably, too, unless --with-nss= or --service= are used, in
176           which case finer control over the services to talk to is required.
177
178       io.systemd.NameServiceSwitch
179           This service is (also) provided by systemd-userdbd.service(8) and
180           converts classic NSS/glibc user and group records to JSON
181           user/group records, providing full backwards compatibility. Use
182           --with-nss=no to disable this compatibility, see above. Note that
183           compatibility is actually provided in both directions: nss-
184           systemd(8) will automatically synthesize classic NSS/glibc
185           user/group records from all JSON user/group records provided to the
186           system, thus using both APIs is mostly equivalent and provides
187           access to the same data, however the NSS/glibc APIs necessarily
188           expose a more reduced set of fields only.
189
190       io.systemd.DropIn
191           This service is (also) provided by systemd-userdbd.service(8) and
192           picks up JSON user/group records from /etc/userdb/, /run/userdb/,
193           /run/host/userdb/, /usr/lib/userdb/.
194
195       Note that userdbctl has internal support for NSS-based lookups too.
196       This means that if neither io.systemd.Multiplexer nor
197       io.systemd.NameServiceSwitch are running look-ups into the basic
198       user/group databases will still work.
199

INTEGRATION WITH SSH

201       The userdbctl tool may be used to make the list of SSH authorized keys
202       possibly contained in a user record available to the SSH daemon for
203       authentication. For that configure the following in sshd_config(5):
204
205           ...
206           AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
207           AuthorizedKeysCommandUser root
208           ...
209
210       Sometimes it's useful to allow chain invocation of another program to
211       list SSH authorized keys. By using the --chain such a tool may be chain
212       executed by userdbctl ssh-authorized-keys once a lookup completes
213       (regardless if an SSH key was found or not). Example:
214
215           ...
216           AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u
217           AuthorizedKeysCommandUser root
218           ...
219
220       The above will first query the userdb database for SSH keys, and then
221       chain execute /usr/bin/othertool to also be queried.
222

EXIT STATUS

224       On success, 0 is returned, a non-zero failure code otherwise.
225

ENVIRONMENT

227       $SYSTEMD_LOG_LEVEL
228           The maximum log level of emitted messages (messages with a higher
229           log level, i.e. less important ones, will be suppressed). Either
230           one of (in order of decreasing importance) emerg, alert, crit, err,
231           warning, notice, info, debug, or an integer in the range 0...7. See
232           syslog(3) for more information.
233
234       $SYSTEMD_LOG_COLOR
235           A boolean. If true, messages written to the tty will be colored
236           according to priority.
237
238           This setting is only useful when messages are written directly to
239           the terminal, because journalctl(1) and other tools that display
240           logs will color messages based on the log level on their own.
241
242       $SYSTEMD_LOG_TIME
243           A boolean. If true, console log messages will be prefixed with a
244           timestamp.
245
246           This setting is only useful when messages are written directly to
247           the terminal or a file, because journalctl(1) and other tools that
248           display logs will attach timestamps based on the entry metadata on
249           their own.
250
251       $SYSTEMD_LOG_LOCATION
252           A boolean. If true, messages will be prefixed with a filename and
253           line number in the source code where the message originates.
254
255           Note that the log location is often attached as metadata to journal
256           entries anyway. Including it directly in the message text can
257           nevertheless be convenient when debugging programs.
258
259       $SYSTEMD_LOG_TID
260           A boolean. If true, messages will be prefixed with the current
261           numerical thread ID (TID).
262
263           Note that the this information is attached as metadata to journal
264           entries anyway. Including it directly in the message text can
265           nevertheless be convenient when debugging programs.
266
267       $SYSTEMD_LOG_TARGET
268           The destination for log messages. One of console (log to the
269           attached tty), console-prefixed (log to the attached tty but with
270           prefixes encoding the log level and "facility", see syslog(3), kmsg
271           (log to the kernel circular log buffer), journal (log to the
272           journal), journal-or-kmsg (log to the journal if available, and to
273           kmsg otherwise), auto (determine the appropriate log target
274           automatically, the default), null (disable log output).
275
276       $SYSTEMD_PAGER
277           Pager to use when --no-pager is not given; overrides $PAGER. If
278           neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
279           pager implementations are tried in turn, including less(1) and
280           more(1), until one is found. If no pager implementation is
281           discovered no pager is invoked. Setting this environment variable
282           to an empty string or the value "cat" is equivalent to passing
283           --no-pager.
284
285       $SYSTEMD_LESS
286           Override the options passed to less (by default "FRSXMK").
287
288           Users might want to change two options in particular:
289
290           K
291               This option instructs the pager to exit immediately when Ctrl+C
292               is pressed. To allow less to handle Ctrl+C itself to switch
293               back to the pager command prompt, unset this option.
294
295               If the value of $SYSTEMD_LESS does not include "K", and the
296               pager that is invoked is less, Ctrl+C will be ignored by the
297               executable, and needs to be handled by the pager.
298
299           X
300               This option instructs the pager to not send termcap
301               initialization and deinitialization strings to the terminal. It
302               is set by default to allow command output to remain visible in
303               the terminal even after the pager exits. Nevertheless, this
304               prevents some pager functionality from working, in particular
305               paged output cannot be scrolled with the mouse.
306
307           See less(1) for more discussion.
308
309       $SYSTEMD_LESSCHARSET
310           Override the charset passed to less (by default "utf-8", if the
311           invoking terminal is determined to be UTF-8 compatible).
312
313       $SYSTEMD_PAGERSECURE
314           Takes a boolean argument. When true, the "secure" mode of the pager
315           is enabled; if false, disabled. If $SYSTEMD_PAGERSECURE is not set
316           at all, secure mode is enabled if the effective UID is not the same
317           as the owner of the login session, see geteuid(2) and
318           sd_pid_get_owner_uid(3). In secure mode, LESSSECURE=1 will be set
319           when invoking the pager, and the pager shall disable commands that
320           open or create new files or start new subprocesses. When
321           $SYSTEMD_PAGERSECURE is not set at all, pagers which are not known
322           to implement secure mode will not be used. (Currently only less(1)
323           implements secure mode.)
324
325           Note: when commands are invoked with elevated privileges, for
326           example under sudo(8) or pkexec(1), care must be taken to ensure
327           that unintended interactive features are not enabled. "Secure" mode
328           for the pager may be enabled automatically as describe above.
329           Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited
330           environment allows the user to invoke arbitrary commands. Note that
331           if the $SYSTEMD_PAGER or $PAGER variables are to be honoured,
332           $SYSTEMD_PAGERSECURE must be set too. It might be reasonable to
333           completely disable the pager using --no-pager instead.
334
335       $SYSTEMD_COLORS
336           Takes a boolean argument. When true, systemd and related utilities
337           will use colors in their output, otherwise the output will be
338           monochrome. Additionally, the variable can take one of the
339           following special values: "16", "256" to restrict the use of colors
340           to the base 16 or 256 ANSI colors, respectively. This can be
341           specified to override the automatic decision based on $TERM and
342           what the console is connected to.
343
344       $SYSTEMD_URLIFY
345           The value must be a boolean. Controls whether clickable links
346           should be generated in the output for terminal emulators supporting
347           this. This can be specified to override the decision that systemd
348           makes based on $TERM and other conditions.
349

SEE ALSO

351       systemd(1), systemd-userdbd.service(8), systemd-homed.service(8), nss-
352       systemd(8), getent(1)
353

NOTES

355        1. JSON User Records
356           https://systemd.io/USER_RECORD
357
358        2. JSON Group Records
359           https://systemd.io/GROUP_RECORD
360
361        3. User/Group Record Lookup API via Varlink
362           https://systemd.io/USER_GROUP_API
363
364
365
366systemd 250                                                       USERDBCTL(1)
Impressum