Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 551 insertions, 0 deletions

diff --git a/upstream/opensuse-leap-15-6/man1/userdbctl.1 b/upstream/opensuse-leap-15-6/man1/userdbctl.1
new file mode 100644
index 00000000..874c9445
--- /dev/null
+++ b/upstream/opensuse-leap-15-6/man1/userdbctl.1
@@ -0,0 +1,551 @@
+'\" t
+.TH "USERDBCTL" "1" "" "systemd 254" "userdbctl"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+userdbctl \- Inspect users, groups and group memberships
+.SH "SYNOPSIS"
+.HP \w'\fBuserdbctl\fR\ 'u
+\fBuserdbctl\fR [OPTIONS...] {COMMAND} [NAME...]
+.SH "DESCRIPTION"
+.PP
+\fBuserdbctl\fR
+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
+\m[blue]\fBJSON User Records\fR\m[]\&\s-2\u[1]\d\s+2
+and
+\m[blue]\fBJSON Group Records\fR\m[]\&\s-2\u[2]\d\s+2
+definitions), and classic UNIX NSS/glibc user and group records\&. This tool is primarily a client to the
+\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[3]\d\s+2, and may also pick up drop\-in JSON user and group records from
+/etc/userdb/,
+/run/userdb/,
+/run/host/userdb/,
+/usr/lib/userdb/\&.
+.SH "OPTIONS"
+.PP
+The following options are understood:
+.PP
+\fB\-\-output=\fR\fIMODE\fR
+.RS 4
+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\&.
+.sp
+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\&.
+.RE
+.PP
+\fB\-\-json=\fR\fIFORMAT\fR
+.RS 4
+Selects JSON output mode (like
+\fB\-\-output=json\fR) 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\&.
+.RE
+.PP
+\fB\-\-service=\fR\fISERVICE\fR[:\fISERVICE\&...\fR], \fB\-s\fR \fISERVICE\fR:\fISERVICE\&...\fR
+.RS 4
+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\&.
+.RE
+.PP
+\fB\-\-with\-nss=\fR\fIBOOL\fR
+.RS 4
+Controls whether to include classic glibc/NSS user/group lookups in the output\&. If
+\fB\-\-with\-nss=no\fR
+is used any attempts to resolve or enumerate users/groups provided only via glibc NSS is suppressed\&. If
+\fB\-\-with\-nss=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.RE
+.PP
+\fB\-\-with\-varlink=\fR\fIBOOL\fR
+.RS 4
+Controls whether to include Varlink user/group lookups in the output, i\&.e\&. those done via the
+\m[blue]\fBUser/Group Record Lookup API via Varlink\fR\m[]\&\s-2\u[3]\d\s+2\&. If
+\fB\-\-with\-varlink=no\fR
+is used any attempts to resolve or enumerate users/groups provided only via Varlink are suppressed\&. If
+\fB\-\-with\-varlink=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.RE
+.PP
+\fB\-\-with\-dropin=\fR\fIBOOL\fR
+.RS 4
+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
+\fB\-\-with\-dropin=no\fR
+is used these records are suppressed\&. If
+\fB\-\-with\-dropin=yes\fR
+is specified such users/groups are included in the output (which is the default)\&.
+.RE
+.PP
+\fB\-\-synthesize=\fR\fIBOOL\fR
+.RS 4
+Controls whether to synthesize records for the root and nobody users/groups if they aren\*(Aqt 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\&.
+.RE
+.PP
+\fB\-N\fR
+.RS 4
+This option is short for
+\fB\-\-with\-nss=no\fR
+\fB\-\-synthesize=no\fR\&. 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\&.
+.RE
+.PP
+\fB\-\-multiplexer=\fR\fIBOOL\fR
+.RS 4
+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\&.
+.RE
+.PP
+\fB\-\-chain\fR
+.RS 4
+When used with the
+\fBssh\-authorized\-keys\fR
+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\&.
+.RE
+.PP
+\fB\-\-no\-pager\fR
+.RS 4
+Do not pipe output into a pager\&.
+.RE
+.PP
+\fB\-\-no\-legend\fR
+.RS 4
+Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-help\fR
+.RS 4
+Print a short help text and exit\&.
+.RE
+.PP
+\fB\-\-version\fR
+.RS 4
+Print a short version string and exit\&.
+.RE
+.SH "COMMANDS"
+.PP
+The following commands are understood:
+.PP
+\fBuser\fR [\fIUSER\fR\&...]
+.RS 4
+List all known users records or show details of one or more specified user records\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.RE
+.PP
+\fBgroup\fR [\fIGROUP\fR\&...]
+.RS 4
+List all known group records or show details of one or more specified group records\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.RE
+.PP
+\fBusers\-in\-group\fR [\fIGROUP\fR\&...]
+.RS 4
+List users that are members of the specified groups\&. If no groups are specified list all user/group memberships defined\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.RE
+.PP
+\fBgroups\-of\-user\fR [\fIUSER\fR\&...]
+.RS 4
+List groups that the specified users are members of\&. If no users are specified list all user/group memberships defined (in this case
+\fBgroups\-of\-user\fR
+and
+\fBusers\-in\-group\fR
+are equivalent)\&. Use
+\fB\-\-output=\fR
+to tweak output mode\&.
+.RE
+.PP
+\fBservices\fR
+.RS 4
+List all services currently providing user/group definitions to the system\&. See below for a list of well\-known services providing user information\&.
+.RE
+.PP
+\fBssh\-authorized\-keys\fR
+.RS 4
+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\&.
+.RE
+.SH "WELL\-KNOWN SERVICES"
+.PP
+The
+\fBuserdbctl services\fR
+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
+\fBio\&.systemd\&.DynamicUser\fR
+.RS 4
+This service is provided by the system service manager itself (i\&.e\&. PID 1) and makes all users (and their groups) synthesized through the
+\fIDynamicUser=\fR
+setting in service unit files available to the system (see
+\fBsystemd.exec\fR(5)
+for details about this setting)\&.
+.RE
+.PP
+\fBio\&.systemd\&.Home\fR
+.RS 4
+This service is provided by
+\fBsystemd-homed.service\fR(8)
+and makes all users (and their groups) belonging to home directories managed by that service available to the system\&.
+.RE
+.PP
+\fBio\&.systemd\&.Machine\fR
+.RS 4
+This service is provided by
+\fBsystemd-machined.service\fR(8)
+and synthesizes records for all users/groups used by a container that employs user namespacing\&.
+.RE
+.PP
+\fBio\&.systemd\&.Multiplexer\fR
+.RS 4
+This service is provided by
+\fBsystemd-userdbd.service\fR(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\&.
+\fBuserdbctl\fR
+uses this service preferably, too, unless
+\fB\-\-with\-nss=\fR
+or
+\fB\-\-service=\fR
+are used, in which case finer control over the services to talk to is required\&.
+.RE
+.PP
+\fBio\&.systemd\&.NameServiceSwitch\fR
+.RS 4
+This service is (also) provided by
+\fBsystemd-userdbd.service\fR(8)
+and converts classic NSS/glibc user and group records to JSON user/group records, providing full backwards compatibility\&. Use
+\fB\-\-with\-nss=no\fR
+to disable this compatibility, see above\&. Note that compatibility is actually provided in both directions:
+\fBnss-systemd\fR(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\&.
+.RE
+.PP
+\fBio\&.systemd\&.DropIn\fR
+.RS 4
+This service is (also) provided by
+\fBsystemd-userdbd.service\fR(8)
+and picks up JSON user/group records from
+/etc/userdb/,
+/run/userdb/,
+/run/host/userdb/,
+/usr/lib/userdb/\&.
+.RE
+.PP
+Note that
+\fBuserdbctl\fR
+has internal support for NSS\-based lookups too\&. This means that if neither
+\fBio\&.systemd\&.Multiplexer\fR
+nor
+\fBio\&.systemd\&.NameServiceSwitch\fR
+are running look\-ups into the basic user/group databases will still work\&.
+.SH "INTEGRATION WITH SSH"
+.PP
+The
+\fBuserdbctl\fR
+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
+\fBsshd_config\fR(5):
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\&...
+AuthorizedKeysCommand /usr/bin/userdbctl ssh\-authorized\-keys %u
+AuthorizedKeysCommandUser root
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+Sometimes it\*(Aqs useful to allow chain invocation of another program to list SSH authorized keys\&. By using the
+\fB\-\-chain\fR
+such a tool may be chain executed by
+\fBuserdbctl ssh\-authorized\-keys\fR
+once a lookup completes (regardless if an SSH key was found or not)\&. Example:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\&...
+AuthorizedKeysCommand /usr/bin/userdbctl ssh\-authorized\-keys %u \-\-chain /usr/bin/othertool %u
+AuthorizedKeysCommandUser root
+\&...
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+The above will first query the userdb database for SSH keys, and then chain execute
+\fB/usr/bin/othertool\fR
+to also be queried\&.
+.SH "EXIT STATUS"
+.PP
+On success, 0 is returned, a non\-zero failure code otherwise\&.
+.SH "ENVIRONMENT"
+.PP
+\fI$SYSTEMD_LOG_LEVEL\fR
+.RS 4
+The maximum log level of emitted messages (messages with a higher log level, i\&.e\&. less important ones, will be suppressed)\&. Either one of (in order of decreasing importance)
+\fBemerg\fR,
+\fBalert\fR,
+\fBcrit\fR,
+\fBerr\fR,
+\fBwarning\fR,
+\fBnotice\fR,
+\fBinfo\fR,
+\fBdebug\fR, or an integer in the range 0\&...7\&. See
+\fBsyslog\fR(3)
+for more information\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_COLOR\fR
+.RS 4
+A boolean\&. If true, messages written to the tty will be colored according to priority\&.
+.sp
+This setting is only useful when messages are written directly to the terminal, because
+\fBjournalctl\fR(1)
+and other tools that display logs will color messages based on the log level on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_TIME\fR
+.RS 4
+A boolean\&. If true, console log messages will be prefixed with a timestamp\&.
+.sp
+This setting is only useful when messages are written directly to the terminal or a file, because
+\fBjournalctl\fR(1)
+and other tools that display logs will attach timestamps based on the entry metadata on their own\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_LOCATION\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with a filename and line number in the source code where the message originates\&.
+.sp
+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
+\fI$SYSTEMD_LOG_TID\fR
+.RS 4
+A boolean\&. If true, messages will be prefixed with the current numerical thread ID (TID)\&.
+.sp
+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
+\fI$SYSTEMD_LOG_TARGET\fR
+.RS 4
+The destination for log messages\&. One of
+\fBconsole\fR
+(log to the attached tty),
+\fBconsole\-prefixed\fR
+(log to the attached tty but with prefixes encoding the log level and "facility", see
+\fBsyslog\fR(3),
+\fBkmsg\fR
+(log to the kernel circular log buffer),
+\fBjournal\fR
+(log to the journal),
+\fBjournal\-or\-kmsg\fR
+(log to the journal if available, and to kmsg otherwise),
+\fBauto\fR
+(determine the appropriate log target automatically, the default),
+\fBnull\fR
+(disable log output)\&.
+.RE
+.PP
+\fI$SYSTEMD_LOG_RATELIMIT_KMSG\fR
+.RS 4
+Whether to ratelimit kmsg or not\&. Takes a boolean\&. Defaults to
+"true"\&. If disabled, systemd will not ratelimit messages written to kmsg\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGER\fR
+.RS 4
+Pager to use when
+\fB\-\-no\-pager\fR
+is not given; overrides
+\fI$PAGER\fR\&. If neither
+\fI$SYSTEMD_PAGER\fR
+nor
+\fI$PAGER\fR
+are set, a set of well\-known pager implementations are tried in turn, including
+\fBless\fR(1)
+and
+\fBmore\fR(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
+\fB\-\-no\-pager\fR\&.
+.sp
+Note: if
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set,
+\fI$SYSTEMD_PAGER\fR
+(as well as
+\fI$PAGER\fR) will be silently ignored\&.
+.RE
+.PP
+\fI$SYSTEMD_LESS\fR
+.RS 4
+Override the options passed to
+\fBless\fR
+(by default
+"FRSXMK")\&.
+.sp
+Users might want to change two options in particular:
+.PP
+\fBK\fR
+.RS 4
+This option instructs the pager to exit immediately when
+Ctrl+C
+is pressed\&. To allow
+\fBless\fR
+to handle
+Ctrl+C
+itself to switch back to the pager command prompt, unset this option\&.
+.sp
+If the value of
+\fI$SYSTEMD_LESS\fR
+does not include
+"K", and the pager that is invoked is
+\fBless\fR,
+Ctrl+C
+will be ignored by the executable, and needs to be handled by the pager\&.
+.RE
+.PP
+\fBX\fR
+.RS 4
+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
+See
+\fBless\fR(1)
+for more discussion\&.
+.RE
+.PP
+\fI$SYSTEMD_LESSCHARSET\fR
+.RS 4
+Override the charset passed to
+\fBless\fR
+(by default
+"utf\-8", if the invoking terminal is determined to be UTF\-8 compatible)\&.
+.RE
+.PP
+\fI$SYSTEMD_PAGERSECURE\fR
+.RS 4
+Takes a boolean argument\&. When true, the "secure" mode of the pager is enabled; if false, disabled\&. If
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, secure mode is enabled if the effective UID is not the same as the owner of the login session, see
+\fBgeteuid\fR(2)
+and
+\fBsd_pid_get_owner_uid\fR(3)\&. In secure mode,
+\fBLESSSECURE=1\fR
+will be set when invoking the pager, and the pager shall disable commands that open or create new files or start new subprocesses\&. When
+\fI$SYSTEMD_PAGERSECURE\fR
+is not set at all, pagers which are not known to implement secure mode will not be used\&. (Currently only
+\fBless\fR(1)
+implements secure mode\&.)
+.sp
+Note: when commands are invoked with elevated privileges, for example under
+\fBsudo\fR(8)
+or
+\fBpkexec\fR(1), care must be taken to ensure that unintended interactive features are not enabled\&. "Secure" mode for the pager may be enabled automatically as describe above\&. Setting
+\fISYSTEMD_PAGERSECURE=0\fR
+or not removing it from the inherited environment allows the user to invoke arbitrary commands\&. Note that if the
+\fI$SYSTEMD_PAGER\fR
+or
+\fI$PAGER\fR
+variables are to be honoured,
+\fI$SYSTEMD_PAGERSECURE\fR
+must be set too\&. It might be reasonable to completely disable the pager using
+\fB\-\-no\-pager\fR
+instead\&.
+.RE
+.PP
+\fI$SYSTEMD_COLORS\fR
+.RS 4
+Takes a boolean argument\&. When true,
+\fBsystemd\fR
+and related utilities will use colors in their output, otherwise the output will be monochrome\&. Additionally, the variable can take one of the following special values:
+"16",
+"256"
+to restrict the use of colors to the base 16 or 256 ANSI colors, respectively\&. This can be specified to override the automatic decision based on
+\fI$TERM\fR
+and what the console is connected to\&.
+.RE
+.PP
+\fI$SYSTEMD_URLIFY\fR
+.RS 4
+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
+\fBsystemd\fR
+makes based on
+\fI$TERM\fR
+and other conditions\&.
+.RE
+.SH "SEE ALSO"
+.PP
+\fBsystemd\fR(1),
+\fBsystemd-userdbd.service\fR(8),
+\fBsystemd-homed.service\fR(8),
+\fBnss-systemd\fR(8),
+\fBgetent\fR(1)
+.SH "NOTES"
+.IP " 1." 4
+JSON User Records
+.RS 4
+\%https://systemd.io/USER_RECORD
+.RE
+.IP " 2." 4
+JSON Group Records
+.RS 4
+\%https://systemd.io/GROUP_RECORD
+.RE
+.IP " 3." 4
+User/Group Record Lookup API via Varlink
+.RS 4
+\%https://systemd.io/USER_GROUP_API
+.RE