1USERDBCTL(1) userdbctl USERDBCTL(1)
2
6 userdbctl - Inspect users, groups and group memberships
7
9 userdbctl [OPTIONS...] {COMMAND} [NAME...]
10
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
23 The following options are understood:
24 --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 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 --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 --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 --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 --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 --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 --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 -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 --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 --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 --no-pager
103 Do not pipe output into a pager.
104 --no-legend
106 Do not print the legend, i.e. column headers and the footer with
107 hints.
108 -h, --help
110 Print a short help text and exit.
111 --version
113 Print a short version string and exit.
114
116 The following commands are understood:
117 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 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 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 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 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 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
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 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 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 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 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 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 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 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
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 ...
206 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
207 AuthorizedKeysCommandUser root
208 ...
209 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 ...
216 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u
217 AuthorizedKeysCommandUser root
218 ...
219 The above will first query the userdb database for SSH keys, and then
221 chain execute /usr/bin/othertool to also be queried.
222
224 On success, 0 is returned, a non-zero failure code otherwise.
225
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 $SYSTEMD_LOG_COLOR
235 A boolean. If true, messages written to the tty will be colored
236 according to priority.
237 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 $SYSTEMD_LOG_TIME
243 A boolean. If true, console log messages will be prefixed with a
244 timestamp.
245 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 $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 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 $SYSTEMD_LOG_TID
260 A boolean. If true, messages will be prefixed with the current
261 numerical thread ID (TID).
262 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 $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 $SYSTEMD_LOG_RATELIMIT_KMSG
277 Whether to ratelimit kmsg or not. Takes a boolean. Defaults to
278 "true". If disabled, systemd will not ratelimit messages written to
279 kmsg.
280 $SYSTEMD_PAGER
282 Pager to use when --no-pager is not given; overrides $PAGER. If
283 neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
284 pager implementations are tried in turn, including less(1) and
285 more(1), until one is found. If no pager implementation is
286 discovered no pager is invoked. Setting this environment variable
287 to an empty string or the value "cat" is equivalent to passing
288 --no-pager.
289 Note: if $SYSTEMD_PAGERSECURE is not set, $SYSTEMD_PAGER (as well
291 as $PAGER) will be silently ignored.
292 $SYSTEMD_LESS
294 Override the options passed to less (by default "FRSXMK").
295 Users might want to change two options in particular:
297 K
299 This option instructs the pager to exit immediately when Ctrl+C
300 is pressed. To allow less to handle Ctrl+C itself to switch
301 back to the pager command prompt, unset this option.
302 If the value of $SYSTEMD_LESS does not include "K", and the
304 pager that is invoked is less, Ctrl+C will be ignored by the
305 executable, and needs to be handled by the pager.
306 X
308 This option instructs the pager to not send termcap
309 initialization and deinitialization strings to the terminal. It
310 is set by default to allow command output to remain visible in
311 the terminal even after the pager exits. Nevertheless, this
312 prevents some pager functionality from working, in particular
313 paged output cannot be scrolled with the mouse.
314 See less(1) for more discussion.
316 $SYSTEMD_LESSCHARSET
318 Override the charset passed to less (by default "utf-8", if the
319 invoking terminal is determined to be UTF-8 compatible).
320 $SYSTEMD_PAGERSECURE
322 Takes a boolean argument. When true, the "secure" mode of the pager
323 is enabled; if false, disabled. If $SYSTEMD_PAGERSECURE is not set
324 at all, secure mode is enabled if the effective UID is not the same
325 as the owner of the login session, see geteuid(2) and
326 sd_pid_get_owner_uid(3). In secure mode, LESSSECURE=1 will be set
327 when invoking the pager, and the pager shall disable commands that
328 open or create new files or start new subprocesses. When
329 $SYSTEMD_PAGERSECURE is not set at all, pagers which are not known
330 to implement secure mode will not be used. (Currently only less(1)
331 implements secure mode.)
332 Note: when commands are invoked with elevated privileges, for
334 example under sudo(8) or pkexec(1), care must be taken to ensure
335 that unintended interactive features are not enabled. "Secure" mode
336 for the pager may be enabled automatically as describe above.
337 Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited
338 environment allows the user to invoke arbitrary commands. Note that
339 if the $SYSTEMD_PAGER or $PAGER variables are to be honoured,
340 $SYSTEMD_PAGERSECURE must be set too. It might be reasonable to
341 completely disable the pager using --no-pager instead.
342 $SYSTEMD_COLORS
344 Takes a boolean argument. When true, systemd and related utilities
345 will use colors in their output, otherwise the output will be
346 monochrome. Additionally, the variable can take one of the
347 following special values: "16", "256" to restrict the use of colors
348 to the base 16 or 256 ANSI colors, respectively. This can be
349 specified to override the automatic decision based on $TERM and
350 what the console is connected to.
351 $SYSTEMD_URLIFY
353 The value must be a boolean. Controls whether clickable links
354 should be generated in the output for terminal emulators supporting
355 this. This can be specified to override the decision that systemd
356 makes based on $TERM and other conditions.
357
359 systemd(1), systemd-userdbd.service(8), systemd-homed.service(8), nss-
360 systemd(8), getent(1)
361
363 1. JSON User Records
364 https://systemd.io/USER_RECORD
365 2. JSON Group Records
367 https://systemd.io/GROUP_RECORD
368 3. User/Group Record Lookup API via Varlink
370 https://systemd.io/USER_GROUP_API
371systemd 254 USERDBCTL(1)