systemd/man/systemd.swap.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
<!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><refentrytitle>swapon</refentrytitle><manvolnum>8</manvolnum></citerefentry>
                binary is executed in, and in
                <citerefentry><refentrytitle>systemd.kill</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which define the way the processes are
                terminated, and in
                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                which configure resource control settings for the
                processes of the service.</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>.</para>

                <para>All swap units automatically get the appropriate
                dependencies on the devices or on the mount points
                of the files they are activated from.</para>

                <para>Swap units with
                <varname>DefaultDependencies=</varname> enabled
                implicitly acquire a conflicting dependency to
                <filename>umount.target</filename> so that they are
                deactivated at shutdown.</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><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. Option <option>auto</option> has the
                    opposite meaning and is the default.</para>
                    </listitem>
                  </varlistentry>

                  <varlistentry>
                    <term><option>nofail</option></term>
                    <term><option>fail</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. Option
                    <option>fail</option> has the opposite meaning and
                    is the default.</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><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.</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><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><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>