From: Todd C. Miller Date: Thu, 22 Jan 2004 01:00:54 +0000 (+0000) Subject: Document sudo -e / sudoedit X-Git-Tag: SUDO_1_6_8~213 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=be8c6acf645f5a6f65f7cb4d588c476d4f1ed127;p=sudo Document sudo -e / sudoedit --- diff --git a/sudo.man.in b/sudo.man.in index bf31f595f..fd6bfaa81 100644 --- a/sudo.man.in +++ b/sudo.man.in @@ -167,7 +167,7 @@ .\" ======================================================================== .\" .IX Title "SUDO @mansectsu@" -.TH SUDO @mansectsu@ "January 18, 2004" "1.6.8" "MAINTENANCE COMMANDS" +.TH SUDO @mansectsu@ "January 21, 2004" "1.6.8" "MAINTENANCE COMMANDS" .SH "NAME" sudo \- execute a command as another user .SH "SYNOPSIS" @@ -175,8 +175,12 @@ sudo \- execute a command as another user \&\fBsudo\fR \fB\-K\fR | \fB\-L\fR | \fB\-V\fR | \fB\-h\fR | \fB\-k\fR | \fB\-l\fR | \fB\-v\fR .PP \&\fBsudo\fR [\fB\-HPSb\fR] [\fB\-a\fR\ \fIauth_type\fR] [\fB\-c\fR\ \fIclass\fR|\fI\-\fR] -s<[\fB\-p\fR \fIprompt\fR]> [\fB\-u\fR\ \fIusername\fR|\fI#uid\fR] -{\fB\-i\fR\ |\ \fB\-s\fR\ |\ \fIcommand\fR} +[\fB\-p\fR\ \fIprompt\fR] [\fB\-u\fR\ \fIusername\fR|\fI#uid\fR] +{\fB\-e\fR\ file\ [...]\ |\ \fB\-i\fR\ |\ \fB\-s\fR\ |\ \fIcommand\fR} +.PP +\&\fBsudoedit\fR [\fB\-S\fR] [\fB\-a\fR\ \fIauth_type\fR] +[\fB\-p\fR\ \fIprompt\fR] [\fB\-u\fR\ \fIusername\fR|\fI#uid\fR] +file [...] .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBsudo\fR allows a permitted user to execute a \fIcommand\fR as the @@ -190,6 +194,9 @@ Once a user has been authenticated, a timestamp is updated and the user may then use sudo without a password for a short period of time (\f(CW\*(C`@timeout@\*(C'\fR minutes unless overridden in \fIsudoers\fR). .PP +When invoked as \fBsudoedit\fR, the \fB\-e\fR option (described below), +is implied. +.PP \&\fBsudo\fR determines who is an authorized user by consulting the file \&\fI@sysconfdir@/sudoers\fR. By giving \fBsudo\fR the \fB\-v\fR flag a user can update the time stamp without running a \fIcommand.\fR The password @@ -205,6 +212,13 @@ to run sudo with the \fB\-l\fR or \fB\-v\fR flags. This allows users to determine for themselves whether or not they are allowed to use \&\fBsudo\fR. .PP +If \fBsudo\fR is run by root and the \f(CW\*(C`SUDO_USER\*(C'\fR environment variable +is set, \fBsudo\fR will use this value to determine who the actual +user is. This can be used by a user to log commands through sudo +even when a root shell has been invoked. It also allows the \fB\-e\fR +flag to remain useful even when being run via a sudo-run script or +program. +.PP \&\fBsudo\fR can log both successful and unsuccessful attempts (as well as errors) to \fIsyslog\fR\|(3), a log file, or both. By default \fBsudo\fR will log via \fIsyslog\fR\|(3) but this is changeable at configure time @@ -269,6 +283,35 @@ argument specifies an existing user class, the command must be run as root, or the \fBsudo\fR command must be run from a shell that is already root. This option is only available on systems with \s-1BSD\s0 login classes where \fBsudo\fR has been configured with the \-\-with\-logincap option. +.IP "\-e" 4 +.IX Item "-e" +The \fB\-e\fR (\fIedit\fR) option indicates that, instead of running +a command, the user wishes to edit one or more files. In lieu +of a command, the string \fI\*(L"sudoedit\*(R"\fR is used when consulting +the \fIsudoers\fR file. If the user is authorized by \fIsudoers\fR +the following steps are taken: +.RS 4 +.IP "1." 8 +Temporary copies are made of the files to be edited, owned by the +invoking user. +.IP "2." 8 +The editor specified by the \f(CW\*(C`VISUAL\*(C'\fR or \f(CW\*(C`EDITOR\*(C'\fR environment +variables is run to edit the temporary files. If neither \f(CW\*(C`VISUAL\*(C'\fR +nor \f(CW\*(C`EDITOR\*(C'\fR are set, the program listed in the \fIeditor\fR \fIsudoers\fR +variable is used. +.IP "3." 8 +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. +.RE +.RS 4 +.Sp +If the specified file does not exist, it will be created. Note +that unlike most commands run by \fBsudo\fR, the editor is run with +the invoking user's environment unmodified. If, for some reason, +\&\fBsudo\fR 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. +.RE .IP "\-h" 4 .IX Item "-h" The \fB\-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a usage message and exit. @@ -325,7 +368,7 @@ sudoers option is set) .ie n .IP "\*(C`%%\*(C'" 8 .el .IP "\f(CW\*(C`%%\*(C'\fR" 8 .IX Item "%%" -two consecutive \f(CW\*(C`%\*(C'\fR characters are collaped into a single \f(CW\*(C`%\*(C'\fR character +two consecutive \f(CW\*(C`%\*(C'\fR characters are collasped into a single \f(CW\*(C`%\*(C'\fR character .RE .RS 4 .RE @@ -467,23 +510,59 @@ to make the \f(CW\*(C`cd\*(C'\fR and file redirection work. .IX Header "ENVIRONMENT" \&\fBsudo\fR utilizes the following environment variables: .PP -.Vb 13 -\& PATH Set to a sane value if SECURE_PATH is set -\& SHELL Used to determine shell to run with -s option -\& USER Set to the target user (root unless the -u option -\& is specified) +.Vb 2 +\& EDITOR Default editor to use in -e (sudoedit) mode if +\& VISUAL is not set +.Ve +.PP +.Vb 3 \& HOME In -s or -H mode (or if sudo was configured with \& the --enable-shell-sets-home option), set to -\& homedir of the target user. +\& homedir of the target user +.Ve +.PP +.Vb 1 +\& PATH Set to a sane value if SECURE_PATH is set +.Ve +.PP +.Vb 1 +\& SHELL Used to determine shell to run with -s option +.Ve +.PP +.Vb 1 \& SUDO_PROMPT Used as the default password prompt +.Ve +.PP +.Vb 1 \& SUDO_COMMAND Set to the command run by sudo +.Ve +.PP +.Vb 1 \& SUDO_USER Set to the login of the user who invoked sudo +.Ve +.PP +.Vb 1 \& SUDO_UID Set to the uid of the user who invoked sudo +.Ve +.PP +.Vb 1 \& SUDO_GID Set to the gid of the user who invoked sudo +.Ve +.PP +.Vb 1 \& SUDO_PS1 If set, PS1 will be set to its value .Ve -.SH "FILES" -.IX Header "FILES" +.PP +.Vb 2 +\& USER Set to the target user (root unless the -u option +\& is specified) +.Ve +.PP +.Vb 2 +\& VISUAL Default editor to use in -e (sudoedit) mode +\&=head1 FILES +.Ve +.PP .Vb 2 \& @sysconfdir@/sudoers List of who can run what \& @timedir@ Directory containing timestamps diff --git a/sudo.pod b/sudo.pod index 0819221cc..9ca04dfa5 100644 --- a/sudo.pod +++ b/sudo.pod @@ -48,8 +48,12 @@ sudo - execute a command as another user B B<-K> | B<-L> | B<-V> | B<-h> | B<-k> | B<-l> | B<-v> B [B<-HPSb>] S<[B<-a> I]> S<[B<-c> I|I<->]> -s<[B<-p> I]> S<[B<-u> I|I<#uid>]> -S<{B<-i> | B<-s> | I}> +S<[B<-p> I]> S<[B<-u> I|I<#uid>]> +S<{B<-e> file [...] | B<-i> | B<-s> | I}> + +B [B<-S>] S<[B<-a> I]> +S<[B<-p> I]> S<[B<-u> I|I<#uid>]> +file [...] =head1 DESCRIPTION @@ -64,6 +68,9 @@ Once a user has been authenticated, a timestamp is updated and the user may then use sudo without a password for a short period of time (C<@timeout@> minutes unless overridden in I). +When invoked as B, the B<-e> option (described below), +is implied. + B determines who is an authorized user by consulting the file F<@sysconfdir@/sudoers>. By giving B the B<-v> flag a user can update the time stamp without running a I The password @@ -79,6 +86,13 @@ to run sudo with the B<-l> or B<-v> flags. This allows users to determine for themselves whether or not they are allowed to use B. +If B is run by root and the C environment variable +is set, B will use this value to determine who the actual +user is. This can be used by a user to log commands through sudo +even when a root shell has been invoked. It also allows the B<-e> +flag to remain useful even when being run via a sudo-run script or +program. + B can log both successful and unsuccessful attempts (as well as errors) to syslog(3), a log file, or both. By default B will log via syslog(3) but this is changeable at configure time @@ -156,6 +170,42 @@ as root, or the B command must be run from a shell that is already root. This option is only available on systems with BSD login classes where B has been configured with the --with-logincap option. +=item -e + +The B<-e> (I) option indicates that, instead of running +a command, the user wishes to edit one or more files. In lieu +of a command, the string I<"sudoedit"> is used when consulting +the I file. If the user is authorized by I +the following steps are taken: + +=over 8 + +=item 1. + +Temporary copies are made of the files to be edited, owned by the +invoking user. + +=item 2. + +The editor specified by the C or C environment +variables is run to edit the temporary files. If neither C +nor C are set, the program listed in the I I +variable is used. + +=item 3. + +If they have been modified, the temporary files are copied back to +their original location and the temporary versions are removed. + +=back 8 + +If the specified file does not exist, it will be created. Note +that unlike most commands run by B, the editor is run with +the invoking user's environment unmodified. If, for some reason, +B 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. + =item -h The B<-h> (I) option causes B to print a usage message and exit. @@ -217,7 +267,7 @@ sudoers option is set) =item C<%%> -two consecutive C<%> characters are collaped into a single C<%> character +two consecutive C<%> characters are collasped into a single C<%> character =back 8 @@ -359,20 +409,33 @@ to make the C and file redirection work. B utilizes the following environment variables: - PATH Set to a sane value if SECURE_PATH is set - SHELL Used to determine shell to run with -s option - USER Set to the target user (root unless the -u option - is specified) + EDITOR Default editor to use in -e (sudoedit) mode if + VISUAL is not set + HOME In -s or -H mode (or if sudo was configured with the --enable-shell-sets-home option), set to - homedir of the target user. + homedir of the target user + + PATH Set to a sane value if SECURE_PATH is set + + SHELL Used to determine shell to run with -s option + SUDO_PROMPT Used as the default password prompt + SUDO_COMMAND Set to the command run by sudo + SUDO_USER Set to the login of the user who invoked sudo + SUDO_UID Set to the uid of the user who invoked sudo + SUDO_GID Set to the gid of the user who invoked sudo + SUDO_PS1 If set, PS1 will be set to its value + USER Set to the target user (root unless the -u option + is specified) + + VISUAL Default editor to use in -e (sudoedit) mode =head1 FILES @sysconfdir@/sudoers List of who can run what diff --git a/sudoers.man.in b/sudoers.man.in index 5ef63f7b3..d27ac0e0a 100644 --- a/sudoers.man.in +++ b/sudoers.man.in @@ -167,7 +167,7 @@ .\" ======================================================================== .\" .IX Title "SUDOERS @mansectform@" -.TH SUDOERS @mansectform@ "January 18, 2004" "1.6.8" "MAINTENANCE COMMANDS" +.TH SUDOERS @mansectform@ "January 21, 2004" "1.6.8" "MAINTENANCE COMMANDS" .SH "NAME" sudoers \- list of which users may execute what .SH "DESCRIPTION" @@ -333,9 +333,10 @@ to be useful. \& filename '""' .Ve .PP -.Vb 3 +.Vb 4 \& Cmnd ::= '!'* commandname | \& '!'* directory | +\& '!'* "sudoedit" | \& '!'* Cmnd_Alias .Ve .PP @@ -354,7 +355,10 @@ If a \f(CW\*(C`Cmnd\*(C'\fR has associated command line arguments, then the argu in the \f(CW\*(C`Cmnd\*(C'\fR must match exactly those given by the user on the command line (or match the wildcards if there are any). Note that the following characters must be escaped with a '\e' if they are used in command -arguments: ',', ':', '=', '\e'. +arguments: ',', ':', '=', '\e'. The special command \f(CW"sudoedit"\fR +is used to permit a user to run \fBsudo\fR with the \fB\-e\fR flag (or +as \fBsudoedit\fR). It may take command line arguments just as +a normal command does. .Sh "Defaults" .IX Subsection "Defaults" Certain configuration options may be changed from their default diff --git a/sudoers.pod b/sudoers.pod index c0426dd73..9c7b1d99f 100644 --- a/sudoers.pod +++ b/sudoers.pod @@ -180,6 +180,7 @@ to be useful. Cmnd ::= '!'* commandname | '!'* directory | + '!'* "sudoedit" | '!'* Cmnd_Alias A C is a list of one or more commandnames, directories, and other @@ -197,7 +198,10 @@ If a C has associated command line arguments, then the arguments in the C must match exactly those given by the user on the command line (or match the wildcards if there are any). Note that the following characters must be escaped with a '\' if they are used in command -arguments: ',', ':', '=', '\'. +arguments: ',', ':', '=', '\'. The special command C<"sudoedit"> +is used to permit a user to run B with the B<-e> flag (or +as B). It may take command line arguments just as +a normal command does. =head2 Defaults