Add a DIAGNOSTICS section with an explanation of the more non-trivial

error messages.

diff --git a/doc/sudo.cat b/doc/sudo.cat
index b026fd4c20e29081c36c014da0066781cc73bb79..abfc3a3fa584c1556eaf17210e3f3b29f6958de7 100644 (file)
--- a/doc/sudo.cat
+++ b/doc/sudo.cat
@@ -606,6 +606,84 @@ E\bEX\bXA\bAM\bMP\bPL\bLE\bES\bS
 
            $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
 
+D\bDI\bIA\bAG\bGN\bNO\bOS\bST\bTI\bIC\bCS\bS
+     Error messages produced by s\bsu\bud\bdo\bo include:
+
+     editing files in a writable directory is not permitted
+           By default, s\bsu\bud\bdo\boe\bed\bdi\bit\bt does not permit editing a file when any of the
+           parent directories are writable by the invoking user.  This avoids
+           a race condition that could allow the user to overwrite an
+           arbitrary file.  See the _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt_\b__\bc_\bh_\be_\bc_\bk_\bd_\bi_\br option in sudoers(4) for
+           more information.
+
+     editing symbolic links is not permitted
+           By default, s\bsu\bud\bdo\boe\bed\bdi\bit\bt does not follow symbolic links when opening
+           files.  See the _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt_\b__\bf_\bo_\bl_\bl_\bo_\bw option in sudoers(4) for more
+           information.
+
+     effective uid is not 0, is sudo installed setuid root?
+           This error indicates that s\bsu\bud\bdo\bo was not run with root privileges.
+           The s\bsu\bud\bdo\bo binary must be owned by the root user and have the Set-
+           user-ID bit set.  Also, it must not be located on a file system
+           mounted with the `nosuid' option or on an NFS file system that maps
+           uid 0 to an unprivileged uid.
+
+     effective uid is not 0, is sudo on a file system with the 'nosuid' option
+           set or an NFS file system without root privileges?
+           This error indicates that the s\bsu\bud\bdo\bo binary has the proper owner and
+           permissions but it still did not run with root privileges.  The
+           most common reason for this is that the file system the s\bsu\bud\bdo\bo binary
+           is located on is mounted with the `nosuid' option or it is an NFS
+           file system that maps uid 0 to an unprivileged uid.
+
+     fatal error, unable to load plugins
+           An error occurred while loading or initializing the plugins
+           specified in sudo.conf(4).
+
+     invalid environment variable name: foo=bar
+           One or more environment variable names specified via the -\b-E\bE option
+           contained an equal sign (`=').  The arguments to the -\b-E\bE option
+           should be environment variable names without an associated value.
+
+     no password was provided
+           When s\bsu\bud\bdo\bo tried to read the password, it did not receive any
+           characters.  This may happen if no terminal is available (or the -\b-S\bS
+           option is specified) and the standard input has been redirected
+           from _\b/_\bd_\be_\bv_\b/_\bn_\bu_\bl_\bl.
+
+     no tty present and no askpass program specified
+           s\bsu\bud\bdo\bo needs to read the password but there is no mechanism available
+           to do so.  A terminal is not present to read the password from,
+           s\bsu\bud\bdo\bo has not been configured to read from the standard input, and
+           no askpass program has been specified either via the -\b-A\bA option or
+           the SUDO_ASKPASS environment variable.
+
+     no writable temporary directory found
+           s\bsu\bud\bdo\boe\bed\bdi\bit\bt was unable to find a usable temporary directory in which
+           to store its intermediate files.
+
+     sudo must be owned by uid 0 and have the setuid bit set
+           This error indicates that the s\bsu\bud\bdo\bo binary does not have the correct
+           owner or permissions.  It must be owned by the root user and have
+           the Set-user-ID bit set.
+
+     sudoedit is not supported on this platform
+           It is only possible to run s\bsu\bud\bdo\boe\bed\bdi\bit\bt on systems that support setting
+           the effective user-ID.
+
+     timed out reading password
+           The user did not enter a password before the password timeout (5
+           minutes by default) expired.
+
+     unknown uid UID: who are you?
+           s\bsu\bud\bdo\bo was unable to look up the invoking user's ID in the password
+           database.
+
+     you may not specify environment variables in edit mode
+           It is only possible to specify environment variables when running a
+           command.  When editing a file, the editor is run with the user's
+           environment unmodified.
+
 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
      su(1), stat(2), login_cap(3), passwd(4), sudo.conf(4), sudo_plugin(4),
      sudoers(4), sudoreplay(1m), visudo(1m)

diff --git a/doc/sudo.man.in b/doc/sudo.man.in
index bd534e6ca623f45a1e8bc1426d5c3088f874c0a1..c5bddb86c97c999bdc183f6b1567547b3e159936 100644 (file)
--- a/doc/sudo.man.in
+++ b/doc/sudo.man.in
@@ -1205,6 +1205,118 @@ and file redirection work.
 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
 .RE
 .fi
+.SH "DIAGNOSTICS"
+Error messages produced by
+\fBsudo\fR
+include:
+.TP 6n
+\fRediting files in a writable directory is not permitted\fR
+By default,
+\fBsudoedit\fR
+does not permit editing a file when any of the parent directories are writable
+by the invoking user.
+This avoids a race condition that could allow the user to overwrite
+an arbitrary file.
+See the
+\fIsudoedit_checkdir\fR
+option in
+sudoers(@mansectform@)
+for more information.
+.TP 6n
+\fRediting symbolic links is not permitted\fR
+By default,
+\fBsudoedit\fR
+does not follow symbolic links when opening files.
+See the
+\fIsudoedit_follow\fR
+option in
+sudoers(@mansectform@)
+for more information.
+.TP 6n
+\fReffective uid is not 0, is sudo installed setuid root?\fR
+This error indicates that
+\fBsudo\fR
+was not run with root privileges.
+The
+\fBsudo\fR
+binary must be owned by the root user and have the Set-user-ID bit set.
+Also, it must not be located on a file system mounted with the
+\(oqnosuid\(cq
+option or on an NFS file system that maps uid 0 to an unprivileged uid.
+.TP 6n
+\fReffective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?\fR
+This error indicates that the
+\fBsudo\fR
+binary has the proper owner and permissions but it still did not run
+with root privileges.
+The most common reason for this is that the file system the
+\fBsudo\fR
+binary is located on is mounted with the
+\(oqnosuid\(cq
+option or it is an NFS file system that maps uid 0 to an unprivileged uid.
+.TP 6n
+\fRfatal error, unable to load plugins\fR
+An error occurred while loading or initializing the plugins specified in
+sudo.conf(@mansectform@).
+.TP 6n
+\fRinvalid environment variable name: foo=bar\fR
+One or more environment variable names specified via the
+\fB\-E\fR
+option contained an equal sign
+(\(oq=\(cq).
+The arguments to the
+\fB\-E\fR
+option should be environment variable names without an associated value.
+.TP 6n
+\fRno password was provided\fR
+When
+\fBsudo\fR
+tried to read the password, it did not receive any characters.
+This may happen if no terminal is available (or the
+\fB\-S\fR
+option is specified) and the standard input has been redirected from
+\fI/dev/null\fR.
+.TP 6n
+\fRno tty present and no askpass program specified\fR
+\fBsudo\fR
+needs to read the password but there is no mechanism available to do so.
+A terminal is not present to read the password from,
+\fBsudo\fR
+has not been configured to read from the standard input,
+and no askpass program has been specified either via the
+\fB\-A\fR
+option or the
+\fRSUDO_ASKPASS\fR
+environment variable.
+.TP 6n
+\fRno writable temporary directory found\fR
+\fBsudoedit\fR
+was unable to find a usable temporary directory in which to store its
+intermediate files.
+.TP 6n
+\fRsudo must be owned by uid 0 and have the setuid bit set\fR
+This error indicates that the
+\fBsudo\fR
+binary does not have the correct owner or permissions.
+It must be owned by the root user and have the Set-user-ID bit set.
+.TP 6n
+\fRsudoedit is not supported on this platform\fR
+It is only possible to run
+\fBsudoedit\fR
+on systems that support setting the effective user-ID.
+.TP 6n
+\fRtimed out reading password\fR
+The user did not enter a password before the password timeout
+(5 minutes by default) expired.
+.TP 6n
+\fRunknown uid UID: who are you?\fR
+\fBsudo\fR
+was unable to look up the invoking user's ID in the password database.
+.TP 6n
+\fRyou may not specify environment variables in edit mode\fR
+It is only possible to specify environment variables when running
+a command.
+When editing a file, the editor is run with the user's environment unmodified.
 .SH "SEE ALSO"
 su(1),
 stat(2),

diff --git a/doc/sudo.mdoc.in b/doc/sudo.mdoc.in
index 7fdc4ce3ec10f014b22f162cdc1ba503c90be6b8..876b23322fedf20a5cd36cf4d8ee6bc8b3579dd1 100644 (file)
--- a/doc/sudo.mdoc.in
+++ b/doc/sudo.mdoc.in
@@ -1098,6 +1098,106 @@ and file redirection work.
 .Bd -literal -offset indent
 $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE"
 .Ed
+.Sh DIAGNOSTICS
+Error messages produced by
+.Nm
+include:
+.Bl -tag -width 4n
+.It Li editing files in a writable directory is not permitted
+By default,
+.Nm sudoedit
+does not permit editing a file when any of the parent directories are writable
+by the invoking user.
+This avoids a race condition that could allow the user to overwrite
+an arbitrary file.
+See the
+.Em sudoedit_checkdir
+option in
+.Xr sudoers @mansectform@
+for more information.
+.It Li editing symbolic links is not permitted
+By default,
+.Nm sudoedit
+does not follow symbolic links when opening files.
+See the
+.Em sudoedit_follow
+option in
+.Xr sudoers @mansectform@
+for more information.
+.It Li effective uid is not 0, is sudo installed setuid root?
+This error indicates that
+.Nm
+was not run with root privileges.
+The
+.Nm
+binary must be owned by the root user and have the Set-user-ID bit set.
+Also, it must not be located on a file system mounted with the
+.Sq nosuid
+option or on an NFS file system that maps uid 0 to an unprivileged uid.
+.It Li effective uid is not 0, is sudo on a file system with the 'nosuid' option set or an NFS file system without root privileges?
+This error indicates that the
+.Nm
+binary has the proper owner and permissions but it still did not run
+with root privileges.
+The most common reason for this is that the file system the
+.Nm
+binary is located on is mounted with the
+.Sq nosuid
+option or it is an NFS file system that maps uid 0 to an unprivileged uid.
+.It Li fatal error, unable to load plugins
+An error occurred while loading or initializing the plugins specified in
+.Xr sudo.conf @mansectform@ .
+.It Li invalid environment variable name: foo=bar
+One or more environment variable names specified via the
+.Fl E
+option contained an equal sign
+.Pq Ql = .
+The arguments to the
+.Fl E
+option should be environment variable names without an associated value.
+.It Li no password was provided
+When
+.Nm
+tried to read the password, it did not receive any characters.
+This may happen if no terminal is available (or the
+.Fl S
+option is specified) and the standard input has been redirected from
+.Pa /dev/null .
+.It Li no tty present and no askpass program specified
+.Nm
+needs to read the password but there is no mechanism available to do so.
+A terminal is not present to read the password from,
+.Nm
+has not been configured to read from the standard input,
+and no askpass program has been specified either via the
+.Fl A
+option or the
+.Ev SUDO_ASKPASS
+environment variable.
+.It Li no writable temporary directory found
+.Nm sudoedit
+was unable to find a usable temporary directory in which to store its
+intermediate files.
+.It Li sudo must be owned by uid 0 and have the setuid bit set
+This error indicates that the
+.Nm
+binary does not have the correct owner or permissions.
+It must be owned by the root user and have the Set-user-ID bit set.
+.It Li sudoedit is not supported on this platform
+It is only possible to run
+.Nm sudoedit
+on systems that support setting the effective user-ID.
+.It Li timed out reading password
+The user did not enter a password before the password timeout
+(5 minutes by default) expired.
+.It Li unknown uid UID: who are you?
+.Nm
+was unable to look up the invoking user's ID in the password database.
+.It Li you may not specify environment variables in edit mode
+It is only possible to specify environment variables when running
+a command.
+When editing a file, the editor is run with the user's environment unmodified.
+.El
 .Sh SEE ALSO
 .Xr su 1 ,
 .Xr stat 2 ,