man/systemd.swap.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   Copyright 2010 Lennart Poettering
   9 -->
  10
  11 <refentry id="systemd.swap">
  12   <refentryinfo>
  13     <title>systemd.swap</title>
  14     <productname>systemd</productname>
  15
  16     <authorgroup>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Lennart</firstname>
  20         <surname>Poettering</surname>
  21         <email>lennart@poettering.net</email>
  22       </author>
  23     </authorgroup>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle>systemd.swap</refentrytitle>
  28     <manvolnum>5</manvolnum>
  29   </refmeta>
  30
  31   <refnamediv>
  32     <refname>systemd.swap</refname>
  33     <refpurpose>Swap unit configuration</refpurpose>
  34   </refnamediv>
  35
  36   <refsynopsisdiv>
  37     <para><filename><replaceable>swap</replaceable>.swap</filename></para>
  38   </refsynopsisdiv>
  39
  40   <refsect1>
  41     <title>Description</title>
  42
  43     <para>A unit configuration file whose name ends in
  44     <literal>.swap</literal> encodes information about a swap device
  45     or file for memory paging controlled and supervised by
  46     systemd.</para>
  47
  48     <para>This man page lists the configuration options specific to
  49     this unit type. See
  50     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  51     for the common options of all unit configuration files. The common
  52     configuration items are configured in the generic [Unit] and
  53     [Install] sections. The swap specific configuration options are
  54     configured in the [Swap] section.</para>
  55
  56     <para>Additional options are listed in
  57     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  58     which define the execution environment the <citerefentry
  59     project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  60     program is executed in, in
  61     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  62     which define the way these processes are
  63     terminated, and in
  64     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  65     which configure resource control settings for these processes of the
  66     unit.</para>
  67
  68     <para>Swap units must be named after the devices or files they control. Example: the swap device <filename
  69     noindex='true'>/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For
  70     details about the escaping logic used to convert a file system path to a unit name, see
  71     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap
  72     units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to
  73     it.</para>
  74   </refsect1>
  75
  76   <refsect1>
  77     <title>Automatic Dependencies</title>
  78
  79     <refsect2>
  80       <title>Implicit Dependencies</title>
  81
  82       <para>The following dependencies are implicitly added:</para>
  83
  84       <itemizedlist>
  85         <listitem><para>All swap units automatically get the
  86         <varname>BindsTo=</varname> and <varname>After=</varname>
  87         dependencies on the device units or the mount units of the files
  88         they are activated from.</para></listitem>
  89       </itemizedlist>
  90
  91       <para>Additional implicit dependencies may be added as result of
  92       execution and resource control parameters as documented in
  93       <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  94       and
  95       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  96     </refsect2>
  97
  98     <refsect2>
  99       <title>Default Dependencies</title>
 100
 101       <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>
 102
 103       <itemizedlist>
 104         <listitem><para>Swap units automatically acquire a <varname>Conflicts=</varname> and a
 105         <varname>Before=</varname> dependency on <filename>umount.target</filename> so that they are deactivated at
 106         shutdown as well as a <varname>Before=swap.target</varname> dependency.</para></listitem>
 107       </itemizedlist>
 108     </refsect2>
 109   </refsect1>
 110
 111   <refsect1>
 112     <title><filename>fstab</filename></title>
 113
 114     <para>Swap units may either be configured via unit files, or via
 115     <filename>/etc/fstab</filename> (see
 116     <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 117     for details). Swaps listed in <filename>/etc/fstab</filename> will
 118     be converted into native units dynamically at boot and when the
 119     configuration of the system manager is reloaded. See
 120     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 121     for details about the conversion.</para>
 122
 123     <para>If a swap device or file is configured in both
 124     <filename>/etc/fstab</filename> and a unit file, the configuration
 125     in the latter takes precedence.</para>
 126
 127     <para>When reading <filename>/etc/fstab</filename>, a few special
 128     options are understood by systemd which influence how dependencies
 129     are created for swap units.</para>
 130
 131     <variablelist class='fstab-options'>
 132       <varlistentry>
 133         <term><option>noauto</option></term>
 134         <term><option>auto</option></term>
 135
 136         <listitem><para>With <option>noauto</option>, the swap unit
 137         will not be added as a dependency for
 138         <filename>swap.target</filename>. This means that it will not
 139         be activated automatically during boot, unless it is pulled in
 140         by some other unit. The <option>auto</option> option has the
 141         opposite meaning and is the default.</para>
 142         </listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term><option>nofail</option></term>
 147
 148         <listitem><para>With <option>nofail</option>, the swap unit
 149         will be only wanted, not required by
 150         <filename>swap.target</filename>. This means that the boot
 151         will continue even if this swap device is not activated
 152         successfully.</para>
 153         </listitem>
 154       </varlistentry>
 155     </variablelist>
 156   </refsect1>
 157
 158   <refsect1>
 159     <title>Options</title>
 160
 161     <para>Swap files must include a [Swap] section, which carries
 162     information about the swap device it supervises. A number of
 163     options that may be used in this section are shared with other
 164     unit types. These options are documented in
 165     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 166     and
 167     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 168     The options specific to the [Swap] section of swap units are the
 169     following:</para>
 170
 171     <variablelist class='unit-directives'>
 172
 173       <varlistentry>
 174         <term><varname>What=</varname></term>
 175         <listitem><para>Takes an absolute path of a device node or file to use for paging. See <citerefentry
 176         project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
 177         details. If this refers to a device node, a dependency on the respective device unit is automatically
 178         created. (See
 179         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry> for more
 180         information.) If this refers to a file, a dependency on the respective mount unit is automatically
 181         created. (See <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 182         for more information.) This option is mandatory. Note that the usual specifier expansion is applied to this
 183         setting, literal percent characters should hence be written as <literal>%%</literal>.</para></listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><varname>Priority=</varname></term>
 188
 189         <listitem><para>Swap priority to use when activating the swap
 190         device or file. This takes an integer. This setting is
 191         optional and ignored when the priority is set by <option>pri=</option> in the
 192         <varname>Options=</varname> key.</para></listitem>
 193       </varlistentry>
 194
 195       <varlistentry>
 196         <term><varname>Options=</varname></term>
 197
 198         <listitem><para>May contain an option string for the swap device. This may be used for controlling discard
 199         options among other functionality, if the swap backing device supports the discard or trim operation. (See
 200         <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 201         for more information.) Note that the usual specifier expansion is applied to this setting, literal percent
 202         characters should hence be written as <literal>%%</literal>.</para></listitem>
 203       </varlistentry>
 204
 205       <varlistentry>
 206         <term><varname>TimeoutSec=</varname></term>
 207         <listitem><para>Configures the time to wait for the swapon
 208         command to finish. If a command does not exit within the
 209         configured time, the swap will be considered failed and be
 210         shut down again. All commands still running will be terminated
 211         forcibly via <constant>SIGTERM</constant>, and after another
 212         delay of this time with <constant>SIGKILL</constant>. (See
 213         <option>KillMode=</option> in
 214         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 215         Takes a unit-less value in seconds, or a time span value such
 216         as "5min 20s". Pass <literal>0</literal> to disable the
 217         timeout logic. Defaults to
 218         <varname>DefaultTimeoutStartSec=</varname> from the manager
 219         configuration file (see
 220         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 221         </para></listitem>
 222       </varlistentry>
 223     </variablelist>
 224
 225     <para>Check
 226     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 227     and
 228     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 229     for more settings.</para>
 230   </refsect1>
 231
 232   <refsect1>
 233       <title>See Also</title>
 234       <para>
 235         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 236         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 237         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 238         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 239         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 240         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 241         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 242         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 243         <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 244         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 245         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 246       </para>
 247   </refsect1>
 248
 249 </refentry>