1<?xml version="1.0"?>
2<!--*-nxml-*-->
3<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6<refentry id="systemd.preset">
7
8  <refentryinfo>
9    <title>systemd.preset</title>
10    <productname>systemd</productname>
11  </refentryinfo>
12
13  <refmeta>
14    <refentrytitle>systemd.preset</refentrytitle>
15    <manvolnum>5</manvolnum>
16  </refmeta>
17
18  <refnamediv>
19    <refname>systemd.preset</refname>
20    <refpurpose>Service enablement presets</refpurpose>
21  </refnamediv>
22
23  <refsynopsisdiv>
24    <para><filename>/etc/systemd/system-preset/*.preset</filename></para>
25    <para><filename>/run/systemd/system-preset/*.preset</filename></para>
26    <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para>
27    <para><filename>/etc/systemd/user-preset/*.preset</filename></para>
28    <para><filename>/run/systemd/user-preset/*.preset</filename></para>
29    <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para>
30  </refsynopsisdiv>
31
32  <refsect1>
33    <title>Description</title>
34
35    <para>Preset files may be used to encode policy which units shall be enabled by default and which ones
36    shall be disabled. They are read by <command>systemctl preset</command> which uses this information to
37    enable or disable a unit. Depending on that policy, <command>systemctl preset</command> is identical to
38    <command>systemctl enable</command> or <command>systemctl disable</command>.
39
40    <command>systemctl preset</command> is used by the post install scriptlets of rpm packages (or other OS
41    package formats), to enable/disable specific units by default on package installation, enforcing
42    distribution, spin or administrator preset policy. This allows choosing a certain set of units to be
43    enabled/disabled even before installing the actual package. For more information, see
44    <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
45
46    <para>It is not recommended to ship preset files within the respective software packages implementing the
47    units, but rather centralize them in a distribution or spin default policy, which can be amended by
48    administrator policy, see below.</para>
49
50    <para>If no preset files exist, <command>systemctl
51    preset</command> will enable all units that are installed by
52    default. If this is not desired and all units shall rather be
53    disabled, it is necessary to ship a preset file with a single,
54    catchall "<filename>disable *</filename>" line. (See example 1,
55    below.)</para>
56  </refsect1>
57
58  <refsect1>
59    <title>Preset File Format</title>
60
61    <para>The preset files contain a list of directives consisting of
62    either the word <literal>enable</literal> or
63    <literal>disable</literal> followed by a space and a unit name
64    (possibly with shell style wildcards), separated by newlines.
65    Empty lines and lines whose first non-whitespace character is <literal>#</literal> or
66    <literal>;</literal> are ignored. Multiple instance names for unit
67    templates may be specified as a space separated list at the end of
68    the line instead of the customary position between <literal>@</literal>
69    and the unit suffix.</para>
70
71    <para>Presets must refer to the "real" unit file, and not to any aliases. See
72    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
73    for a description of unit aliasing.</para>
74
75    <para>Two different directives are understood:
76    <literal>enable</literal> may be used to enable units by default,
77    <literal>disable</literal> to disable units by default.</para>
78
79    <para>If multiple lines apply to a unit name, the first matching
80    one takes precedence over all others.</para>
81
82    <para>Each preset file shall be named in the style of
83    <filename>&lt;priority&gt;-&lt;policy-name&gt;.preset</filename>. Files
84    in <filename>/etc/</filename> override files with the same name in
85    <filename>/usr/lib/</filename> and <filename>/run/</filename>.
86    Files in <filename>/run/</filename> override files with the same
87    name in <filename>/usr/lib/</filename>. Packages should install
88    their preset files in <filename>/usr/lib/</filename>. Files in
89    <filename>/etc/</filename> are reserved for the local
90    administrator, who may use this logic to override the preset files
91    installed by vendor packages. All preset files are sorted by their
92    filename in lexicographic order, regardless of which of the
93    directories they reside in. If multiple files specify the same
94    unit name, the entry in the file with the lexicographically
95    earliest name will be applied. It is recommended to prefix all
96    filenames with a two-digit number and a dash, to simplify the
97    ordering of the files.</para>
98
99    <para>If the administrator wants to disable a preset file supplied
100    by the vendor, the recommended way is to place a symlink to
101    <filename>/dev/null</filename> in
102    <filename>/etc/systemd/system-preset/</filename> bearing the same
103    filename.</para>
104  </refsect1>
105
106  <refsect1>
107    <title>Examples</title>
108
109    <example>
110      <title>Default to off</title>
111
112      <programlisting># /usr/lib/systemd/system-preset/99-default.preset
113
114disable *</programlisting>
115    </example>
116
117    <para>This disables all units. Due to the filename prefix
118    <literal>99-</literal>, it will be read last and hence can easily
119    be overridden by spin or administrator preset policy.</para>
120
121    <example>
122      <title>Enable multiple template instances</title>
123
124      <programlisting># /usr/lib/systemd/system-preset/80-dirsrv.preset
125
126enable dirsrv@.service foo bar baz</programlisting>
127    </example>
128
129    <para>This enables all three of <filename>dirsrv@foo.service</filename>,
130    <filename>dirsrv@bar.service</filename> and <filename>dirsrv@baz.service</filename>.</para>
131
132    <example>
133      <title>A GNOME spin</title>
134
135      <programlisting># /usr/lib/systemd/system-preset/50-gnome.preset
136
137enable gdm.service
138enable colord.service
139enable accounts-daemon.service
140enable avahi-daemon.*</programlisting>
141
142    </example>
143
144    <para>This enables the three mentioned units, plus all
145    <filename>avahi-daemon</filename> regardless of which unit type. A
146    file like this could be useful for inclusion in a GNOME spin of a
147    distribution. It will ensure that the units necessary for GNOME
148    are properly enabled as they are installed. It leaves all other
149    units untouched, and subject to other (later) preset files, for
150    example like the one from the first example above.</para>
151
152    <example>
153      <title>Administrator policy</title>
154
155      <programlisting># /etc/systemd/system-preset/00-lennart.preset
156
157enable httpd.service
158enable sshd.service
159enable postfix.service
160disable *</programlisting>
161    </example>
162
163    <para>This enables three specific services and disables all
164    others. This is useful for administrators to specifically select
165    the units to enable, and disable all others. Due to the filename
166    prefix <literal>00-</literal> it will be read early and
167    override all other preset policy files.</para>
168  </refsect1>
169
170  <refsect1>
171    <title>Motivation for the preset logic</title>
172
173    <para>Different distributions have different policies on which services shall be enabled by default when
174    the package they are shipped in is installed. On Fedora all services stay off by default, so that
175    installing a package will not cause a service to be enabled (with some exceptions). On Debian all
176    services are immediately enabled by default, so that installing a package will cause its services to be
177    enabled right-away.</para>
178
179    <para>Even within a single distribution, different spins (flavours, remixes, whatever you might want to
180    call them) of a distribution also have different policies on what services to enable, and what services
181    to leave off. For example, Fedora Workstation will enable <command>gdm</command> as display manager by
182    default, while the Fedora KDE spin will enable <command>sddm</command> instead.</para>
183
184    <para>Different sites might also have different policies what to turn on by default and what to turn
185    off. For example, one administrator would prefer to enforce the policy of "<command>sshd</command> should
186    be always on, but everything else off", while another one might say "<command>snmpd</command> always on,
187    and for everything else use the distribution policy defaults".</para>
188
189    <para>Traditionally, policy about which services shall be enabled were implemented in each package
190    individually. This made it cumbersome to implement different policies per spin or per site, or to create
191    software packages that do the right thing on more than one distribution. The enablement mechanism was
192    also encoding the enablement policy.</para>
193
194    <para>The preset mechanism allows clean separation of the enablement mechanism (inside the package
195    scriptlets, by invoking <command>systemctl preset</command>) and enablement policy (centralized in the
196    preset files), and lifts the configuration out of individual packages. Preset files may be written for
197    specific distributions, for specific spins or for specific sites, in order to enforce different policies
198    as needed. It is recommended to apply the policy encoded in preset files in package installation
199    scriptlets.</para>
200  </refsect1>
201
202  <refsect1>
203    <title>See Also</title>
204    <para>
205      <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
206      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
207      <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
208    </para>
209
210    <para><citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
211    has a discussion of packaging scriptlets.</para>
212
213    <para>Fedora page introducing the use of presets:
214    <ulink url="https://fedoraproject.org/wiki/Features/PackagePresets">Features/PackagePresets</ulink>.
215    </para>
216  </refsect1>
217
218</refentry>
219