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
  59                 swap device or file for memory paging controlled and
  60                 supervised by systemd.</para>
  61
  62                 <para>This man page lists the configuration options
  63                 specific to this unit type. See
  64                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  65                 for the common options of all unit configuration
  66                 files. The common configuration items are configured
  67                 in the generic [Unit] and [Install] sections. The swap
  68                 specific configuration options are configured in the
  69                 [Swap] section.</para>
  70
  71                 <para>Additional options are listed in
  72                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  73                 which define the execution environment the
  74                 <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  75                 binary is executed in, and in
  76                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  77                 which define the way the processes are
  78                 terminated, and in
  79                 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
  80                 which configure resource control settings for the
  81                 processes of the service.</para>
  82
  83                 <para>Swap units must be named after the devices
  84                 or files they control. Example: the swap device
  85                 <filename noindex='true'>/dev/sda5</filename> must be configured in a
  86                 unit file <filename>dev-sda5.swap</filename>. For
  87                 details about the escaping logic used to convert a
  88                 file system path to a unit name, see
  89                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  90
  91                 <para>All swap units automatically get the appropriate
  92                 dependencies on the devices or on the mount points
  93                 of the files they are activated from.</para>
  94
  95                 <para>Swap units with
  96                 <varname>DefaultDependencies=</varname> enabled
  97                 implicitly acquire a conflicting dependency to
  98                 <filename>umount.target</filename> so that they are
  99                 deactivated at shutdown.</para>
 100         </refsect1>
 101
 102         <refsect1>
 103                 <title><filename>fstab</filename></title>
 104
 105                 <para>Swap units may either be configured via unit
 106                 files, or via <filename>/etc/fstab</filename> (see
 107                 <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 108                 for details). Swaps listed in
 109                 <filename>/etc/fstab</filename> will be converted into
 110                 native units dynamically at boot and when the
 111                 configuration of the system manager is
 112                 reloaded. See
 113                 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 114                 for details about the conversion.</para>
 115
 116                 <para>If a swap device or file is configured in both
 117                 <filename>/etc/fstab</filename> and a unit file, the
 118                 configuration in the latter takes precedence.</para>
 119
 120                 <para>When reading <filename>/etc/fstab</filename> a
 121                 few special options are understood by systemd which
 122                 influence how dependencies are created for swap
 123                 units.</para>
 124
 125                 <variablelist class='fstab-options'>
 126                   <varlistentry>
 127                     <term><option>noauto</option></term>
 128                     <term><option>auto</option></term>
 129
 130                     <listitem><para>With <option>noauto</option> the
 131                     swap unit will not be added as a dependency for
 132                     <filename>swap.target</filename>. This means that
 133                     it will not be activated automatically during
 134                     boot, unless it is pulled in by some other
 135                     unit. Option <option>auto</option> has the
 136                     opposite meaning and is the default.</para>
 137                     </listitem>
 138                   </varlistentry>
 139
 140                   <varlistentry>
 141                     <term><option>nofail</option></term>
 142                     <term><option>fail</option></term>
 143
 144                     <listitem><para>With <option>nofail</option> the
 145                     swap unit will be only wanted, not required by
 146                     <filename>swap.target</filename>. This means that
 147                     the boot will continue even if this swap device is
 148                     not activated successfully. Option
 149                     <option>fail</option> has the opposite meaning and
 150                     is the default.</para>
 151                     </listitem>
 152                   </varlistentry>
 153                 </variablelist>
 154         </refsect1>
 155
 156         <refsect1>
 157                 <title>Options</title>
 158
 159                 <para>Swap files must include a [Swap] section, which
 160                 carries information about the swap device it
 161                 supervises. A number of options that may be used in
 162                 this section are shared with other unit types. These
 163                 options are documented in
 164                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 165                 and
 166                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 167                 options specific to the [Swap] section of swap units
 168                 are the following:</para>
 169
 170                 <variablelist class='unit-directives'>
 171
 172                         <varlistentry>
 173                                 <term><varname>What=</varname></term>
 174                                 <listitem><para>Takes an absolute path
 175                                 of a device node or file to use for
 176                                 paging. See
 177                                 <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 178                                 for details. If this refers to a
 179                                 device node, a dependency on the
 180                                 respective device unit is
 181                                 automatically created. (See
 182                                 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 183                                 for more information.) If this refers
 184                                 to a file, a dependency on the
 185                                 respective mount unit is automatically
 186                                 created. (See
 187                                 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 188                                 for more information.) This option is
 189                                 mandatory.</para></listitem>
 190                         </varlistentry>
 191
 192                         <varlistentry>
 193                                 <term><varname>Priority=</varname></term>
 194
 195                                 <listitem><para>Swap priority to use
 196                                 when activating the swap device or
 197                                 file. This takes an integer. This
 198                                 setting is optional.</para></listitem>
 199                         </varlistentry>
 200
 201                         <varlistentry>
 202                                 <term><varname>Options=</varname></term>
 203
 204                                 <listitem><para>May contain an option
 205                                 string for the swap device. This may
 206                                 be used for controlling discard
 207                                 options among other functionality, if
 208                                 the swap backing device supports the
 209                                 discard or trim operation. (See
 210                                 <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 211                                 for more information.)
 212                                 </para></listitem>
 213                         </varlistentry>
 214
 215                         <varlistentry>
 216                                 <term><varname>TimeoutSec=</varname></term>
 217                                 <listitem><para>Configures the time to
 218                                 wait for the swapon command to
 219                                 finish. If a command does not exit
 220                                 within the configured time, the swap
 221                                 will be considered failed and be shut
 222                                 down again. All commands still running
 223                                 will be terminated forcibly via
 224                                 <constant>SIGTERM</constant>, and after another delay of
 225                                 this time with <constant>SIGKILL</constant>. (See
 226                                 <option>KillMode=</option> in
 227                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 228                                 Takes a unit-less value in seconds, or
 229                                 a time span value such as "5min
 230                                 20s". Pass <literal>0</literal> to disable the timeout
 231                                 logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the
 232                                 manager configuration file
 233                                 (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 234                                 </para></listitem>
 235                         </varlistentry>
 236                 </variablelist>
 237
 238                 <para>Check
 239                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 240                 and
 241                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 242                 for more settings.</para>
 243         </refsect1>
 244
 245         <refsect1>
 246                   <title>See Also</title>
 247                   <para>
 248                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 249                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 250                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 251                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 252                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 253                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 254                           <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 255                           <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 256                           <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 257                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 258                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 259                   </para>
 260         </refsect1>
 261
 262 </refentry>