From: Todd C. Miller Date: Fri, 6 Jan 2012 14:44:41 +0000 (-0500) Subject: Document Debug setting in sudo.conf and debug_flags in plugin. X-Git-Tag: SUDO_1_8_4~87^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=45e1623b5d971b3c2978ec14a394098242d65e48;p=sudo Document Debug setting in sudo.conf and debug_flags in plugin. --- diff --git a/doc/sudo.pod b/doc/sudo.pod index d11705b90..eb6c27cb9 100644 --- a/doc/sudo.pod +++ b/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 Permission to use, copy, modify, and distribute this software for any @@ -65,7 +65,7 @@ option was specified). B 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 front end. The default security policy is I, which is configured via the file F<@sysconfdir@/sudoers>, or via LDAP. See the L 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 option is set in I, the command to be run has the C tag set or the command matched is C, the user may set variables -that would overwise be forbidden. See L for more information. +that would otherwise be forbidden. See L 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 versions 1.8.4 and higher support a flexible debugging +framework that can help track down what B is doing internally +when there is a problem. + +A C line consists of the C keyword, followed by the +name of the program to debug (B, B, B), +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by B and the I plugin is +I@I 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 level and higher +in addition to those at the I level for the plugin subsystem. + +Currently, only one C entry per program is supported. The +C C entry is shared by the B front end, B +and the plugins. A future release may add support for per-plugin +C lines and/or support for multiple debugging files for a +single program. + +For reference, the priorities supported by the B front end and +I are: I, I, I, I, I, +I, I and I. + +The following subsystems are defined: I
, I, I, +I, I, I, I, I, I, I, +I, I, I, I, I, I, I, +I, I, I, I, I, I, I, +I, I. The subsystem I includes every subsystem. + =head1 RETURN VALUES Upon successful execution of a program, the exit status from B @@ -598,7 +635,7 @@ is not set =item F<@sysconfdir@/sudo.conf> -B plugin and path configuration +B front end configuration =back diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod index 570218088..3513cae0a 100644 --- a/doc/sudo_plugin.pod +++ b/doc/sudo_plugin.pod @@ -1,4 +1,4 @@ -Copyright (c) 2009-2011 Todd C. Miller +Copyright (c) 2009-2012 Todd C. Miller 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 might. =over 4 +=item debug_flags=string + +A comma-separated list of debug flags that correspond to B's +C 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 and the I plugin is +I@I 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 front end and +I are: I, I, I, I, I, +I, I and I. + +The following subsystems are defined: I
, I, I, +I, I, I, I, I, I, I, +I, I, I, I, I, I, I, +I, I, I, I, I, I, I, +I, I. The subsystem I 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 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. =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, if any. The printf-style function uses the same underlying mechanism as the -conversation function but only supports C and -C for the I parameter. It can be -more convenient than using the conversation function if no user -reply is needed and supports standard printf() escape sequences. +conversation function but only supports C, +C and C for the I +parameter. It can be more convenient than using the conversation +function if no user reply is needed and supports standard printf() +escape sequences. + +Unlike, C and C, messages +sent with the I are not directly +user-visible. Instead, they are logged to the file specified in +the C 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 setting. See the sample plugin for an example of the conversation function usage.