man: document the sysusers tool

1 files changed, 180 insertions, 0 deletions

diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
new file mode 100644
index 0000000000..af31ec078d
--- /dev/null
+++ b/man/sysusers.d.xml
@@ -0,0 +1,180 @@
+<?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">
+<!--
+  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">
+
+        <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>/usr/lib/sysusers.d/*.conf</filename></para>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para><command>systemd-sysusers</command> uses the
+                files from <filename>/usr/lib/sysusers.d/</filename>
+                to create system users and groups at package
+                installation or boot time. This tool may be used for
+                allocating system users and groups only, it is not
+                useful for creating non-system users and groups, as it
+                accessed <filename>/etc/passwd</filename> and
+                <filename>/etc/group</filename> directly, bypassing
+                any more complex user database, for example any
+                database involving NIS or LDAP.</para>
+
+        </refsect1>
+
+        <refsect1>
+                <title>File Format</title>
+
+                <para>Each file shall be named in the style of
+                <filename><replaceable>package</replaceable>.conf</filename>.</para>
+
+                <para>All files are sorted by their filename in
+                lexicographic order, regardless of which of the
+                directories they reside in. If multiple files specify
+                the same user or group, the entry in the file with the
+                lexicographically earliest name will be applied, all
+                all other conflicting entries will be logged as
+                errors. Users and groups are
+                processed in the order they are listed.</para>
+
+                <para>The file format is one line per user or group
+                containing name, ID and GECOS field description:</para>
+
+                <programlisting># Type Name ID GECOS
+u httpd 440 "HTTP User"
+u authd /usr/bin/authd "Authorization user"
+g input - -</programlisting>
+
+                <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/login</filename>,
+                                        the home directory to
+                                        <filename>/</filename>. 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>
+                        </variablelist>
+                </refsect2>
+
+                <refsect2>
+                        <title>Name</title>
+
+                        <para>The name field specifies the user or
+                        group name. It should be be shorter than 256
+                        characters and avoid any non-ASCII characters,
+                        and not begin with a numeric character. 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>
+                </refsect2>
+
+                <refsect2>
+                        <title>ID</title>
+
+                        <para>The numeric 32bit UID or GID of the
+                        user/group. Do not use IDs 65535 or
+                        4294967295, as they have special placeholder
+                        meanings. Specify "-" 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>
+                </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>
+                </refsect2>
+
+        </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>