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                 services 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>It is not recommended to ship preset files
  76                 within the respective software packages implementing
  77                 the services, but rather centralize them in a
  78                 distribution or spin default policy, which can be
  79                 amended by administrator policy.</para>
  80
  81                 <para>If no preset files exist, <command>systemctl
  82                 preset</command> will enable all units that are
  83                 installed by default. If this is not desired and all
  84                 units shall rather be disabled it is necessary to ship
  85                 a preset file with a single, catchall
  86                 "<filename>disable *</filename>" line. (See example 1,
  87                 below.)</para>
  88         </refsect1>
  89
  90         <refsect1>
  91                 <title>Preset File Format</title>
  92
  93                 <para>The preset files contain a list of
  94                 directives consisting of either the word
  95                 <literal>enable</literal> or
  96                 <literal>disable</literal> followed by a space and a
  97                 unit name (possibly with shell style wildcards),
  98                 separated by newlines. Empty lines and lines whose
  99                 first non-whitespace character is # or ; are
 100                 ignored.</para>
 101
 102                 <para>Two different directives are understood:
 103                 <literal>enable</literal> may be used to enable units
 104                 by default, <literal>disable</literal> to disable
 105                 units by default.</para>
 106
 107                 <para>If multiple lines apply to a unit name the
 108                 first matching one takes precedence over all
 109                 others.</para>
 110
 111                 <para>Each preset file shall be named in the style of
 112                 <filename>&lt;priority&gt;-&lt;program&gt;.conf</filename>.
 113                 Files in <filename>/etc/</filename> override files
 114                 with the same name in <filename>/usr/lib/</filename>
 115                 and <filename>/run/</filename>.  Files in
 116                 <filename>/run/</filename> override files with the
 117                 same name in <filename>/usr/lib/</filename>. Packages
 118                 should install their preset files in
 119                 <filename>/usr/lib/</filename>. Files in
 120                 <filename>/etc/</filename> are reserved for the local
 121                 administrator, who may use this logic to override the
 122                 preset files installed by vendor packages. All preset
 123                 files are sorted by their filename in alphabetical
 124                 order, regardless in which of the directories they
 125                 reside, to guarantee that a specific preset file takes
 126                 precedence over another file with an alphabetically
 127                 earlier name, if both files contain lines that apply
 128                 to the same unit names. It is recommended to prefix
 129                 all file names with two-digit number, to simplify
 130                 ordering.</para>
 131
 132                 <para>If the administrator wants to disable a preset
 133                 file supplied by the vendor the recommended way is to
 134                 place a symlink to <filename>/dev/null</filename> in
 135                 <filename>/etc/systemd/system-preset/</filename>
 136                 bearing the same file name.</para>
 137         </refsect1>
 138
 139         <refsect1>
 140                 <title>Example</title>
 141
 142                 <example>
 143                         <title>Default off example <filename>/usr/lib/systemd/system-preset/99-default.preset</filename>:</title>
 144
 145                         <programlisting>disable *</programlisting>
 146                 </example>
 147
 148                 <para>This disables all units. Due to the file name
 149                 prefix <literal>99-</literal> it will be read last and
 150                 hence can easily be overridden by spin or
 151                 administrator preset policy or suchlike.</para>
 152
 153                 <example>
 154                         <title>A GNOME spin example <filename>/usr/lib/systemd/system-preset/50-gnome.preset</filename>:</title>
 155
 156                         <programlisting>enable gdm.service
 157 enable colord.service
 158 enable accounts-daemon.service
 159 enable avahi-daemon.*</programlisting>
 160
 161                 </example>
 162
 163                 <para>This enables the three mentioned units, plus all
 164                 <filename>avahi-daemon</filename> regardless of which
 165                 unit type. A file like this could be useful for
 166                 inclusion in a GNOME spin of a distribution. It will
 167                 ensure that the units necessary for GNOME are properly
 168                 enabled as they are installed. It leaves all other
 169                 units untouched, and subject to other (later) preset
 170                 files, for example like the one from the first example
 171                 above.</para>
 172
 173                 <example>
 174                         <title>Administrator policy <filename>/etc/systemd/system-preset/00-lennart.preset</filename>:</title>
 175
 176                         <programlisting>enable httpd.service
 177 enable sshd.service
 178 enable postfix.service
 179 disable *</programlisting>
 180                 </example>
 181
 182                 <para>This enables three specific services and
 183                 disables all others. This is useful for administrators
 184                 to specifically select the units to enable, and
 185                 disable all others. Due to the file name prefix
 186                 <literal>00-</literal> it will be read early and hence
 187                 overrides all other preset policy files.</para>
 188         </refsect1>
 189
 190         <refsect1>
 191                 <title>See Also</title>
 192                 <para>
 193                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 194                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 195                         <citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 196                 </para>
 197         </refsect1>
 198
 199 </refentry>