From c65aafbb3371db9047ad688493400a0b881c3949 Mon Sep 17 00:00:00 2001
From: Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Date: Mon, 9 Jan 2017 13:51:06 -0500
Subject: man: add more links to systemd-ask-password and
 systemd-tty-ask-password-agent

Loosely inspired by https://bugzilla.redhat.com/show_bug.cgi?id=1411134.
---
 man/systemd-ask-password.xml | 43 ++++++++++++++++++++++++++++---------------
 1 file changed, 28 insertions(+), 15 deletions(-)

(limited to 'man/systemd-ask-password.xml')

diff --git a/man/systemd-ask-password.xml b/man/systemd-ask-password.xml
index 2b6fb5a82f..8d3355819b 100644
--- a/man/systemd-ask-password.xml
+++ b/man/systemd-ask-password.xml
@@ -61,10 +61,9 @@
     a system password or passphrase from the user, using a question
     message specified on the command line. When run from a TTY it will
     query a password on the TTY and print it to standard output. When
-    run with no TTY or with <option>--no-tty</option> it will query
-    the password system-wide and allow active users to respond via
-    several agents. The latter is only available to privileged
-    processes.</para>
+    run with no TTY or with <option>--no-tty</option> it will use the
+    system-wide query mechanism, which allows active users to respond via
+    several agents, listed below.</para>
 
     <para>The purpose of this tool is to query system-wide passwords
     — that is passwords not attached to a specific user account.
@@ -76,25 +75,38 @@
     <itemizedlist>
 
       <listitem><para>A boot-time password agent asking the user for
-      passwords using Plymouth</para></listitem>
+      passwords using
+      <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      </para></listitem>
 
       <listitem><para>A boot-time password agent querying the user
-      directly on the console</para></listitem>
+      directly on the console —
+      <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      </para></listitem>
 
       <listitem><para>An agent requesting password input via a
-      <citerefentry
-      project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-      message</para></listitem>
-
-      <listitem><para>A command line agent which can be started
-      temporarily to process queued password
-      requests</para></listitem>
+      <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+      message —
+      <citerefentry><refentrytitle>systemd-ask-password-wall.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      </para></listitem>
 
       <listitem><para>A TTY agent that is temporarily spawned during
       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-      invocations</para></listitem>
+      invocations,</para></listitem>
+
+      <listitem><para>A command line agent which can be started
+      temporarily to process queued password
+      requests — <command>systemd-tty-ask-password-agent --query</command>.
+      </para></listitem>
     </itemizedlist></para>
 
+    <para>Answering system-wide password queries is a privileged operation, hence
+    all the agents listed above (except for the last one), run as privileged
+    system services. The last one also needs elevated privileges, so
+    should be run through
+    <citerefentry project='die-net'><refentrytitle>sudo</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    or similar.</para>
+
     <para>Additional password agents may be implemented according to
     the <ulink
     url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">systemd
@@ -217,7 +229,8 @@
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-      <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-ask-password-console.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>systemd-tty-ask-password</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>keyctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
       <citerefentry project='die-net'><refentrytitle>plymouth</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-- 
cgit v1.2.3-54-g00ecf