From cb1c2d174c1170e89cb69c44c372bd54ca75ce2c Mon Sep 17 00:00:00 2001
From: =?utf8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Wed, 26 Jul 2017 15:53:30 -0400
Subject: [PATCH] man: do not encourgage starting of poweroff/halt/reboot/kexec
 targets directly

Going through logind and systemd allows polkit to be used,
the job mode will be set properly, and is generally easier
to get correct.

Fixes #6452.
---
 man/systemd.special.xml | 32 ++++++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 8 deletions(-)

diff --git a/man/systemd.special.xml b/man/systemd.special.xml
index 66c45e39a3c..b31c087c763 100644
--- a/man/systemd.special.xml
+++ b/man/systemd.special.xml
@@ -305,8 +305,12 @@
           really just halts the system rather than powering it
           down.</para>
 
-          <para>Applications wanting to halt the system should start
-          this unit.</para>
+          <para>Applications wanting to halt the system should not start this unit
+          directly, but should instead execute <command>systemctl halt</command>
+          (possibly with the <option>--no-block</option> option) or call
+          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+          <command>org.freedesktop.systemd1.Manager.Halt</command> D-Bus method
+          directly.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -336,8 +340,12 @@
           <para>A special target unit for shutting down and rebooting
           the system via kexec.</para>
 
-          <para>Applications wanting to reboot the system with kexec
-          should start this unit.</para>
+          <para>Applications wanting to reboot the system should not start this unit
+          directly, but should instead execute <command>systemctl kexec</command>
+          (possibly with the <option>--no-block</option> option) or call
+          <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+          <command>org.freedesktop.systemd1.Manager.KExec</command> D-Bus method
+          directly.</para>
         </listitem>
       </varlistentry>
       <varlistentry>
@@ -430,8 +438,12 @@
           <para>A special target unit for shutting down and powering
           off the system.</para>
 
-          <para>Applications wanting to power off the system should
-          start this unit.</para>
+          <para>Applications wanting to reboot the system should not start this unit
+          directly, but should instead execute <command>systemctl poweroff</command>
+          (possibly with the <option>--no-block</option> option) or call
+          <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
+          <command>org.freedesktop.login1.Manager.PowerOff</command> D-Bus method
+          directly.</para>
 
           <para><filename>runlevel0.target</filename> is an alias for
           this target unit, for compatibility with SysV.</para>
@@ -443,8 +455,12 @@
           <para>A special target unit for shutting down and rebooting
           the system.</para>
 
-          <para>Applications wanting to reboot the system should start
-          this unit.</para>
+          <para>Applications wanting to reboot the system should not start this unit
+          directly, but should instead execute <command>systemctl reboot</command>
+          (possibly with the <option>--no-block</option> option) or call
+          <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
+          <command>org.freedesktop.login1.Manager.Reboot</command> D-Bus method
+          directly.</para>
 
           <para><filename>runlevel6.target</filename> is an alias for
           this target unit, for compatibility with SysV.</para>
-- 
2.47.3