Merge pull request #288 from phomes/cgroup-util

[thirdparty/systemd.git] / man / systemd.swap.xml

<?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" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>

<!--
  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, 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 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. Option <option>auto</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 priority is set by <option>pri=</option> in the
        <varname>Options=</varname> option.</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>