From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Wed, 26 Jul 2017 19:53:30 +0000 (-0400)
Subject: man: do not encourgage starting of poweroff/halt/reboot/kexec targets directly
X-Git-Tag: v235~289^2~1
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=cb1c2d174c1170e89cb69c44c372bd54ca75ce2c;p=thirdparty%2Fsystemd.git

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.
---

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>