chiark / gitweb /
man: explain time units in tmpfiles
[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 units shall
61     be enabled by default and which ones shall be disabled. They are
62     read by <command>systemctl preset</command> (for more information
63     see
64     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>)
65     which uses this information to enable or disable a unit according
66     to preset policy. <command>systemctl preset</command> is used by
67     the post install scriptlets of RPM packages (or other OS package
68     formats), to enable/disable specific units by default on package
69     installation, enforcing distribution, spin or administrator preset
70     policy. This allows choosing a certain set of units to be
71     enabled/disabled even before installing the actual package.</para>
72
73     <para>For more information on the preset logic please have a look
74     at the <ulink
75     url="http://freedesktop.org/wiki/Software/systemd/Preset">Presets</ulink>
76     document.</para>
77
78     <para>It is not recommended to ship preset files within the
79     respective software packages implementing the units, but rather
80     centralize them in a distribution or spin default policy, which
81     can be amended by administrator policy.</para>
82
83     <para>If no preset files exist, <command>systemctl
84     preset</command> will enable all units that are installed by
85     default. If this is not desired and all units shall rather be
86     disabled, it is necessary to ship a preset file with a single,
87     catchall "<filename>disable *</filename>" line. (See example 1,
88     below.)</para>
89   </refsect1>
90
91   <refsect1>
92     <title>Preset File Format</title>
93
94     <para>The preset files contain a list of directives consisting of
95     either the word <literal>enable</literal> or
96     <literal>disable</literal> followed by a space and a unit name
97     (possibly with shell style wildcards), separated by newlines.
98     Empty lines and lines whose first non-whitespace character is # or
99     ; are ignored.</para>
100
101     <para>Two different directives are understood:
102     <literal>enable</literal> may be used to enable units by default,
103     <literal>disable</literal> to disable units by default.</para>
104
105     <para>If multiple lines apply to a unit name, the first matching
106     one takes precedence over all others.</para>
107
108     <para>Each preset file shall be named in the style of
109     <filename>&lt;priority&gt;-&lt;program&gt;.conf</filename>. Files
110     in <filename>/etc/</filename> override files with the same name in
111     <filename>/usr/lib/</filename> and <filename>/run/</filename>.
112     Files in <filename>/run/</filename> override files with the same
113     name in <filename>/usr/lib/</filename>. Packages should install
114     their preset files in <filename>/usr/lib/</filename>. Files in
115     <filename>/etc/</filename> are reserved for the local
116     administrator, who may use this logic to override the preset files
117     installed by vendor packages. All preset files are sorted by their
118     filename in lexicographic order, regardless of which of the
119     directories they reside in. If multiple files specify the same
120     unit name, the entry in the file with the lexicographically
121     earliest name will be applied. It is recommended to prefix all
122     filenames with a two-digit number and a dash, to simplify the
123     ordering of the files.</para>
124
125     <para>If the administrator wants to disable a preset file supplied
126     by the vendor, the recommended way is to place a symlink to
127     <filename>/dev/null</filename> in
128     <filename>/etc/systemd/system-preset/</filename> bearing the same
129     filename.</para>
130   </refsect1>
131
132   <refsect1>
133     <title>Example</title>
134
135     <example>
136       <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
137
138       <programlisting>disable *</programlisting>
139     </example>
140
141     <para>This disables all units. Due to the filename prefix
142     <literal>99-</literal>, it will be read last and hence can easily
143     be overridden by spin or administrator preset policy or
144     suchlike.</para>
145
146     <example>
147       <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
148
149       <programlisting>enable gdm.service
150 enable colord.service
151 enable accounts-daemon.service
152 enable avahi-daemon.*</programlisting>
153
154     </example>
155
156     <para>This enables the three mentioned units, plus all
157     <filename>avahi-daemon</filename> regardless of which unit type. A
158     file like this could be useful for inclusion in a GNOME spin of a
159     distribution. It will ensure that the units necessary for GNOME
160     are properly enabled as they are installed. It leaves all other
161     units untouched, and subject to other (later) preset files, for
162     example like the one from the first example above.</para>
163
164     <example>
165       <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
166
167       <programlisting>enable httpd.service
168 enable sshd.service
169 enable postfix.service
170 disable *</programlisting>
171     </example>
172
173     <para>This enables three specific services and disables all
174     others. This is useful for administrators to specifically select
175     the units to enable, and disable all others. Due to the filename
176     prefix <literal>00-</literal> it will be read early and hence
177     overrides all other preset policy files.</para>
178   </refsect1>
179
180   <refsect1>
181     <title>See Also</title>
182     <para>
183       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
184       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
185       <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
186     </para>
187   </refsect1>
188
189 </refentry>