summaryrefslogtreecommitdiff
path: root/man/systemd.swap.xml
blob: cf4e1ba8398584ef1c9f7e2fc390a914729104e3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2010 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.swap">
  <refentryinfo>
    <title>systemd.swap</title>
    <productname>systemd</productname>

    <authorgroup>
      <author>
        <contrib>Developer</contrib>
        <firstname>Lennart</firstname>
        <surname>Poettering</surname>
        <email>lennart@poettering.net</email>
      </author>
    </authorgroup>
  </refentryinfo>

  <refmeta>
    <refentrytitle>systemd.swap</refentrytitle>
    <manvolnum>5</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>systemd.swap</refname>
    <refpurpose>Swap unit configuration</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <para><filename><replaceable>swap</replaceable>.swap</filename></para>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para>A unit configuration file whose name ends in
    <literal>.swap</literal> encodes information about a swap device
    or file for memory paging controlled and supervised by
    systemd.</para>

    <para>This man page lists the configuration options specific to
    this unit type. See
    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for the common options of all unit configuration files. The common
    configuration items are configured in the generic [Unit] and
    [Install] sections. The swap specific configuration options are
    configured in the [Swap] section.</para>

    <para>Additional options are listed in
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    which define the execution environment the <citerefentry
    project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    binary is executed in, in
    <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    which define the way these processes are
    terminated, and in
    <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
    which configure resource control settings for these processes of the
    unit.</para>

    <para>Swap units must be named after the devices or files they control. Example: the swap device <filename
    noindex='true'>/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For
    details about the escaping logic used to convert a file system path to a unit name, see
    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap
    units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to
    it.</para>
  </refsect1>

  <refsect1>
    <title>Automatic Dependencies</title>

    <para>All swap units automatically get the
    <varname>BindsTo=</varname> and <varname>After=</varname>
    dependencies on the device units or the mount units of the files
    they are activated from.</para>

    <para>Swap units with <varname>DefaultDependencies=</varname> in the <literal>[Unit]</literal> section enabled
    implicitly acquire a <varname>Conflicts=</varname> and an <varname>After=</varname> dependency on
    <filename>umount.target</filename> so that they are deactivated at shutdown, unless
    <varname>DefaultDependencies=no</varname> is specified.</para>

    <para>Additional implicit dependencies may be added as result of
    execution and resource control parameters as documented in
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  </refsect1>

  <refsect1>
    <title><filename>fstab</filename></title>

    <para>Swap units may either be configured via unit files, or via
    <filename>/etc/fstab</filename> (see
    <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for details). Swaps listed in <filename>/etc/fstab</filename> will
    be converted into native units dynamically at boot and when the
    configuration of the system manager is reloaded. See
    <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
    for details about the conversion.</para>

    <para>If a swap device or file is configured in both
    <filename>/etc/fstab</filename> and a unit file, the configuration
    in the latter takes precedence.</para>

    <para>When reading <filename>/etc/fstab</filename>, a few special
    options are understood by systemd which influence how dependencies
    are created for swap units.</para>

    <variablelist class='fstab-options'>
      <varlistentry>
        <term><option>noauto</option></term>
        <term><option>auto</option></term>

        <listitem><para>With <option>noauto</option>, the swap unit
        will not be added as a dependency for
        <filename>swap.target</filename>. This means that it will not
        be activated automatically during boot, unless it is pulled in
        by some other unit. The <option>auto</option> option has the
        opposite meaning and is the default.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>nofail</option></term>

        <listitem><para>With <option>nofail</option>, the swap unit
        will be only wanted, not required by
        <filename>swap.target</filename>. This means that the boot
        will continue even if this swap device is not activated
        successfully.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <para>Swap files must include a [Swap] section, which carries
    information about the swap device it supervises. A number of
    options that may be used in this section are shared with other
    unit types. These options are documented in
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
    The options specific to the [Swap] section of swap units are the
    following:</para>

    <variablelist class='unit-directives'>

      <varlistentry>
        <term><varname>What=</varname></term>
        <listitem><para>Takes an absolute path of a device node or
        file to use for paging. See
        <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        for details. If this refers to a device node, a dependency on
        the respective device unit is automatically created. (See
        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        for more information.) If this refers to a file, a dependency
        on the respective mount unit is automatically created. (See
        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
        for more information.) This option is
        mandatory.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Priority=</varname></term>

        <listitem><para>Swap priority to use when activating the swap
        device or file. This takes an integer. This setting is
        optional and ignored when the priority is set by <option>pri=</option> in the
        <varname>Options=</varname> key.</para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>Options=</varname></term>

        <listitem><para>May contain an option string for the swap
        device. This may be used for controlling discard options among
        other functionality, if the swap backing device supports the
        discard or trim operation. (See
        <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
        for more information.) </para></listitem>
      </varlistentry>

      <varlistentry>
        <term><varname>TimeoutSec=</varname></term>
        <listitem><para>Configures the time to wait for the swapon
        command to finish. If a command does not exit within the
        configured time, the swap will be considered failed and be
        shut down again. All commands still running will be terminated
        forcibly via <constant>SIGTERM</constant>, and after another
        delay of this time with <constant>SIGKILL</constant>. (See
        <option>KillMode=</option> in
        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
        Takes a unit-less value in seconds, or a time span value such
        as "5min 20s". Pass <literal>0</literal> to disable the
        timeout logic. Defaults to
        <varname>DefaultTimeoutStartSec=</varname> from the manager
        configuration file (see
        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
        </para></listitem>
      </varlistentry>
    </variablelist>

    <para>Check
    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    and
    <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
    for more settings.</para>
  </refsect1>

  <refsect1>
      <title>See Also</title>
      <para>
        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
        <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
      </para>
  </refsect1>

</refentry>