|
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | WELL-KNOWN SERVICES | INTEGRATION WITH SSH | EXIT STATUS | ENVIRONMENT | SEE ALSO | NOTES | COLOPHON |
USERDBCTL(1) userdbctl USERDBCTL(1)
userdbctl - Inspect users, groups and group memberships
userdbctl [OPTIONS...] {COMMAND} [NAME...]
userdbctl may be used to inspect user and groups (as well as group
memberships) of the system. This client utility inquires user/group
information provided by various system services, both operating on
JSON user/group records (as defined by the JSON User Record[1] and
JSON Group Record[2] definitions), and classic UNIX NSS/glibc user
and group records. This tool is primarily a client to the User/Group
Record Lookup API via Varlink[3].
The following options are understood:
--output=MODE
Choose the output mode, takes one of "classic", "friendly",
"table", "json". If "classic", an output very close to the format
of /etc/passwd or /etc/group is generated. If "friendly" a more
comprehensive and user friendly, human readable output is
generated; if "table" a minimal, tabular output is generated; if
"json" a JSON formatted output is generated. Defaults to
"friendly" if a user/group is specified on the command line,
"table" otherwise.
--service=SERVICE[:SERVICE...], -s SERVICE:SERVICE...
Controls which services to query for users/groups. Takes a list
of one or more service names, separated by ":". See below for a
list of well-known service names. If not specified all available
services are queried at once.
--with-nss=BOOL
Controls whether to include classic glibc/NSS user/group lookups
in the output. If --with-nss=no is used any attempts to resolve
or enumerate users/groups provided only via glibc NSS is
suppressed. If --with-nss=yes is specified such users/groups are
included in the output (which is the default).
--synthesize=BOOL
Controls whether to synthesize records for the root and nobody
users/groups if they aren't defined otherwise. By default (or
"yes") such records are implicitly synthesized if otherwise
missing since they have special significance to the OS. When "no"
this synthesizing is turned off.
-N
This option is short for --with-nss=no --synthesize=no. Use this
option to show only records that are natively defined as JSON
user or group records, with all NSS/glibc compatibility and all
implicit synthesis turned off.
--no-pager
Do not pipe output into a pager.
--no-legend
Do not print the legend, i.e. column headers and the footer with
hints.
-h, --help
Print a short help text and exit.
--version
Print a short version string and exit.
The following commands are understood:
user [USER...]
List all known users records or show details of one or more
specified user records. Use --output= to tweak output mode.
group [GROUP...]
List all known group records or show details of one or more
specified group records. Use --output= to tweak output mode.
users-in-group [GROUP...]
List users that are members of the specified groups. If no groups
are specified list all user/group memberships defined. Use
--output= to tweak output mode.
groups-of-user [USER...]
List groups that the specified users are members of. If no users
are specified list all user/group memberships defined (in this
case groups-of-user and users-in-group are equivalent). Use
--output= to tweak output mode.
services
List all services currently providing user/group definitions to
the system. See below for a list of well-known services providing
user information.
ssh-authorized-keys
This operation is not a public, user-facing interface. It is used
to allow the SSH daemon to pick up authorized keys from user
records, see below.
The userdbctl services command will list all currently running
services that provide user or group definitions to the system. The
following well-known services are shown among this list:
io.systemd.DynamicUser
This service is provided by the system service manager itself
(i.e. PID 1) and makes all users (and their groups) synthesized
through the DynamicUser= setting in service unit files available
to the system (see systemd.exec(5) for details about this
setting).
io.systemd.Home
This service is provided by systemd-homed.service(8) and makes
all users (and their groups) belonging to home directories
managed by that service available to the system.
io.systemd.Machine
This service is provided by systemd-machined.service(8) and
synthesizes records for all users/groups used by a container that
employs user namespacing.
io.systemd.Multiplexer
This service is provided by systemd-userdbd.service(8) and
multiplexes user/group look-ups to all other running lookup
services. This is the primary entry point for user/group record
clients, as it simplifies client side implementation
substantially since they can ask a single service for lookups
instead of asking all running services in parallel. userdbctl
uses this service preferably, too, unless --with-nss= or
--service= are used, in which case finer control over the
services to talk to is required.
io.systemd.NameSeviceSwitch
This service is (also) provided by systemd-userdbd.service(8) and
converts classic NSS/glibc user and group records to JSON
user/group records, providing full backwards compatibility. Use
--with-nss=no to disable this compatibility, see above. Note that
compatibility is actually provided in both directions:
nss-systemd(8) will automatically synthesize classic NSS/glibc
user/group records from all JSON user/group records provided to
the system, thus using both APIs is mostly equivalent and
provides access to the same data, however the NSS/glibc APIs
necessarily expose a more reduced set of fields only.
Note that userdbctl has internal support for NSS-based lookups too.
This means that if neither io.systemd.Multiplexer nor
io.systemd.NameSeviceSwitch are running look-ups into the basic
user/group databases will still work.
The userdbctl tool may be used to make the list of SSH authorized
keys possibly contained in a user record available to the SSH daemon
for authentication. For that configure the following in
sshd_config(5):
...
AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u
AuthorizedKeysCommandUser root
...
On success, 0 is returned, a non-zero failure code otherwise.
$SYSTEMD_PAGER
Pager to use when --no-pager is not given; overrides $PAGER. If
neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known
pager implementations are tried in turn, including less(1) and
more(1), until one is found. If no pager implementation is
discovered no pager is invoked. Setting this environment variable
to an empty string or the value "cat" is equivalent to passing
--no-pager.
$SYSTEMD_LESS
Override the options passed to less (by default "FRSXMK").
Users might want to change two options in particular:
K
This option instructs the pager to exit immediately when
Ctrl+C is pressed. To allow less to handle Ctrl+C itself to
switch back to the pager command prompt, unset this option.
If the value of $SYSTEMD_LESS does not include "K", and the
pager that is invoked is less, Ctrl+C will be ignored by the
executable, and needs to be handled by the pager.
X
This option instructs the pager to not send termcap
initialization and deinitialization strings to the terminal.
It is set by default to allow command output to remain
visible in the terminal even after the pager exits.
Nevertheless, this prevents some pager functionality from
working, in particular paged output cannot be scrolled with
the mouse.
See less(1) for more discussion.
$SYSTEMD_LESSCHARSET
Override the charset passed to less (by default "utf-8", if the
invoking terminal is determined to be UTF-8 compatible).
$SYSTEMD_COLORS
The value must be a boolean. Controls whether colorized output
should be generated. This can be specified to override the
decision that systemd makes based on $TERM and what the console
is connected to.
$SYSTEMD_URLIFY
The value must be a boolean. Controls whether clickable links
should be generated in the output for terminal emulators
supporting this. This can be specified to override the decision
that systemd makes based on $TERM and other conditions.
systemd(1), systemd-userdbd.service(8), systemd-homed.service(8),
nss-systemd(8), getent(1)
1. JSON User Record
https://systemd.io/USER_RECORD
2. JSON Group Record
https://systemd.io/GROUP_RECORD
3. User/Group Record Lookup API via Varlink
https://systemd.io/USER_GROUP_API
This page is part of the systemd (systemd system and service manager)
project. Information about the project can be found at
⟨http://www.freedesktop.org/wiki/Software/systemd⟩. If you have a bug
report for this manual page, see
⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩. This
page was obtained from the project's upstream Git repository
⟨https://github.com/systemd/systemd.git⟩ on 2020-08-13. (At that
time, the date of the most recent commit that was found in the repos‐
itory was 2020-08-11.) If you discover any rendering problems in
this HTML version of the page, or you believe there is a better or
more up-to-date source for the page, or you have corrections or
improvements to the information in this COLOPHON (which is not part
of the original manual page), send a mail to man-pages@man7.org
systemd 246 USERDBCTL(1)
Pages that refer to this page: homectl(1) , 30-systemd-environment-d-generator(7) , systemd.directives(7) , systemd.index(7) , systemd-homed(8) , systemd-homed.service(8) , systemd-machined(8) , systemd-machined.service(8) , systemd-userdbd(8) , systemd-userdbd.service(8)