mirror of
https://github.com/systemd/systemd.git
synced 2024-11-27 20:23:36 +08:00
251 lines
10 KiB
XML
251 lines
10 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-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
|
|
|
|
systemd is free software; you can redistribute it and/or modify it
|
|
under the terms of the GNU Lesser General Public License as published by
|
|
the Free Software Foundation; either version 2.1 of the License, or
|
|
(at your option) any later version.
|
|
|
|
systemd is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public License
|
|
along with systemd; If not, see <http://www.gnu.org/licenses/>.
|
|
-->
|
|
<refentry id="sysusers.d" conditional='ENABLE_SYSUSERS'
|
|
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>/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 (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 Directories and Precedence</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>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 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>
|
|
|
|
<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
|
|
do not exist 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. 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>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 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
|
|
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>
|
|
|
|
<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 is 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>
|