man/systemd.preset.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   5 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   6 <refentry id="systemd.preset">
   7
   8   <refentryinfo>
   9     <title>systemd.preset</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd.preset</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd.preset</refname>
  20     <refpurpose>Service enablement presets</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <para><simplelist>
  25       <member><filename>/etc/systemd/system-preset/*.preset</filename></member>
  26       <member><filename>/run/systemd/system-preset/*.preset</filename></member>
  27       <member><filename>/usr/lib/systemd/system-preset/*.preset</filename></member>
  28       <member><filename>/etc/systemd/user-preset/*.preset</filename></member>
  29       <member><filename>/run/systemd/user-preset/*.preset</filename></member>
  30       <member><filename>/usr/lib/systemd/user-preset/*.preset</filename></member>
  31     </simplelist></para>
  32   </refsynopsisdiv>
  33
  34   <refsect1>
  35     <title>Description</title>
  36
  37     <para>Preset files may be used to encode policy which units shall be enabled by default and which ones
  38     shall be disabled. They are read by <command>systemctl preset</command> which uses this information to
  39     enable or disable a unit. Depending on that policy, <command>systemctl preset</command> is identical to
  40     <command>systemctl enable</command> or <command>systemctl disable</command>.
  41
  42     <command>systemctl preset</command> is used by the post install scriptlets of rpm packages (or other OS
  43     package formats), to enable/disable specific units by default on package installation, enforcing
  44     distribution, spin, or administrator preset policy. This allows choosing a certain set of units to be
  45     enabled/disabled even before installing the actual package. For more information, see
  46     <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  47
  48     <para>It is not recommended to ship preset files within the respective software packages implementing the
  49     units, but rather centralize them in a distribution or spin default policy, which can be amended by
  50     administrator policy, see below.</para>
  51
  52     <para>If no preset files exist, preset operations will enable all units that are installed by default. If
  53     this is not desired and all units shall rather be disabled, it is necessary to ship a preset file with a
  54     single, catchall "<filename>disable *</filename>" line. (See example 1, below.)</para>
  55
  56     <para>When the machine is booted for the first time,
  57     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> will
  58     enable/disable all units according to preset policy, similarly to <command>systemctl
  59     preset-all</command>. Also see <varname>ConditionFirstBoot=</varname> in
  60     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> and
  61     "First Boot Semantics" in
  62     <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  63     </para>
  64   </refsect1>
  65
  66   <refsect1>
  67     <title>Preset File Format</title>
  68
  69     <para>The preset files contain a list of directives, one per line. Empty lines and lines whose first
  70     non-whitespace character is <literal>#</literal> or <literal>;</literal> are ignored.  Each directive
  71     consists of one of the words <literal>enable</literal>, <literal>disable</literal>, or
  72     <literal>ignore</literal>, followed by whitespace and a unit name. The unit name may contain shell-style
  73     wildcards.</para>
  74
  75     <para>For the enable directive for template units, one or more instance names may be specified as a
  76     space-separated list after the unit name. In this case, those instances will be enabled instead of the
  77     instance specified via DefaultInstance= in the unit.</para>
  78
  79     <para>Presets must refer to the "real" unit file, and not to any aliases. See
  80     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  81     for a description of unit aliasing.</para>
  82
  83     <para>Three different directives are understood: <literal>enable</literal> may be used to enable units by
  84     default, <literal>disable</literal> to disable units by default, and <literal>ignore</literal> to ignore
  85     units and leave existing configuration intact.</para>
  86
  87     <para>If multiple lines apply to a unit name, the first matching
  88     one takes precedence over all others.</para>
  89
  90     <para>Each preset file shall be named in the style of
  91     <filename>&lt;priority&gt;-&lt;policy-name&gt;.preset</filename>. Files
  92     in <filename>/etc/</filename> override files with the same name in
  93     <filename>/usr/lib/</filename> and <filename>/run/</filename>.
  94     Files in <filename>/run/</filename> override files with the same
  95     name in <filename>/usr/lib/</filename>. Packages should install
  96     their preset files in <filename>/usr/lib/</filename>. Files in
  97     <filename>/etc/</filename> are reserved for the local
  98     administrator, who may use this logic to override the preset files
  99     installed by vendor packages. All preset files are sorted by their
 100     filename in lexicographic order, regardless of which of the
 101     directories they reside in. If multiple files specify the same
 102     unit name, the entry in the file with the lexicographically
 103     earliest name will be applied. It is recommended to prefix all
 104     filenames with a two-digit number and a dash, to simplify the
 105     ordering of the files.</para>
 106
 107     <para>If the administrator wants to disable a preset file supplied
 108     by the vendor, the recommended way is to place a symlink to
 109     <filename>/dev/null</filename> in
 110     <filename>/etc/systemd/system-preset/</filename> bearing the same
 111     filename.</para>
 112   </refsect1>
 113
 114   <refsect1>
 115     <title>Examples</title>
 116
 117     <example>
 118       <title>Default to off</title>
 119
 120       <programlisting># /usr/lib/systemd/system-preset/99-default.preset
 121
 122 disable *</programlisting>
 123     </example>
 124
 125     <para>This disables all units. Due to the filename prefix
 126     <literal>99-</literal>, it will be read last and hence can easily
 127     be overridden by spin or administrator preset policy.</para>
 128
 129     <example>
 130       <title>Enable multiple template instances</title>
 131
 132       <programlisting># /usr/lib/systemd/system-preset/80-dirsrv.preset
 133
 134 enable dirsrv@.service foo bar baz</programlisting>
 135     </example>
 136
 137     <para>This enables all three of <filename>dirsrv@foo.service</filename>,
 138     <filename>dirsrv@bar.service</filename> and <filename>dirsrv@baz.service</filename>.</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>Motivation for the preset logic</title>
 180
 181     <para>Different distributions have different policies on which services shall be enabled by default when
 182     the package they are shipped in is installed. On Fedora all services stay off by default, so that
 183     installing a package will not cause a service to be enabled (with some exceptions). On Debian all
 184     services are immediately enabled by default, so that installing a package will cause its services to be
 185     enabled right-away.</para>
 186
 187     <para>Even within a single distribution, different spins (flavours, remixes, whatever you might want to
 188     call them) of a distribution also have different policies on what services to enable, and what services
 189     to leave off. For example, Fedora Workstation will enable <command>gdm</command> as display manager by
 190     default, while the Fedora KDE spin will enable <command>sddm</command> instead.</para>
 191
 192     <para>Different sites might also have different policies what to turn on by default and what to turn
 193     off. For example, one administrator would prefer to enforce the policy of "<command>sshd</command> should
 194     be always on, but everything else off", while another one might say "<command>snmpd</command> always on,
 195     and for everything else use the distribution policy defaults".</para>
 196
 197     <para>Traditionally, policy about which services shall be enabled were implemented in each package
 198     individually. This made it cumbersome to implement different policies per spin or per site, or to create
 199     software packages that do the right thing on more than one distribution. The enablement mechanism was
 200     also encoding the enablement policy.</para>
 201
 202     <para>The preset mechanism allows clean separation of the enablement mechanism (inside the package
 203     scriptlets, by invoking <command>systemctl preset</command>) and enablement policy (centralized in the
 204     preset files), and lifts the configuration out of individual packages. Preset files may be written for
 205     specific distributions, for specific spins or for specific sites, in order to enforce different policies
 206     as needed. It is recommended to apply the policy encoded in preset files in package installation
 207     scriptlets.</para>
 208   </refsect1>
 209
 210   <refsect1>
 211     <title>See Also</title>
 212     <para><simplelist type="inline">
 213       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 214       <member><citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 215       <member><citerefentry><refentrytitle>systemd-delta</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 216     </simplelist></para>
 217
 218     <para><citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 219     has a discussion of packaging scriptlets.</para>
 220
 221     <para>Fedora page introducing the use of presets:
 222     <ulink url="https://fedoraproject.org/wiki/Features/PackagePresets">Features/PackagePresets</ulink>.
 223     </para>
 224   </refsect1>
 225
 226 </refentry>