21236ab51082668914b933041893a1cf45218a3dLennart Poettering<!--*-nxml-*-->
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
21236ab51082668914b933041893a1cf45218a3dLennart Poettering This file is part of systemd.
21236ab51082668914b933041893a1cf45218a3dLennart Poettering Copyright 2014 Lennart Poettering
21236ab51082668914b933041893a1cf45218a3dLennart Poettering systemd is free software; you can redistribute it and/or modify it
21236ab51082668914b933041893a1cf45218a3dLennart Poettering under the terms of the GNU Lesser General Public License as published by
21236ab51082668914b933041893a1cf45218a3dLennart Poettering the Free Software Foundation; either version 2.1 of the License, or
21236ab51082668914b933041893a1cf45218a3dLennart Poettering (at your option) any later version.
21236ab51082668914b933041893a1cf45218a3dLennart Poettering systemd is distributed in the hope that it will be useful, but
21236ab51082668914b933041893a1cf45218a3dLennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
21236ab51082668914b933041893a1cf45218a3dLennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21236ab51082668914b933041893a1cf45218a3dLennart Poettering Lesser General Public License for more details.
21236ab51082668914b933041893a1cf45218a3dLennart Poettering You should have received a copy of the GNU Lesser General Public License
21236ab51082668914b933041893a1cf45218a3dLennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
e6de49abfd28098c65b8a0be05bb84cf6cf780aeMichael Biebl<refentry id="sysusers.d" conditional='ENABLE_SYSUSERS'
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek xmlns:xi="http://www.w3.org/2001/XInclude">
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>sysusers.d</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Declarative allocation of system users and groups</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><command>systemd-sysusers</command> uses the files from
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>sysusers.d</filename> directory to create system users
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and groups at package installation or boot time. This tool may be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek used to allocate system users and groups only, it is not useful
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for creating non-system users and groups, as it accesses
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/passwd</filename> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/group</filename> directly, bypassing any more
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek complex user databases, for example any database involving NIS or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Configuration Format</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Each configuration file shall be named in the style of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename><replaceable>package</replaceable>.conf</filename> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek The second variant should be used when it is desirable to make it
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek easy to override just this part of configuration.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The file format is one line per user or group containing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name, ID, GECOS field description and home directory:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting># Type Name ID GECOS
21236ab51082668914b933041893a1cf45218a3dLennart Poetteringu httpd 440 "HTTP User"
21236ab51082668914b933041893a1cf45218a3dLennart Poetteringu authd /usr/bin/authd "Authorization user"
7629889c86005017eb1a7f1f803c0d8e7a5bef08Lennart Poetteringu root 0 "Superuser" /root</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The type consists of a single letter. The following line
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek types are understood:</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>u</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Create a system user and group of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified name should they not exist yet. The user's primary
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek group will be set to the group bearing the same name. The
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek user's shell will be set to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/sbin/nologin</filename>, the home directory to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the specified home directory, or <filename>/</filename> if
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek none is given. The account will be created disabled, so that
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek logins are not allowed.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>g</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Create a system group of the specified name
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek should it not exist yet. Note that <varname>u</varname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek implicitly create a matching group. The group will be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek created with no password set.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>m</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Add a user to a group. If the user or group
cd72d2044ad28b475bf84a38ba6db45292467dd8Jan Engelhardt do not exist yet, they will be implicitly
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <term><varname>r</varname></term>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <listitem><para>Add a range of numeric UIDs/GIDs to the pool
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to allocate new UIDs and GIDs from. If no line of this type
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt is specified, the range of UIDs/GIDs is set to some
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek compiled-in default. Note that both UIDs and GIDs are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek allocated from the same pool, in order to ensure that users
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek and groups of the same name are likely to carry the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek numeric UID and GID.</para></listitem>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The name field specifies the user or group name. It should
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be shorter than 31 characters and avoid any non-ASCII
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek characters, and not begin with a numeric character. It is
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek strongly recommended to pick user and group names that are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unlikely to clash with normal users created by the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek administrator. A good scheme to guarantee this is by prefixing
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek all system and group names with the underscore, and avoiding too
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek generic names.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>For <varname>m</varname> lines, this field should contain
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the user name to add to a group.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>For lines of type <varname>r</varname>, this field should
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be set to <literal>-</literal>.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>For <varname>u</varname> and <varname>g</varname>, the
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt numeric 32-bit UID or GID of the user/group. Do not use IDs 65535
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek or 4294967295, as they have special placeholder meanings.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Specify <literal>-</literal> for automatic UID/GID allocation
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek for the user or group. Alternatively, specify an absolute path
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt in the file system. In this case, the UID/GID is read from the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek path's owner/group. This is useful to create users whose UID/GID
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek match the owners of pre-existing files (such as SUID or SGID
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek binaries).</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>For <varname>m</varname> lines, this field should contain
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the group name to add to a user to.</para>
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>For lines of type <varname>r</varname>, this field should
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be set to a UID/GID range in the format
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <literal>FROM-TO</literal>, where both values are formatted as
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek decimal ASCII numbers. Alternatively, a single UID/GID may be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek specified formatted as decimal ASCII numbers.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>A short, descriptive string for users to be created,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek enclosed in quotation marks. Note that this field may not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek contain colons.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Only applies to lines of type <varname>u</varname> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek should otherwise be left unset, or be set to
b938cb902c3b5bca807a94b277672c64d6767886Jan Engelhardt <para>The home directory for a new system user. If omitted,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek defaults to the root directory. It is recommended to not
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unnecessarily specify home directories for system users, unless
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek software strictly requires one to be set.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Only applies to lines of type <varname>u</varname> and
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek should otherwise be left unset, or be set to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <xi:include href="standard-conf.xml" xpointer="confd" />
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Note that <command>systemd-sysusers</command> will do
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek nothing if the specified users or groups already exist, so
a8eaaee72a2f06e0fb64fb71de3b71ecba31dafbJan Engelhardt normally, there is no reason to override
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>sysusers.d</filename> vendor configuration, except to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek block certain users or groups from being created.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>