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 alphabetical
 129                 order, regardless in which of the directories they
 130                 reside, to guarantee that a specific preset file takes
 131                 precedence over another file with an alphabetically
 132                 earlier name, if both files contain lines that apply
 133                 to the same unit names. It is recommended to prefix
 134                 all file names with two-digit number, to simplify
 135                 ordering.</para>
 136
 137                 <para>If the administrator wants to disable a preset
 138                 file supplied by the vendor the recommended way is to
 139                 place a symlink to <filename>/dev/null</filename> in
 140                 <filename>/etc/systemd/system-preset/</filename>
 141                 bearing the same file name.</para>
 142         </refsect1>
 143
 144         <refsect1>
 145                 <title>Example</title>
 146
 147                 <example>
 148                         <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
 149
 150                         <programlisting>disable *</programlisting>
 151                 </example>
 152
 153                 <para>This disables all units. Due to the file name
 154                 prefix <literal>99-</literal> it will be read last and
 155                 hence can easily be overridden by spin or
 156                 administrator preset policy or suchlike.</para>
 157
 158                 <example>
 159                         <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
 160
 161                         <programlisting>enable gdm.service
 162 enable colord.service
 163 enable accounts-daemon.service
 164 enable avahi-daemon.*</programlisting>
 165
 166                 </example>
 167
 168                 <para>This enables the three mentioned units, plus all
 169                 <filename>avahi-daemon</filename> regardless of which
 170                 unit type. A file like this could be useful for
 171                 inclusion in a GNOME spin of a distribution. It will
 172                 ensure that the units necessary for GNOME are properly
 173                 enabled as they are installed. It leaves all other
 174                 units untouched, and subject to other (later) preset
 175                 files, for example like the one from the first example
 176                 above.</para>
 177
 178                 <example>
 179                         <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
 180
 181                         <programlisting>enable httpd.service
 182 enable sshd.service
 183 enable postfix.service
 184 disable *</programlisting>
 185                 </example>
 186
 187                 <para>This enables three specific services and
 188                 disables all others. This is useful for administrators
 189                 to specifically select the units to enable, and
 190                 disable all others. Due to the file name prefix
 191                 <literal>00-</literal> it will be read early and hence
 192                 overrides all other preset policy files.</para>
 193         </refsect1>
 194
 195         <refsect1>
 196                 <title>See Also</title>
 197                 <para>
 198                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 199                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 200                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 201                 </para>
 202         </refsect1>
 203
 204 </refentry>