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. If multiple files specify the same unit name,
 131                 the entry in the file with the alphabetically 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>