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

doc/sudo.cat

@@ -386,24 +386,45 @@ CCOOMMMMAANNDD EEXXEECCUUTTIIOONN
      ++oo   scheduling priority (aka nice value)
 
    PPrroocceessss mmooddeell
-     When ssuuddoo runs a command, it calls fork(2), sets up the execution
+     There are two distinct ways ssuuddoo can run a command.
-     environment as described above, and calls the execve system call in the
+
-     child process.  The main ssuuddoo process waits until the command has
+     If an I/O logging plugin is configured or if the security policy
-     completed, then passes the command's exit status to the security policy's
+     explicitly requests it, a new pseudo-terminal ("pty") is allocated and
-     close function and exits.  If an I/O logging plugin is configured or if
+     fork(2) is used to create a second ssuuddoo process, referred to as the
-     the security policy explicitly requests it, a new  pseudo-terminal
+     _m_o_n_i_t_o_r.  The _m_o_n_i_t_o_r creates a new terminal session with itself as the
-     ("pty") is created and a second ssuuddoo process is used to relay job control
+     leader and the pty as its controlling terminal, calls fork(2), sets up
-     signals between the user's existing pty and the new pty the command is
+     the execution environment as described above, and then uses the execve(2)
-     being run in.  This extra process makes it possible to, for example,
+     system call to run the command in the child process.  The _m_o_n_i_t_o_r exists
-     suspend and resume the command.  Without it, the command would be in what
+     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
+     control signals from the kernel.  When the command exits or is terminated
-     a close function and no pty is required, ssuuddoo will execute the command
+     by a signal, the _m_o_n_i_t_o_r passes the command's exit status to the main
-     directly instead of calling fork(2) first.  The _s_u_d_o_e_r_s policy plugin
+     ssuuddoo process and exits.  On most systems, processes created by the
-     will only define a close function when I/O logging is enabled, a pty is
+     command that are still running in the background when the command exits
-     required, or the _p_a_m___s_e_s_s_i_o_n or _p_a_m___s_e_t_c_r_e_d options are enabled.  Note
+     and that have not changed their session will receive the SIGHUP signal
-     that _p_a_m___s_e_s_s_i_o_n and _p_a_m___s_e_t_c_r_e_d are enabled by default on systems using
+     when the monitor exits, since it is the terminal session leader.  To
-     PAM.
+     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 ssuuddoo could exit before nohup(1)
+     or setsid(1) have time to complete their setup.
+
+     If no pty is used, ssuuddoo 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 ssuuddoo 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, ssuuddoo will
+     execute the command directly instead of calling fork(2) first.  The
+     _s_u_d_o_e_r_s policy plugin will only define a close function when I/O logging
+     is enabled, a pty is required, or the _p_a_m___s_e_s_s_i_o_n or _p_a_m___s_e_t_c_r_e_d options
+     are enabled.  Note that _p_a_m___s_e_s_s_i_o_n and _p_a_m___s_e_t_c_r_e_d are enabled by
+     default on systems using PAM.
 
    SSiiggnnaall hhaannddlliinngg
      When the command is run as a child of the ssuuddoo process, ssuuddoo will relay
@@ -644,4 +665,4 @@ DDIISSCCLLAAIIMMEERR
      file distributed with ssuuddoo 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

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
+There are two distinct ways
 \fBsudo\fR
-runs a command, it calls
+can run a command.
-fork(2),
+.PP
-sets up the execution environment as described above, and calls the
-execve
-system call in the child process.
-The main
-\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.
 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
+process, referred to as the
-existing pty and the new pty the command is being run in.
+\fImonitor\fR.
-This extra process makes it possible to, for example, suspend
+The
-and resume the command.
+\fImonitor\fR
-Without it, the command would be in what POSIX terms an
+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

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
+There are two distinct ways
 .Nm
-runs a command, it calls
+can run a command.
-.Xr fork 2 ,
+.Pp
-sets up the execution environment as described above, and calls the
-.Xr execve
-system call in the child process.
-The main
-.Nm
-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
+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
+process, referred to as the
-existing pty and the new pty the command is being run in.
+.Em monitor .
-This extra process makes it possible to, for example, suspend
+The
-and resume the command.
+.Em monitor
-Without it, the command would be in what POSIX terms an
+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