More accurately describe the use_pty option now that its behavior

has changed with respect to interposition with a pipe.
Also describe some caveats with log_input.

diff --git a/doc/sudoers.cat b/doc/sudoers.cat
index b4be9ede41a7a354b3632fb30313196bd4d4ab13..755364aea66a0540ddf328dfb91168f3659b466a 100644 (file)
--- a/doc/sudoers.cat
+++ b/doc/sudoers.cat
@@ -1149,13 +1149,19 @@ S\bSU\bUD\bDO\bOE\bER\bRS\bS O\bOP\bPT\bTI\bIO\bON\bNS\bS
                        connected to the user's tty, due to I/O redirection or
                        because the command is part of a pipeline, that input
                        is also captured and stored in a separate log file.
-                       For more information, see the _\bI_\b/_\bO _\bL_\bO_\bG _\bF_\bI_\bL_\bE_\bS section.
-                       This flag is _\bo_\bf_\bf by default.
+                       Anything sent to the standard input will be consumed,
+                       regardless of whether or not the command run via s\bsu\bud\bdo\bo
+                       is actually reading the standard input.  This may have
+                       unexpected results when using s\bsu\bud\bdo\bo in a shell script
+                       that expects to process the standard input.  For more
+                       information about I/O logging, see the _\bI_\b/_\bO _\bL_\bO_\bG _\bF_\bI_\bL_\bE_\bS
+                       section.  This flag is _\bo_\bf_\bf by default.
 
      log_output        If set, s\bsu\bud\bdo\bo will run the command in a pseudo-tty and
                        log all output that is sent to the screen, similar to
-                       the script(1) command.  For more information, see the
-                       _\bI_\b/_\bO _\bL_\bO_\bG _\bF_\bI_\bL_\bE_\bS section.  This flag is _\bo_\bf_\bf by default.
+                       the script(1) command.  For more information about I/O
+                       logging, see the _\bI_\b/_\bO _\bL_\bO_\bG _\bF_\bI_\bL_\bE_\bS section.  This flag is
+                       _\bo_\bf_\bf by default.
 
      log_year          If set, the four-digit year will be logged in the (non-
                        syslog) s\bsu\bud\bdo\bo log file.  This flag is _\bo_\bf_\bf by default.
@@ -1464,13 +1470,18 @@ S\bSU\bUD\bDO\bOE\bER\bRS\bS O\bOP\bPT\bTI\bIO\bON\bNS\bS
                        not needed, this option can be disabled to reduce the
                        load on the LDAP server.  This flag is _\bo_\bn by default.
 
-     use_pty           If set, s\bsu\bud\bdo\bo will run the command in a pseudo-pty even
-                       if no I/O logging is being gone.  A malicious program
-                       run under s\bsu\bud\bdo\bo could conceivably fork a background
-                       process that retains to the user's terminal device
-                       after the main program has finished executing.  Use of
-                       this option will make that impossible.  This flag is
-                       _\bo_\bf_\bf by default.
+     use_pty           If set, and s\bsu\bud\bdo\bo is running in a terminal, the command
+                       will be run in a pseudo-pty (even if no I/O logging is
+                       being done).  If the s\bsu\bud\bdo\bo process is not attached to a
+                       terminal, _\bu_\bs_\be_\b__\bp_\bt_\by has no effect.
+
+                       A malicious program run under s\bsu\bud\bdo\bo may be capable of
+                       injecting injecting commands into the user's terminal
+                       or running a background process that retains access to
+                       the user's terminal device even after the main program
+                       has finished executing.  By running the command in a
+                       separate pseudo-pty, this attack is no longer possible.
+                       This flag is _\bo_\bf_\bf by default.
 
      user_command_timeouts
                        If set, the user may specify a timeout on the command
@@ -2328,11 +2339,11 @@ L\bLO\bOG\bG F\bFO\bOR\bRM\bMA\bAT\bT
 
 I\bI/\b/O\bO L\bLO\bOG\bG F\bFI\bIL\bLE\bES\bS
      When I/O logging is enabled, s\bsu\bud\bdo\bo will run the command in a pseudo-tty
-     and log all user input and/or output.  I/O is logged to the directory
-     specified by the _\bi_\bo_\bl_\bo_\bg_\b__\bd_\bi_\br option (_\b/_\bv_\ba_\br_\b/_\bl_\bo_\bg_\b/_\bs_\bu_\bd_\bo_\b-_\bi_\bo by default) using a
-     unique session ID that is included in the s\bsu\bud\bdo\bo log line, prefixed with
-     "TSID=".  The _\bi_\bo_\bl_\bo_\bg_\b__\bf_\bi_\bl_\be option may be used to control the format of the
-     session ID.
+     and log all user input and/or output, depending on which options are
+     enabled.  I/O is logged to the directory specified by the _\bi_\bo_\bl_\bo_\bg_\b__\bd_\bi_\br
+     option (_\b/_\bv_\ba_\br_\b/_\bl_\bo_\bg_\b/_\bs_\bu_\bd_\bo_\b-_\bi_\bo by default) using a unique session ID that is
+     included in the s\bsu\bud\bdo\bo log line, prefixed with "TSID=".  The _\bi_\bo_\bl_\bo_\bg_\b__\bf_\bi_\bl_\be
+     option may be used to control the format of the session ID.
 
      Each I/O log is stored in a separate directory that contains the
      following files:
@@ -2868,4 +2879,4 @@ D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
      file distributed with s\bsu\bud\bdo\bo or https://www.sudo.ws/license.html for
      complete details.
 
-Sudo 1.8.21                     August 4, 2017                     Sudo 1.8.21
+Sudo 1.8.21                    September 7, 2017                   Sudo 1.8.21

diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in
index aa7435bd897cd9a34deba0f7e5e0aafcc73e9607..e84357fc335f7da4341e7c06ed3eccd999726d0e 100644 (file)
--- a/doc/sudoers.man.in
+++ b/doc/sudoers.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 "SUDOERS" "5" "August 4, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
+.TH "SUDOERS" "5" "September 7, 2017" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -2425,7 +2425,14 @@ will run the command in a pseudo-tty and log all user input.
 If the standard input is not connected to the user's tty, due to
 I/O redirection or because the command is part of a pipeline, that
 input is also captured and stored in a separate log file.
-For more information, see the
+Anything sent to the standard input will be consumed, regardless of
+whether or not the command run via
+\fBsudo\fR
+is actually reading the standard input.
+This may have unexpected results when using
+\fBsudo\fR
+in a shell script that expects to process the standard input.
+For more information about I/O logging, see the
 \fII/O LOG FILES\fR
 section.
 This flag is
@@ -2439,7 +2446,7 @@ will run the command in a pseudo-tty and log all output that is sent
 to the screen, similar to the
 script(1)
 command.
-For more information, see the
+For more information about I/O logging, see the
 \fII/O LOG FILES\fR
 section.
 This flag is
@@ -3066,14 +3073,24 @@ This flag is
 by default.
 .TP 18n
 use_pty
-If set,
+If set, and
+\fBsudo\fR
+is running in a terminal, the command will be run in a pseudo-pty
+(even if no I/O logging is being done).
+If the
 \fBsudo\fR
-will run the command in a pseudo-pty even if no I/O logging is being gone.
+process is not attached to a terminal,
+\fIuse_pty\fR
+has no effect.
+.sp
 A malicious program run under
 \fBsudo\fR
-could conceivably fork a background process that retains to the user's
-terminal device after the main program has finished executing.
-Use of this option will make that impossible.
+may be capable of injecting injecting commands into the user's
+terminal or running a background process that retains access to the
+user's terminal device even after the main program has finished
+executing.
+By running the command in a separate pseudo-pty, this attack is
+no longer possible.
 This flag is
 \fIoff\fR
 by default.
@@ -4616,7 +4633,8 @@ word wrap will be disabled.
 .SH "I/O LOG FILES"
 When I/O logging is enabled,
 \fBsudo\fR
-will run the command in a pseudo-tty and log all user input and/or output.
+will run the command in a pseudo-tty and log all user input and/or output,
+depending on which options are enabled.
 I/O is logged to the directory specified by the
 \fIiolog_dir\fR
 option

diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in
index f411a59e6155786fbd1957915fa2fa9a6c3ea7da..02688445270486eaffcb27116c7abbb10c520441 100644 (file)
--- a/doc/sudoers.mdoc.in
+++ b/doc/sudoers.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 August 4, 2017
+.Dd September 7, 2017
 .Dt SUDOERS @mansectform@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -2277,7 +2277,14 @@ will run the command in a pseudo-tty and log all user input.
 If the standard input is not connected to the user's tty, due to
 I/O redirection or because the command is part of a pipeline, that
 input is also captured and stored in a separate log file.
-For more information, see the
+Anything sent to the standard input will be consumed, regardless of
+whether or not the command run via
+.Nm sudo
+is actually reading the standard input.
+This may have unexpected results when using
+.Nm sudo
+in a shell script that expects to process the standard input.
+For more information about I/O logging, see the
 .Sx "I/O LOG FILES"
 section.
 This flag is
@@ -2290,7 +2297,7 @@ will run the command in a pseudo-tty and log all output that is sent
 to the screen, similar to the
 .Xr script 1
 command.
-For more information, see the
+For more information about I/O logging, see the
 .Sx "I/O LOG FILES"
 section.
 This flag is
@@ -2880,14 +2887,24 @@ This flag is
 .Em on
 by default.
 .It use_pty
-If set,
+If set, and
+.Nm sudo
+is running in a terminal, the command will be run in a pseudo-pty
+(even if no I/O logging is being done).
+If the
 .Nm sudo
-will run the command in a pseudo-pty even if no I/O logging is being gone.
+process is not attached to a terminal,
+.Em use_pty
+has no effect.
+.Pp
 A malicious program run under
 .Nm sudo
-could conceivably fork a background process that retains to the user's
-terminal device after the main program has finished executing.
-Use of this option will make that impossible.
+may be capable of injecting injecting commands into the user's
+terminal or running a background process that retains access to the
+user's terminal device even after the main program has finished
+executing.
+By running the command in a separate pseudo-pty, this attack is
+no longer possible.
 This flag is
 .Em off
 by default.
@@ -4292,7 +4309,8 @@ word wrap will be disabled.
 .Sh I/O LOG FILES
 When I/O logging is enabled,
 .Nm sudo
-will run the command in a pseudo-tty and log all user input and/or output.
+will run the command in a pseudo-tty and log all user input and/or output,
+depending on which options are enabled.
 I/O is logged to the directory specified by the
 .Em iolog_dir
 option