man/systemd.swap.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2010 Lennart Poettering
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="systemd.swap">
  26   <refentryinfo>
  27     <title>systemd.swap</title>
  28     <productname>systemd</productname>
  29
  30     <authorgroup>
  31       <author>
  32         <contrib>Developer</contrib>
  33         <firstname>Lennart</firstname>
  34         <surname>Poettering</surname>
  35         <email>lennart@poettering.net</email>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd.swap</refentrytitle>
  42     <manvolnum>5</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd.swap</refname>
  47     <refpurpose>Swap unit configuration</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <para><filename><replaceable>swap</replaceable>.swap</filename></para>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para>A unit configuration file whose name ends in
  58     <literal>.swap</literal> encodes information about a swap device
  59     or file for memory paging controlled and supervised by
  60     systemd.</para>
  61
  62     <para>This man page lists the configuration options specific to
  63     this unit type. See
  64     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65     for the common options of all unit configuration files. The common
  66     configuration items are configured in the generic [Unit] and
  67     [Install] sections. The swap specific configuration options are
  68     configured in the [Swap] section.</para>
  69
  70     <para>Additional options are listed in
  71     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  72     which define the execution environment the
  73     <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  74     binary is executed in, and in
  75     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  76     which define the way the processes are terminated, and in
  77     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  78     which configure resource control settings for the processes of the
  79     service.</para>
  80
  81     <para>Swap units must be named after the devices
  82     or files they control. Example: the swap device
  83     <filename noindex='true'>/dev/sda5</filename> must be configured in a
  84     unit file <filename>dev-sda5.swap</filename>. For details about
  85     the escaping logic used to convert a file system path to a unit
  86     name, see
  87     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  88
  89     <para>All swap units automatically get the appropriate
  90     dependencies on the devices or on the mount points of the files
  91     they are activated from.</para>
  92
  93     <para>Swap units with <varname>DefaultDependencies=</varname>
  94     enabled implicitly acquire a conflicting dependency to
  95     <filename>umount.target</filename> so that they are deactivated at
  96     shutdown.</para>
  97   </refsect1>
  98
  99   <refsect1>
 100     <title><filename>fstab</filename></title>
 101
 102     <para>Swap units may either be configured via unit files, or via
 103     <filename>/etc/fstab</filename> (see
 104     <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 105     for details). Swaps listed in <filename>/etc/fstab</filename> will
 106     be converted into native units dynamically at boot and when the
 107     configuration of the system manager is reloaded. See
 108     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 109     for details about the conversion.</para>
 110
 111     <para>If a swap device or file is configured in both
 112     <filename>/etc/fstab</filename> and a unit file, the configuration
 113     in the latter takes precedence.</para>
 114
 115     <para>When reading <filename>/etc/fstab</filename> a few special
 116     options are understood by systemd which influence how dependencies
 117     are created for swap units.</para>
 118
 119     <variablelist class='fstab-options'>
 120       <varlistentry>
 121         <term><option>noauto</option></term>
 122         <term><option>auto</option></term>
 123
 124         <listitem><para>With <option>noauto</option> the swap unit
 125         will not be added as a dependency for
 126         <filename>swap.target</filename>. This means that it will not
 127         be activated automatically during boot, unless it is pulled in
 128         by some other unit. Option <option>auto</option> has the
 129         opposite meaning and is the default.</para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term><option>nofail</option></term>
 135
 136         <listitem><para>With <option>nofail</option> the swap unit
 137         will be only wanted, not required by
 138         <filename>swap.target</filename>. This means that the boot
 139         will continue even if this swap device is not activated
 140         successfully.</para>
 141         </listitem>
 142       </varlistentry>
 143     </variablelist>
 144   </refsect1>
 145
 146   <refsect1>
 147     <title>Options</title>
 148
 149     <para>Swap files must include a [Swap] section, which carries
 150     information about the swap device it supervises. A number of
 151     options that may be used in this section are shared with other
 152     unit types. These options are documented in
 153     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 154     and
 155     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 156     The options specific to the [Swap] section of swap units are the
 157     following:</para>
 158
 159     <variablelist class='unit-directives'>
 160
 161       <varlistentry>
 162         <term><varname>What=</varname></term>
 163         <listitem><para>Takes an absolute path of a device node or
 164         file to use for paging. See
 165         <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 166         for details. If this refers to a device node, a dependency on
 167         the respective device unit is automatically created. (See
 168         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 169         for more information.) If this refers to a file, a dependency
 170         on the respective mount unit is automatically created. (See
 171         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 172         for more information.) This option is
 173         mandatory.</para></listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term><varname>Priority=</varname></term>
 178
 179         <listitem><para>Swap priority to use when activating the swap
 180         device or file. This takes an integer. This setting is
 181         optional.</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><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><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>