[thirdparty/systemd.git] / man / sysusers.d.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
-->
<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 and
    to add users to 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, home directory, and login shell:</para>

    <programlisting>#Type Name     ID             GECOS                 Home directory Shell
u     httpd    404            "HTTP User"
u     authd    /usr/bin/authd "Authorization user"
u     postgres -              "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb
g     input    -              -
m     authd    input
u     root     0              "Superuser"           /root          /bin/zsh</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 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 (this is strongly recommended unless it is strictly
      necessary to use a specific UID or GID). 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).
      The syntax <literal><replaceable>uid</replaceable>:<replaceable>gid</replaceable></literal> is also supported to
      allow creating user and group pairs with different numeric UID and GID values. The group with the indicated GID must get created explicitly before or it must already exist. Specifying <literal>-</literal> for the UID in this syntax
      is also supported.
      </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 <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.</para>

      <para>Only applies to lines of type <varname>u</varname> and should otherwise
      be left unset (or <literal>-</literal>). It is recommended to omit this, unless
      software strictly requires a home directory to be set.</para>
    </refsect2>

    <refsect2>
      <title>Shell</title>

      <para>The login shell of the user. If not specified, this will be set to
      <filename>/sbin/nologin</filename>, except if the UID of the user is 0, in
      which case <filename>/bin/sh</filename> will be used.</para>

      <para>Only applies to lines of type <varname>u</varname> and should otherwise
      be left unset (or <literal>-</literal>). It is recommended to omit this, unless
      a shell different <filename>/sbin/nologin</filename> must be used.</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 or the users are members of specified
    groups, 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>
Commit	Line	Data
21236ab5 LP	1	<?xml version="1.0"?>
21236ab5 LP	2	<!---nxml--->
12b42c76	3	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
21236ab5	4	<!--
572eb058 ZJS	5	SPDX-License-Identifier: LGPL-2.1+
572eb058 ZJS	6
21236ab5 LP	7	This file is part of systemd.
	8
	9	Copyright 2014 Lennart Poettering
21236ab5	10	-->
e6de49ab	11	<refentry id="sysusers.d" conditional='ENABLE_SYSUSERS'
798d3a52 ZJS	12	xmlns:xi="http://www.w3.org/2001/XInclude">
	13
	14	<refentryinfo>
	15	<title>sysusers.d</title>
	16	<productname>systemd</productname>
	17
	18	<authorgroup>
	19	<author>
	20	<contrib>Developer</contrib>
	21	<firstname>Lennart</firstname>
	22	<surname>Poettering</surname>
	23	<email>lennart@poettering.net</email>
	24	</author>
	25	</authorgroup>
	26	</refentryinfo>
	27
	28	<refmeta>
	29	<refentrytitle>sysusers.d</refentrytitle>
	30	<manvolnum>5</manvolnum>
	31	</refmeta>
	32
	33	<refnamediv>
	34	<refname>sysusers.d</refname>
	35	<refpurpose>Declarative allocation of system users and groups</refpurpose>
	36	</refnamediv>
	37
	38	<refsynopsisdiv>
9b5c390f YW	39	<para><filename>/etc/sysusers.d/*.conf</filename></para>
9b5c390f YW	40	<para><filename>/run/sysusers.d/*.conf</filename></para>
798d3a52 ZJS	41	<para><filename>/usr/lib/sysusers.d/*.conf</filename></para>
	42	</refsynopsisdiv>
	43
	44	<refsect1>
	45	<title>Description</title>
	46
7b1aaf66 ZJS	47	<para><command>systemd-sysusers</command> uses the files from
	48	<filename>sysusers.d</filename> directory to create system users and groups and
	49	to add users to groups, at package installation or boot time. This tool may be
	50	used to allocate system users and groups only, it is not useful for creating
	51	non-system (i.e. regular, "human") users and groups, as it accesses
	52	<filename>/etc/passwd</filename> and <filename>/etc/group</filename> directly,
	53	bypassing any more complex user databases, for example any database involving NIS
	54	or LDAP.</para>
798d3a52 ZJS	55	</refsect1>
	56
	57	<refsect1>
8165be2e	58	<title>Configuration Directories and Precedence</title>
798d3a52 ZJS	59
	60	<para>Each configuration file shall be named in the style of
	61	<filename><replaceable>package</replaceable>.conf</filename> or
	62	<filename><replaceable>package</replaceable>-<replaceable>part</replaceable>.conf</filename>.
	63	The second variant should be used when it is desirable to make it
	64	easy to override just this part of configuration.</para>
	65
8165be2e ZJS	66	<para>Files in <filename>/etc/sysusers.d</filename> override files
	67	with the same name in <filename>/usr/lib/sysusers.d</filename> and
	68	<filename>/run/sysusers.d</filename>. Files in
	69	<filename>/run/sysusers.d</filename> override files with the same
	70	name in <filename>/usr/lib/sysusers.d</filename>. Packages should
	71	install their configuration files in
	72	<filename>/usr/lib/sysusers.d</filename>. Files in
	73	<filename>/etc/sysusers.d</filename> are reserved for the local
	74	administrator, who may use this logic to override the
	75	configuration files installed by vendor packages. All
	76	configuration files are sorted by their filename in lexicographic
	77	order, regardless of which of the directories they reside in. If
	78	multiple files specify the same path, the entry in the file with
	79	the lexicographically earliest name will be applied. All later
	80	entries for the same user and group names will be logged as warnings.
	81	</para>
	82
	83	<para>If the administrator wants to disable a configuration file
	84	supplied by the vendor, the recommended way is to place a symlink
	85	to <filename>/dev/null</filename> in
	86	<filename>/etc/sysusers.d/</filename> bearing the same filename.
	87	</para>
	88	</refsect1>
	89
	90	<refsect1>
	91	<title>Configuration File Format</title>
	92
7b1aaf66 ZJS	93	<para>The file format is one line per user or group containing name, ID, GECOS
7b1aaf66 ZJS	94	field description, home directory, and login shell:</para>
798d3a52	95
7b1aaf66 ZJS	96	<programlisting>#Type Name ID GECOS Home directory Shell
	97	u httpd 404 "HTTP User"
	98	u authd /usr/bin/authd "Authorization user"
	99	u postgres - "Postgresql Database" /var/lib/pgsql /usr/libexec/postgresdb
	100	g input - -
	101	m authd input
	102	u root 0 "Superuser" /root /bin/zsh</programlisting>
21236ab5	103
565dab8e LP	104	<para>Empty lines and lines beginning with the <literal>#</literal> character are ignored, and may be used for
	105	commenting.</para>
	106
798d3a52 ZJS	107	<refsect2>
	108	<title>Type</title>
	109
	110	<para>The type consists of a single letter. The following line
	111	types are understood:</para>
	112
	113	<variablelist>
	114	<varlistentry>
	115	<term><varname>u</varname></term>
7b1aaf66 ZJS	116	<listitem><para>Create a system user and group of the specified name should
	117	they not exist yet. The user's primary group will be set to the group
	118	bearing the same name. The account will be created disabled, so that logins
	119	are not allowed.</para></listitem>
798d3a52 ZJS	120	</varlistentry>
	121
	122	<varlistentry>
	123	<term><varname>g</varname></term>
	124	<listitem><para>Create a system group of the specified name
	125	should it not exist yet. Note that <varname>u</varname>
	126	implicitly create a matching group. The group will be
	127	created with no password set.</para></listitem>
	128	</varlistentry>
	129
	130	<varlistentry>
	131	<term><varname>m</varname></term>
	132	<listitem><para>Add a user to a group. If the user or group
cd72d204	133	do not exist yet, they will be implicitly
798d3a52 ZJS	134	created.</para></listitem>
	135	</varlistentry>
	136
	137	<varlistentry>
	138	<term><varname>r</varname></term>
	139	<listitem><para>Add a range of numeric UIDs/GIDs to the pool
	140	to allocate new UIDs and GIDs from. If no line of this type
b938cb90	141	is specified, the range of UIDs/GIDs is set to some
798d3a52 ZJS	142	compiled-in default. Note that both UIDs and GIDs are
	143	allocated from the same pool, in order to ensure that users
	144	and groups of the same name are likely to carry the same
	145	numeric UID and GID.</para></listitem>
	146	</varlistentry>
	147
	148	</variablelist>
	149	</refsect2>
	150
	151	<refsect2>
	152	<title>Name</title>
	153
565dab8e LP	154	<para>The name field specifies the user or group name. The specified name must consist only of the characters a-z,
	155	A-Z, 0-9, <literal>_</literal> and <literal>-</literal>, except for the first character which must be one of a-z,
	156	A-Z or <literal>_</literal> (i.e. numbers and <literal>-</literal> are not permitted as first character). The
	157	user/group name must have at least one character, and at most 31.</para>
	158
	159	<para>It is strongly recommended to pick user and group names that are unlikely to clash with normal users
	160	created by the administrator. A good scheme to guarantee this is by prefixing all system and group names with the
	161	underscore, and avoiding too generic names.</para>
798d3a52	162
b938cb90	163	<para>For <varname>m</varname> lines, this field should contain
798d3a52 ZJS	164	the user name to add to a group.</para>
798d3a52 ZJS	165
b938cb90	166	<para>For lines of type <varname>r</varname>, this field should
798d3a52 ZJS	167	be set to <literal>-</literal>.</para>
	168	</refsect2>
	169
	170	<refsect2>
	171	<title>ID</title>
	172
b938cb90 JE	173	<para>For <varname>u</varname> and <varname>g</varname>, the
b938cb90 JE	174	numeric 32-bit UID or GID of the user/group. Do not use IDs 65535
798d3a52 ZJS	175	or 4294967295, as they have special placeholder meanings.
798d3a52 ZJS	176	Specify <literal>-</literal> for automatic UID/GID allocation
7b1aaf66 ZJS	177	for the user or group (this is strongly recommended unless it is strictly
7b1aaf66 ZJS	178	necessary to use a specific UID or GID). Alternatively, specify an absolute path
b938cb90	179	in the file system. In this case, the UID/GID is read from the
798d3a52 ZJS	180	path's owner/group. This is useful to create users whose UID/GID
798d3a52 ZJS	181	match the owners of pre-existing files (such as SUID or SGID
4cb41413 MV	182	binaries).
4cb41413 MV	183	The syntax <literal><replaceable>uid</replaceable>:<replaceable>gid</replaceable></literal> is also supported to
1825c909 MV	184	allow creating user and group pairs with different numeric UID and GID values. The group with the indicated GID must get created explicitly before or it must already exist. Specifying <literal>-</literal> for the UID in this syntax
1825c909 MV	185	is also supported.
4cb41413	186	</para>
798d3a52	187
b938cb90	188	<para>For <varname>m</varname> lines, this field should contain
798d3a52 ZJS	189	the group name to add to a user to.</para>
798d3a52 ZJS	190
b938cb90	191	<para>For lines of type <varname>r</varname>, this field should
798d3a52	192	be set to a UID/GID range in the format
b938cb90	193	<literal>FROM-TO</literal>, where both values are formatted as
798d3a52 ZJS	194	decimal ASCII numbers. Alternatively, a single UID/GID may be
	195	specified formatted as decimal ASCII numbers.</para>
	196	</refsect2>
	197
	198	<refsect2>
	199	<title>GECOS</title>
	200
7b1aaf66 ZJS	201	<para>A short, descriptive string for users to be created, enclosed in
7b1aaf66 ZJS	202	quotation marks. Note that this field may not contain colons.</para>
798d3a52	203
7b1aaf66 ZJS	204	<para>Only applies to lines of type <varname>u</varname> and should otherwise
7b1aaf66 ZJS	205	be left unset (or <literal>-</literal>).</para>
798d3a52 ZJS	206	</refsect2>
	207
	208	<refsect2>
	209	<title>Home Directory</title>
	210
7b1aaf66 ZJS	211	<para>The home directory for a new system user. If omitted, defaults to the
7b1aaf66 ZJS	212	root directory.</para>
798d3a52	213
7b1aaf66 ZJS	214	<para>Only applies to lines of type <varname>u</varname> and should otherwise
	215	be left unset (or <literal>-</literal>). It is recommended to omit this, unless
	216	software strictly requires a home directory to be set.</para>
	217	</refsect2>
	218
	219	<refsect2>
	220	<title>Shell</title>
	221
	222	<para>The login shell of the user. If not specified, this will be set to
	223	<filename>/sbin/nologin</filename>, except if the UID of the user is 0, in
	224	which case <filename>/bin/sh</filename> will be used.</para>
	225
	226	<para>Only applies to lines of type <varname>u</varname> and should otherwise
	227	be left unset (or <literal>-</literal>). It is recommended to omit this, unless
	228	a shell different <filename>/sbin/nologin</filename> must be used.</para>
798d3a52	229	</refsect2>
798d3a52 ZJS	230	</refsect1>
798d3a52 ZJS	231
798d3a52 ZJS	232	<refsect1>
	233	<title>Idempotence</title>
	234
7b1aaf66 ZJS	235	<para>Note that <command>systemd-sysusers</command> will do nothing if the
	236	specified users or groups already exist or the users are members of specified
	237	groups, so normally there is no reason to override
	238	<filename>sysusers.d</filename> vendor configuration, except to block certain
	239	users or groups from being created.</para>
798d3a52 ZJS	240	</refsect1>
	241
	242	<refsect1>
	243	<title>See Also</title>
	244	<para>
	245	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
	246	<citerefentry><refentrytitle>systemd-sysusers</refentrytitle><manvolnum>8</manvolnum></citerefentry>
	247	</para>
	248	</refsect1>
21236ab5 LP	249
21236ab5 LP	250	</refentry>