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