From 29908cb6dff901df7aa083e2a8c44b0f9cc57253 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Tue, 16 Jul 2013 16:31:59 -0600 Subject: [PATCH] Document that the -h option can be used specify a host name for future plugins. --- doc/sudo.cat | 23 +++++++++------ doc/sudo.man.in | 76 ++++++++++++++++++++++++++---------------------- doc/sudo.mdoc.in | 28 ++++++++++++++---- 3 files changed, 77 insertions(+), 50 deletions(-) diff --git a/doc/sudo.cat b/doc/sudo.cat index 75f6876b5..29bc20736 100644 --- a/doc/sudo.cat +++ b/doc/sudo.cat @@ -7,14 +7,14 @@ SSYYNNOOPPSSIISS ssuuddoo --hh | --KK | --kk | --VV ssuuddoo --vv [--AAkknnSS] [--aa _a_u_t_h___t_y_p_e] [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--pp _p_r_o_m_p_t] [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] - ssuuddoo --ll[_l] [--AAkknnSS] [--aa _a_u_t_h___t_y_p_e] [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--pp _p_r_o_m_p_t] - [--UU _u_s_e_r _n_a_m_e] [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] [_c_o_m_m_a_n_d] + ssuuddoo --ll[_l] [--AAkknnSS] [--aa _a_u_t_h___t_y_p_e] [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--hh _h_o_s_t _n_a_m_e] + [--pp _p_r_o_m_p_t] [--UU _u_s_e_r _n_a_m_e] [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] [_c_o_m_m_a_n_d] ssuuddoo [--AAbbEEHHnnPPSS] [--aa _a_u_t_h___t_y_p_e] [--CC _f_d] [--cc _c_l_a_s_s | _-] - [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--pp _p_r_o_m_p_t] [--rr _r_o_l_e] [--tt _t_y_p_e] - [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] [VVAARR=_v_a_l_u_e] --ii | --ss [_c_o_m_m_a_n_d] + [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--hh _h_o_s_t _n_a_m_e] [--pp _p_r_o_m_p_t] [--rr _r_o_l_e] + [--tt _t_y_p_e] [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] [VVAARR=_v_a_l_u_e] --ii | --ss [_c_o_m_m_a_n_d] ssuuddooeeddiitt [--AAnnSS] [--aa _a_u_t_h___t_y_p_e] [--CC _f_d] [--cc _c_l_a_s_s | _-] - [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--pp _p_r_o_m_p_t] [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] file - ... + [--gg _g_r_o_u_p _n_a_m_e | _#_g_i_d] [--hh _h_o_s_t _n_a_m_e] [--pp _p_r_o_m_p_t] + [--uu _u_s_e_r _n_a_m_e | _#_u_i_d] file ... DDEESSCCRRIIPPTTIIOONN ssuuddoo allows a permitted user to execute a _c_o_m_m_a_n_d as the superuser or @@ -148,8 +148,13 @@ DDEESSCCRRIIPPTTIIOONN database. Depending on the policy, this may be the default behavior. - --hh The --hh (_h_e_l_p) option causes ssuuddoo to print a short help - message to the standard output and exit. + --hh [_h_o_s_t _n_a_m_e] + If a _h_o_s_t _n_a_m_e is specified and the policy plugin supports + it, the command will be run on the specified remote host. + Note that the _s_u_d_o_e_r_s plugin does not currently support + running remote commands. If no _h_o_s_t _n_a_m_e is specified, ssuuddoo + will print a short help message to the standard output and + exit. --ii [_c_o_m_m_a_n_d] The --ii (_s_i_m_u_l_a_t_e _i_n_i_t_i_a_l _l_o_g_i_n) option runs the shell @@ -561,4 +566,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for complete details. -Sudo 1.8.7 March 13, 2013 Sudo 1.8.7 +Sudo 1.8.8 July 16, 2013 Sudo 1.8.8 diff --git a/doc/sudo.man.in b/doc/sudo.man.in index 5c6f032b7..b2faf186f 100644 --- a/doc/sudo.man.in +++ b/doc/sudo.man.in @@ -21,7 +21,7 @@ .\" Agency (DARPA) and Air Force Research Laboratory, Air Force .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. .\" -.TH "SUDO" "@mansectsu@" "March 13, 2013" "Sudo @PACKAGE_VERSION@" "System Manager's Manual" +.TH "SUDO" "@mansectsu@" "July 16, 2013" "Sudo @PACKAGE_VERSION@" "System Manager's Manual" .nh .if n .ad l .SH "NAME" @@ -31,7 +31,7 @@ .SH "SYNOPSIS" .HP 5n \fBsudo\fR -\fB\-h\fR | \fB\-K\fR | \fB\-k\fR | \fB\-V\fR +\fB\-h\fR\ |\ \fB\-K\fR\ |\ \fB\-k\fR\ |\ \fB\-V\fR .PD 0 .HP 5n \fBsudo\fR @@ -48,6 +48,7 @@ [\fB\-AknS\fR] [\fB\-a\fR\ \fIauth_type\fR] [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR] +[\fB\-h\fR\ \fIhost\ name\fR] [\fB\-p\fR\ \fIprompt\fR] [\fB\-U\fR\ \fIuser\ name\fR] [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR] @@ -60,6 +61,7 @@ [\fB\-C\fR\ \fIfd\fR] [\fB\-c\fR\ \fIclass\fR\ |\ \fI-\fR] [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR] +[\fB\-h\fR\ \fIhost\ name\fR] [\fB\-p\fR\ \fIprompt\fR] [\fB\-r\fR\ \fIrole\fR] [\fB\-t\fR\ \fItype\fR] @@ -75,6 +77,7 @@ [\fB\-C\fR\ \fIfd\fR] [\fB\-c\fR\ \fIclass\fR\ |\ \fI-\fR] [\fB\-g\fR\ \fIgroup\ name\fR\ |\ \fI#gid\fR] +[\fB\-h\fR\ \fIhost\ name\fR] [\fB\-p\fR\ \fIprompt\fR] [\fB\-u\fR\ \fIuser\ name\fR\ |\ \fI#uid\fR] file ... @@ -166,21 +169,19 @@ sudo.conf(@mansectform@) contains a line specifying the askpass program, that value will be used. For example: -.RS .nf .sp -.RS 4n +.RS 16n # Path to askpass helper program Path askpass /usr/X11R6/bin/ssh-askpass .RE .fi +.RS 12n .sp If no askpass program is available, \fBsudo\fR will exit with an error. -.PP .RE -.PD 0 .TP 12n \fB\-a\fR \fItype\fR The @@ -192,11 +193,10 @@ as allowed by \fI/etc/login.conf\fR. The system administrator may specify a list of sudo-specific authentication methods by adding an -``auth-sudo'' +\(lqauth-sudo\(rq entry in \fI/etc/login.conf\fR. This option is only available on systems that support BSD authentication. -.PD .TP 12n \fB\-b\fR The @@ -243,7 +243,7 @@ The argument can be either a class name as defined in \fI/etc/login.conf\fR, or a single -`\-' +\(oq\-\(cq character. Specifying a \fIclass\fR @@ -278,7 +278,7 @@ In lieu of a command, the string "sudoedit" is used when consulting the security policy. If the user is authorized by the policy, the following steps are taken: -.RS +.RS 13n .TP 5n 1. Temporary copies are made of the files to be edited with the owner @@ -308,7 +308,9 @@ option is used. 3. If they have been modified, the temporary files are copied back to their original location and the temporary versions are removed. -.PP +.RE +.RS 12n +.sp If the specified file does not exist, it will be created. Note that unlike most commands run by \fIsudo\fR, @@ -318,9 +320,7 @@ If, for some reason, is unable to update a file with its edited version, the user will receive a warning and the edited copy will remain in a temporary file. -.PP .RE -.PD 0 .TP 12n \fB\-g\fR \fIgroup\fR Normally, @@ -344,16 +344,15 @@ use When running commands as a \fIgid\fR, many shells require that the -`#' +\(oq#\(cq be escaped with a backslash -(`\e'). +(\(oq\e\(cq). If no \fB\-u\fR option is specified, the command will be run as the invoking user (not root). In either case, the primary group will be set to \fIgroup\fR. -.PD .TP 12n \fB\-H\fR The @@ -364,12 +363,19 @@ environment variable to the home directory of the target user (root by default) as specified by the password database. Depending on the policy, this may be the default behavior. .TP 12n -\fB\-h\fR -The -\fB\-h\fR (\fIhelp\fR) -option causes +\fB\-h\fR [\fIhost name\fR] +If a +\fIhost name\fR +is specified and the policy plugin supports it, the command will be run +on the specified remote host. +Note that the +\fIsudoers\fR +plugin does not currently support running remote commands. +If no +\fIhost name\fR +is specified, \fBsudo\fR -to print a short help message to the standard output and exit. +will print a short help message to the standard output and exit. .TP 12n \fB\-i\fR [\fIcommand\fR] The @@ -497,11 +503,13 @@ The option allows you to override the default password prompt and use a custom one. The following percent -(`%') +(\(oq%\(cq) escapes are supported by the \fIsudoers\fR policy: -.RS +.PP +.RS 12n +.PD 0 .TP 4n \fR%H\fR expanded to the host name including the domain name (on if the @@ -509,6 +517,7 @@ machine's host name is fully qualified or the \fIfqdn\fR option is set in sudoers(@mansectform@)) +.PD .TP 4n \fR%h\fR expanded to the local host name without the domain name @@ -534,9 +543,9 @@ expanded to the invoking user's login name .TP 4n \fR%%\fR two consecutive -`%' +\(oq%\(cq characters are collapsed into a single -`%' +\(oq%\(cq character .PP The prompt specified by the @@ -546,9 +555,7 @@ support PAM unless the \fIpassprompt_override\fR flag is disabled in \fIsudoers\fR. -.PP .RE -.PD 0 .TP 12n \fB\-r\fR \fIrole\fR The @@ -556,7 +563,6 @@ The option causes the new (SELinux) security context to have the role specified by \fIrole\fR. -.PD .TP 12n \fB\-S\fR The @@ -617,9 +623,9 @@ instead of a When running commands as a \fIuid\fR, many shells require that the -`#' +\(oq#\(cq be escaped with a backslash -(`\e'). +(\(oq\e\(cq). Security policies may restrict \fIuid\fRs to those listed in the password database. @@ -750,7 +756,7 @@ process waits until the command has completed, then passes the command's exit status to the security policy's close function and exits. If an I/O logging plugin is configured or if the security policy explicitly requests it, a new pseudo-terminal -(``pty'') +(\(lqpty\(rq) is created and a second \fBsudo\fR process is used to relay job control signals between the user's @@ -758,7 +764,7 @@ existing pty and the new pty the command is being run in. This extra process makes it possible to, for example, suspend and resume the command. Without it, the command would be in what POSIX terms an -``orphaned process group'' +\(lqorphaned process group\(rq and it would not receive any job control signals. As a special case, if the policy plugin does not define a close function and no pty is required, @@ -885,7 +891,7 @@ This should not happen under normal circumstances. The most common reason for stat(2) to return -``permission denied'' +\(lqpermission denied\(rq is if you are running an automounter and one of the directories in your \fRPATH\fR @@ -939,7 +945,7 @@ re-enabled for the command that is run). To aid in debugging \fBsudo\fR crashes, you may wish to re-enable core dumps by setting -``disable_coredump'' +\(lqdisable_coredump\(rq to false in the sudo.conf(@mansectform@) file as follows: @@ -1191,7 +1197,7 @@ search the archives. .SH "DISCLAIMER" \fBsudo\fR is provided -``AS IS'' +\(lqAS IS\(rq and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in index 605dd3f39..74dd3cd3b 100644 --- a/doc/sudo.mdoc.in +++ b/doc/sudo.mdoc.in @@ -19,7 +19,7 @@ .\" Agency (DARPA) and Air Force Research Laboratory, Air Force .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. .\" -.Dd March 13, 2013 +.Dd July 16, 2013 .Dt SUDO @mansectsu@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -54,6 +54,9 @@ .Op Fl g Ar group name No | Ar #gid .Ek .Bk -words +.Op Fl h Ar host name +.Ek +.Bk -words .Op Fl p Ar prompt .Ek .Bk -words @@ -78,6 +81,9 @@ .Op Fl g Ar group name No | Ar #gid .Ek .Bk -words +.Op Fl h Ar host name +.Ek +.Bk -words .Op Fl p Ar prompt .Ek .Bk -words @@ -111,6 +117,9 @@ .Op Fl g Ar group name No | Ar #gid .Ek .Bk -words +.Op Fl h Ar host name +.Ek +.Bk -words .Op Fl p Ar prompt .Ek .Bk -words @@ -381,12 +390,19 @@ option requests that the security policy set the environment variable to the home directory of the target user (root by default) as specified by the password database. Depending on the policy, this may be the default behavior. -.It Fl h -The -.Fl h No ( Em help Ns No ) -option causes +.It Fl h Op Ar host name +If a +.Ar host name +is specified and the policy plugin supports it, the command will be run +on the specified remote host. +Note that the +.Em sudoers +plugin does not currently support running remote commands. +If no +.Ar host name +is specified, .Nm sudo -to print a short help message to the standard output and exit. +will print a short help message to the standard output and exit. .It Fl i Op Ar command The .Fl i No ( Em simulate initial login Ns No )