shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-10-30 06:25:37 +03:00
Code
331f44c149
systemd/man/systemd-sysusers.xml

210 lines
10 KiB
XML
Raw Normal View History

man: document the sysusers tool
2014-06-30 00:15:01 +04:00
<?xml version='1.0'?> <!--*-nxml-*-->
man: use same header for all files The "include" files had type "book" for some raeason. I don't think this is meaningful. Let's just use the same everywhere. $ perl -i -0pe 's^..DOCTYPE (book|refentry) PUBLIC "-//OASIS//DTD DocBook XML V4.[25]//EN"\s+"http^<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"\n "http^gms' man/*.xml
2019-03-14 16:40:58 +03:00
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
man: revert dynamic paths for split-usr setups This did not really work out as we had hoped. Trying to do this upstream introduced several problems that probably makes it better suited as a downstream patch after all. At any rate, it is not releaseable in the current state, so we at least need to revert this before the release. * by adjusting the path to binaries, but not do the same thing to the search path we end up with inconsistent man-pages. Adjusting the search path too would be quite messy, and it is not at all obvious that this is worth the effort, but at any rate it would have to be done before we could ship this. * this means that distributed man-pages does not make sense as they depend on config options, and for better or worse we are still distributing man pages, so that is something that definitely needs sorting out before we could ship with this patch. * we have long held that split-usr is only minimally supported in order to boot, and something we hope will eventually go away. So before we start adding even more magic/effort in order to make this work nicely, we should probably question if it makes sense at all.
2015-06-18 20:47:44 +03:00
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: document the sysusers tool
2014-06-30 00:15:01 +04:00
<refentry id="systemd-sysusers"
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-sysusers</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-sysusers</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-sysusers</refname>
<refname>systemd-sysusers.service</refname>
<refpurpose>Allocate system users and groups</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>systemd-sysusers</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg>
</cmdsynopsis>
<para><filename>systemd-sysusers.service</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-sysusers</command> creates system users and
groups, based on the file format and location specified in
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
sysusers: allow admin/runtime overrides to command-line config When used in a package installation script, we want to invoke systemd-sysusers before that package is installed (so it can contain files owned by the newly created user), so the configuration to use is specified on the command line. This should be a copy of the configuration that will be installed as /usr/lib/sysusers.d/package.conf. We still want to obey any overrides in /etc/sysusers.d or /run/sysusers.d in the usual fashion. Otherwise, we'd get a different result when systemd-sysusers is run with a copy of the new config on the command line and when systemd-sysusers is run at boot after package instalation. In the second case any files in /etc or /run have higher priority, so the same should happen when the configuration is given on the command line. More generally, we want the behaviour in this special case to be as close to the case where the file is finally on disk as possible, so we have to read all configuration files, since they all might contain overrides and additional configuration that matters. Even files that have lower priority might specify additional groups for the user we are creating. Thus, we need to read all configuration, but insert our new configuration somewhere with the right priority. If --target=/path/to/file.conf is given on the command line, we gather the list of files, and pretend that the command-line config is read from /path/to/file.conf (doesn't matter if the file on disk actually exists or not). All package scripts should use this option to obtain consistent and idempotent behaviour. The corner case when --target= is specified and there are no positional arguments is disallowed. v1: - version with --config-name= v2: - disallow --config-name= and no positional args v3: - remove --config-name= v4: - add --target= and rework the code completely v5: - fix argcounting bug and add example in man page v6: - rename --target to --replace
2018-01-31 17:37:02 +03:00
<para>If invoked with no arguments, it applies all directives from all files
found in the directories specified by
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
When invoked with positional arguments, if option
<option>--replace=<replaceable>PATH</replaceable></option> is specified, arguments
specified on the command line are used instead of the configuration file
<replaceable>PATH</replaceable>. Otherwise, just the configuration specified by
the command line arguments is executed. The string <literal>-</literal> may be
specified instead of a filename to instruct <command>systemd-sysusers</command>
to read the configuration from standard input. If only the basename of a file is
specified, all configuration directories are searched for a matching file and
the file found that has the highest priority is executed.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--root=<replaceable>root</replaceable></option></term>
<listitem><para>Takes a directory path as an argument. All
paths will be prefixed with the given alternate
<replaceable>root</replaceable> path, including config search
paths. </para></listitem>
</varlistentry>
man: document the new --image= switches in journalctl/sysusers/tmpfiles
2020-07-28 20:28:43 +03:00
<varlistentry>
<term><option>--image=<replaceable>image</replaceable></option></term>
<listitem><para>Takes a path to a disk image file or block device node. If specified all operations
are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
but operates on file systems stored in disk images or block devices. The disk image should either
contain just a file system or a set of file systems within a GPT partition table, following the
<ulink url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para></listitem>
</varlistentry>
sysusers: allow admin/runtime overrides to command-line config When used in a package installation script, we want to invoke systemd-sysusers before that package is installed (so it can contain files owned by the newly created user), so the configuration to use is specified on the command line. This should be a copy of the configuration that will be installed as /usr/lib/sysusers.d/package.conf. We still want to obey any overrides in /etc/sysusers.d or /run/sysusers.d in the usual fashion. Otherwise, we'd get a different result when systemd-sysusers is run with a copy of the new config on the command line and when systemd-sysusers is run at boot after package instalation. In the second case any files in /etc or /run have higher priority, so the same should happen when the configuration is given on the command line. More generally, we want the behaviour in this special case to be as close to the case where the file is finally on disk as possible, so we have to read all configuration files, since they all might contain overrides and additional configuration that matters. Even files that have lower priority might specify additional groups for the user we are creating. Thus, we need to read all configuration, but insert our new configuration somewhere with the right priority. If --target=/path/to/file.conf is given on the command line, we gather the list of files, and pretend that the command-line config is read from /path/to/file.conf (doesn't matter if the file on disk actually exists or not). All package scripts should use this option to obtain consistent and idempotent behaviour. The corner case when --target= is specified and there are no positional arguments is disallowed. v1: - version with --config-name= v2: - disallow --config-name= and no positional args v3: - remove --config-name= v4: - add --target= and rework the code completely v5: - fix argcounting bug and add example in man page v6: - rename --target to --replace
2018-01-31 17:37:02 +03:00
<varlistentry>
<term><option>--replace=<replaceable>PATH</replaceable></option></term>
Typos found by codespell
2021-10-20 10:38:57 +03:00
<listitem><para>When this option is given, one or more positional arguments
sysusers: allow admin/runtime overrides to command-line config When used in a package installation script, we want to invoke systemd-sysusers before that package is installed (so it can contain files owned by the newly created user), so the configuration to use is specified on the command line. This should be a copy of the configuration that will be installed as /usr/lib/sysusers.d/package.conf. We still want to obey any overrides in /etc/sysusers.d or /run/sysusers.d in the usual fashion. Otherwise, we'd get a different result when systemd-sysusers is run with a copy of the new config on the command line and when systemd-sysusers is run at boot after package instalation. In the second case any files in /etc or /run have higher priority, so the same should happen when the configuration is given on the command line. More generally, we want the behaviour in this special case to be as close to the case where the file is finally on disk as possible, so we have to read all configuration files, since they all might contain overrides and additional configuration that matters. Even files that have lower priority might specify additional groups for the user we are creating. Thus, we need to read all configuration, but insert our new configuration somewhere with the right priority. If --target=/path/to/file.conf is given on the command line, we gather the list of files, and pretend that the command-line config is read from /path/to/file.conf (doesn't matter if the file on disk actually exists or not). All package scripts should use this option to obtain consistent and idempotent behaviour. The corner case when --target= is specified and there are no positional arguments is disallowed. v1: - version with --config-name= v2: - disallow --config-name= and no positional args v3: - remove --config-name= v4: - add --target= and rework the code completely v5: - fix argcounting bug and add example in man page v6: - rename --target to --replace
2018-01-31 17:37:02 +03:00
must be specified. All configuration files found in the directories listed in
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
will be read, and the configuration given on the command line will be
handled instead of and with the same priority as the configuration file
<replaceable>PATH</replaceable>.</para>
<para>This option is intended to be used when package installation scripts
are running and files belonging to that package are not yet available on
disk, so their contents must be given on the command line, but the admin
configuration might already exist and should be given higher priority.
</para>
<example>
<title>RPM installation script for radvd</title>
<programlisting>echo 'u radvd - "radvd daemon"' | \
systemd-sysusers --replace=/usr/lib/sysusers.d/radvd.conf -</programlisting>
<para>This will create the radvd user as if
<filename>/usr/lib/sysusers.d/radvd.conf</filename> was already on disk.
An admin might override the configuration specified on the command line by
placing <filename>/etc/sysusers.d/radvd.conf</filename> or even
<filename>/etc/sysusers.d/00-overrides.conf</filename>.</para>
man/systemd-sysusers: Fix typo in *from* to *form*
2019-04-08 11:53:55 +03:00
<para>Note that this is the expanded form, and when used in a package, this
sysusers: allow admin/runtime overrides to command-line config When used in a package installation script, we want to invoke systemd-sysusers before that package is installed (so it can contain files owned by the newly created user), so the configuration to use is specified on the command line. This should be a copy of the configuration that will be installed as /usr/lib/sysusers.d/package.conf. We still want to obey any overrides in /etc/sysusers.d or /run/sysusers.d in the usual fashion. Otherwise, we'd get a different result when systemd-sysusers is run with a copy of the new config on the command line and when systemd-sysusers is run at boot after package instalation. In the second case any files in /etc or /run have higher priority, so the same should happen when the configuration is given on the command line. More generally, we want the behaviour in this special case to be as close to the case where the file is finally on disk as possible, so we have to read all configuration files, since they all might contain overrides and additional configuration that matters. Even files that have lower priority might specify additional groups for the user we are creating. Thus, we need to read all configuration, but insert our new configuration somewhere with the right priority. If --target=/path/to/file.conf is given on the command line, we gather the list of files, and pretend that the command-line config is read from /path/to/file.conf (doesn't matter if the file on disk actually exists or not). All package scripts should use this option to obtain consistent and idempotent behaviour. The corner case when --target= is specified and there are no positional arguments is disallowed. v1: - version with --config-name= v2: - disallow --config-name= and no positional args v3: - remove --config-name= v4: - add --target= and rework the code completely v5: - fix argcounting bug and add example in man page v6: - rename --target to --replace
2018-01-31 17:37:02 +03:00
would be written using a macro with "radvd" and a file containing the
configuration line as arguments.</para>
</example>
</listitem>
</varlistentry>
sysusers: add --dry-run
2021-12-08 12:33:53 +03:00
<varlistentry>
<term><option>--dry-run</option></term>
<listitem><para>Process the configuration and figure out what entries would be created, but don't
actually write anything.</para></listitem>
</varlistentry>
sysusers: take configuration as positional arguments If the configuration is included in a script, this is more convient. I thought it would be possible to use this for rpm scriptlets with '%pre -p systemd-sysuser "..."', but apparently there is no way to pass arguments to the executable ($1 is used for the package installation count). But this functionality seems generally useful, e.g. for testing and one-off scripts, so let's keep it. There's a slight change in behaviour when files are given on the command line: if we cannot parse them, error out instead of ignoring the failure. When trying to parse all configuration files, we don't want to fail even if some config files are broken, but when parsing a list of items specified explicitly, we should. v2: - rename --direct to --inline
2018-01-29 16:47:01 +03:00
<varlistentry>
<term><option>--inline</option></term>
<listitem><para>Treat each positional argument as a separate configuration
line instead of a file name.</para></listitem>
</varlistentry>
sysusers: add --cat-config
2018-04-26 21:38:39 +03:00
<xi:include href="standard-options.xml" xpointer="cat-config" />
binfmt,sysctl,sysuers,tmpfiles: add auto-paging for --cat-config commands The output of these commands is really long, and already enriched with color. Let's add auto-paging to make this easier to digest.
2018-06-12 16:37:53 +03:00
<xi:include href="standard-options.xml" xpointer="no-pager" />
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
sysusers: read passwords from the credentials logic Let's make use of our own credentials infrastructure in our tools: let's hook up systemd-sysusers with the credentials logic, so that the root password can be provisioned this way. This is really useful when working with stateless systems, in particular nspawn's "--volatile=yes" switch, as this works now: # systemd-nspawn -i foo.raw --volatile=yes --set-credential=passwd.plaintext-password:foo For the first time we have a nice, non-interactive way to provision the root password for a fully stateless system from the container manager. Yay!
2021-03-11 12:34:20 +03:00
</refsect1>
<refsect1>
<title>Credentials</title>
<para><command>systemd-sysusers</command> supports the service credentials logic as implemented by
<varname>LoadCredential=</varname>/<varname>SetCredential=</varname> (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> for
details). The following credentials are used when passed in:</para>
<variablelist>
<varlistentry>
<term><literal>passwd.hashed-password.<replaceable>user</replaceable></literal></term>
<listitem><para>A UNIX hashed password string to use for the specified user, when creating an entry
for it. This is particularly useful for the <literal>root</literal> user as it allows provisioning
the default root password to use via a unit file drop-in or from a container manager passing in this
credential. Note that setting this credential has no effect if the specified user account already
exists. This credential is hence primarily useful in first boot scenarios or systems that are fully
stateless and come up with an empty <filename>/etc/</filename> on every boot.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>passwd.plaintext-password.<replaceable>user</replaceable></literal></term>
<listitem><para>Similar to <literal>passwd.hashed-password.<replaceable>user</replaceable></literal>
but expect a literal, plaintext password, which is then automatically hashed before used for the user
account. If both the hashed and the plaintext credential are specified for the same user the
former takes precedence. It's generally recommended to specify the hashed version; however in test
environments with weaker requirements on security it might be easier to pass passwords in plaintext
instead.</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>passwd.shell.<replaceable>user</replaceable></literal></term>
tree-wide: fix "the the" and "a a"
2021-06-30 14:53:14 +03:00
<listitem><para>Specifies the shell binary to use for the specified account when creating it.</para></listitem>
sysusers: read passwords from the credentials logic Let's make use of our own credentials infrastructure in our tools: let's hook up systemd-sysusers with the credentials logic, so that the root password can be provisioned this way. This is really useful when working with stateless systems, in particular nspawn's "--volatile=yes" switch, as this works now: # systemd-nspawn -i foo.raw --volatile=yes --set-credential=passwd.plaintext-password:foo For the first time we have a nice, non-interactive way to provision the root password for a fully stateless system from the container manager. Yay!
2021-03-11 12:34:20 +03:00
</varlistentry>
</variablelist>
<para>Note that by default the <filename>systemd-sysusers.service</filename> unit file is set up to
inherit the <literal>passwd.hashed-password.root</literal>,
<literal>passwd.plaintext-password.root</literal> and <literal>passwd.shell.root</literal> credentials
from the service manager. Thus, when invoking a container with an unpopulated <filename>/etc/</filename>
for the first time it is possible to configure the root user's password to be <literal>systemd</literal>
like this:</para>
man systemd-sysusers: fix password to passwd
2021-08-06 21:05:18 +03:00
<para><programlisting># systemd-nspawn --image=… --set-credential=passwd.hashed-password.root:'$y$j9T$yAuRJu1o5HioZAGDYPU5d.$F64ni6J2y2nNQve90M/p0ZP0ECP/qqzipNyaY9fjGpC' …</programlisting></para>
sysusers: read passwords from the credentials logic Let's make use of our own credentials infrastructure in our tools: let's hook up systemd-sysusers with the credentials logic, so that the root password can be provisioned this way. This is really useful when working with stateless systems, in particular nspawn's "--volatile=yes" switch, as this works now: # systemd-nspawn -i foo.raw --volatile=yes --set-credential=passwd.plaintext-password:foo For the first time we have a nice, non-interactive way to provision the root password for a fully stateless system from the container manager. Yay!
2021-03-11 12:34:20 +03:00
<para>Note again that the data specified in these credentials is consulted only when creating an account
for the first time, it may not be used for changing the password or shell of an account that already
exists.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
sysusers: read passwords from the credentials logic Let's make use of our own credentials infrastructure in our tools: let's hook up systemd-sysusers with the credentials logic, so that the root password can be provisioned this way. This is really useful when working with stateless systems, in particular nspawn's "--volatile=yes" switch, as this works now: # systemd-nspawn -i foo.raw --volatile=yes --set-credential=passwd.plaintext-password:foo For the first time we have a nice, non-interactive way to provision the root password for a fully stateless system from the container manager. Yay!
2021-03-11 12:34:20 +03:00
<para>Use <citerefentry><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for generating UNIX password hashes from the command line.</para>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</refsect1>
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned, a non-zero failure code
otherwise.</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
man: link two more documents from systemd.io from appropriate man pages
2018-10-12 15:06:41 +03:00
<citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
sysusers: read passwords from the credentials logic Let's make use of our own credentials infrastructure in our tools: let's hook up systemd-sysusers with the credentials logic, so that the root password can be provisioned this way. This is really useful when working with stateless systems, in particular nspawn's "--volatile=yes" switch, as this works now: # systemd-nspawn -i foo.raw --volatile=yes --set-credential=passwd.plaintext-password:foo For the first time we have a nice, non-interactive way to provision the root password for a fully stateless system from the container manager. Yay!
2021-03-11 12:34:20 +03:00
<ulink url="https://systemd.io/UIDS-GIDS">Users, Groups, UIDs and GIDs on systemd systems</ulink>,
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>mkpasswd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
Reindent man pages to 2ch
2015-02-04 05:14:13 +03:00
</para>
</refsect1>
man: document the sysusers tool
2014-06-30 00:15:01 +04:00
</refentry>
Copy Permalink