man: document preset files

2 files changed, 208 insertions, 5 deletions

diff --git a/man/systemctl.xml b/man/systemctl.xml
index 64f2edf64a..646437a4ca 100644
--- a/man/systemctl.xml
+++ b/man/systemctl.xml
@@ -814,12 +814,15 @@
 
                                 <listitem><para>Reset one or more unit
                                 files, as specified on the command
-                                line, to the defaults configured in a
-                                preset file. This has the same effect
-                                as <command>disable</command> or
+                                line, to the defaults configured in
+                                the preset policy files. This has the
+                                same effect as
+                                <command>disable</command> or
                                 <command>enable</command>, depending
                                 how the unit is listed in the preset
-                                files.</para>
+                                files. For more information on preset
+                                policy see
+                                <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
                                 </listitem>
                         </varlistentry>
 
@@ -1230,7 +1233,8 @@
                         <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
-                        <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                        <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>
 
diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml
new file mode 100644
index 0000000000..21de529366
--- /dev/null
+++ b/man/systemd.preset.xml
@@ -0,0 +1,199 @@
+<?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 2011 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.preset">
+
+        <refentryinfo>
+                <title>systemd.preset</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.preset</refentrytitle>
+                <manvolnum>5</manvolnum>
+        </refmeta>
+
+        <refnamediv>
+                <refname>systemd.preset</refname>
+                <refpurpose>Service enablement presets</refpurpose>
+        </refnamediv>
+
+        <refsynopsisdiv>
+                <para><filename>/etc/systemd/system-preset/*.preset</filename></para>
+                <para><filename>/run/systemd/system-preset/*.preset</filename></para>
+                <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para>
+                <para><filename>/etc/systemd/user-preset/*.preset</filename></para>
+                <para><filename>/run/systemd/user-preset/*.preset</filename></para>
+                <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para>
+        </refsynopsisdiv>
+
+        <refsect1>
+                <title>Description</title>
+
+                <para>Preset files may be used to encode policy which
+                services shall be enabled by default and which ones
+                shall be disabled. They are read by <command>systemctl
+                preset</command> (for more information see
+                <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
+                which uses this information to enable or disable a
+                unit according to preset policy. <command>systemctl
+                preset</command> is used by the post install
+                scriptlets of RPM packages (or other OS package formats),
+                to enable/disable specific units by default on package
+                installation, enforcing distribution, spin or
+                administrator preset policy. This allows choosing a certain
+                set of units to be enabled/disabled even before
+                installing the actual package.</para>
+
+                <para>It is not recommended to ship preset files
+                within the respective software packages implementing
+                the services, but rather centralize them in a
+                distribution or spin default policy, which can be
+                amended by administrator policy.</para>
+
+                <para>If no preset files exist, <command>systemctl
+                preset</command> will enable all units that are
+                installed by default. If this is not desired and all
+                units shall rather be disabled it is necessary to ship
+                a preset file with a single, catchall
+                "<filename>disable *</filename>" line. (See example 1,
+                below.)</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Preset File Format</title>
+
+                <para>The preset files contain a list of
+                directives consisting of either the word
+                <literal>enable</literal> or
+                <literal>disable</literal> followed by a space and a
+                unit name (possibly with shell style wildcards),
+                separated by newlines. Empty lines and lines whose
+                first non-whitespace character is # or ; are
+                ignored.</para>
+
+                <para>Two different directives are understood:
+                <literal>enable</literal> may be used to enable units
+                by default, <literal>disable</literal> to disable
+                units by default.</para>
+
+                <para>If multiple lines apply to a unit name the
+                first matching one takes precedence over all
+                others.</para>
+
+                <para>Each preset file shall be named in the style of
+                <filename>&lt;priority&gt;-&lt;program&gt;.conf</filename>.
+                Files in <filename>/etc/</filename> override files
+                with the same name in <filename>/usr/lib/</filename>
+                and <filename>/run/</filename>.  Files in
+                <filename>/run/</filename> override files with the
+                same name in <filename>/usr/lib/</filename>. Packages
+                should install their preset files in
+                <filename>/usr/lib/</filename>. Files in
+                <filename>/etc/</filename> are reserved for the local
+                administrator, who may use this logic to override the
+                preset files installed by vendor packages. All preset
+                files are sorted by their filename in alphabetical
+                order, regardless in which of the directories they
+                reside, to guarantee that a specific preset file takes
+                precedence over another file with an alphabetically
+                earlier name, if both files contain lines that apply
+                to the same unit names. It is recommended to prefix
+                all file names with two-digit number, to simplify
+                ordering.</para>
+
+                <para>If the administrator wants to disable a preset
+                file supplied by the vendor the recommended way is to
+                place a symlink to <filename>/dev/null</filename> in
+                <filename>/etc/systemd/system-preset/</filename>
+                bearing the same file name.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>Example</title>
+
+                <example>
+                        <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
+
+                        <programlisting>disable *</programlisting>
+                </example>
+
+                <para>This disables all units. Due to the file name
+                prefix <literal>99-</literal> it will be read last and
+                hence can easily be overridden by spin or
+                administrator preset policy or suchlike.</para>
+
+                <example>
+                        <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
+
+                        <programlisting>enable gdm.service
+enable colord.service
+enable accounts-daemon.service
+enable avahi-daemon.*</programlisting>
+
+                </example>
+
+                <para>This enables the three mentioned units, plus all
+                <filename>avahi-daemon</filename> regardless of which
+                unit type. A file like this could be useful for
+                inclusion in a GNOME spin of a distribution. It will
+                ensure that the units necessary for GNOME are properly
+                enabled as they are installed. It leaves all other
+                units untouched, and subject to other (later) preset
+                files, for example like the one from the first example
+                above.</para>
+
+                <example>
+                        <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
+
+                        <programlisting>enable httpd.service
+enable sshd.service
+enable postfix.service
+disable *</programlisting>
+                </example>
+
+                <para>This enables three specific services and
+                disables all others. This is useful for administrators
+                to specifically select the units to enable, and
+                disable all others. Due to the file name prefix
+                <literal>00-</literal> it will be read early and hence
+                overrides all other preset policy files.</para>
+        </refsect1>
+
+        <refsect1>
+                <title>See Also</title>
+                <para>
+                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+                </para>
+        </refsect1>
+
+</refentry>