75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering<!--*-nxml-*-->
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering This file is part of systemd.
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering Copyright 2011 Lennart Poettering
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering systemd is free software; you can redistribute it and/or modify it
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering under the terms of the GNU Lesser General Public License as published by
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering (at your option) any later version.
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering systemd is distributed in the hope that it will be useful, but
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering Lesser General Public License for more details.
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering You should have received a copy of the GNU Lesser General Public License
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <productname>systemd</productname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <email>lennart@poettering.net</email>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refentrytitle>systemd.preset</refentrytitle>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refname>systemd.preset</refname>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refpurpose>Service enablement presets</refpurpose>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <refsynopsisdiv>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/etc/systemd/system-preset/*.preset</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><filename>/run/systemd/system-preset/*.preset</filename></para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/etc/systemd/user-preset/*.preset</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para><filename>/run/systemd/user-preset/*.preset</filename></para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek </refsynopsisdiv>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Preset files may be used to encode policy which units shall
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be enabled by default and which ones shall be disabled. They are
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek read by <command>systemctl preset</command> (for more information
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek which uses this information to enable or disable a unit according
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek to preset policy. <command>systemctl preset</command> is used by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the post install scriptlets of RPM packages (or other OS package
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek formats), to enable/disable specific units by default on package
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek installation, enforcing distribution, spin or administrator preset
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek policy. This allows choosing a certain set of units to be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek enabled/disabled even before installing the actual package.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>For more information on the preset logic please have a look
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek document.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>It is not recommended to ship preset files within the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek respective software packages implementing the units, but rather
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek centralize them in a distribution or spin default policy, which
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek can be amended by administrator policy.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If no preset files exist, <command>systemctl
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek preset</command> will enable all units that are installed by
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek default. If this is not desired and all units shall rather be
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek disabled, it is necessary to ship a preset file with a single,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek catchall "<filename>disable *</filename>" line. (See example 1,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <title>Preset File Format</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>The preset files contain a list of directives consisting of
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek either the word <literal>enable</literal> or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>disable</literal> followed by a space and a unit name
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek (possibly with shell style wildcards), separated by newlines.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Empty lines and lines whose first non-whitespace character is # or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek ; are ignored.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Two different directives are understood:
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>enable</literal> may be used to enable units by default,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>disable</literal> to disable units by default.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If multiple lines apply to a unit name, the first matching
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek one takes precedence over all others.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>Each preset file shall be named in the style of
9e0d90f99d9d20d30b1965999be5ad84bcd60cf2Vivenzio Pagliari <filename><priority>-<policy-name>.preset</filename>. Files
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek in <filename>/etc/</filename> override files with the same name in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/usr/lib/</filename> and <filename>/run/</filename>.
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek Files in <filename>/run/</filename> override files with the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek name in <filename>/usr/lib/</filename>. Packages should install
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek their preset files in <filename>/usr/lib/</filename>. Files in
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/etc/</filename> are reserved for the local
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek administrator, who may use this logic to override the preset files
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek installed by vendor packages. All preset files are sorted by their
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek filename in lexicographic order, regardless of which of the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek directories they reside in. If multiple files specify the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek unit name, the entry in the file with the lexicographically
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek earliest name will be applied. It is recommended to prefix all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek filenames with a two-digit number and a dash, to simplify the
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek ordering of the files.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>If the administrator wants to disable a preset file supplied
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek by the vendor, the recommended way is to place a symlink to
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>/dev/null</filename> in
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <filename>/etc/systemd/system-preset/</filename> bearing the same
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek filename.</para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting>disable *</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This disables all units. Due to the filename prefix
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <literal>99-</literal>, it will be read last and hence can easily
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek be overridden by spin or administrator preset policy or
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek suchlike.</para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting>enable gdm.service
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poetteringenable avahi-daemon.*</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This enables the three mentioned units, plus all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <filename>avahi-daemon</filename> regardless of which unit type. A
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek file like this could be useful for inclusion in a GNOME spin of a
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek distribution. It will ensure that the units necessary for GNOME
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek are properly enabled as they are installed. It leaves all other
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek units untouched, and subject to other (later) preset files, for
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek example like the one from the first example above.</para>
12b42c76672a66c2d4ea7212c14f8f1b5a62b78dTom Gundersen <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <programlisting>enable httpd.service
75d67e683735035949bfdcf71140747b9909d8a1Lennart Poetteringdisable *</programlisting>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <para>This enables three specific services and disables all
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek others. This is useful for administrators to specifically select
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek the units to enable, and disable all others. Due to the filename
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek prefix <literal>00-</literal> it will be read early and hence
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek overrides all other preset policy files.</para>
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
798d3a524ea57aaf40cb53858aaa45ec702f012dZbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>