]> granicus.if.org Git - sudo/commitdiff
rename "ENVIRONMENT VARIABLES" section to "ENVIRONMENT" to be more standard and add...
authorTodd C. Miller <Todd.Miller@courtesan.com>
Thu, 26 Aug 1999 09:10:12 +0000 (09:10 +0000)
committerTodd C. Miller <Todd.Miller@courtesan.com>
Thu, 26 Aug 1999 09:10:12 +0000 (09:10 +0000)
sudo.cat
sudo.html
sudo.man
sudo.pod

index d4c5a3f49c7b77cfe62e4d95ed53424d8dd48259..8929dac4d5c6362b61105baff94cae13074777b1 100644 (file)
--- a/sudo.cat
+++ b/sudo.cat
@@ -45,11 +45,11 @@ O\bO\bO\bOP\bP\bP\bPT\bT\bT\bTI\bI\bI\bIO\bO\bO\bON\bN\bN\bNS\bS\bS\bS
        -V  The -V (_\bv_\be_\br_\bs_\bi_\bo_\bn) option causes s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo to print the
            version number and exit.
 
-       -l  The -l (_\bl_\bi_\bs_\bt) option will list out the allowed and
-           forbidden commands for the user on the current host.
+       -l  The -l (_\bl_\bi_\bs_\bt) option will list out the allowed (and
+           forbidden) commands for the user on the current host.
 
-       -h  The -h (_\bh_\be_\bl_\bp) option causes s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo to print the version
-           of s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo and a usage message before exiting.
+       -h  The -h (_\bh_\be_\bl_\bp) option causes s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo to print a usage
+           message and exit.
 
        -v  If given the -v (_\bv_\ba_\bl_\bi_\bd_\ba_\bt_\be) option, s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo will update
            the user's timestamp, prompting for the user's
@@ -61,7 +61,7 @@ O\bO\bO\bOP\bP\bP\bPT\bT\bT\bTI\bI\bI\bIO\bO\bO\bON\bN\bN\bNS\bS\bS\bS
 
 
 
-17/Aug/1999                    1.6                              1
+25/Aug/1999                    1.6                              1
 
 
 
@@ -71,15 +71,15 @@ SUDO(8)                MAINTENANCE COMMANDS               SUDO(8)
 
 
        -k  The -k (_\bk_\bi_\bl_\bl) option to s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo invalidates the user's
-           timestamp file by setting the time on it to the epoch.
-           The next time s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo is run a password will be required.
+           timestamp by setting the time on it to the epoch.  The
+           next time s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo is run a password will be required.
            This option does not require a password and was added
            to allow a user to revoke s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo permissions from a
            .logout file.
 
        -K  The -K (sure _\bk_\bi_\bl_\bl) option to s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo removes the user's
-           timestamp file entirely.  This option does not require
-           password.
+           timestamp entirely.  This option does not require a
+           password.
 
        -b  The -b (_\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd) option tells s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo to run the given
            command in the background.  Note that if you use the
@@ -127,7 +127,7 @@ R\bR\bR\bRE\bE\bE\bET\bT\bT\bTU\bU\bU\bUR\bR\bR\bRN\bN\bN\bN V\bV\bV\bVA\bA\bA\bAL\bL\bL\bLU\bU\bU\bUE\bE\bE\bES\b
 
 
 
-17/Aug/1999                    1.6                              2
+25/Aug/1999                    1.6                              2
 
 
 
@@ -184,7 +184,7 @@ S\bS\bS\bSE\bE\bE\bEC\bC\bC\bCU\bU\bU\bUR\bR\bR\bRI\bI\bI\bIT\bT\bT\bTY\bY\bY\bY N\bN\bN\bNO\bO\bO\bOT\bT\bT\bTE\b
        instance) or create /tmp/.odus with the appropriate owner
        (root) and permissions (0700) in the system startup files.
 
-       sudo will not honor timestamps set far in the future.
+       s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo will not honor timestamps set far in the future.
        Timestamps with a date greater than current_time + 2 *
        TIMEOUT will be ignored and sudo will log and complain.
        This is done to keep a user from creating his/her own
@@ -193,7 +193,7 @@ S\bS\bS\bSE\bE\bE\bEC\bC\bC\bCU\bU\bU\bUR\bR\bR\bRI\bI\bI\bIT\bT\bT\bTY\bY\bY\bY N\bN\bN\bNO\bO\bO\bOT\bT\bT\bTE\b
 
 
 
-17/Aug/1999                    1.6                              3
+25/Aug/1999                    1.6                              3
 
 
 
@@ -202,13 +202,72 @@ S\bS\bS\bSE\bE\bE\bEC\bC\bC\bCU\bU\bU\bUR\bR\bR\bRI\bI\bI\bIT\bT\bT\bTY\bY\bY\bY N\bN\bN\bNO\bO\bO\bOT\bT\bT\bTE\b
 SUDO(8)                MAINTENANCE COMMANDS               SUDO(8)
 
 
+E\bE\bE\bEX\bX\bX\bXA\bA\bA\bAM\bM\bM\bMP\bP\bP\bPL\bL\bL\bLE\bE\bE\bES\bS\bS\bS
+       Note: the following examples assume suitable _\bs_\bu_\bd_\bo_\be_\br_\bs(5)
+       entries.
+
+       To get a file listing of an unreadable directory:
+
+        % sudo ls /usr/local/protected
+
+       To list the home directory of user yazza on a machine
+       where the filesystem holding ~yazza is not exported as
+       root:
+
+        % sudo -u yazza ls ~yazza
+
+       To edit the _\bi_\bn_\bd_\be_\bx_\b._\bh_\bt_\bm_\bl file as user www:
+
+        % sudo -u www vi ~www/htdocs/index.html
+
+       To shutdown a machine:
+
+        % sudo shutdown -r +15 "quick reboot"
+
+       To make a usage listing of the directories in the /home
+       partition.  Note that this runs the commands in a sub-
+       shell to make the cd and file redirection work.
+
+        % sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
+
+
+E\bE\bE\bEN\bN\bN\bNV\bV\bV\bVI\bI\bI\bIR\bR\bR\bRO\bO\bO\bON\bN\bN\bNM\bM\bM\bME\bE\bE\bEN\bN\bN\bNT\bT\bT\bT
+       s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo 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)
+        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.
+        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
+
+
 F\bF\bF\bFI\bI\bI\bIL\bL\bL\bLE\bE\bE\bES\bS\bS\bS
         /etc/sudoers           List of who can run what
         /var/run/sudo          Directory containing timestamps
-        /tmp/.odus             Same as above if no /var/run exists
+
+       s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo utilizes the following environment variables:
+
+
+
+
+
+25/Aug/1999                    1.6                              4
+
+
+
+
+
+SUDO(8)                MAINTENANCE COMMANDS               SUDO(8)
 
 
-E\bE\bE\bEN\bN\bN\bNV\bV\bV\bVI\bI\bI\bIR\bR\bR\bRO\bO\bO\bON\bN\bN\bNM\bM\bM\bME\bE\bE\bEN\bN\bN\bNT\bT\bT\bT V\bV\bV\bVA\bA\bA\bAR\bR\bR\bRI\bI\bI\bIA\bA\bA\bAB\bB\bB\bBL\bL\bL\bLE\bE\bE\bES\bS\bS\bS
         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
@@ -224,6 +283,12 @@ E\bE\bE\bEN\bN\bN\bNV\bV\bV\bVI\bI\bI\bIR\bR\bR\bRO\bO\bO\bON\bN\bN\bNM\bM\bM\bME\bE\bE\bEN\bN\bN\bNT\bT\bT\bT V\b
         SUDO_PS1               If set, PS1 will be set to its value
 
 
+F\bF\bF\bFI\bI\bI\bIL\bL\bL\bLE\bE\bE\bES\bS\bS\bS
+        /etc/sudoers           List of who can run what
+        /var/run/sudo          Directory containing timestamps
+        /tmp/.odus             Same as above if no /var/run exists
+
+
 A\bA\bA\bAU\bU\bU\bUT\bT\bT\bTH\bH\bH\bHO\bO\bO\bOR\bR\bR\bRS\bS\bS\bS
        Many people have worked on s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo over the years, this
        version consists of code written primarily by:
@@ -256,10 +321,11 @@ C\bC\bC\bCA\bA\bA\bAV\bV\bV\bVE\bE\bE\bEA\bA\bA\bAT\bT\bT\bTS\bS\bS\bS
        shell regardless of any '!'  elements in the user
        specification.
 
+       Running shell scripts via s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo can expose the same kernel
 
 
 
-17/Aug/1999                    1.6                              4
+25/Aug/1999                    1.6                              5
 
 
 
@@ -268,9 +334,9 @@ C\bC\bC\bCA\bA\bA\bAV\bV\bV\bVE\bE\bE\bEA\bA\bA\bAT\bT\bT\bTS\bS\bS\bS
 SUDO(8)                MAINTENANCE COMMANDS               SUDO(8)
 
 
-       Running shell scripts via s\bs\bs\bsu\bu\bu\bud\bd\bd\bdo\bo\bo\bo can expose the same kernel
        bugs that make setuid shell scripts unsafe on some
-       operating systems.
+       operating systems (if your OS supports the /dev/fd/
+       directory, setuid shell scripts are generally safe).
 
 S\bS\bS\bSE\bE\bE\bEE\bE\bE\bE A\bA\bA\bAL\bL\bL\bLS\bS\bS\bSO\bO\bO\bO
        _\bs_\bu_\bd_\bo_\be_\br_\bs(5), _\bv_\bi_\bs_\bu_\bd_\bo(8), _\bs_\bu(1).
@@ -325,6 +391,6 @@ S\bS\bS\bSE\bE\bE\bEE\bE\bE\bE A\bA\bA\bAL\bL\bL\bLS\bS\bS\bSO\bO\bO\bO
 
 
 
-17/Aug/1999                    1.6                              5
+25/Aug/1999                    1.6                              6
 
 
index 7204aa2f0fbbbe4eb19c8548bdb0688394ec1736..38ba8a4ed9f2f38b838e9838579db5a04a6a57cd 100644 (file)
--- a/sudo.html
+++ b/sudo.html
        <LI><A HREF="#OPTIONS">OPTIONS</A>
        <LI><A HREF="#RETURN_VALUES">RETURN VALUES</A>
        <LI><A HREF="#SECURITY_NOTES">SECURITY NOTES</A>
+       <LI><A HREF="#EXAMPLES">EXAMPLES</A>
+       <LI><A HREF="#ENVIRONMENT">ENVIRONMENT</A>
+       <LI><A HREF="#FILES">FILES</A>
        <LI><A HREF="#FILES">FILES</A>
-       <LI><A HREF="#ENVIRONMENT_VARIABLES">ENVIRONMENT VARIABLES</A>
        <LI><A HREF="#AUTHORS">AUTHORS</A>
        <LI><A HREF="#BUGS">BUGS</A>
        <LI><A HREF="#DISCLAIMER">DISCLAIMER</A>
@@ -81,12 +83,12 @@ The <CODE>-V</CODE> (<EM>version</EM>) option causes <STRONG>sudo</STRONG> to pr
 
 <DT><STRONG><A NAME="item__l">-l</A></STRONG><DD>
 <P>
-The <CODE>-l</CODE> (<EM>list</EM>) option will list out the allowed and forbidden commands for the user on
+The <CODE>-l</CODE> (<EM>list</EM>) option will list out the allowed (and forbidden) commands for the user on
 the current host.
 
 <DT><STRONG><A NAME="item__h">-h</A></STRONG><DD>
 <P>
-The <CODE>-h</CODE> (<EM>help</EM>) option causes <STRONG>sudo</STRONG> to print the version of <STRONG>sudo</STRONG> and a usage message before exiting.
+The <CODE>-h</CODE> (<EM>help</EM>) option causes <STRONG>sudo</STRONG> to print a usage message and exit.
 
 <DT><STRONG><A NAME="item__v">-v</A></STRONG><DD>
 <P>
@@ -96,13 +98,13 @@ and defaults to 5 minutes) but does not run a command.
 
 <DT><STRONG><A NAME="item__k">-k</A></STRONG><DD>
 <P>
-The <CODE>-k</CODE> (<EM>kill</EM>) option to <STRONG>sudo</STRONG> invalidates the user's timestamp file by setting the time on it to the
-epoch. The next time <STRONG>sudo</STRONG> is run a password will be required. This option does not require a password
+The <CODE>-k</CODE> (<EM>kill</EM>) option to <STRONG>sudo</STRONG> invalidates the user's timestamp by setting the time on it to the epoch.
+The next time <STRONG>sudo</STRONG> is run a password will be required. This option does not require a password
 and was added to allow a user to revoke <STRONG>sudo</STRONG> permissions from a .logout file.
 
 <DT><STRONG><A NAME="item__K">-K</A></STRONG><DD>
 <P>
-The <CODE>-K</CODE> (sure <EM>kill</EM>) option to <STRONG>sudo</STRONG> removes the user's timestamp file entirely. This option does not require a
+The <CODE>-K</CODE> (sure <EM>kill</EM>) option to <STRONG>sudo</STRONG> removes the user's timestamp entirely. This option does not require a
 password.
 
 <DT><STRONG><A NAME="item__b">-b</A></STRONG><DD>
@@ -190,23 +192,82 @@ can use a directory that is not world-writable for the timestamps (<EM>/var/adm/
 permissions (0700) in the system startup files.
 
 <P>
-<CODE>sudo</CODE> will not honor timestamps set far in the future. Timestamps with a date
+<STRONG>sudo</STRONG> will not honor timestamps set far in the future. Timestamps with a date
 greater than current_time + 2 * <CODE>TIMEOUT</CODE>
 will be ignored and sudo will log and complain. This is done to keep a user
 from creating his/her own timestamp with a bogus date on system that allow
 users to give away files.
 
+<P>
+<HR>
+<H1><A NAME="EXAMPLES">EXAMPLES</A></H1>
+<P>
+Note: the following examples assume suitable <CODE>sudoers(5)</CODE>
+entries.
+
+<P>
+To get a file listing of an unreadable directory:
+
+<P>
+<PRE> % sudo ls /usr/local/protected
+</PRE>
+<P>
+To list the home directory of user yazza on a machine where the filesystem
+holding ~yazza is not exported as root:
+
+<P>
+<PRE> % sudo -u yazza ls ~yazza
+</PRE>
+<P>
+To edit the <EM>index.html</EM> file as user www:
+
+<P>
+<PRE> % sudo -u www vi ~www/htdocs/index.html
+</PRE>
+<P>
+To shutdown a machine:
+
+<P>
+<PRE> % sudo shutdown -r +15 &quot;quick reboot&quot;
+</PRE>
+<P>
+To make a usage listing of the directories in the /home partition. Note
+that this runs the commands in a sub-shell to make the <CODE>cd</CODE> and file redirection work.
+
+<P>
+<PRE> % sudo sh -c &quot;cd /home ; du -s * | sort -rn &gt; USAGE&quot;
+</PRE>
+<P>
+<HR>
+<H1><A NAME="ENVIRONMENT">ENVIRONMENT</A></H1>
+<P>
+<STRONG>sudo</STRONG> utilizes the following environment variables:
+
+<P>
+<PRE> 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)
+ 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.
+ 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
+</PRE>
 <P>
 <HR>
 <H1><A NAME="FILES">FILES</A></H1>
 <P>
 <PRE> /etc/sudoers           List of who can run what
  /var/run/sudo          Directory containing timestamps
- /tmp/.odus             Same as above if no /var/run exists
 </PRE>
 <P>
-<HR>
-<H1><A NAME="ENVIRONMENT_VARIABLES">ENVIRONMENT VARIABLES</A></H1>
+<STRONG>sudo</STRONG> utilizes the following environment variables:
+
 <P>
 <PRE> PATH                   Set to a sane value if SECURE_PATH is set
  SHELL                  Used to determine shell to run with -s option
@@ -224,6 +285,14 @@ users to give away files.
 </PRE>
 <P>
 <HR>
+<H1><A NAME="FILES">FILES</A></H1>
+<P>
+<PRE> /etc/sudoers           List of who can run what
+ /var/run/sudo          Directory containing timestamps
+ /tmp/.odus             Same as above if no /var/run exists
+</PRE>
+<P>
+<HR>
 <H1><A NAME="AUTHORS">AUTHORS</A></H1>
 <P>
 Many people have worked on <STRONG>sudo</STRONG> over the years, this version consists of code written primarily by:
@@ -259,13 +328,13 @@ There is no easy way to prevent a user from gaining a root shell if that
 user has access to commands allowing shell escapes.
 
 <P>
-If users have sudo ALL there is nothing to prevent them from creating their
-own program that gives them a root shell regardless of any '!' elements in
-the user specification.
+If users have sudo <CODE>ALL</CODE> there is nothing to prevent them from creating their own program that gives
+them a root shell regardless of any '!' elements in the user specification.
 
 <P>
 Running shell scripts via <STRONG>sudo</STRONG> can expose the same kernel bugs that make setuid shell scripts unsafe on
-some operating systems.
+some operating systems (if your OS supports the /dev/fd/ directory, setuid
+shell scripts are generally safe).
 
 <P>
 <HR>
index c071564f17766174eb19d516612007face51f1ea..a1b65b21d49dc2a1bffba082ed7ad15a505be518 100644 (file)
--- a/sudo.man
+++ b/sudo.man
@@ -2,8 +2,8 @@
 ''' $RCSfile$$Revision$$Date$
 '''
 ''' $Log$
-''' Revision 1.35  1999/08/17 15:20:48  millert
-''' Add BUGS section
+''' Revision 1.36  1999/08/26 09:10:11  millert
+''' rename "ENVIRONMENT VARIABLES" section to "ENVIRONMENT" to be more standard and add "EXAMPLES" section
 '''
 '''
 .de Sh
@@ -96,7 +96,7 @@
 .nr % 0
 .rr F
 .\}
-.TH SUDO 8 "1.6" "17/Aug/1999" "MAINTENANCE COMMANDS"
+.TH SUDO 8 "1.6" "25/Aug/1999" "MAINTENANCE COMMANDS"
 .UC
 .if n .hy 0
 .if n .na
@@ -225,11 +225,10 @@ will log via \fIsyslog\fR\|(3) but this is changeable at configure time.
 The \f(CW-V\fR (\fIversion\fR) option causes \fBsudo\fR to print the
 version number and exit.
 .Ip "-l" 4
-The \f(CW-l\fR (\fIlist\fR) option will list out the allowed and
-forbidden commands for the user on the current host.
+The \f(CW-l\fR (\fIlist\fR) option will list out the allowed (and
+forbidden) commands for the user on the current host.
 .Ip "-h" 4
-The \f(CW-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print the version
-of \fBsudo\fR and a usage message before exiting.
+The \f(CW-h\fR (\fIhelp\fR) option causes \fBsudo\fR to print a usage message and exit.
 .Ip "-v" 4
 If given the \f(CW-v\fR (\fIvalidate\fR) option, \fBsudo\fR will update the
 user's timestamp, prompting for the user's password if necessary.
@@ -238,13 +237,13 @@ This extends the \fBsudo\fR timeout to for another N minutes
 minutes) but does not run a command.
 .Ip "-k" 4
 The \f(CW-k\fR (\fIkill\fR) option to \fBsudo\fR invalidates the user's timestamp
-file by setting the time on it to the epoch.  The next time \fBsudo\fR is
+by setting the time on it to the epoch.  The next time \fBsudo\fR is
 run a password will be required.  This option does not require a password
 and was added to allow a user to revoke \fBsudo\fR permissions from a .logout
 file.
 .Ip "-K" 4
 The \f(CW-K\fR (sure \fIkill\fR) option to \fBsudo\fR removes the user's timestamp
-file entirely.  This option does not require a password.
+entirely.  This option does not require a password.
 .Ip "-b" 4
 The \f(CW-b\fR (\fIbackground\fR) option tells \fBsudo\fR to run the given
 command in the background.  Note that if you use the \f(CW-b\fR
@@ -326,19 +325,67 @@ that is not world-writable for the timestamps (\fI/var/adm/sudo\fR for
 instance) or create /tmp/.odus with the appropriate owner (root)
 and permissions (0700) in the system startup files.
 .PP
-\f(CWsudo\fR will not honor timestamps set far in the future.
+\fBsudo\fR will not honor timestamps set far in the future.
 Timestamps with a date greater than current_time + 2 * \f(CWTIMEOUT\fR
 will be ignored and sudo will log and complain.  This is done to
 keep a user from creating his/her own timestamp with a bogus
 date on system that allow users to give away files.
+.SH "EXAMPLES"
+Note: the following examples assume suitable \fIsudoers\fR\|(5) entries.
+.PP
+To get a file listing of an unreadable directory:
+.PP
+.Vb 1
+\& % sudo ls /usr/local/protected
+.Ve
+To list the home directory of user yazza on a machine where the
+filesystem holding ~yazza is not exported as root:
+.PP
+.Vb 1
+\& % sudo -u yazza ls ~yazza
+.Ve
+To edit the \fIindex.html\fR file as user www:
+.PP
+.Vb 1
+\& % sudo -u www vi ~www/htdocs/index.html
+.Ve
+To shutdown a machine:
+.PP
+.Vb 1
+\& % sudo shutdown -r +15 "quick reboot"
+.Ve
+To make a usage listing of the directories in the /home
+partition.  Note that this runs the commands in a sub-shell
+to make the \f(CWcd\fR and file redirection work.
+.PP
+.Vb 1
+\& % sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
+.Ve
+.SH "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)
+\& 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.
+\& 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
+.Ve
 .SH "FILES"
 .PP
-.Vb 3
+.Vb 2
 \& /etc/sudoers           List of who can run what
 \& /var/run/sudo          Directory containing timestamps
-\& /tmp/.odus             Same as above if no /var/run exists
 .Ve
-.SH "ENVIRONMENT VARIABLES"
+\fBsudo\fR utilizes the following environment variables:
 .PP
 .Vb 13
 \& PATH                   Set to a sane value if SECURE_PATH is set
@@ -355,6 +402,13 @@ date on system that allow users to give away files.
 \& SUDO_GID               Set to the gid of the user who invoked sudo
 \& SUDO_PS1               If set, PS1 will be set to its value
 .Ve
+.SH "FILES"
+.PP
+.Vb 3
+\& /etc/sudoers           List of who can run what
+\& /var/run/sudo          Directory containing timestamps
+\& /tmp/.odus             Same as above if no /var/run exists
+.Ve
 .SH "AUTHORS"
 Many people have worked on \fBsudo\fR over the years, this
 version consists of code written primarily by:
@@ -378,12 +432,14 @@ See the LICENSE file distributed with \fBsudo\fR for complete details.
 There is no easy way to prevent a user from gaining a root shell if
 that user has access to commands allowing shell escapes.
 .PP
-If users have sudo ALL there is nothing to prevent them from creating
+If users have sudo \f(CWALL\fR there is nothing to prevent them from creating
 their own program that gives them a root shell regardless of any \*(L'!\*(R'
 elements in the user specification.
 .PP
 Running shell scripts via \fBsudo\fR can expose the same kernel bugs
-that make setuid shell scripts unsafe on some operating systems.
+that make setuid shell scripts unsafe on some operating systems
+(if your OS supports the /dev/fd/ directory, setuid shell scripts
+are generally safe).
 .SH "SEE ALSO"
 \fIsudoers\fR\|(5), \fIvisudo\fR\|(8), \fIsu\fR\|(1).
 
@@ -429,9 +485,13 @@ that make setuid shell scripts unsafe on some operating systems.
 
 .IX Header "SECURITY NOTES"
 
+.IX Header "EXAMPLES"
+
+.IX Header "ENVIRONMENT"
+
 .IX Header "FILES"
 
-.IX Header "ENVIRONMENT VARIABLES"
+.IX Header "FILES"
 
 .IX Header "AUTHORS"
 
index 9c0eaa9d5e1d761d4f5eb3bdfce46133647a579d..9a522d8dfe8db0d9b38484d5c498edaa3f4feec8 100644 (file)
--- a/sudo.pod
+++ b/sudo.pod
@@ -83,13 +83,12 @@ version number and exit.
 
 =item -l
 
-The C<-l> (I<list>) option will list out the allowed and
-forbidden commands for the user on the current host.
+The C<-l> (I<list>) option will list out the allowed (and
+forbidden) commands for the user on the current host.
 
 =item -h
 
-The C<-h> (I<help>) option causes B<sudo> to print the version
-of B<sudo> and a usage message before exiting.
+The C<-h> (I<help>) option causes B<sudo> to print a usage message and exit.
 
 =item -v
 
@@ -102,7 +101,7 @@ minutes) but does not run a command.
 =item -k
 
 The C<-k> (I<kill>) option to B<sudo> invalidates the user's timestamp
-file by setting the time on it to the epoch.  The next time B<sudo> is
+by setting the time on it to the epoch.  The next time B<sudo> is
 run a password will be required.  This option does not require a password
 and was added to allow a user to revoke B<sudo> permissions from a .logout
 file.
@@ -110,7 +109,7 @@ file.
 =item -K
 
 The C<-K> (sure I<kill>) option to B<sudo> removes the user's timestamp
-file entirely.  This option does not require a password.
+entirely.  This option does not require a password.
 
 =item -b
 
@@ -212,19 +211,63 @@ that is not world-writable for the timestamps (F</var/adm/sudo> for
 instance) or create /tmp/.odus with the appropriate owner (root)
 and permissions (0700) in the system startup files.
 
-C<sudo> will not honor timestamps set far in the future.
+B<sudo> will not honor timestamps set far in the future.
 Timestamps with a date greater than current_time + 2 * C<TIMEOUT>
 will be ignored and sudo will log and complain.  This is done to
 keep a user from creating his/her own timestamp with a bogus
 date on system that allow users to give away files.
 
+=head1 EXAMPLES
+
+Note: the following examples assume suitable sudoers(5) entries.
+
+To get a file listing of an unreadable directory:
+
+ % sudo ls /usr/local/protected
+
+To list the home directory of user yazza on a machine where the
+filesystem holding ~yazza is not exported as root:
+
+ % sudo -u yazza ls ~yazza
+
+To edit the F<index.html> file as user www:
+
+ % sudo -u www vi ~www/htdocs/index.html
+
+To shutdown a machine:
+
+ % sudo shutdown -r +15 "quick reboot"
+
+To make a usage listing of the directories in the /home
+partition.  Note that this runs the commands in a sub-shell
+to make the C<cd> and file redirection work.
+
+ % sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
+
+=head1 ENVIRONMENT
+
+B<sudo> 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)
+ 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.
+ 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
+
 =head1 FILES
 
  /etc/sudoers          List of who can run what
  /var/run/sudo         Directory containing timestamps
- /tmp/.odus            Same as above if no /var/run exists
 
-=head1 ENVIRONMENT VARIABLES
+B<sudo> 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
@@ -240,6 +283,12 @@ date on system that allow users to give away files.
  SUDO_GID              Set to the gid of the user who invoked sudo
  SUDO_PS1              If set, PS1 will be set to its value
 
+=head1 FILES
+
+ /etc/sudoers          List of who can run what
+ /var/run/sudo         Directory containing timestamps
+ /tmp/.odus            Same as above if no /var/run exists
+
 =head1 AUTHORS
 
 Many people have worked on B<sudo> over the years, this
@@ -269,12 +318,14 @@ See the LICENSE file distributed with B<sudo> for complete details.
 There is no easy way to prevent a user from gaining a root shell if
 that user has access to commands allowing shell escapes.
 
-If users have sudo ALL there is nothing to prevent them from creating
+If users have sudo C<ALL> there is nothing to prevent them from creating
 their own program that gives them a root shell regardless of any '!'
 elements in the user specification.
 
 Running shell scripts via B<sudo> can expose the same kernel bugs
-that make setuid shell scripts unsafe on some operating systems.
+that make setuid shell scripts unsafe on some operating systems
+(if your OS supports the /dev/fd/ directory, setuid shell scripts
+are generally safe).
 
 =head1 SEE ALSO