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
 143                     <listitem><para>With <option>nofail</option> the
 144                     swap unit will be only wanted, not required by
 145                     <filename>swap.target</filename>. This means that
 146                     the boot will continue even if this swap device is
 147                     not activated successfully.</para>
 148                     </listitem>
 149                   </varlistentry>
 150                 </variablelist>
 151         </refsect1>
 152
 153         <refsect1>
 154                 <title>Options</title>
 155
 156                 <para>Swap files must include a [Swap] section, which
 157                 carries information about the swap device it
 158                 supervises. A number of options that may be used in
 159                 this section are shared with other unit types. These
 160                 options are documented in
 161                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 162                 and
 163                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>. The
 164                 options specific to the [Swap] section of swap units
 165                 are the following:</para>
 166
 167                 <variablelist class='unit-directives'>
 168
 169                         <varlistentry>
 170                                 <term><varname>What=</varname></term>
 171                                 <listitem><para>Takes an absolute path
 172                                 of a device node or file to use for
 173                                 paging. See
 174                                 <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 175                                 for details. If this refers to a
 176                                 device node, a dependency on the
 177                                 respective device unit is
 178                                 automatically created. (See
 179                                 <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 180                                 for more information.) If this refers
 181                                 to a file, a dependency on the
 182                                 respective mount unit is automatically
 183                                 created. (See
 184                                 <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 185                                 for more information.) This option is
 186                                 mandatory.</para></listitem>
 187                         </varlistentry>
 188
 189                         <varlistentry>
 190                                 <term><varname>Priority=</varname></term>
 191
 192                                 <listitem><para>Swap priority to use
 193                                 when activating the swap device or
 194                                 file. This takes an integer. This
 195                                 setting is optional.</para></listitem>
 196                         </varlistentry>
 197
 198                         <varlistentry>
 199                                 <term><varname>Options=</varname></term>
 200
 201                                 <listitem><para>May contain an option
 202                                 string for the swap device. This may
 203                                 be used for controlling discard
 204                                 options among other functionality, if
 205                                 the swap backing device supports the
 206                                 discard or trim operation. (See
 207                                 <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 208                                 for more information.)
 209                                 </para></listitem>
 210                         </varlistentry>
 211
 212                         <varlistentry>
 213                                 <term><varname>TimeoutSec=</varname></term>
 214                                 <listitem><para>Configures the time to
 215                                 wait for the swapon command to
 216                                 finish. If a command does not exit
 217                                 within the configured time, the swap
 218                                 will be considered failed and be shut
 219                                 down again. All commands still running
 220                                 will be terminated forcibly via
 221                                 <constant>SIGTERM</constant>, and after another delay of
 222                                 this time with <constant>SIGKILL</constant>. (See
 223                                 <option>KillMode=</option> in
 224                                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
 225                                 Takes a unit-less value in seconds, or
 226                                 a time span value such as "5min
 227                                 20s". Pass <literal>0</literal> to disable the timeout
 228                                 logic. Defaults to <varname>DefaultTimeoutStartSec=</varname> from the
 229                                 manager configuration file
 230                                 (see <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 231                                 </para></listitem>
 232                         </varlistentry>
 233                 </variablelist>
 234
 235                 <para>Check
 236                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 237                 and
 238                 <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 239                 for more settings.</para>
 240         </refsect1>
 241
 242         <refsect1>
 243                   <title>See Also</title>
 244                   <para>
 245                           <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 246                           <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 247                           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 248                           <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 249                           <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 250                           <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 251                           <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 252                           <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 253                           <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 254                           <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 255                           <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 256                   </para>
 257         </refsect1>
 258
 259 </refentry>