man: document the sysusers tool

2 files changed, 297 insertions, 0 deletions

diff --git a/man/systemd-sysusers.xml b/man/systemd-sysusers.xml
new file mode 100644
index 000000000..4de1973dc
--- /dev/null
+++ b/man/systemd-sysusers.xml
@@ -0,0 +1,117 @@
+<?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="systemd-sysusers"
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+        <refentryinfo>
+                <title>systemd-sysusers</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>systemd-sysusers</refentrytitle>
+                <manvolnum>8</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>systemd-sysusers</refname>
+                <refname>systemd-sysusers.service</refname>
+                <refpurpose>Allocate system users and groups</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <cmdsynopsis>
+                        <command>systemd-sysusers</command>
+                        <arg choice="opt" rep="repeat">OPTIONS</arg>
+                        <arg choice="opt" rep="repeat"><replaceable>CONFIGFILE</replaceable></arg>
+                </cmdsynopsis>
+
+                <para><filename>systemd-sysusers.service</filename></para>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para><command>systemd-sysusers</command> creates
+                system users and groups, based on the file format and
+                location specified in
+                <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                </para>
+
+                <para>If invoked with no arguments, it applies all
+                directives from all files found. If one or more
+                filenames are passed on the command line, only the
+                directives in these files are applied. If only the
+                basename of a file is specified, all directories as
+                specified in
+                <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                are searched for a matching file.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Options</title>
+
+                <para>The following options are understood:</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><option>--root=<replaceable>root</replaceable></option></term>
+                                <listitem><para>Takes a directory path
+                                as an argument. All paths will be
+                                prefixed with the given alternate <replaceable>root</replaceable>
+                                path, including config search paths.
+                                </para></listitem>
+                        </varlistentry>
+
+                        <xi:include href="standard-options.xml" xpointer="help" />
+                        <xi:include href="standard-options.xml" xpointer="version" />
+                </variablelist>
+
+        </refsect1>
+
+        <refsect1>
+                <title>Exit status</title>
+
+                <para>On success, 0 is returned, a non-zero failure
+                code otherwise.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>sysusers.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                </para>
+        </refsect1>
+
+</refentry>
diff --git a/man/sysusers.d.xml b/man/sysusers.d.xml
new file mode 100644
index 000000000..af31ec078
--- /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>