| USERDBCTL(1) | userdbctl | USERDBCTL(1) |
.SH "NAME" userdbctl - Inspect users, groups and group
memberships
.SH "SYNOPSIS"
.HP 240u
userdbctl
[OPTIONS...]
{COMMAND}
[NAME...]
.SH "DESCRIPTION"
.PP 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 Records[1] and
JSON Group Records[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], and may also pick up drop-in JSON user
and group records from /etc/userdb/, /run/userdb/, /run/host/userdb/,
/usr/lib/userdb/ (see nss-systemd(8) for details about drop-in user
records).
.SH "OPTIONS"
.PP The following options are understood:
.PP --output=MODE
Chooses the output mode. Takes one of classic, friendly, table or 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.
Note that most output formats do not show all available information. In
particular, classic and table show only the most important fields. Various
modes also do not show password hashes. Use json to view all fields,
including any authentication fields.
Added in version 245.
.RE
.PP --json=FORMAT
Selects JSON output mode (like --output=json) and selects the precise
display mode. Takes one of pretty or short. If pretty, human-friendly
whitespace and newlines are inserted in the output to make the JSON data
more readable. If short, all superfluous whitespace is suppressed.
Added in version 250.
.RE
.PP --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.
Added in version 245.
.RE
.PP --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).
Added in version 245.
.RE
.PP --with-varlink=BOOL
Controls whether to include Varlink user/group lookups in the output, i.e.
those done via the User/Group Record Lookup API via Varlink[3]. If
--with-varlink=no is used, any attempts to resolve or enumerate
users/groups provided only via Varlink are suppressed. If
--with-varlink=yes is specified, such users/groups are included in
the output (which is the default).
Added in version 249.
.RE
.PP --with-dropin=BOOL
Controls whether to include user/group lookups in the output that are defined
using drop-in files in /etc/userdb/, /run/userdb/, /run/host/userdb/,
/usr/lib/userdb/. If --with-dropin=no is used, these records are
suppressed. If --with-dropin=yes is specified, such users/groups are
included in the output (which is the default).
Added in version 249.
.RE
.PP --synthesize=BOOL
Controls whether to synthesize records for the root and nobody users/groups
if they are not defined otherwise, as well as the user/groups for the
"foreign" UID range. By default (or with yes), such records are
implicitly synthesized if otherwise missing since they have special
significance to the OS. When no, this synthesizing is turned off.
Added in version 245.
.RE
.PP -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.
Added in version 245.
.RE
.PP --multiplexer=BOOL
Controls whether to do lookups via the multiplexer service (if specified as
true, the default) or do lookups in the client (if specified as false).
Using the multiplexer service is typically preferable, since it runs in a
locked down sandbox.
Added in version 250.
.RE
.PP --chain
When used with the ssh-authorized-keys command, this will allow
passing an additional command line after the user name that is chain
executed after the lookup completed. This allows chaining multiple tools
that show SSH authorized keys.
Added in version 250.
.RE
.PP --fuzzy, -z
When used with the user or group command, do a fuzzy string
search. Any specified arguments will be matched against the user name, the
real name of the user record, the email address, and other descriptive
strings of the user or group record. Moreover, instead of precise matching,
a substring match or a match allowing slight deviations in spelling is
applied.
Added in version 257.
.RE
.PP --disposition=
When used with the user or group command, filters by
disposition of the record. Takes one of intrinsic, system, regular, dynamic,
container. May be used multiple times, in which case only users matching any
of the specified dispositions are shown.
Added in version 257.
.RE
.PP -I, -S, -R
Shortcuts for --disposition=intrinsic, --disposition=system,
--disposition=regular, respectively.
Added in version 257.
.RE
.PP --uid-min=, --uid-max=
When used with the user or group command, filters the output by
UID/GID ranges. Takes numeric minimum or maximum UID/GID values,
respectively. Shows only records within the specified range. When applied to
the user command, it matches against UIDs. When applied to the
group command, matches against GIDs (despite the name of the switch).
If unspecified, defaults to 0 (for the minimum) and 4294967294 (for the
maximum), i.e. by default, no filtering is applied, as the whole UID/GID
range is covered.
Added in version 257.
.RE
.PP --uuid=
When used with the user or group command, filters the output to
the record with the specified UUID. If unspecified, no UUID-based filtering
is applied.
Added in version 259.
.RE
.PP --boundaries=
When used with the user or group command, controls whether to
show relevant UID/GID range boundary information in the tabular output.
Takes a boolean. Defaults to true.
Added in version 257.
.RE
.PP -B
Shortcut for --boundaries=no.
Added in version 257.
.RE
.PP --from-file=PATH, -F
When used with the user or group command, read the user
definition in JSON format from the specified file, instead of querying it
from the system. If the path is specified as -, reads the JSON data from
standard input. This is useful to validate and introspect JSON user or group
records quickly, and check how they would be interpreted on the local
system.
Added in version 258.
.RE
.PP --no-pager
Do not pipe output into a pager.
.RE
.PP --no-legend
Do not print the legend, i.e. column headers and the footer with hints.
.RE
.PP -h, --help
Print a short help text and exit.
.RE
.PP --version
Print a short version string and exit.
.RE
.SH "COMMANDS"
.PP The following commands are understood:
.PP user [USER...]
List all known users records or show details of one or more specified user
records. Use --output= to tweak output mode.
If used in conjunction with --from-file= the user record data is read
in JSON format from the specified file instead of querying it from the
system. For details see above.
Added in version 245.
.RE
.PP group [GROUP...]
List all known group records or show details of one or more specified group
records. Use --output= to tweak the output mode.
If used in conjunction with --from-file= the group record data is read
in JSON format from the specified file instead of querying it from the
system. For details see above.
Added in version 245.
.RE
.PP 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 the output mode.
Added in version 245.
.RE
.PP groups-of-user [USER...]
Lists groups that the specified users are members of. If no users are
specified, lists all user/group memberships defined (in this case,
groups-of-user and users-in-group are equivalent). Use
--output= to tweak the output mode.
Added in version 245.
.RE
.PP services
List all services currently providing user/group definitions to the system.
See below for a list of well-known services providing user information.
Added in version 245.
.RE
.PP ssh-authorized-keys
Show SSH authorized keys for this account. This command is intended to be
used to allow the SSH daemon to pick up authorized keys from user records,
see below.
Added in version 245.
.RE
.PP load-credentials
When specified, the following credentials are used when passed in:
.PP userdb.user.*, userdb.group.*,
userdb.transient.user.*, userdb.transient.group.*
These credentials should contain valid JSON User[1] and JSON
Group[2] records. For userdb.user.* and userdb.group.*
credentials, records are placed in /etc/userdb/, while for
userdb.transient.user.* and userdb.transient.group.*
credentials they are placed in /run/userdb/. These records implement the
interface described in nss-systemd(8). Any passed user records must
contain valid UID and GID fields. Any passed group records must contain a
GID field (i.e. automatic UID/GID allocation is not supported). For both
user and group records, the credential suffix (for userdb.user.foobar the
suffix is foobar) must match the user or group name encoded in the
record.
Added in version 258.
.RE
.sp
Added in version 258.
.RE
.SH "WELL-KNOWN SERVICES"
.PP 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:
.PP 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).
Added in version 245.
.RE
.PP 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.
Added in version 245.
.RE
.PP 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.
Added in version 246.
.RE
.PP 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.
Added in version 245.
.RE
.PP io.systemd.NameServiceSwitch
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.
Added in version 245.
.RE
.PP io.systemd.DropIn
This service is (also) provided by systemd-userdbd.service(8) and
picks up JSON user/group records from /etc/userdb/, /run/userdb/,
/run/host/userdb/, /usr/lib/userdb/.
Added in version 249.
.RE
.PP Note that userdbctl has internal support for NSS-based lookups
too. This means that if neither io.systemd.Multiplexer nor
io.systemd.NameServiceSwitch are running, look-ups into the basic
user/group databases will still work.
.SH "INTEGRATION WITH SSH"
.PP 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 ...
.PP Sometimes, it is useful to allow chain invocation of another program to
list SSH authorized keys. By using the --chain option, such a tool
may be chain executed by userdbctl ssh-authorized-keys once a lookup
completes, regardless of whether an SSH key was found or not. Example:
... AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/othertool %u AuthorizedKeysCommandUser root ...
.PP The above will first query the userdb database for SSH keys, and then
chain execute /usr/bin/othertool to also be queried.
.SH "EXIT STATUS"
.PP On success, 0 is returned, and a non-zero failure code otherwise.
.SH "ENVIRONMENT"
.PP $SYSTEMD_LOG_LEVEL
The maximum log level of emitted messages (messages with a higher log level,
i.e. less important ones, will be suppressed). Takes a comma-separated list
of values. A value may be either one of (in order of decreasing importance)
emerg, alert, crit, err, warning,
notice, info, debug, or an integer in the range 0...7.
See syslog(3) for more information. Each value may optionally be
prefixed with one of console, syslog, kmsg or
journal followed by a colon to set the maximum log level for that
specific log target (e.g. SYSTEMD_LOG_LEVEL=debug,console:info
specifies to log at debug level except when logging to the console which
should be at info level). Note that the global maximum log level takes
priority over any per target maximum log levels.
.RE
.PP $SYSTEMD_LOG_COLOR
A boolean. If true, messages written to the tty will be colored according to
priority.
This setting is only useful when messages are written directly to the
terminal, because journalctl(1) and other tools that display logs
will color messages based on the log level on their own.
.RE
.PP $SYSTEMD_LOG_TIME
A boolean. If true, console log messages will be prefixed with a
timestamp.
This setting is only useful when messages are written directly to the
terminal or a file, because journalctl(1) and other tools that
display logs will attach timestamps based on the entry metadata on their
own.
.RE
.PP $SYSTEMD_LOG_LOCATION
A boolean. If true, messages will be prefixed with a filename and line number
in the source code where the message originates.
Note that the log location is often attached as metadata to journal entries
anyway. Including it directly in the message text can nevertheless be
convenient when debugging programs.
.RE
.PP $SYSTEMD_LOG_TID
A boolean. If true, messages will be prefixed with the current numerical
thread ID (TID).
Note that the this information is attached as metadata to journal entries
anyway. Including it directly in the message text can nevertheless be
convenient when debugging programs.
.RE
.PP $SYSTEMD_LOG_TARGET
The destination for log messages. One of console (log to the attached
tty), console-prefixed (log to the attached tty but with prefixes
encoding the log level and "facility", see syslog(3),
kmsg (log to the kernel circular log buffer), journal (log to
the journal), journal-or-kmsg (log to the journal if available, and
to kmsg otherwise), auto (determine the appropriate log target
automatically, the default), null (disable log output).
.RE
.PP $SYSTEMD_LOG_RATELIMIT_KMSG
Whether to ratelimit kmsg or not. Takes a boolean. Defaults to true. If
disabled, systemd will not ratelimit messages written to kmsg.
.RE
.PP $SYSTEMD_PAGER, $PAGER
Pager to use when --no-pager is not given. $SYSTEMD_PAGER is
used if set; otherwise $PAGER is used. If neither
$SYSTEMD_PAGER nor $PAGER are set, a set of well-known pager
implementations is tried in turn, including less(1) and
more(1), until one is found. If no pager implementation is
discovered, no pager is invoked. Setting those environment variables to an
empty string or the value cat is equivalent to passing
--no-pager.
Note: if $SYSTEMD_PAGERSECURE is not set, $SYSTEMD_PAGER and
$PAGER can only be used to disable the pager (with cat or ), and are
otherwise ignored.
.RE
.PP $SYSTEMD_LESS
Override the options passed to less (by default FRSXMK).
Users might want to change two options in particular:
.PP 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.
.RE
.PP 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.
.RE
.sp
Note that setting the regular $LESS environment variable has no effect
for less invocations by systemd tools.
See less(1) for more discussion.
.RE
.PP $SYSTEMD_LESSCHARSET
Override the charset passed to less (by default utf-8, if the invoking
terminal is determined to be UTF-8 compatible).
Note that setting the regular $LESSCHARSET environment variable has no
effect for less invocations by systemd tools.
.RE
.PP $SYSTEMD_PAGERSECURE
Common pager commands like less(1), in addition to "paging",
i.e. scrolling through the output, support opening of or writing to other
files and running arbitrary shell commands. When commands are invoked with
elevated privileges, for example under sudo(8) or pkexec(1),
the pager becomes a security boundary. Care must be taken that only programs
with strictly limited functionality are used as pagers, and unintended
interactive features like opening or creation of new files or starting of
subprocesses are not allowed. "Secure mode" for the pager may be
enabled as described below, if the pager supports that (most pagers
are not written in a way that takes this into consideration). It is
recommended to either explicitly enable "secure mode" or to
completely disable the pager using --no-pager or PAGER=cat
when allowing untrusted users to execute commands with elevated
privileges.
This option takes a boolean argument. When set to true, the "secure
mode" of the pager is enabled. In "secure mode",
LESSSECURE=1 will be set when invoking the pager, which instructs the
pager to disable commands that open or create new files or start new
subprocesses. Currently only less(1) is known to understand this
variable and implement "secure mode".
When set to false, no limitation is placed on the pager. Setting
SYSTEMD_PAGERSECURE=0 or not removing it from the inherited
environment may allow the user to invoke arbitrary commands.
When $SYSTEMD_PAGERSECURE is not set, systemd tools attempt to
automatically figure out if "secure mode" should be enabled and
whether the pager supports it. "Secure mode" is enabled if the
effective UID is not the same as the owner of the login session, see
geteuid(2) and sd_pid_get_owner_uid(3), or when running under
sudo(8) or similar tools ($SUDO_UID is set [4]). In those
cases, SYSTEMD_PAGERSECURE=1 will be set and pagers which are not
known to implement "secure mode" will not be used at all. Note
that this autodetection only covers the most common mechanisms to elevate
privileges and is intended as convenience. It is recommended to explicitly
set $SYSTEMD_PAGERSECURE or disable the pager.
Note that if the $SYSTEMD_PAGER or $PAGER variables are to be
honoured, other than to disable the pager, $SYSTEMD_PAGERSECURE must
be set too.
.RE
.PP $SYSTEMD_COLORS
Takes a boolean argument, or a special value. By default (unset),
systemd and related utilities will use colors in their output if
possible. If $COLORTERM is set to truecolor or 24bit, 24-bit colors
will be enabled, 256 colors otherwise, unless $NO_COLOR or
$TERM indicates colors are disabled.
.PP true
Same as unset, except that $NO_COLOR is ignored.
.RE
.PP false
The output will be monochrome.
.RE
.PP 16, 256, 24bit
Always use the base 16 ANSI colors, 256 colors, or 24 bit color,
respectively.
.RE
.PP auto-16, auto-256, auto-24bit
Use the given quantity of colours, subject to $TERM, and what the
console is connected to.
.RE
.sp
.RE
.PP $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.
.RE
.SH "SEE ALSO"
.PP systemd(1), systemd-userdbd.service(8),
systemd-homed.service(8), nss-systemd(8), getent(1)
NOTES
- 1.
- JSON User Records
- 2.
- JSON Group Records
- 3.
- User/Group Record Lookup API via Varlink
- 4.
-
It is recommended for other tools to set and check $SUDO_UID as appropriate, treating it is a common interface.
| systemd 262.2 |