From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 15 May 2025 12:58:07 +0000 (+0200)
Subject: man: document how to hook stuff into system wakeup
X-Git-Tag: v258-rc1~592
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=edecb56216c910b36980fcf590b385ede413392b;p=thirdparty%2Fsystemd.git

man: document how to hook stuff into system wakeup

Fixes: #6364
---

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 0195bcb7fb3..3e5e90cae85 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -754,12 +754,38 @@
         <varlistentry>
           <term><filename>sleep.target</filename></term>
           <listitem>
-            <para>A special target unit that is pulled in by
-            <filename>suspend.target</filename>,
-            <filename>hibernate.target</filename>,
-            <filename>suspend-then-hibernate.target</filename>, and
-            <filename>hybrid-sleep.target</filename> and may be used to
-            hook units into the sleep state logic.</para>
+            <para>A special target unit that is pulled in by <filename>suspend.target</filename>,
+            <filename>hibernate.target</filename>, <filename>suspend-then-hibernate.target</filename>, and
+            <filename>hybrid-sleep.target</filename> and may be used to hook units into the sleep state
+            logic.</para>
+
+            <para>In order to hook external programs <emphasis>before</emphasis> the actual system sleep
+            operation, place their command line in a service unit file's <varname>ExecStart=</varname> line
+            (use <varname>Type=oneshot</varname>), and ensure the unit is pulled in by
+            <filename>sleep.target</filename> and ordered before it. In order to hook program code
+            <emphasis>after</emphasis> the actual system sleep operation (i.e. to be run after the system
+            woke up again), place the command in <varname>ExecStop=</varname> instead, and make sure to
+            enable <varname>StopWhenUnneeded=</varname> and <varname>RemainAfterExit=</varname>. Both
+            approaches can be combined into one unit file in order to run programs both before and after the
+            sleep operation.</para>
+
+            <example>
+              <title>Combined Example</title>
+
+              <programlisting>[Unit]
+DefaultDependencies=no
+StopWhenUnneeded=yes
+Before=sleep.target
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+ExecStart=/usr/bin/some-before-command
+ExecStop=/Usr/bin/some-after-command
+
+[Install]
+WantedBy=sleep.target</programlisting>
+            </example>
           </listitem>
         </varlistentry>
         <varlistentry>