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