<!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2014 Lennart Poettering
</refnamediv>
<refsynopsisdiv>
+ <para><filename>/etc/sysusers.d/*.conf</filename></para>
+ <para><filename>/run/sysusers.d/*.conf</filename></para>
<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>
+ <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 (i.e. regular, "human") 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>
+ <title>Configuration Directories and Precedence</title>
<para>Each configuration file shall be named in the style of
<filename><replaceable>package</replaceable>.conf</filename> or
The second variant should be used when it is desirable to make it
easy to override just this part of configuration.</para>
+ <para>Files in <filename>/etc/sysusers.d</filename> override files
+ with the same name in <filename>/usr/lib/sysusers.d</filename> and
+ <filename>/run/sysusers.d</filename>. Files in
+ <filename>/run/sysusers.d</filename> override files with the same
+ name in <filename>/usr/lib/sysusers.d</filename>. Packages should
+ install their configuration files in
+ <filename>/usr/lib/sysusers.d</filename>. Files in
+ <filename>/etc/sysusers.d</filename> are reserved for the local
+ administrator, who may use this logic to override the
+ configuration files installed by vendor packages. All
+ configuration files are sorted by their filename in lexicographic
+ order, regardless of which of the directories they reside in. If
+ multiple files specify the same path, the entry in the file with
+ the lexicographically earliest name will be applied. All later
+ entries for the same user and group names will be logged as warnings.
+ </para>
+
+ <para>If the administrator wants to disable a configuration file
+ supplied by the vendor, the recommended way is to place a symlink
+ to <filename>/dev/null</filename> in
+ <filename>/etc/sysusers.d/</filename> bearing the same filename.
+ </para>
+ </refsect1>
+
+ <refsect1>
+ <title>Configuration File Format</title>
+
<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>
+ <programlisting>#Type Name ID GECOS Home directory
+u httpd 440 "HTTP User"
+u authd /usr/bin/authd "Authorization user"
+g input - -
+m authd input
+u root 0 "Superuser" /root</programlisting>
+
+ <para>Empty lines and lines beginning with the <literal>#</literal> character are ignored, and may be used for
+ commenting.</para>
<refsect2>
<title>Type</title>
<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
+ do not exist yet, they will be implicitly
created.</para></listitem>
</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
+ 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
<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>The name field specifies the user or group name. The specified name must consist only of the characters a-z,
+ A-Z, 0-9, <literal>_</literal> and <literal>-</literal>, except for the first character which must be one of a-z,
+ A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted as first character). The
+ user/group name must have at least one character, and at most 31.</para>
- <para>For <varname>m</varname> lines this field should contain
+ <para>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
+ <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
+ <para>For <varname>u</varname> and <varname>g</varname>, the
+ numeric 32-bit 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
+ 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
+ <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
+ <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
+ <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>Home Directory</title>
- <para>The home directory for a new system user. If omitted
+ <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>
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
+ normally, there is no reason to override
<filename>sysusers.d</filename> vendor configuration, except to
block certain users or groups from being created.</para>
</refsect1>
projects / thirdparty / systemd.git / blobdiff