chiark / gitweb /
service: add FailureAction= option
[elogind.git] / man / systemd.preset.xml
1 <?xml version="1.0"?>
2 <!--*-nxml-*-->
3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!--
5   This file is part of systemd.
6
7   Copyright 2011 Lennart Poettering
8
9   systemd is free software; you can redistribute it and/or modify it
10   under the terms of the GNU Lesser General Public License as published by
11   the Free Software Foundation; either version 2.1 of the License, or
12   (at your option) any later version.
13
14   systemd is distributed in the hope that it will be useful, but
15   WITHOUT ANY WARRANTY; without even the implied warranty of
16   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17   Lesser General Public License for more details.
18
19   You should have received a copy of the GNU Lesser General Public License
20   along with systemd; If not, see <http://www.gnu.org/licenses/>.
21 -->
22 <refentry id="systemd.preset">
23
24         <refentryinfo>
25                 <title>systemd.preset</title>
26                 <productname>systemd</productname>
27
28                 <authorgroup>
29                         <author>
30                                 <contrib>Developer</contrib>
31                                 <firstname>Lennart</firstname>
32                                 <surname>Poettering</surname>
33                                 <email>lennart@poettering.net</email>
34                         </author>
35                 </authorgroup>
36         </refentryinfo>
37
38         <refmeta>
39                 <refentrytitle>systemd.preset</refentrytitle>
40                 <manvolnum>5</manvolnum>
41         </refmeta>
42
43         <refnamediv>
44                 <refname>systemd.preset</refname>
45                 <refpurpose>Service enablement presets</refpurpose>
46         </refnamediv>
47
48         <refsynopsisdiv>
49                 <para><filename>/etc/systemd/system-preset/*.preset</filename></para>
50                 <para><filename>/run/systemd/system-preset/*.preset</filename></para>
51                 <para><filename>/usr/lib/systemd/system-preset/*.preset</filename></para>
52                 <para><filename>/etc/systemd/user-preset/*.preset</filename></para>
53                 <para><filename>/run/systemd/user-preset/*.preset</filename></para>
54                 <para><filename>/usr/lib/systemd/user-preset/*.preset</filename></para>
55         </refsynopsisdiv>
56
57         <refsect1>
58                 <title>Description</title>
59
60                 <para>Preset files may be used to encode policy which
61                 units shall be enabled by default and which ones
62                 shall be disabled. They are read by <command>systemctl
63                 preset</command> (for more information see
64                 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
65                 which uses this information to enable or disable a
66                 unit according to preset policy. <command>systemctl
67                 preset</command> is used by the post install
68                 scriptlets of RPM packages (or other OS package formats),
69                 to enable/disable specific units by default on package
70                 installation, enforcing distribution, spin or
71                 administrator preset policy. This allows choosing a certain
72                 set of units to be enabled/disabled even before
73                 installing the actual package.</para>
74
75                 <para>For more information on the preset logic please
76                 have a look at the <ulink
77                 url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink>
78                 document.</para>
79
80                 <para>It is not recommended to ship preset files
81                 within the respective software packages implementing
82                 the units, but rather centralize them in a
83                 distribution or spin default policy, which can be
84                 amended by administrator policy.</para>
85
86                 <para>If no preset files exist, <command>systemctl
87                 preset</command> will enable all units that are
88                 installed by default. If this is not desired and all
89                 units shall rather be disabled, it is necessary to ship
90                 a preset file with a single, catchall
91                 "<filename>disable *</filename>" line. (See example 1,
92                 below.)</para>
93         </refsect1>
94
95         <refsect1>
96                 <title>Preset File Format</title>
97
98                 <para>The preset files contain a list of
99                 directives consisting of either the word
100                 <literal>enable</literal> or
101                 <literal>disable</literal> followed by a space and a
102                 unit name (possibly with shell style wildcards),
103                 separated by newlines. Empty lines and lines whose
104                 first non-whitespace character is # or ; are
105                 ignored.</para>
106
107                 <para>Two different directives are understood:
108                 <literal>enable</literal> may be used to enable units
109                 by default, <literal>disable</literal> to disable
110                 units by default.</para>
111
112                 <para>If multiple lines apply to a unit name, the
113                 first matching one takes precedence over all
114                 others.</para>
115
116                 <para>Each preset file shall be named in the style of
117                 <filename>&lt;priority&gt;-&lt;program&gt;.conf</filename>.
118                 Files in <filename>/etc/</filename> override files
119                 with the same name in <filename>/usr/lib/</filename>
120                 and <filename>/run/</filename>.  Files in
121                 <filename>/run/</filename> override files with the
122                 same name in <filename>/usr/lib/</filename>. Packages
123                 should install their preset files in
124                 <filename>/usr/lib/</filename>. Files in
125                 <filename>/etc/</filename> are reserved for the local
126                 administrator, who may use this logic to override the
127                 preset files installed by vendor packages. All preset
128                 files are sorted by their filename in lexicographic
129                 order, regardless of which of the directories they
130                 reside in. If multiple files specify the same unit name,
131                 the entry in the file with the lexicographically earliest
132                 name will be applied. It is recommended to prefix all
133                 filenames with a two-digit number and a dash, to simplify
134                 the ordering of the files.</para>
135
136                 <para>If the administrator wants to disable a preset
137                 file supplied by the vendor, the recommended way is to
138                 place a symlink to <filename>/dev/null</filename> in
139                 <filename>/etc/systemd/system-preset/</filename>
140                 bearing the same filename.</para>
141         </refsect1>
142
143         <refsect1>
144                 <title>Example</title>
145
146                 <example>
147                         <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
148
149                         <programlisting>disable *</programlisting>
150                 </example>
151
152                 <para>This disables all units. Due to the filename
153                 prefix <literal>99-</literal>, it will be read last and
154                 hence can easily be overridden by spin or
155                 administrator preset policy or suchlike.</para>
156
157                 <example>
158                         <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
159
160                         <programlisting>enable gdm.service
161 enable colord.service
162 enable accounts-daemon.service
163 enable avahi-daemon.*</programlisting>
164
165                 </example>
166
167                 <para>This enables the three mentioned units, plus all
168                 <filename>avahi-daemon</filename> regardless of which
169                 unit type. A file like this could be useful for
170                 inclusion in a GNOME spin of a distribution. It will
171                 ensure that the units necessary for GNOME are properly
172                 enabled as they are installed. It leaves all other
173                 units untouched, and subject to other (later) preset
174                 files, for example like the one from the first example
175                 above.</para>
176
177                 <example>
178                         <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
179
180                         <programlisting>enable httpd.service
181 enable sshd.service
182 enable postfix.service
183 disable *</programlisting>
184                 </example>
185
186                 <para>This enables three specific services and
187                 disables all others. This is useful for administrators
188                 to specifically select the units to enable, and
189                 disable all others. Due to the filename prefix
190                 <literal>00-</literal> it will be read early and hence
191                 overrides all other preset policy files.</para>
192         </refsect1>
193
194         <refsect1>
195                 <title>See Also</title>
196                 <para>
197                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
198                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
199                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
200                 </para>
201         </refsect1>
202
203 </refentry>