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