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