Better describe things when a command is run in a pty.

diff --git a/doc/sudo.cat b/doc/sudo.cat
index 836b6d86665be56e0a0e3b3666bc6134433685bb..ebec2753a6709be0f0963efb74627ff2a21df92f 100644 (file)
--- a/doc/sudo.cat
+++ b/doc/sudo.cat
@@ -386,24 +386,45 @@ C\bCO\bOM\bMM\bMA\bAN\bND\bD E\bEX\bXE\bEC\bCU\bUT\bTI\bIO\bON\bN
      +\b+\bo\bo   scheduling priority (aka nice value)
 
    P\bPr\bro\boc\bce\bes\bss\bs m\bmo\bod\bde\bel\bl
-     When s\bsu\bud\bdo\bo runs a command, it calls fork(2), sets up the execution
-     environment as described above, and calls the execve system call in the
-     child process.  The main s\bsu\bud\bdo\bo 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") is created and a second s\bsu\bud\bdo\bo process is used to relay job control
-     signals between the user's 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
+     There are two distinct ways s\bsu\bud\bdo\bo can run a command.
+
+     If an I/O logging plugin is configured or if the security policy
+     explicitly requests it, a new pseudo-terminal ("pty") is allocated and
+     fork(2) is used to create a second s\bsu\bud\bdo\bo process, referred to as the
+     _\bm_\bo_\bn_\bi_\bt_\bo_\br.  The _\bm_\bo_\bn_\bi_\bt_\bo_\br creates a new terminal session with itself as the
+     leader and the pty as its controlling terminal, calls fork(2), sets up
+     the execution environment as described above, and then uses the execve(2)
+     system call to run the command in the child process.  The _\bm_\bo_\bn_\bi_\bt_\bo_\br exists
+     to relay job control signals between the user's existing terminal and the
+     pty the command is being run in.  This makes it possible to suspend and
+     resume the command.  Without the monitor, the command would be in what
      POSIX terms an "orphaned process group" 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, s\bsu\bud\bdo\bo will execute the command
-     directly instead of calling fork(2) first.  The _\bs_\bu_\bd_\bo_\be_\br_\bs policy plugin
-     will only define a close function when I/O logging is enabled, a pty is
-     required, or the _\bp_\ba_\bm_\b__\bs_\be_\bs_\bs_\bi_\bo_\bn or _\bp_\ba_\bm_\b__\bs_\be_\bt_\bc_\br_\be_\bd options are enabled.  Note
-     that _\bp_\ba_\bm_\b__\bs_\be_\bs_\bs_\bi_\bo_\bn and _\bp_\ba_\bm_\b__\bs_\be_\bt_\bc_\br_\be_\bd are enabled by default on systems using
-     PAM.
+     control signals from the kernel.  When the command exits or is terminated
+     by a signal, the _\bm_\bo_\bn_\bi_\bt_\bo_\br passes the command's exit status to the main
+     s\bsu\bud\bdo\bo process and exits.  On most systems, processes created by the
+     command that are still running in the background when the command exits
+     and that have not changed their session will receive the SIGHUP signal
+     when the monitor exits, since it is the terminal session leader.  To
+     prevent this from happening, background processes started by the command
+     can be invoked via the nohup(1) command to ignore SIGHUP.  Alternately,
+     some systems provide a setsid(1) command which can be used to run the
+     command in a new session.  In both cases, there is a potential race
+     condition where the command being run via s\bsu\bud\bdo\bo could exit before nohup(1)
+     or setsid(1) have time to complete their setup.
+
+     If no pty is used, s\bsu\bud\bdo\bo calls fork(2), sets up the execution environment
+     as described above, and uses the execve(2) system call to run the command
+     in the child process.
+
+     In both cases, the main s\bsu\bud\bdo\bo process waits until the command (or monitor)
+     has completed, then passes the command's exit status to the security
+     policy's close function and exits.  As a special case, if the policy
+     plugin does not define a close function and no pty is required, s\bsu\bud\bdo\bo will
+     execute the command directly instead of calling fork(2) first.  The
+     _\bs_\bu_\bd_\bo_\be_\br_\bs policy plugin will only define a close function when I/O logging
+     is enabled, a pty is required, or the _\bp_\ba_\bm_\b__\bs_\be_\bs_\bs_\bi_\bo_\bn or _\bp_\ba_\bm_\b__\bs_\be_\bt_\bc_\br_\be_\bd options
+     are enabled.  Note that _\bp_\ba_\bm_\b__\bs_\be_\bs_\bs_\bi_\bo_\bn and _\bp_\ba_\bm_\b__\bs_\be_\bt_\bc_\br_\be_\bd are enabled by
+     default on systems using PAM.
 
    S\bSi\big\bgn\bna\bal\bl h\bha\ban\bnd\bdl\bli\bin\bng\bg
      When the command is run as a child of the s\bsu\bud\bdo\bo process, s\bsu\bud\bdo\bo will relay
@@ -644,4 +665,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                    October 12, 2017                    Sudo 1.8.21
+Sudo 1.8.21                    November 29, 2017                   Sudo 1.8.21

diff --git a/doc/sudo.man.in b/doc/sudo.man.in
index 51428fa397474f0620d4b339ab4170219b4f2099..2b89288193508d79ed98d1515a249271bd636dd6 100644 (file)
--- 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" "8" "October 12, 2017" "Sudo @PACKAGE_VERSION@" "System Manager's Manual"
+.TH "SUDO" "8" "November 29, 2017" "Sudo @PACKAGE_VERSION@" "System Manager's Manual"
 .nh
 .if n .ad l
 .SH "NAME"
@@ -722,29 +722,74 @@ BSD login class
 \fB\(bu\fR
 scheduling priority (aka nice value)
 .SS "Process model"
-When
-\fBsudo\fR
-runs a command, it calls
-fork(2),
-sets up the execution environment as described above, and calls the
-execve
-system call in the child process.
-The main
+There are two distinct ways
 \fBsudo\fR
-process waits until the command has completed, then passes the
-command's exit status to the security policy's close function and exits.
+can run a command.
+.PP
 If an I/O logging plugin is configured or if the security policy
-explicitly requests it, a new  pseudo-terminal
+explicitly requests it, a new pseudo-terminal
 (\(Lqpty\(Rq)
-is created and a second
+is allocated and
+fork(2)
+is used to create a second
 \fBsudo\fR
-process is used to relay job control signals between the user's
-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
+process, referred to as the
+\fImonitor\fR.
+The
+\fImonitor\fR
+creates a new terminal session with itself as the leader and the pty as its
+controlling terminal, calls
+fork(2),
+sets up the execution environment as described above, and then uses the
+execve(2)
+system call to run the command in the child process.
+The
+\fImonitor\fR
+exists to relay job control signals between the user's
+existing terminal and the pty the command is being run in.
+This makes it possible to suspend and resume the command.
+Without the monitor, the command would be in what POSIX terms an
 \(Lqorphaned process group\(Rq
-and it would not receive any job control signals.
+and it would not receive any job control signals from the kernel.
+When the command exits or is terminated by a signal, the
+\fImonitor\fR
+passes the command's exit status to the main
+\fBsudo\fR
+process and exits.
+On most systems, processes created by the command that are still
+running in the background when the command exits and that have
+not changed their session will receive the
+\fRSIGHUP\fR
+signal when the monitor exits, since it is the terminal session leader.
+To prevent this from happening, background processes started by the command
+can be invoked via the
+nohup(1)
+command to ignore
+\fRSIGHUP\fR.
+Alternately, some systems provide a
+setsid(1)
+command which can be used to run the command in a new session.
+In both cases, there is a potential race condition where the
+command being run via
+\fBsudo\fR
+could exit before
+nohup(1)
+or
+setsid(1)
+have time to complete their setup.
+.PP
+If no pty is used,
+\fBsudo\fR
+calls
+fork(2),
+sets up the execution environment as described above, and uses the
+execve(2)
+system call to run the command in the child process.
+.PP
+In both cases, the main
+\fBsudo\fR
+process waits until the command (or monitor) has completed, then passes the
+command's exit status to the security policy's close function and exits.
 As a special case, if the policy plugin does not define a close
 function and no pty is required,
 \fBsudo\fR

diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in
index afba9d6a289e8c3240f4a97d057306269156d735..d4b6b0f9eb2939c730ce2ac45c36dd27866381db 100644 (file)
--- 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 October 12, 2017
+.Dd November 29, 2017
 .Dt SUDO @mansectsu@
 .Os Sudo @PACKAGE_VERSION@
 .Sh NAME
@@ -651,29 +651,74 @@ BSD login class
 scheduling priority (aka nice value)
 .El
 .Ss Process model
-When
-.Nm
-runs a command, it calls
-.Xr fork 2 ,
-sets up the execution environment as described above, and calls the
-.Xr execve
-system call in the child process.
-The main
+There are two distinct ways
 .Nm
-process waits until the command has completed, then passes the
-command's exit status to the security policy's close function and exits.
+can run a command.
+.Pp
 If an I/O logging plugin is configured or if the security policy
-explicitly requests it, a new  pseudo-terminal
+explicitly requests it, a new pseudo-terminal
 .Pq Dq pty
-is created and a second
+is allocated and
+.Xr fork 2
+is used to create a second
 .Nm
-process is used to relay job control signals between the user's
-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
+process, referred to as the
+.Em monitor .
+The
+.Em monitor
+creates a new terminal session with itself as the leader and the pty as its
+controlling terminal, calls
+.Xr fork 2 ,
+sets up the execution environment as described above, and then uses the
+.Xr execve 2
+system call to run the command in the child process.
+The
+.Em monitor
+exists to relay job control signals between the user's
+existing terminal and the pty the command is being run in.
+This makes it possible to suspend and resume the command.
+Without the monitor, the command would be in what POSIX terms an
 .Dq orphaned process group
-and it would not receive any job control signals.
+and it would not receive any job control signals from the kernel.
+When the command exits or is terminated by a signal, the
+.Em monitor
+passes the command's exit status to the main
+.Nm
+process and exits.
+On most systems, processes created by the command that are still
+running in the background when the command exits and that have
+not changed their session will receive the
+.Dv SIGHUP
+signal when the monitor exits, since it is the terminal session leader.
+To prevent this from happening, background processes started by the command
+can be invoked via the
+.Xr nohup 1
+command to ignore
+.Dv SIGHUP .
+Alternately, some systems provide a
+.Xr setsid 1
+command which can be used to run the command in a new session.
+In both cases, there is a potential race condition where the
+command being run via
+.Nm
+could exit before
+.Xr nohup 1
+or
+.Xr setsid 1
+have time to complete their setup.
+.Pp
+If no pty is used,
+.Nm
+calls
+.Xr fork 2 ,
+sets up the execution environment as described above, and uses the
+.Xr execve 2
+system call to run the command in the child process.
+.Pp
+In both cases, the main
+.Nm
+process waits until the command (or monitor) has completed, then passes the
+command's exit status to the security policy's close function and exits.
 As a special case, if the policy plugin does not define a close
 function and no pty is required,
 .Nm