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 --service=SERVICE[:SERVICE...], -s SERVICE:SERVICE...
42 Controls which services to query for users/groups. Takes a list of
43 one or more service names, separated by ":". See below for a list
44 of well-known service names. If not specified all available
45 services are queried at once.
46 --with-nss=BOOL
48 Controls whether to include classic glibc/NSS user/group lookups in
49 the output. If --with-nss=no is used any attempts to resolve or
50 enumerate users/groups provided only via glibc NSS is suppressed.
51 If --with-nss=yes is specified such users/groups are included in
52 the output (which is the default).
53 --with-varlink=BOOL
55 Controls whether to include Varlink user/group lookups in the
56 output, i.e. those done via the User/Group Record Lookup API via
57 Varlink[3]. If --with-varlink=no is used any attempts to resolve or
58 enumerate users/groups provided only via Varlink are suppressed. If
59 --with-varlink=yes is specified such users/groups are included in
60 the output (which is the default).
61 --with-dropin=BOOL
63 Controls whether to include user/group lookups in the output that
64 are defined using drop-in files in /etc/userdb/, /run/userdb/,
65 /run/host/userdb/, /usr/lib/userdb/. If --with-dropin=no is used
66 these records are suppressed. If --with-dropin=yes is specified
67 such users/groups are included in the output (which is the
68 default).
69 --synthesize=BOOL
71 Controls whether to synthesize records for the root and nobody
72 users/groups if they aren't defined otherwise. By default (or
73 "yes") such records are implicitly synthesized if otherwise missing
74 since they have special significance to the OS. When "no" this
75 synthesizing is turned off.
76 -N
78 This option is short for --with-nss=no --synthesize=no. Use this
79 option to show only records that are natively defined as JSON user
80 or group records, with all NSS/glibc compatibility and all implicit
81 synthesis turned off.
82 --no-pager
84 Do not pipe output into a pager.
85 --no-legend
87 Do not print the legend, i.e. column headers and the footer with
88 hints.
89 -h, --help
91 Print a short help text and exit.
92 --version
94 Print a short version string and exit.
95
97 The following commands are understood:
98 user [USER...]
100 List all known users records or show details of one or more
101 specified user records. Use --output= to tweak output mode.
102 group [GROUP...]
104 List all known group records or show details of one or more
105 specified group records. Use --output= to tweak output mode.
106 users-in-group [GROUP...]
108 List users that are members of the specified groups. If no groups
109 are specified list all user/group memberships defined. Use
110 --output= to tweak output mode.
111 groups-of-user [USER...]
113 List groups that the specified users are members of. If no users
114 are specified list all user/group memberships defined (in this case
115 groups-of-user and users-in-group are equivalent). Use --output= to
116 tweak output mode.
117 services
119 List all services currently providing user/group definitions to the
120 system. See below for a list of well-known services providing user
121 information.
122 ssh-authorized-keys
124 This operation is not a public, user-facing interface. It is used
125 to allow the SSH daemon to pick up authorized keys from user
126 records, see below.
127
129 The userdbctl services command will list all currently running services
130 that provide user or group definitions to the system. The following
131 well-known services are shown among this list:
132 io.systemd.DynamicUser
134 This service is provided by the system service manager itself (i.e.
135 PID 1) and makes all users (and their groups) synthesized through
136 the DynamicUser= setting in service unit files available to the
137 system (see systemd.exec(5) for details about this setting).
138 io.systemd.Home
140 This service is provided by systemd-homed.service(8) and makes all
141 users (and their groups) belonging to home directories managed by
142 that service available to the system.
143 io.systemd.Machine
145 This service is provided by systemd-machined.service(8) and
146 synthesizes records for all users/groups used by a container that
147 employs user namespacing.
148 io.systemd.Multiplexer
150 This service is provided by systemd-userdbd.service(8) and
151 multiplexes user/group look-ups to all other running lookup
152 services. This is the primary entry point for user/group record
153 clients, as it simplifies client side implementation substantially
154 since they can ask a single service for lookups instead of asking
155 all running services in parallel. userdbctl uses this service
156 preferably, too, unless --with-nss= or --service= are used, in
157 which case finer control over the services to talk to is required.
158 io.systemd.NameServiceSwitch
160 This service is (also) provided by systemd-userdbd.service(8) and
161 converts classic NSS/glibc user and group records to JSON
162 user/group records, providing full backwards compatibility. Use
163 --with-nss=no to disable this compatibility, see above. Note that
164 compatibility is actually provided in both directions: nss-
165 systemd(8) will automatically synthesize classic NSS/glibc
166 user/group records from all JSON user/group records provided to the
167 system, thus using both APIs is mostly equivalent and provides
168 access to the same data, however the NSS/glibc APIs necessarily
169 expose a more reduced set of fields only.
170 io.systemd.DropIn
172 This service is (also) provided by systemd-userdbd.service(8) and
173 picks up JSON user/group records from /etc/userdb/, /run/userdb/,
174 /run/host/userdb/, /usr/lib/userdb/.
175 Note that userdbctl has internal support for NSS-based lookups too.
177 This means that if neither io.systemd.Multiplexer nor
178 io.systemd.NameServiceSwitch are running look-ups into the basic
179 user/group databases will still work.
180
182 The userdbctl tool may be used to make the list of SSH authorized keys
183 possibly contained in a user record available to the SSH daemon for
184 authentication. For that configure the following in sshd_config(5):
185 ...
187 AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
188 AuthorizedKeysCommandUser root
189 ...
190
192 On success, 0 is returned, a non-zero failure code otherwise.
193
195 $SYSTEMD_LOG_LEVEL
196 The maximum log level of emitted messages (messages with a higher
197 log level, i.e. less important ones, will be suppressed). Either
198 one of (in order of decreasing importance) emerg, alert, crit, err,
199 warning, notice, info, debug, or an integer in the range 0...7. See
200 syslog(3) for more information.
201 $SYSTEMD_LOG_COLOR
203 A boolean. If true, messages written to the tty will be colored
204 according to priority.
205 This setting is only useful when messages are written directly to
207 the terminal, because journalctl(1) and other tools that display
208 logs will color messages based on the log level on their own.
209 $SYSTEMD_LOG_TIME
211 A boolean. If true, console log messages will be prefixed with a
212 timestamp.
213 This setting is only useful when messages are written directly to
215 the terminal or a file, because journalctl(1) and other tools that
216 display logs will attach timestamps based on the entry metadata on
217 their own.
218 $SYSTEMD_LOG_LOCATION
220 A boolean. If true, messages will be prefixed with a filename and
221 line number in the source code where the message originates.
222 Note that the log location is often attached as metadata to journal
224 entries anyway. Including it directly in the message text can
225 nevertheless be convenient when debugging programs.
226 $SYSTEMD_LOG_TID
228 A boolean. If true, messages will be prefixed with the current
229 numerical thread ID (TID).
230 Note that the this information is attached as metadata to journal
232 entries anyway. Including it directly in the message text can
233 nevertheless be convenient when debugging programs.
234 $SYSTEMD_LOG_TARGET
236 The destination for log messages. One of console (log to the
237 attached tty), console-prefixed (log to the attached tty but with
238 prefixes encoding the log level and "facility", see syslog(3), kmsg
239 (log to the kernel circular log buffer), journal (log to the
240 journal), journal-or-kmsg (log to the journal if available, and to
241 kmsg otherwise), auto (determine the appropriate log target
242 automatically, the default), null (disable log output).
243 $SYSTEMD_PAGER
245 Pager to use when --no-pager is not given; overrides $PAGER. If
246 neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
247 pager implementations are tried in turn, including less(1) and
248 more(1), until one is found. If no pager implementation is
249 discovered no pager is invoked. Setting this environment variable
250 to an empty string or the value "cat" is equivalent to passing
251 --no-pager.
252 $SYSTEMD_LESS
254 Override the options passed to less (by default "FRSXMK").
255 Users might want to change two options in particular:
257 K
259 This option instructs the pager to exit immediately when Ctrl+C
260 is pressed. To allow less to handle Ctrl+C itself to switch
261 back to the pager command prompt, unset this option.
262 If the value of $SYSTEMD_LESS does not include "K", and the
264 pager that is invoked is less, Ctrl+C will be ignored by the
265 executable, and needs to be handled by the pager.
266 X
268 This option instructs the pager to not send termcap
269 initialization and deinitialization strings to the terminal. It
270 is set by default to allow command output to remain visible in
271 the terminal even after the pager exits. Nevertheless, this
272 prevents some pager functionality from working, in particular
273 paged output cannot be scrolled with the mouse.
274 See less(1) for more discussion.
276 $SYSTEMD_LESSCHARSET
278 Override the charset passed to less (by default "utf-8", if the
279 invoking terminal is determined to be UTF-8 compatible).
280 $SYSTEMD_PAGERSECURE
282 Takes a boolean argument. When true, the "secure" mode of the pager
283 is enabled; if false, disabled. If $SYSTEMD_PAGERSECURE is not set
284 at all, secure mode is enabled if the effective UID is not the same
285 as the owner of the login session, see geteuid(2) and
286 sd_pid_get_owner_uid(3). In secure mode, LESSSECURE=1 will be set
287 when invoking the pager, and the pager shall disable commands that
288 open or create new files or start new subprocesses. When
289 $SYSTEMD_PAGERSECURE is not set at all, pagers which are not known
290 to implement secure mode will not be used. (Currently only less(1)
291 implements secure mode.)
292 Note: when commands are invoked with elevated privileges, for
294 example under sudo(8) or pkexec(1), care must be taken to ensure
295 that unintended interactive features are not enabled. "Secure" mode
296 for the pager may be enabled automatically as describe above.
297 Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited
298 environment allows the user to invoke arbitrary commands. Note that
299 if the $SYSTEMD_PAGER or $PAGER variables are to be honoured,
300 $SYSTEMD_PAGERSECURE must be set too. It might be reasonable to
301 completely disable the pager using --no-pager instead.
302 $SYSTEMD_COLORS
304 Takes a boolean argument. When true, systemd and related utilities
305 will use colors in their output, otherwise the output will be
306 monochrome. Additionally, the variable can take one of the
307 following special values: "16", "256" to restrict the use of colors
308 to the base 16 or 256 ANSI colors, respectively. This can be
309 specified to override the automatic decision based on $TERM and
310 what the console is connected to.
311 $SYSTEMD_URLIFY
313 The value must be a boolean. Controls whether clickable links
314 should be generated in the output for terminal emulators supporting
315 this. This can be specified to override the decision that systemd
316 makes based on $TERM and other conditions.
317
319 systemd(1), systemd-userdbd.service(8), systemd-homed.service(8), nss-
320 systemd(8), getent(1)
321
323 1. JSON User Records
324 https://systemd.io/USER_RECORD
325 2. JSON Group Records
327 https://systemd.io/GROUP_RECORD
328 3. User/Group Record Lookup API via Varlink
330 https://systemd.io/USER_GROUP_API
331systemd 249 USERDBCTL(1)