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