From: Todd C. Miller <Todd.Miller@courtesan.com>
Date: Sun, 2 Mar 2008 22:31:08 +0000 (+0000)
Subject: document -A and askpass
X-Git-Tag: SUDO_1_7_0~172
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=143691e6d75b41c5716904f05f8c088b33dfa261;p=sudo

document -A and askpass
---

diff --git a/sudo.pod b/sudo.pod
index e2d19377b..ba3af82ee 100644
--- a/sudo.pod
+++ b/sudo.pod
@@ -29,10 +29,10 @@ sudo, sudoedit - execute a command as another user
 
 B<sudo> B<-h> | B<-K> | B<-k> | B<-L> | B<-V> | B<-v>
 
-B<sudo> B<-l[l]> S<[B<-g> I<groupname>|I<#gid>]> S<[B<-U> I<username>]>
+B<sudo> B<-l[l]> [B<-AS>] S<[B<-g> I<groupname>|I<#gid>]> S<[B<-U> I<username>]>
 S<[B<-u> I<username>|I<#uid>]> [I<command>]
 
-B<sudo> [B<-bEHPS>]
+B<sudo> [B<-AbEHPS>]
 S<[B<-a> I<auth_type>]>
 S<[B<-C> I<fd>]>
 S<[B<-c> I<class>|I<->]>
@@ -41,7 +41,7 @@ S<[B<-r> I<role>]> S<[B<-t> I<type>]>
 S<[B<-u> I<username>|I<#uid>]>
 S<[B<VAR>=I<value>]> [S<{B<-i> | B<-s>] [<I<command>}>]
 
-B<sudoedit> [B<-S>]
+B<sudoedit> [B<-AS>]
 S<[B<-a> I<auth_type>]>
 S<[B<-C> I<fd>]>
 S<[B<-c> I<class>|I<->]>
@@ -101,6 +101,16 @@ B<sudo> accepts the following command line options:
 
 =over 12
 
+=item -A
+
+Normally, if B<sudo> requires a password, it will read it from the
+current terminal.  If the B<-A> (I<askpass>) option is specified,
+a helper program is executed to read the user's password and output
+the password to the standard output.  If the C<SUDO_ASKPASS>
+environment variable is set, it specifies the path to the helper
+program.  Otherwise, the value specified by the I<askpass> option
+in L<sudoers(5)> is used.
+
 =item -a I<type>
 
 The B<-a> (I<authentication type>) option causes B<sudo> to use the
@@ -483,6 +493,11 @@ Set to a sane value if the I<secure_path> sudoers option is set.
 
 Used to determine shell to run with C<-s> option
 
+=item C<SUDO_ASKPASS>
+
+Specifies the path to a helper program used to read the password
+if no terminal is available or if the C<-A> option is specified.
+
 =item C<SUDO_PROMPT>
 
 Used as the default password prompt
diff --git a/sudo_usage.h.in b/sudo_usage.h.in
index e893e2d0e..2351505ce 100644
--- a/sudo_usage.h.in
+++ b/sudo_usage.h.in
@@ -5,8 +5,8 @@
  * Usage strings for sudo.  These are here because we
  * need to be able to substitute values from configure.
  */
-#define SUDO_USAGE1 " [-A] -h | -K | -k | -L | -V | -v"
-#define SUDO_USAGE2 " -l[l] [-A] [-g groupname|#gid] [-U username] [-u username|#uid] [-g groupname|#gid] [command]"
+#define SUDO_USAGE1 " -h | -K | -k | -L | -V | -v"
+#define SUDO_USAGE2 " -l[l] [-AS] [-g groupname|#gid] [-U username] [-u username|#uid] [-g groupname|#gid] [command]"
 #define SUDO_USAGE3 " [-AbEHPS] @BSDAUTH_USAGE@@SELINUX_USAGE@[-C fd] @LOGINCAP_USAGE@[-g groupname|#gid] [-p prompt] [-u username|#uid] [-g groupname|#gid] [VAR=value] [-i|-s] [<command>]"
 #define SUDO_USAGE4 " -e [-AS] @BSDAUTH_USAGE@@SELINUX_USAGE@[-C fd] @LOGINCAP_USAGE@[-g groupname|#gid] [-p prompt] [-u username|#uid] file ..."
 
diff --git a/sudoers.pod b/sudoers.pod
index f7db3efbf..8d11f9dee 100644
--- a/sudoers.pod
+++ b/sudoers.pod
@@ -915,6 +915,17 @@ B<Strings that can be used in a boolean context>:
 
 =over 12
 
+=item askpass
+
+The I<askpass> option specifies the fully-qualilfy path to a helper
+program used to read the user's password when no terminal is
+available.  This may be the case when B<sudo> is executed from a
+graphical (as opposed to text-based) application.  The program
+specified by I<askpass> should display the argument passed to it
+as the prompt and write the user's password to the standard output.
+The value of I<askpass> may be overridden by the C<SUDO_ASKPASS>
+environment variable.
+
 =item exempt_group
 
 Users in this group are exempt from password and PATH requirements.