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