chiark / gitweb /
analyze: change behaviour of combined --to/from--pattern
[elogind.git] / man / systemd.swap.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2010 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd.swap">
25   <refentryinfo>
26     <title>systemd.swap</title>
27     <productname>systemd</productname>
28
29     <authorgroup>
30       <author>
31         <contrib>Developer</contrib>
32         <firstname>Lennart</firstname>
33         <surname>Poettering</surname>
34         <email>lennart@poettering.net</email>
35       </author>
36     </authorgroup>
37   </refentryinfo>
38
39   <refmeta>
40     <refentrytitle>systemd.swap</refentrytitle>
41     <manvolnum>5</manvolnum>
42   </refmeta>
43
44   <refnamediv>
45     <refname>systemd.swap</refname>
46     <refpurpose>Swap unit configuration</refpurpose>
47   </refnamediv>
48
49   <refsynopsisdiv>
50     <para><filename><replaceable>swap</replaceable>.swap</filename></para>
51   </refsynopsisdiv>
52
53   <refsect1>
54     <title>Description</title>
55
56     <para>A unit configuration file whose name ends in
57     <literal>.swap</literal> encodes information about a swap device
58     or file for memory paging controlled and supervised by
59     systemd.</para>
60
61     <para>This man page lists the configuration options specific to
62     this unit type. See
63     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
64     for the common options of all unit configuration files. The common
65     configuration items are configured in the generic [Unit] and
66     [Install] sections. The swap specific configuration options are
67     configured in the [Swap] section.</para>
68
69     <para>Additional options are listed in
70     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
71     which define the execution environment the
72     <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
73     binary is executed in, and in
74     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
75     which define the way the processes are terminated, and in
76     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
77     which configure resource control settings for the processes of the
78     service.</para>
79
80     <para>Swap units must be named after the devices
81     or files they control. Example: the swap device
82     <filename noindex='true'>/dev/sda5</filename> must be configured in a
83     unit file <filename>dev-sda5.swap</filename>. For details about
84     the escaping logic used to convert a file system path to a unit
85     name, see
86     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
87
88     <para>All swap units automatically get the appropriate
89     dependencies on the devices or on the mount points of the files
90     they are activated from.</para>
91
92     <para>Swap units with <varname>DefaultDependencies=</varname>
93     enabled implicitly acquire a conflicting dependency to
94     <filename>umount.target</filename> so that they are deactivated at
95     shutdown.</para>
96   </refsect1>
97
98   <refsect1>
99     <title><filename>fstab</filename></title>
100
101     <para>Swap units may either be configured via unit files, or via
102     <filename>/etc/fstab</filename> (see
103     <citerefentry><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>
104     for details). Swaps listed in <filename>/etc/fstab</filename> will
105     be converted into native units dynamically at boot and when the
106     configuration of the system manager is reloaded. See
107     <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
108     for details about the conversion.</para>
109
110     <para>If a swap device or file is configured in both
111     <filename>/etc/fstab</filename> and a unit file, the configuration
112     in the latter takes precedence.</para>
113
114     <para>When reading <filename>/etc/fstab</filename> a few special
115     options are understood by systemd which influence how dependencies
116     are created for swap units.</para>
117
118     <variablelist class='fstab-options'>
119       <varlistentry>
120         <term><option>noauto</option></term>
121         <term><option>auto</option></term>
122
123         <listitem><para>With <option>noauto</option> the swap unit
124         will not be added as a dependency for
125         <filename>swap.target</filename>. This means that it will not
126         be activated automatically during boot, unless it is pulled in
127         by some other unit. Option <option>auto</option> has the
128         opposite meaning and is the default.</para>
129         </listitem>
130       </varlistentry>
131
132       <varlistentry>
133         <term><option>nofail</option></term>
134
135         <listitem><para>With <option>nofail</option> the swap unit
136         will be only wanted, not required by
137         <filename>swap.target</filename>. This means that the boot
138         will continue even if this swap device is not activated
139         successfully.</para>
140         </listitem>
141       </varlistentry>
142     </variablelist>
143   </refsect1>
144
145   <refsect1>
146     <title>Options</title>
147
148     <para>Swap files must include a [Swap] section, which carries
149     information about the swap device it supervises. A number of
150     options that may be used in this section are shared with other
151     unit types. These options are documented in
152     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
153     and
154     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
155     The options specific to the [Swap] section of swap units are the
156     following:</para>
157
158     <variablelist class='unit-directives'>
159
160       <varlistentry>
161         <term><varname>What=</varname></term>
162         <listitem><para>Takes an absolute path of a device node or
163         file to use for paging. See
164         <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
165         for details. If this refers to a device node, a dependency on
166         the respective device unit is automatically created. (See
167         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>
168         for more information.) If this refers to a file, a dependency
169         on the respective mount unit is automatically created. (See
170         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>
171         for more information.) This option is
172         mandatory.</para></listitem>
173       </varlistentry>
174
175       <varlistentry>
176         <term><varname>Priority=</varname></term>
177
178         <listitem><para>Swap priority to use when activating the swap
179         device or file. This takes an integer. This setting is
180         optional.</para></listitem>
181       </varlistentry>
182
183       <varlistentry>
184         <term><varname>Options=</varname></term>
185
186         <listitem><para>May contain an option string for the swap
187         device. This may be used for controlling discard options among
188         other functionality, if the swap backing device supports the
189         discard or trim operation. (See
190         <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
191         for more information.) </para></listitem>
192       </varlistentry>
193
194       <varlistentry>
195         <term><varname>TimeoutSec=</varname></term>
196         <listitem><para>Configures the time to wait for the swapon
197         command to finish. If a command does not exit within the
198         configured time, the swap will be considered failed and be
199         shut down again. All commands still running will be terminated
200         forcibly via <constant>SIGTERM</constant>, and after another
201         delay of this time with <constant>SIGKILL</constant>. (See
202         <option>KillMode=</option> in
203         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>.)
204         Takes a unit-less value in seconds, or a time span value such
205         as "5min 20s". Pass <literal>0</literal> to disable the
206         timeout logic. Defaults to
207         <varname>DefaultTimeoutStartSec=</varname> from the manager
208         configuration file (see
209         <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
210         </para></listitem>
211       </varlistentry>
212     </variablelist>
213
214     <para>Check
215     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
216     and
217     <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>
218     for more settings.</para>
219   </refsect1>
220
221   <refsect1>
222       <title>See Also</title>
223       <para>
224         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
225         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
226         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
227         <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
228         <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
229         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
230         <citerefentry><refentrytitle>systemd.device</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
231         <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
232         <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
233         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
234         <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
235       </para>
236   </refsect1>
237
238 </refentry>