diff --git a/doc/Makefile.in b/doc/Makefile.in index e2c1ef8a4..0589a5e5c 100644 --- a/doc/Makefile.in +++ b/doc/Makefile.in @@ -111,13 +111,13 @@ $(srcdir)/sudo.man.in: $(srcdir)/sudo.mdoc.in fi sudo.man.sed: $(srcdir)/fixman.sh - BAMAN=@BAMAN@ LCMAN=@LCMAN@ SEMAN=@SEMAN@ $(SHELL) $(srcdir)/fixman.sh $@ + BAMAN=@BAMAN@ LCMAN=@LCMAN@ SEMAN=@SEMAN@ PSMAN=@PSMAN@ $(SHELL) $(srcdir)/fixman.sh $@ sudo.man: $(srcdir)/sudo.man.in sudo.man.sed (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/$@.in | $(SED) -f $@.sed > $@ sudo.mdoc.sed: $(srcdir)/fixmdoc.sh - BAMAN=@BAMAN@ LCMAN=@LCMAN@ SEMAN=@SEMAN@ $(SHELL) $(srcdir)/fixmdoc.sh $@ + BAMAN=@BAMAN@ LCMAN=@LCMAN@ SEMAN=@SEMAN@ PSMAN=@PSMAN@ $(SHELL) $(srcdir)/fixmdoc.sh $@ sudo.mdoc: $(srcdir)/sudo.mdoc.in sudo.mdoc.sed (cd $(top_builddir) && $(SHELL) config.status --file=-) < $(srcdir)/$@.in | $(SED) -f $@.sed > $@ diff --git a/doc/fixman.sh b/doc/fixman.sh index 05c54db3a..f0f9e1038 100755 --- a/doc/fixman.sh +++ b/doc/fixman.sh @@ -42,6 +42,12 @@ case "$OUTFILE" in /^\\fB\\-c\\fR \\fIclass\\fR$/,/^\.TP 12n$/ { /^\.PD$/!d } + /^login_cap(3),$/d + /^BSD login class$/ { + N + N + /^BSD login class\n\.TP 4n\n\\fBo\\fR$/d + } EOF fi @@ -52,6 +58,25 @@ case "$OUTFILE" in /^\\fB\\-[rt]\\fR \\fI[rt][oy][lp]e\\fR$/,/^\.TP 12n$/ { /^\.PD$/!d } + /^SELinux role and type$/ { + N + N + /^SELinux role and type\n\.TP 4n\n\\fBo\\fR$/d + } + EOF + fi + + # Solaris privileges + if [ X"$PSMAN" != X"1" ]; then + cat >>"$OUTFILE" <<-'EOF' + /^Solaris project$/ { + N + N + N + N + N + /^Solaris project\n\.TP 4n\n\\fBo\\fR\nSolaris privileges\n\.TP 4n\n\\fBo\\fR$/d + } EOF fi ;; diff --git a/doc/fixmdoc.sh b/doc/fixmdoc.sh index 6ef1f00ff..6171f3edb 100755 --- a/doc/fixmdoc.sh +++ b/doc/fixmdoc.sh @@ -35,6 +35,10 @@ case "$OUTFILE" in d } /^\.Xr login_cap 3 ,$/d + /^BSD login class$/ { + N + /^BSD login class\n\.It$/d + } EOF fi @@ -49,6 +53,22 @@ case "$OUTFILE" in /^\.It Fl t Ar type/,/specified role\.$/ { d } + /^SELinux role and type$/ { + N + /^SELinux role and type\n\.It$/d + } + EOF + fi + + # Solaris privileges + if [ X"$PSMAN" != X"1" ]; then + cat >>"$OUTFILE" <<-'EOF' + /^Solaris project$/ { + N + N + N + /^Solaris project\n\.It\nSolaris privileges\n\.It$/d + } EOF fi diff --git a/doc/sudo.cat b/doc/sudo.cat index 60d41961d..b74a427d1 100644 --- a/doc/sudo.cat +++ b/doc/sudo.cat @@ -18,10 +18,7 @@ SSYYNNOOPPSSIISS DDEESSCCRRIIPPTTIIOONN ssuuddoo allows a permitted user to execute a _c_o_m_m_a_n_d as the superuser or - another user, as specified by the security policy. The real and - effective uid and gid are set to match those of the target user, as - specified in the password database, and the group vector is initialized - based on the group database (unless the --PP option was specified). + another user, as specified by the security policy. ssuuddoo supports a plugin architecture for security policies and input/output logging. Third parties can develop and distribute their own @@ -300,6 +297,74 @@ DDEESSCCRRIIPPTTIIOONN the user may set variables that would otherwise be forbidden. See sudoers(4) for more information. +CCOOMMMMAANNDD EEXXEECCUUTTIIOONN + When ssuuddoo executes a command, the security policy specifies the execution + envionment for the command. Typically, the real and effective uid and + gid are set to match those of the target user, as specified in the + password database, and the group vector is initialized based on the group + database (unless the --PP option was specified). + + The following parameters may be specified by security policy: + + oo real and effective user ID + + oo real and effective group ID + + oo supplementary group IDs + + oo the environment list + + oo current working directory + + oo file creation mode mask (umask) + + oo SELinux role and type + + oo Solaris project + + oo Solaris privileges + + oo BSD login class + + oo scheduling priority (aka nice value) + + PPrroocceessss MMooddeell + When ssuuddoo 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 ssuuddoo process waits until the command has + completed, then passes the command's exit status to the security policy's + close method and exits. If an I/O logging plugin is configured, a new + pseudo-terminal (``pty'') is created and a second ssuuddoo 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 ``orphaned process group'' and it would + not receive any job control signals. + + SSiiggnnaall HHaannddlliinngg + Because the command is run as a child of the ssuuddoo process, ssuuddoo will + relay signals it receives to the command. Unless the command is being + run in a new pty, the SIGHUP, SIGINT and SIGQUIT signals are not relayed + unless they are sent by a user process, not the kernel. Otherwise, the + command would receive SIGINT twice every time the user entered control-C. + Some signals, such as SIGSTOP and SIGKILL, cannot be caught and thus will + not be relayed to the command. As a general rule, SIGTSTP should be used + instead of SIGSTOP when you wish to suspend a command being run by ssuuddoo. + + As a special case, ssuuddoo will not relay signals that were sent by the + command it is running. This prevents the command from accidentally + killing itself. On some systems, the reboot(1m) command sends SIGTERM to + all non-system processes other than itself before rebooting the systyem. + This prevents ssuuddoo from relaying the SIGTERM signal it received back to + reboot(1m), which might then exit before the system was actually rebooted, + leaving it in a half-dead state similar to single user mode. Note, + however, that this check only applies to the command run by ssuuddoo and not + any other processes that the command may create. As a result, running a + script that calls reboot(1m) or shutdown(1m) via ssuuddoo may cause the system + to end up in this undefined state unless the reboot(1m) or shutdown(1m) are + run using the eexxeecc() family of functions instead of ssyysstteemm() (which + interposes a shell between the command and the calling process). + PPLLUUGGIINNSS Plugins are dynamically loaded based on the contents of the _/_e_t_c_/_s_u_d_o_._c_o_n_f file. If no _/_e_t_c_/_s_u_d_o_._c_o_n_f file is present, or it diff --git a/doc/sudo.man.in b/doc/sudo.man.in index b1f11ccae..7b8eff7f7 100644 --- a/doc/sudo.man.in +++ b/doc/sudo.man.in @@ -85,11 +85,6 @@ allows a permitted user to execute a \fIcommand\fR as the superuser or another user, as specified by the security policy. -The real and effective uid and gid are set to match those of the -target user, as specified in the password database, and the group -vector is initialized based on the group database (unless the -\fB\-P\fR -option was specified). .PP \fBsudo\fR supports a plugin architecture for security policies and input/output @@ -695,6 +690,139 @@ the user may set variables that would otherwise be forbidden. See sudoers(@mansectform@) for more information. +.SH "COMMAND EXECUTION" +When +\fBsudo\fR +executes a command, the security policy specifies the execution +envionment for the command. +Typically, the real and effective uid and gid are set to +match those of the target user, as specified in the password database, +and the group vector is initialized based on the group database +(unless the +\fB\-P\fR +option was specified). +.PP +The following parameters may be specified by security policy: +.TP 4n +\fBo\fR +real and effective user ID +.TP 4n +\fBo\fR +real and effective group ID +.TP 4n +\fBo\fR +supplementary group IDs +.TP 4n +\fBo\fR +the environment list +.TP 4n +\fBo\fR +current working directory +.TP 4n +\fBo\fR +file creation mode mask (umask) +.TP 4n +\fBo\fR +SELinux role and type +.TP 4n +\fBo\fR +Solaris project +.TP 4n +\fBo\fR +Solaris privileges +.TP 4n +\fBo\fR +BSD login class +.TP 4n +\fBo\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 +\fBsudo\fR +process waits until the command has completed, then passes the +command's exit status to the security policy's close method and exits. +If an I/O logging plugin is configured, a new pseudo-terminal +(``pty'') +is created and 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 +``orphaned process group'' +and it would not receive any job control signals. +.SS "Signal Handling" +Because the command is run as a child of the +\fBsudo\fR +process, +\fBsudo\fR +will relay signals it receives to the command. +Unless the command is being run in a new pty, the +\fRSIGHUP\fR, +\fRSIGINT\fR +and +\fRSIGQUIT\fR +signals are not relayed unless they are sent by a user process, +not the kernel. +Otherwise, the command would receive +\fRSIGINT\fR +twice every time the user entered control-C. +Some signals, such as +\fRSIGSTOP\fR +and +\fRSIGKILL\fR, +cannot be caught and thus will not be relayed to the command. +As a general rule, +\fRSIGTSTP\fR +should be used instead of +\fRSIGSTOP\fR +when you wish to suspend a command being run by +\fBsudo\fR. +.PP +As a special case, +\fBsudo\fR +will not relay signals that were sent by the command it is running. +This prevents the command from accidentally killing itself. +On some systems, the +reboot(@mansectsu@) +command sends +\fRSIGTERM\fR +to all non-system processes other than itself before rebooting +the systyem. +This prevents +\fBsudo\fR +from relaying the +\fRSIGTERM\fR +signal it received back to +reboot(@mansectsu@), +which might then exit before the system was actually rebooted, +leaving it in a half-dead state similar to single user mode. +Note, however, that this check only applies to the command run by +\fBsudo\fR +and not any other processes that the command may create. +As a result, running a script that calls +reboot(@mansectsu@) +or +shutdown(@mansectsu@) +via +\fBsudo\fR +may cause the system to end up in this undefined state unless the +reboot(@mansectsu@) +or +shutdown(@mansectsu@) +are run using the +\fBexec\fR() +family of functions instead of +\fBsystem\fR() +(which interposes a shell between the command and the calling process). .SH "PLUGINS" Plugins are dynamically loaded based on the contents of the \fI@sysconfdir@/sudo.conf\fR diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in index ae1e21b99..55cf0e08a 100644 --- a/doc/sudo.mdoc.in +++ b/doc/sudo.mdoc.in @@ -125,11 +125,6 @@ allows a permitted user to execute a .Ar command as the superuser or another user, as specified by the security policy. -The real and effective uid and gid are set to match those of the -target user, as specified in the password database, and the group -vector is initialized based on the group database (unless the -.Fl P -option was specified). .Pp .Nm sudo supports a plugin architecture for security policies and input/output @@ -688,6 +683,130 @@ the user may set variables that would otherwise be forbidden. See .Xr sudoers @mansectform@ for more information. +.Sh COMMAND EXECUTION +When +.Nm sudo +executes a command, the security policy specifies the execution +envionment for the command. +Typically, the real and effective uid and gid are set to +match those of the target user, as specified in the password database, +and the group vector is initialized based on the group database +(unless the +.Fl P +option was specified). +.Pp +The following parameters may be specified by security policy: +.Bl -bullet +.It +real and effective user ID +.It +real and effective group ID +.It +supplementary group IDs +.It +the environment list +.It +current working directory +.It +file creation mode mask (umask) +.It +SELinux role and type +.It +Solaris project +.It +Solaris privileges +.It +BSD login class +.It +scheduling priority (aka nice value) +.El +.Ss Process Model +When +.Nm sudo +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 +.Nm sudo +process waits until the command has completed, then passes the +command's exit status to the security policy's close method and exits. +If an I/O logging plugin is configured, a new pseudo-terminal +.Pq Dq pty +is created and a second +.Nm sudo +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 +.Dq orphaned process group +and it would not receive any job control signals. +.Ss Signal Handling +Because the command is run as a child of the +.Nm sudo +process, +.Nm sudo +will relay signals it receives to the command. +Unless the command is being run in a new pty, the +.Dv SIGHUP , +.Dv SIGINT +and +.Dv SIGQUIT +signals are not relayed unless they are sent by a user process, +not the kernel. +Otherwise, the command would receive +.Dv SIGINT +twice every time the user entered control-C. +Some signals, such as +.Dv SIGSTOP +and +.Dv SIGKILL , +cannot be caught and thus will not be relayed to the command. +As a general rule, +.Dv SIGTSTP +should be used instead of +.Dv SIGSTOP +when you wish to suspend a command being run by +.Nm sudo . +.Pp +As a special case, +.Nm sudo +will not relay signals that were sent by the command it is running. +This prevents the command from accidentally killing itself. +On some systems, the +.Xr reboot @mansectsu@ +command sends +.Dv SIGTERM +to all non-system processes other than itself before rebooting +the systyem. +This prevents +.Nm sudo +from relaying the +.Dv SIGTERM +signal it received back to +.Xr reboot @mansectsu@ , +which might then exit before the system was actually rebooted, +leaving it in a half-dead state similar to single user mode. +Note, however, that this check only applies to the command run by +.Nm sudo +and not any other processes that the command may create. +As a result, running a script that calls +.Xr reboot @mansectsu@ +or +.Xr shutdown @mansectsu@ +via +.Nm sudo +may cause the system to end up in this undefined state unless the +.Xr reboot @mansectsu@ +or +.Xr shutdown @mansectsu@ +are run using the +.Fn exec +family of functions instead of +.Fn system +(which interposes a shell between the command and the calling process). .Sh PLUGINS Plugins are dynamically loaded based on the contents of the .Pa @sysconfdir@/sudo.conf