From c65aafbb3371db9047ad688493400a0b881c3949 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@in.waw.pl>
Date: Mon, 9 Jan 2017 13:51:06 -0500
Subject: [PATCH] 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 +++++++++++++++++---------
 man/systemd-tty-ask-password-agent.xml | 10 ++++--
 2 files changed, 35 insertions(+), 18 deletions(-)

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>
diff --git a/man/systemd-tty-ask-password-agent.xml b/man/systemd-tty-ask-password-agent.xml
index 2876fab644..2e4b31be07 100644
--- a/man/systemd-tty-ask-password-agent.xml
+++ b/man/systemd-tty-ask-password-agent.xml
@@ -50,7 +50,9 @@
 
   <refsynopsisdiv>
     <cmdsynopsis>
-      <command>systemd-tty-ask-password-agent <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg></command>
+      <command>systemd-tty-ask-password-agent</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="opt" rep="repeat">VARIABLE=VALUE</arg>
     </cmdsynopsis>
   </refsynopsisdiv>
 
@@ -65,8 +67,10 @@
 
     <para><command>systemd-tty-ask-password-agent</command> implements
     the <ulink url="http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents">Password
-    Agents Specification</ulink>.</para>
-
+    Agents Specification</ulink>, and is one of many possible response agents which
+    answer to queries formulated with
+    <citerefentry><refentrytitle>systemd-ask-password</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    </para>
   </refsect1>
 
   <refsect1>