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