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