man/sysusers.d.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4 <!--
   5   This file is part of systemd.
   6
   7   Copyright 2014 Lennart Poettering
   8
   9   systemd is free software; you can redistribute it and/or modify it
  10   under the terms of the GNU Lesser General Public License as published by
  11   the Free Software Foundation; either version 2.1 of the License, or
  12   (at your option) any later version.
  13
  14   systemd is distributed in the hope that it will be useful, but
  15   WITHOUT ANY WARRANTY; without even the implied warranty of
  16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  17   Lesser General Public License for more details.
  18
  19   You should have received a copy of the GNU Lesser General Public License
  20   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  21 -->
  22 <refentry id="sysusers.d"
  23     xmlns:xi="http://www.w3.org/2001/XInclude">
  24
  25   <refentryinfo>
  26     <title>sysusers.d</title>
  27     <productname>systemd</productname>
  28
  29     <authorgroup>
  30       <author>
  31         <contrib>Developer</contrib>
  32         <firstname>Lennart</firstname>
  33         <surname>Poettering</surname>
  34         <email>lennart@poettering.net</email>
  35       </author>
  36     </authorgroup>
  37   </refentryinfo>
  38
  39   <refmeta>
  40     <refentrytitle>sysusers.d</refentrytitle>
  41     <manvolnum>5</manvolnum>
  42   </refmeta>
  43
  44   <refnamediv>
  45     <refname>sysusers.d</refname>
  46     <refpurpose>Declarative allocation of system users and groups</refpurpose>
  47   </refnamediv>
  48
  49   <refsynopsisdiv>
  50     <para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
  51   </refsynopsisdiv>
  52
  53   <refsect1>
  54     <title>Description</title>
  55
  56     <para><command>systemd-sysusers</command> uses the files from
  57     <filename>sysusers.d</filename> directory to create system users
  58     and groups at package installation or boot time. This tool may be
  59     used to allocate system users and groups only, it is not useful
  60     for creating non-system users and groups, as it accesses
  61     <filename>/etc/passwd</filename> and
  62     <filename>/etc/group</filename> directly, bypassing any more
  63     complex user databases, for example any database involving NIS or
  64     LDAP.</para>
  65   </refsect1>
  66
  67   <refsect1>
  68     <title>Configuration Format</title>
  69
  70     <para>Each configuration file shall be named in the style of
  71     <filename><replaceable>package</replaceable>.conf</filename> or
  72     <filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
  73     The second variant should be used when it is desirable to make it
  74     easy to override just this part of configuration.</para>
  75
  76     <para>The file format is one line per user or group containing
  77     name, ID, GECOS field description and home directory:</para>
  78
  79     <programlisting># Type Name ID GECOS
  80 u httpd 440 "HTTP User"
  81 u authd /usr/bin/authd "Authorization user"
  82 g input - -
  83 m authd input
  84 u root 0 "Superuser" /root</programlisting>
  85
  86     <refsect2>
  87       <title>Type</title>
  88
  89       <para>The type consists of a single letter. The following line
  90       types are understood:</para>
  91
  92       <variablelist>
  93         <varlistentry>
  94           <term><varname>u</varname></term>
  95           <listitem><para>Create a system user and group of the
  96           specified name should they not exist yet. The user's primary
  97           group will be set to the group bearing the same name. The
  98           user's shell will be set to
  99           <filename>/sbin/nologin</filename>, the home directory to
 100           the specified home directory, or <filename>/</filename> if
 101           none is given. The account will be created disabled, so that
 102           logins are not allowed.</para></listitem>
 103         </varlistentry>
 104
 105         <varlistentry>
 106           <term><varname>g</varname></term>
 107           <listitem><para>Create a system group of the specified name
 108           should it not exist yet. Note that <varname>u</varname>
 109           implicitly create a matching group. The group will be
 110           created with no password set.</para></listitem>
 111         </varlistentry>
 112
 113         <varlistentry>
 114           <term><varname>m</varname></term>
 115           <listitem><para>Add a user to a group. If the user or group
 116           are not existing yet, they will be implicitly
 117           created.</para></listitem>
 118         </varlistentry>
 119
 120         <varlistentry>
 121           <term><varname>r</varname></term>
 122           <listitem><para>Add a range of numeric UIDs/GIDs to the pool
 123           to allocate new UIDs and GIDs from. If no line of this type
 124           is specified the range of UIDs/GIDs is set to some
 125           compiled-in default. Note that both UIDs and GIDs are
 126           allocated from the same pool, in order to ensure that users
 127           and groups of the same name are likely to carry the same
 128           numeric UID and GID.</para></listitem>
 129         </varlistentry>
 130
 131       </variablelist>
 132     </refsect2>
 133
 134     <refsect2>
 135       <title>Name</title>
 136
 137       <para>The name field specifies the user or group name. It should
 138       be shorter than 31 characters and avoid any non-ASCII
 139       characters, and not begin with a numeric character. It is
 140       strongly recommended to pick user and group names that are
 141       unlikely to clash with normal users created by the
 142       administrator. A good scheme to guarantee this is by prefixing
 143       all system and group names with the underscore, and avoiding too
 144       generic names.</para>
 145
 146       <para>For <varname>m</varname> lines this field should contain
 147       the user name to add to a group.</para>
 148
 149       <para>For lines of type <varname>r</varname> this field should
 150       be set to <literal>-</literal>.</para>
 151     </refsect2>
 152
 153     <refsect2>
 154       <title>ID</title>
 155
 156       <para>For <varname>u</varname> and <varname>g</varname> the
 157       numeric 32bit UID or GID of the user/group. Do not use IDs 65535
 158       or 4294967295, as they have special placeholder meanings.
 159       Specify <literal>-</literal> for automatic UID/GID allocation
 160       for the user or group. Alternatively, specify an absolute path
 161       in the file system. In this case the UID/GID is read from the
 162       path's owner/group. This is useful to create users whose UID/GID
 163       match the owners of pre-existing files (such as SUID or SGID
 164       binaries).</para>
 165
 166       <para>For <varname>m</varname> lines this field should contain
 167       the group name to add to a user to.</para>
 168
 169       <para>For lines of type <varname>r</varname> this field should
 170       be set to a UID/GID range in the format
 171       <literal>FROM-TO</literal> where both values are formatted as
 172       decimal ASCII numbers. Alternatively, a single UID/GID may be
 173       specified formatted as decimal ASCII numbers.</para>
 174     </refsect2>
 175
 176     <refsect2>
 177       <title>GECOS</title>
 178
 179       <para>A short, descriptive string for users to be created,
 180       enclosed in quotation marks. Note that this field may not
 181       contain colons.</para>
 182
 183       <para>Only applies to lines of type <varname>u</varname> and
 184       should otherwise be left unset, or be set to
 185       <literal>-</literal>.</para>
 186     </refsect2>
 187
 188     <refsect2>
 189       <title>Home Directory</title>
 190
 191       <para>The home directory for a new system user. If omitted
 192       defaults to the root directory. It is recommended to not
 193       unnecessarily specify home directories for system users, unless
 194       software strictly requires one to be set.</para>
 195
 196       <para>Only applies to lines of type <varname>u</varname> and
 197       should otherwise be left unset, or be set to
 198       <literal>-</literal>.</para>
 199     </refsect2>
 200
 201   </refsect1>
 202
 203   <xi:include href="standard-conf.xml" xpointer="confd" />
 204
 205   <refsect1>
 206     <title>Idempotence</title>
 207
 208     <para>Note that <command>systemd-sysusers</command> will do
 209     nothing if the specified users or groups already exist, so
 210     normally there no reason to override
 211     <filename>sysusers.d</filename> vendor configuration, except to
 212     block certain users or groups from being created.</para>
 213   </refsect1>
 214
 215   <refsect1>
 216     <title>See Also</title>
 217     <para>
 218       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 219       <citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 220     </para>
 221   </refsect1>
 222
 223 </refentry>