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>SuspendState=</varname></term>
 158
 159         <listitem><para>The string to be written to <filename>/sys/power/state</filename> by <citerefentry>
 160         <refentrytitle>systemd-suspend.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/state</command> to display). See <ulink
 167         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 this value when suspending.</para>
 173
 174         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><varname>HibernateMode=</varname></term>
 179
 180         <listitem><para>The string to be written to <filename>/sys/power/disk</filename> by <citerefentry>
 181         <refentrytitle>systemd-hibernate.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/disk</command> to display). See the kernel documentation page
 188         <ulink 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 the value of <varname>HibernateMode=</varname> when hibernating.</para>
 194
 195         <xi:include href="version-info.xml" xpointer="v203"/></listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><varname>MemorySleepMode=</varname></term>
 200
 201         <listitem><para>The string to be written to <filename>/sys/power/mem_sleep</filename>
 202         when <option>SuspendState=mem</option> or <command>hybrid-sleep</command> is used.
 203         More than one value can be specified by separating multiple values with whitespace. They will be
 204         tried in turn, until one is written without error. If none of the writes succeed, the operation will
 205         be aborted. Defaults to empty, i.e. the kernel default or kernel command line option
 206         <varname>mem_sleep_default=</varname> is respected.</para>
 207
 208         <para>The allowed set of values is determined by the kernel and is shown in the file itself (use
 209         <command>cat /sys/power/mem_sleep</command> to display). See the kernel documentation page
 210         <ulink url="https://docs.kernel.org/admin-guide/pm/sleep-states.html#basic-sysfs-interfaces-for-system-suspend-and-hibernation">
 211           Basic sysfs Interfaces for System Suspend and Hibernation</ulink> for more details.</para>
 212
 213         <xi:include href="version-info.xml" xpointer="v256"/></listitem>
 214       </varlistentry>
 215
 216       <varlistentry>
 217         <term><varname>HibernateDelaySec=</varname></term>
 218
 219         <listitem>
 220           <para>The amount of time the system spends in suspend mode before the system is
 221           automatically put into hibernate mode. Only used by
 222           <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 223           Refer to <command>suspend-then-hibernate</command> for details on how this option interacts with
 224           other options/system battery state.</para>
 225
 226           <xi:include href="version-info.xml" xpointer="v239"/>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry>
 231         <term><varname>HibernateOnACPower=</varname></term>
 232
 233         <listitem>
 234           <para>Whether to allow hibernation when the system has AC power. Only used by
 235           <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 236           when <varname>HibernateDelaySec=</varname> is set.</para>
 237
 238           <para>If this option is disabled, the countdown of <varname>HibernateDelaySec=</varname> starts only
 239           after AC power is disconnected, keeping the system in the suspend state otherwise.</para>
 240
 241           <para>This option is only effective on systems with a battery.</para>
 242
 243           <xi:include href="version-info.xml" xpointer="v257"/>
 244         </listitem>
 245       </varlistentry>
 246
 247       <varlistentry>
 248         <term><varname>SuspendEstimationSec=</varname></term>
 249
 250         <listitem>
 251           <para>The RTC alarm will wake the system after the specified timespan to measure the system battery
 252           capacity level and estimate battery discharging rate. Only used by
 253           <citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 254           Refer to <command>suspend-then-hibernate</command> for details on how this option interacts with
 255           other options/system battery state.</para>
 256
 257           <xi:include href="version-info.xml" xpointer="v253"/></listitem>
 258       </varlistentry>
 259     </variablelist>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>Example: freeze</title>
 264
 265     <para>Example: to exploit the <quote>freeze</quote> mode added
 266     in Linux 3.9, one can use <command>systemctl suspend</command>
 267     with
 268     <programlisting>[Sleep]
 269 SuspendState=freeze</programlisting></para>
 270   </refsect1>
 271
 272   <refsect1>
 273     <title>See Also</title>
 274     <para><simplelist type="inline">
 275       <member><citerefentry><refentrytitle>systemd-sleep</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 276       <member><citerefentry><refentrytitle>systemd-suspend.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 277       <member><citerefentry><refentrytitle>systemd-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 278       <member><citerefentry><refentrytitle>systemd-hybrid-sleep.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 279       <member><citerefentry><refentrytitle>systemd-suspend-then-hibernate.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 280       <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 281       <member><citerefentry><refentrytitle>systemd.directives</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 282     </simplelist></para>
 283   </refsect1>
 284
 285 </refentry>