1<?xml version='1.0'?> <!--*-nxml-*-->
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="systemd.swap" xmlns:xi="http://www.w3.org/2001/XInclude">
7  <refentryinfo>
8    <title>systemd.swap</title>
9    <productname>systemd</productname>
10  </refentryinfo>
11
12  <refmeta>
13    <refentrytitle>systemd.swap</refentrytitle>
14    <manvolnum>5</manvolnum>
15  </refmeta>
16
17  <refnamediv>
18    <refname>systemd.swap</refname>
19    <refpurpose>Swap unit configuration</refpurpose>
20  </refnamediv>
21
22  <refsynopsisdiv>
23    <para><filename><replaceable>swap</replaceable>.swap</filename></para>
24  </refsynopsisdiv>
25
26  <refsect1>
27    <title>Description</title>
28
29    <para>A unit configuration file whose name ends in
30    <literal>.swap</literal> encodes information about a swap device
31    or file for memory paging controlled and supervised by
32    systemd.</para>
33
34    <para>This man page lists the configuration options specific to
35    this unit type. See
36    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
37    for the common options of all unit configuration files. The common
38    configuration items are configured in the generic [Unit] and
39    [Install] sections. The swap specific configuration options are
40    configured in the [Swap] section.</para>
41
42    <para>Additional options are listed in
43    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
44    which define the execution environment the <citerefentry
45    project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
46    program is executed in, in
47    <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
48    which define the way these processes are
49    terminated, and in
50    <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
51    which configure resource control settings for these processes of the
52    unit.</para>
53
54    <para>Swap units must be named after the devices or files they control. Example: the swap device <filename
55    index="false">/dev/sda5</filename> must be configured in a unit file <filename>dev-sda5.swap</filename>. For
56    details about the escaping logic used to convert a file system path to a unit name, see
57    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Note that swap
58    units cannot be templated, nor is possible to add multiple names to a swap unit by creating additional symlinks to
59    it.</para>
60
61    <para>Note that swap support on Linux is privileged, swap units are hence only available in the system
62    service manager (and root's user service manager), but not in unprivileged user's service manager.</para>
63  </refsect1>
64
65  <refsect1>
66    <title>Automatic Dependencies</title>
67
68    <refsect2>
69      <title>Implicit Dependencies</title>
70
71      <para>The following dependencies are implicitly added:</para>
72
73      <itemizedlist>
74        <listitem><para>All swap units automatically get the
75        <varname>BindsTo=</varname> and <varname>After=</varname>
76        dependencies on the device units or the mount units of the files
77        they are activated from.</para></listitem>
78      </itemizedlist>
79
80      <para>Additional implicit dependencies may be added as result of
81      execution and resource control parameters as documented in
82      <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
83      and
84      <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
85    </refsect2>
86
87    <refsect2>
88      <title>Default Dependencies</title>
89
90      <para>The following dependencies are added unless <varname>DefaultDependencies=no</varname> is set:</para>
91
92      <itemizedlist>
93        <listitem><para>Swap units automatically acquire a <varname>Conflicts=</varname> and a
94        <varname>Before=</varname> dependency on <filename>umount.target</filename> so that they are deactivated at
95        shutdown as well as a <varname>Before=swap.target</varname> dependency.</para></listitem>
96      </itemizedlist>
97    </refsect2>
98  </refsect1>
99
100  <refsect1>
101    <title><filename>fstab</filename></title>
102
103    <para>Swap units may either be configured via unit files, or via
104    <filename>/etc/fstab</filename> (see
105    <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
106    for details). Swaps listed in <filename>/etc/fstab</filename> will
107    be converted into native units dynamically at boot and when the
108    configuration of the system manager is reloaded. See
109    <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
110    for details about the conversion.</para>
111
112    <para>If a swap device or file is configured in both
113    <filename>/etc/fstab</filename> and a unit file, the configuration
114    in the latter takes precedence.</para>
115
116    <para>When reading <filename>/etc/fstab</filename>, a few special
117    options are understood by systemd which influence how dependencies
118    are created for swap units.</para>
119
120    <variablelist class='fstab-options'>
121      <varlistentry>
122        <term><option>noauto</option></term>
123        <term><option>auto</option></term>
124
125        <listitem><para>With <option>noauto</option>, the swap unit
126        will not be added as a dependency for
127        <filename>swap.target</filename>. This means that it will not
128        be activated automatically during boot, unless it is pulled in
129        by some other unit. The <option>auto</option> option has the
130        opposite meaning and is the default.</para>
131        </listitem>
132      </varlistentry>
133
134      <varlistentry>
135        <term><option>nofail</option></term>
136
137        <listitem><para>With <option>nofail</option>, the swap unit
138        will be only wanted, not required by
139        <filename>swap.target</filename>. This means that the boot
140        will continue even if this swap device is not activated
141        successfully.</para>
142        </listitem>
143      </varlistentry>
144
145      <xi:include href="systemd.mount.xml" xpointer="device-timeout" />
146
147      <varlistentry>
148        <term><option>x-systemd.makefs</option></term>
149
150        <listitem><para>The swap structure will be initialized on the device. If the device is not
151        "empty", i.e. it contains any signature, the operation will be skipped. It is hence expected
152        that this option remains set even after the device has been initialized.</para>
153
154        <para>Note that this option can only be used in <filename>/etc/fstab</filename>, and will be
155        ignored when part of the <varname>Options=</varname> setting in a unit file.</para>
156
157        <para>See
158        <citerefentry><refentrytitle>systemd-mkswap@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
159        and the discussion of
160        <citerefentry project='man-pages'><refentrytitle>wipefs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
161        in <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
162        </para></listitem>
163      </varlistentry>
164    </variablelist>
165  </refsect1>
166
167  <refsect1>
168    <title>Options</title>
169
170    <para>Swap unit files may include [Unit] and [Install] sections, which are described in
171    <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
172    </para>
173
174    <para>Swap unit files must include a [Swap] section, which carries
175    information about the swap device it supervises. A number of
176    options that may be used in this section are shared with other
177    unit types. These options are documented in
178    <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
179    and
180    <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
181    The options specific to the [Swap] section of swap units are the
182    following:</para>
183
184    <variablelist class='unit-directives'>
185
186      <varlistentry>
187        <term><varname>What=</varname></term>
188        <listitem><para>Takes an absolute path of a device node or file to use for paging. See <citerefentry
189        project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
190        details. If this refers to a device node, a dependency on the respective device unit is automatically
191        created. (See
192        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
193        for more information.) If this refers to a file, a dependency on the respective mount unit is
194        automatically created. (See
195        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
196        more information.) This option is mandatory. Note that the usual specifier expansion is applied to
197        this setting, literal percent characters should hence be written as
198        <literal class='specifiers'>%%</literal>.</para></listitem>
199      </varlistentry>
200
201      <varlistentry>
202        <term><varname>Priority=</varname></term>
203
204        <listitem><para>Swap priority to use when activating the swap
205        device or file. This takes an integer. This setting is
206        optional and ignored when the priority is set by <option>pri=</option> in the
207        <varname>Options=</varname> key.</para></listitem>
208      </varlistentry>
209
210      <varlistentry>
211        <term><varname>Options=</varname></term>
212
213        <listitem><para>May contain an option string for the swap device. This may be used for controlling discard
214        options among other functionality, if the swap backing device supports the discard or trim operation. (See
215        <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
216        for more information.) Note that the usual specifier expansion is applied to this setting, literal percent
217        characters should hence be written as <literal>%%</literal>.</para></listitem>
218      </varlistentry>
219
220      <varlistentry>
221        <term><varname>TimeoutSec=</varname></term>
222        <listitem><para>Configures the time to wait for the swapon
223        command to finish. If a command does not exit within the
224        configured time, the swap will be considered failed and be
225        shut down again. All commands still running will be terminated
226        forcibly via <constant>SIGTERM</constant>, and after another
227        delay of this time with <constant>SIGKILL</constant>. (See
228        <option>KillMode=</option> in
229        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
230        Takes a unit-less value in seconds, or a time span value such
231        as "5min 20s". Pass <literal>0</literal> to disable the
232        timeout logic. Defaults to
233        <varname>DefaultTimeoutStartSec=</varname> from the manager
234        configuration file (see
235        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
236        </para></listitem>
237      </varlistentry>
238    </variablelist>
239
240    <xi:include href="systemd.service.xml" xpointer="shared-unit-options" />
241  </refsect1>
242
243  <refsect1>
244      <title>See Also</title>
245      <para>
246        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
247        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
248        <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
249        <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
250        <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
251        <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
252        <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
253        <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
254        <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
255        <citerefentry project='man-pages'><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
256        <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
257        <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
258      </para>
259  </refsect1>
260
261</refentry>
262