summaryrefslogtreecommitdiff
path: root/man/sysusers.d.xml
diff options
context:
space:
mode:
Diffstat (limited to 'man/sysusers.d.xml')
-rw-r--r--man/sysusers.d.xml427
1 files changed, 193 insertions, 234 deletions
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
index ac2db98853..99aa07a1cc 100644
--- a/man/sysusers.d.xml
+++ b/man/sysusers.d.xml
@@ -20,245 +20,204 @@
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="sysusers.d"
- xmlns:xi="http://www.w3.org/2001/XInclude">
-
- <refentryinfo>
- <title>sysusers.d</title>
- <productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
- </refentryinfo>
-
- <refmeta>
- <refentrytitle>sysusers.d</refentrytitle>
- <manvolnum>5</manvolnum>
- </refmeta>
-
- <refnamediv>
- <refname>sysusers.d</refname>
- <refpurpose>Declarative allocation of system users and groups</refpurpose>
- </refnamediv>
-
- <refsynopsisdiv>
- <para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
- </refsynopsisdiv>
-
- <refsect1>
- <title>Description</title>
-
- <para><command>systemd-sysusers</command> uses the
- files from <filename>sysusers.d</filename> directory
- to create system users and groups at package
- installation or boot time. This tool may be used to
- allocate system users and groups only, it is not
- useful for creating non-system users and groups, as it
- accesses <filename>/etc/passwd</filename> and
- <filename>/etc/group</filename> directly, bypassing
- any more complex user databases, for example any
- database involving NIS or LDAP.</para>
- </refsect1>
-
- <refsect1>
- <title>Configuration Format</title>
-
- <para>Each configuration file shall be named in the
- style of
- <filename><replaceable>package</replaceable>.conf</filename>
- or
- <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
- The second variant should be used when it is desirable
- to make it easy to override just this part of
- configuration.</para>
-
- <para>The file format is one line per user or group
- containing name, ID, GECOS field description and home directory:</para>
-
- <programlisting># Type Name ID GECOS
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+ <refentryinfo>
+ <title>sysusers.d</title>
+ <productname>systemd</productname>
+
+ <authorgroup>
+ <author>
+ <contrib>Developer</contrib>
+ <firstname>Lennart</firstname>
+ <surname>Poettering</surname>
+ <email>lennart@poettering.net</email>
+ </author>
+ </authorgroup>
+ </refentryinfo>
+
+ <refmeta>
+ <refentrytitle>sysusers.d</refentrytitle>
+ <manvolnum>5</manvolnum>
+ </refmeta>
+
+ <refnamediv>
+ <refname>sysusers.d</refname>
+ <refpurpose>Declarative allocation of system users and groups</refpurpose>
+ </refnamediv>
+
+ <refsynopsisdiv>
+ <para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
+ </refsynopsisdiv>
+
+ <refsect1>
+ <title>Description</title>
+
+ <para><command>systemd-sysusers</command> uses the files from
+ <filename>sysusers.d</filename> directory to create system users
+ and groups at package installation or boot time. This tool may be
+ used to allocate system users and groups only, it is not useful
+ for creating non-system users and groups, as it accesses
+ <filename>/etc/passwd</filename> and
+ <filename>/etc/group</filename> directly, bypassing any more
+ complex user databases, for example any database involving NIS or
+ LDAP.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>Configuration Format</title>
+
+ <para>Each configuration file shall be named in the style of
+ <filename><replaceable>package</replaceable>.conf</filename> or
+ <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
+ The second variant should be used when it is desirable to make it
+ easy to override just this part of configuration.</para>
+
+ <para>The file format is one line per user or group containing
+ name, ID, GECOS field description and home directory:</para>
+
+ <programlisting># Type Name ID GECOS
u httpd 440 "HTTP User"
u authd /usr/bin/authd "Authorization user"
g input - -
m authd input
u root 0 "Superuser" /root</programlisting>
- <refsect2>
- <title>Type</title>
-
- <para>The type consists of a single
- letter. The following line types are
- understood:</para>
-
- <variablelist>
- <varlistentry>
- <term><varname>u</varname></term>
- <listitem><para>Create a
- system user and group of the
- specified name should they not
- exist yet. The user's primary
- group will be set to the group
- bearing the same name. The
- user's shell will be set to
- <filename>/sbin/nologin</filename>,
- the home directory to the
- specified home directory, or
- <filename>/</filename> if none
- is given. The account will be
- created disabled, so that
- logins are not
- allowed.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>g</varname></term>
- <listitem><para>Create a
- system group of the specified
- name should it not exist
- yet. Note that
- <varname>u</varname>
- implicitly create a matching
- group. The group will be
- created with no password
- set.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>m</varname></term>
- <listitem><para>Add a user to
- a group. If the user or group
- are not existing yet, they
- will be implicitly
- created.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><varname>r</varname></term>
- <listitem><para>Add a range of
- numeric UIDs/GIDs to the pool
- to allocate new UIDs and GIDs
- from. If no line of this type
- is specified the range of
- UIDs/GIDs is set to some
- compiled-in default. Note that
- both UIDs and GIDs are
- allocated from the same pool,
- in order to ensure that users
- and groups of the same name
- are likely to carry the same
- numeric UID and
- GID.</para></listitem>
- </varlistentry>
-
- </variablelist>
- </refsect2>
-
- <refsect2>
- <title>Name</title>
-
- <para>The name field specifies the user or
- group name. It should be shorter than 31
- characters and avoid any non-ASCII characters,
- and not begin with a numeric character. It is
- strongly recommended to pick user and group
- names that are unlikely to clash with normal
- users created by the administrator. A good
- scheme to guarantee this is by prefixing all
- system and group names with the underscore,
- and avoiding too generic names.</para>
-
- <para>For <varname>m</varname> lines this
- field should contain the user name to add to a
- group.</para>
-
- <para>For lines of type <varname>r</varname>
- this field should be set to
- <literal>-</literal>.</para>
- </refsect2>
-
- <refsect2>
- <title>ID</title>
-
- <para>For <varname>u</varname> and
- <varname>g</varname> the numeric 32bit UID or
- GID of the user/group. Do not use IDs 65535 or
- 4294967295, as they have special placeholder
- meanings. Specify <literal>-</literal> for
- automatic UID/GID allocation for the user or
- group. Alternatively, specify an absolute path
- in the file system. In this case the UID/GID
- is read from the path's owner/group. This is
- useful to create users whose UID/GID match the
- owners of pre-existing files (such as SUID or
- SGID binaries).</para>
-
- <para>For <varname>m</varname> lines this
- field should contain the group name to add to
- a user to.</para>
-
- <para>For lines of type <varname>r</varname>
- this field should be set to a UID/GID range in
- the format <literal>FROM-TO</literal> where
- both values are formatted as decimal ASCII
- numbers. Alternatively, a single UID/GID may
- be specified formatted as decimal ASCII
- numbers.</para>
- </refsect2>
-
- <refsect2>
- <title>GECOS</title>
-
- <para>A short, descriptive string for users to
- be created, enclosed in quotation marks. Note
- that this field may not contain colons.</para>
-
- <para>Only applies to lines of type
- <varname>u</varname> and should otherwise be
- left unset, or be set to
- <literal>-</literal>.</para>
- </refsect2>
-
- <refsect2>
- <title>Home Directory</title>
-
- <para>The home directory for a new system
- user. If omitted defaults to the root
- directory. It is recommended to not
- unnecessarily specify home directories for
- system users, unless software strictly
- requires one to be set.</para>
-
- <para>Only applies to lines of type
- <varname>u</varname> and should otherwise be
- left unset, or be set to
- <literal>-</literal>.</para>
- </refsect2>
-
- </refsect1>
-
- <xi:include href="standard-conf.xml" xpointer="confd" />
-
- <refsect1>
- <title>Idempotence</title>
-
- <para>Note that <command>systemd-sysusers</command>
- will do nothing if the specified users or groups
- already exist, so normally there no reason to override
- <filename>sysusers.d</filename> vendor configuration,
- except to block certain users or groups from being
- created.</para>
- </refsect1>
-
- <refsect1>
- <title>See Also</title>
- <para>
- <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- </para>
- </refsect1>
+ <refsect2>
+ <title>Type</title>
+
+ <para>The type consists of a single letter. The following line
+ types are understood:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><varname>u</varname></term>
+ <listitem><para>Create a system user and group of the
+ specified name should they not exist yet. The user's primary
+ group will be set to the group bearing the same name. The
+ user's shell will be set to
+ <filename>/sbin/nologin</filename>, the home directory to
+ the specified home directory, or <filename>/</filename> if
+ none is given. The account will be created disabled, so that
+ logins are not allowed.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>g</varname></term>
+ <listitem><para>Create a system group of the specified name
+ should it not exist yet. Note that <varname>u</varname>
+ implicitly create a matching group. The group will be
+ created with no password set.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>m</varname></term>
+ <listitem><para>Add a user to a group. If the user or group
+ are not existing yet, they will be implicitly
+ created.</para></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><varname>r</varname></term>
+ <listitem><para>Add a range of numeric UIDs/GIDs to the pool
+ to allocate new UIDs and GIDs from. If no line of this type
+ is specified the range of UIDs/GIDs is set to some
+ compiled-in default. Note that both UIDs and GIDs are
+ allocated from the same pool, in order to ensure that users
+ and groups of the same name are likely to carry the same
+ numeric UID and GID.</para></listitem>
+ </varlistentry>
+
+ </variablelist>
+ </refsect2>
+
+ <refsect2>
+ <title>Name</title>
+
+ <para>The name field specifies the user or group name. It should
+ be shorter than 31 characters and avoid any non-ASCII
+ characters, and not begin with a numeric character. It is
+ strongly recommended to pick user and group names that are
+ unlikely to clash with normal users created by the
+ administrator. A good scheme to guarantee this is by prefixing
+ all system and group names with the underscore, and avoiding too
+ generic names.</para>
+
+ <para>For <varname>m</varname> lines this field should contain
+ the user name to add to a group.</para>
+
+ <para>For lines of type <varname>r</varname> this field should
+ be set to <literal>-</literal>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>ID</title>
+
+ <para>For <varname>u</varname> and <varname>g</varname> the
+ numeric 32bit UID or GID of the user/group. Do not use IDs 65535
+ or 4294967295, as they have special placeholder meanings.
+ Specify <literal>-</literal> for automatic UID/GID allocation
+ for the user or group. Alternatively, specify an absolute path
+ in the file system. In this case the UID/GID is read from the
+ path's owner/group. This is useful to create users whose UID/GID
+ match the owners of pre-existing files (such as SUID or SGID
+ binaries).</para>
+
+ <para>For <varname>m</varname> lines this field should contain
+ the group name to add to a user to.</para>
+
+ <para>For lines of type <varname>r</varname> this field should
+ be set to a UID/GID range in the format
+ <literal>FROM-TO</literal> where both values are formatted as
+ decimal ASCII numbers. Alternatively, a single UID/GID may be
+ specified formatted as decimal ASCII numbers.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>GECOS</title>
+
+ <para>A short, descriptive string for users to be created,
+ enclosed in quotation marks. Note that this field may not
+ contain colons.</para>
+
+ <para>Only applies to lines of type <varname>u</varname> and
+ should otherwise be left unset, or be set to
+ <literal>-</literal>.</para>
+ </refsect2>
+
+ <refsect2>
+ <title>Home Directory</title>
+
+ <para>The home directory for a new system user. If omitted
+ defaults to the root directory. It is recommended to not
+ unnecessarily specify home directories for system users, unless
+ software strictly requires one to be set.</para>
+
+ <para>Only applies to lines of type <varname>u</varname> and
+ should otherwise be left unset, or be set to
+ <literal>-</literal>.</para>
+ </refsect2>
+
+ </refsect1>
+
+ <xi:include href="standard-conf.xml" xpointer="confd" />
+
+ <refsect1>
+ <title>Idempotence</title>
+
+ <para>Note that <command>systemd-sysusers</command> will do
+ nothing if the specified users or groups already exist, so
+ normally there no reason to override
+ <filename>sysusers.d</filename> vendor configuration, except to
+ block certain users or groups from being created.</para>
+ </refsect1>
+
+ <refsect1>
+ <title>See Also</title>
+ <para>
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ </para>
+ </refsect1>
</refentry>