Document Debug setting in sudo.conf and debug_flags in plugin.

doc/sudo.pod

@@ -1,4 +1,4 @@
-Copyright (c) 1994-1996, 1998-2005, 2007-2011
+Copyright (c) 1994-1996, 1998-2005, 2007-2012
 	Todd C. Miller <Todd.Miller@courtesan.com>
 
 Permission to use, copy, modify, and distribute this software for any
@@ -65,7 +65,7 @@ option was specified).
 
 B<sudo> supports a plugin architecture for security policies and
 input/output logging.  Third parties can develop and distribute
-their own policy and I/O logging modules to work seemlessly with
+their own policy and I/O logging modules to work seamlessly with
 the B<sudo> front end.  The default security policy is I<sudoers>,
 which is configured via the file F<@sysconfdir@/sudoers>, or via
 LDAP.  See the L<PLUGINS> section for more information.
@@ -407,7 +407,7 @@ command line are subject to the same restrictions as normal environment
 variables with one important exception.  If the I<setenv> option
 is set in I<sudoers>, the command to be run has the C<SETENV> tag
 set or the command matched is C<ALL>, the user may set variables
-that would overwise be forbidden.  See L<sudoers(5)> for more information.
+that would otherwise be forbidden.  See L<sudoers(5)> for more information.
 
 =head1 PLUGINS
 
@@ -424,6 +424,7 @@ which corresponds to the following F<@sysconfdir@/sudo.conf> file.
  #   Plugin plugin_name plugin_path
  #   Path askpass /path/to/askpass
  #   Path noexec /path/to/noexec.so
+ #   Debug sudo /var/log/sudo_debug all@warn
  #
  # The plugin_path is relative to @prefix@/libexec unless
  #   fully qualified.
@@ -477,6 +478,42 @@ Defaults to F<@noexec_file@>.
 
 =back
 
+=head1 DEBUG FLAGS
+
+B<sudo> versions 1.8.4 and higher support a flexible debugging
+framework that can help track down what B<sudo> is doing internally
+when there is a problem.
+
+A C<Debug> line consists of the C<Debug> keyword, followed by the
+name of the program to debug (B<sudo>, B<visudo>, B<sudoreplay>),
+the debug file name and a comma-separated list of debug flags.
+The debug flag syntax used by B<sudo> and the I<sudoers> plugin is
+I<subsystem>@I<priority> but the plugin is free to use a different
+format so long as it does not include a command C<,>.
+
+For instance:
+
+ Debug sudo /var/log/sudo_debug all@warn,plugin@info
+
+would log all debugging statements at the I<warn> level and higher
+in addition to those at the I<info> level for the plugin subsystem.
+
+Currently, only one C<Debug> entry per program is supported.  The
+C<sudo> C<Debug> entry is shared by the B<sudo> front end, B<sudoedit>
+and the plugins.  A future release may add support for per-plugin
+C<Debug> lines and/or support for multiple debugging files for a
+single program.
+
+For reference, the priorities supported by the B<sudo> front end and
+I<sudoers> are: I<crit>, I<err>, I<warn>, I<notice>, I<diag>,
+I<info>, I<trace> and I<debug>.
+
+The following subsystems are defined: I<main>, I<memory>, I<args>,
+I<exec>, I<pty>, I<utmp>, I<conv>, I<pcomm>, I<util>, I<list>,
+I<netif>, I<audit>, I<edit>, I<selinux>, I<ldap>, I<match>, I<parser>,
+I<alias>, I<defaults>, I<auth>, I<env>, I<logging>, I<nss>, I<rbtree>,
+I<perms>, I<plugin>.  The subsystem I<all> includes every subsystem.
+
 =head1 RETURN VALUES
 
 Upon successful execution of a program, the exit status from B<sudo>
@@ -598,7 +635,7 @@ is not set
 
 =item F<@sysconfdir@/sudo.conf>
 
-B<sudo> plugin and path configuration
+B<sudo> front end configuration
 
 =back
 

doc/sudo_plugin.pod

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2011 Todd C. Miller <Todd.Miller@courtesan.com>
+Copyright (c) 2009-2012 Todd C. Miller <Todd.Miller@courtesan.com>
 
 Permission to use, copy, modify, and distribute this software for any
 purpose with or without fee is hereby granted, provided that the above
@@ -163,9 +163,31 @@ itself but the I<value> might.
 
 =over 4
 
+=item debug_flags=string
+
+A comma-separated list of debug flags that correspond to B<sudo>'s
+C<Debug> entry in F<@sysconfdir@/sudo.conf>, if there is one.  The
+flags are passed to the plugin as they appear in F<@sysconfdir@/sudo.conf>.
+The syntax used by B<sudo> and the I<sudoers> plugin is
+I<subsystem>@I<priority> but the plugin is free to use a different
+format so long as it does not include a command C<,>.
+
+For reference, the priorities supported by the B<sudo> front end and
+I<sudoers> are: I<crit>, I<err>, I<warn>, I<notice>, I<diag>,
+I<info>, I<trace> and I<debug>.
+
+The following subsystems are defined: I<main>, I<memory>, I<args>,
+I<exec>, I<pty>, I<utmp>, I<conv>, I<pcomm>, I<util>, I<list>,
+I<netif>, I<audit>, I<edit>, I<selinux>, I<ldap>, I<match>, I<parser>,
+I<alias>, I<defaults>, I<auth>, I<env>, I<logging>, I<nss>, I<rbtree>,
+I<perms>, I<plugin>.  The subsystem I<all> includes every subsystem.
+
+There is not currently a way to specify a set of debug flags specific
+to the plugin--the flags are shared by B<sudo> and the plugin.
+
 =item debug_level=number
 
-A numeric debug level, from 1-9, if specified via the C<-D> flag.
+This setting has been deprecated in favor of I<debug_flags>.
 
 =item runas_user=string
 
@@ -1064,6 +1086,7 @@ convenient for simple messages where no use input is required.
  #define SUDO_CONV_ERROR_MSG	    0x0003 /* error message */
  #define SUDO_CONV_INFO_MSG	    0x0004 /* informational message */
  #define SUDO_CONV_PROMPT_MASK	    0x0005 /* mask user input */
+ #define SUDO_CONV_DEBUG_MSG	    0x0006 /* debugging message */
  #define SUDO_CONV_PROMPT_ECHO_OK   0x1000 /* flag: allow echo if no tty */
      int msg_type;
      int timeout;
@@ -1091,10 +1114,18 @@ freeing the reply buffer filled in to the C<struct sudo_conv_reply>,
 if any.
 
 The printf-style function uses the same underlying mechanism as the
-conversation function but only supports C<SUDO_CONV_INFO_MSG> and
+conversation function but only supports C<SUDO_CONV_INFO_MSG>,
-C<SUDO_CONV_ERROR_MSG> for the I<msg_type> parameter.  It can be
+C<SUDO_CONV_ERROR_MSG> and C<SUDO_CONV_DEBUG_MSG> for the I<msg_type>
-more convenient than using the conversation function if no user
+parameter.  It can be more convenient than using the conversation
-reply is needed and supports standard printf() escape sequences.
+function if no user reply is needed and supports standard printf()
+escape sequences.
+
+Unlike, C<SUDO_CONV_INFO_MSG> and C<SUDO_CONV_ERROR_MSG>, messages
+sent with the <SUDO_CONV_DEBUG_MSG> I<msg_type> are not directly
+user-visible.  Instead, they are logged to the file specified in
+the C<Debug> statement (if any) in the F<@sysconfdir@/sudo.conf>
+file.  This allows a plugin to log debugging information and is
+intended to be used in conjunction with the I<debug_flags> setting.
 
 See the sample plugin for an example of the conversation function usage.