From edecb56216c910b36980fcf590b385ede413392b Mon Sep 17 00:00:00 2001
From: Lennart Poettering <lennart@poettering.net>
Date: Thu, 15 May 2025 14:58:07 +0200
Subject: [PATCH] man: document how to hook stuff into system wakeup

Fixes: #6364
---
 man/systemd.special.xml | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 0195bcb7fb..3e5e90cae8 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>