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