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