man/systemd-sleep.conf.xml

   1 <?xml version='1.0'?>
   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-sleep.conf"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>systemd-sleep.conf</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-sleep.conf</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-sleep.conf</refname>
  20     <refname>sleep.conf.d</refname>
  21     <refpurpose>Suspend and hibernation configuration file</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>/etc/systemd/sleep.conf</filename></para>
  26     <para><filename>/etc/systemd/sleep.conf.d/*.conf</filename></para>
  27     <para><filename>/run/systemd/sleep.conf.d/*.conf</filename></para>
  28     <para><filename>/usr/lib/systemd/sleep.conf.d/*.conf</filename></para>
  29   </refsynopsisdiv>
  30
  31   <refsect1>
  32     <title>Description</title>
  33
  34     <para><command>systemd</command> supports four general
  35     power-saving modes:</para>
  36
  37     <variablelist>
  38       <varlistentry>
  39         <term>suspend</term>
  40
  41         <listitem><para>a low-power state
  42         where execution of the OS is paused,
  43         and complete power loss might result
  44         in lost data, and which is fast to
  45         enter and exit. This corresponds to
  46         suspend, standby, or freeze states as
  47         understood by the kernel.
  48         </para>
  49
  50         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
  51       </varlistentry>
  52
  53       <varlistentry>
  54         <term>hibernate</term>
  55
  56         <listitem><para>a low-power state
  57         where execution of the OS is paused,
  58         and complete power loss does not
  59         result in lost data, and which might
  60         be slow to enter and exit. This
  61         corresponds to the hibernation as
  62         understood by the kernel.
  63         </para>
  64
  65         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
  66       </varlistentry>
  67
  68       <varlistentry>
  69         <term>hybrid-sleep</term>
  70
  71         <listitem><para>a low-power state
  72         where execution of the OS is paused,
  73         which might be slow to enter, and on
  74         complete power loss does not result in
  75         lost data but might be slower to exit
  76         in that case. This mode is called
  77         suspend-to-both by the kernel.
  78         </para>
  79
  80         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
  81       </varlistentry>
  82
  83       <varlistentry>
  84         <term>suspend-then-hibernate</term>
  85
  86         <listitem>
  87           <para>A low power state where the system is initially suspended (the state is stored in RAM).
  88           When the battery level is too low (less than 5%) or a certain timespan has passed, whichever
  89           happens first, the system is automatically woken up and then hibernated. This establishes a balance
  90           between speed and safety.</para>
  91
  92           <para>If the system has no battery, it would be hibernated after <varname>HibernateDelaySec=</varname>
  93           has passed. If not set, then defaults to <literal>2h</literal>.</para>
  94
  95           <para>If the system has battery and <varname>HibernateDelaySec=</varname> is not set, low-battery
  96           alarms (ACPI _BTP) are tried first for detecting battery percentage and wake up the system for hibernation.
  97           If not available, or <varname>HibernateDelaySec=</varname> is set, the system would regularly wake
  98           up to check the time and detect the battery percentage/discharging rate. The rate is used to
  99           schedule the next detection. If that is also not available, <varname>SuspendEstimationSec=</varname>
 100           is used as last resort.</para>
 101
 102           <xi:include href="version-info.xml" xpointer="v239"/>
 103         </listitem>
 104       </varlistentry>
 105
 106     </variablelist>
 107
 108     <para>Settings in these files determine what strings
 109     will be written to
 110     <filename>/sys/power/disk</filename> and
 111     <filename>/sys/power/state</filename> by
 112     <citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 113     when
 114     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 115     attempts to suspend or hibernate the machine.
 116     See
 117     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 118     for a general description of the syntax.</para>
 119   </refsect1>
 120
 121   <xi:include href="standard-conf.xml" xpointer="main-conf" />
 122
 123   <refsect1>
 124     <title>Options</title>
 125
 126     <para>The following options can be configured in the
 127     [Sleep] section of
 128     <filename>/etc/systemd/sleep.conf</filename> or a
 129     <filename>sleep.conf.d</filename> file:</para>
 130
 131     <variablelist class='config-directives'>
 132       <varlistentry>
 133         <term><varname>AllowSuspend=</varname></term>
 134         <term><varname>AllowHibernation=</varname></term>
 135         <term><varname>AllowHybridSleep=</varname></term>
 136         <term><varname>AllowSuspendThenHibernate=</varname></term>
 137
 138         <listitem><para>By default any power-saving mode is advertised if possible (i.e.
 139         the kernel supports that mode, the necessary resources are available). Those
 140         switches can be used to disable specific modes.</para>
 141
 142         <para>If <varname>AllowHibernation=no</varname> or <varname>AllowSuspend=no</varname> is
 143         used, this implies <varname>AllowSuspendThenHibernate=no</varname> and
 144         <varname>AllowHybridSleep=no</varname>, since those methods use both suspend and hibernation
 145         internally. <varname>AllowSuspendThenHibernate=yes</varname> and
 146         <varname>AllowHybridSleep=yes</varname> can be used to override and enable those specific
 147         modes.</para>
 148
 149         <xi:include href="version-info.xml" xpointer="v240"/></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><varname>HibernateMode=</varname></term>
 154
 155         <listitem><para>The string to be written to <filename>/sys/power/disk</filename> by <citerefentry>
 156         <refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 157         More than one value can be specified by separating multiple values with whitespace. They will be
 158         tried in turn, until one is written without error. If none of the writes succeed, the operation will
 159         be aborted.</para>
 160
 161         <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
 162         <command>cat /sys/power/disk</command> to display). See the kernel documentation page
 163         <ulink url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
 164           Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
 165
 166         <para>
 167         <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 168         uses the value of <varname>HibernateMode=</varname> when hibernating.</para>
 169
 170         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
 171       </varlistentry>
 172
 173       <varlistentry>
 174         <term><varname>SuspendState=</varname></term>
 175
 176         <listitem><para>The string to be written to <filename>/sys/power/state</filename> by <citerefentry>
 177         <refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 178         More than one value can be specified by separating multiple values with whitespace. They will be
 179         tried in turn, until one is written without error. If none of the writes succeed, the operation will
 180         be aborted.</para>
 181
 182         <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
 183         <command>cat /sys/power/state</command> to display). See <ulink
 184         url="https://www.kernel.org/doc/html/latest/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
 185           Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
 186
 187         <para>
 188         <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 189         uses this value when suspending.</para>
 190
 191         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
 192       </varlistentry>
 193
 194       <varlistentry>
 195         <term><varname>HibernateDelaySec=</varname></term>
 196
 197         <listitem>
 198           <para>The amount of time the system spends in suspend mode before the system is
 199           automatically put into hibernate mode. Only used by
 200           <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 201           Refer to <command>suspend-then-hibernate</command> for details on how this option interacts with
 202           other options/system battery state.</para>
 203
 204           <xi:include href="version-info.xml" xpointer="v239"/>
 205         </listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><varname>SuspendEstimationSec=</varname></term>
 210
 211         <listitem>
 212           <para>The RTC alarm will wake the system after the specified timespan to measure the system battery
 213           capacity level and estimate battery discharging rate. Only used by
 214           <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 215           Refer to <command>suspend-then-hibernate</command> for details on how this option interacts with
 216           other options/system battery state.</para>
 217
 218           <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 219       </varlistentry>
 220     </variablelist>
 221   </refsect1>
 222
 223   <refsect1>
 224     <title>Example: freeze</title>
 225
 226     <para>Example: to exploit the <quote>freeze</quote> mode added
 227     in Linux 3.9, one can use <command>systemctl suspend</command>
 228     with
 229     <programlisting>[Sleep]
 230 SuspendState=freeze</programlisting></para>
 231   </refsect1>
 232
 233   <refsect1>
 234     <title>See Also</title>
 235     <para>
 236       <citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 237       <citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 238       <citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 239       <citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 240       <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 241       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 242       <citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 243     </para>
 244   </refsect1>
 245
 246 </refentry>