From 3f6f61f852a537967a77d1898b457b0ceed90f98 Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Tue, 28 Dec 2010 12:25:06 -0500 Subject: [PATCH] Document iolog_compress in command_info --- doc/sudo_plugin.cat | 166 ++++++++++++++++++++--------------------- doc/sudo_plugin.man.in | 31 ++++---- doc/sudo_plugin.pod | 34 +++++---- 3 files changed, 121 insertions(+), 110 deletions(-) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index a6f474299..47be5e9eb 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -61,7 +61,7 @@ DDEESSCCRRIIPPTTIIOONN -1.8.0b3 December 27, 2010 1 +1.8.0b3 December 28, 2010 1 @@ -127,7 +127,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 2 +1.8.0b3 December 28, 2010 2 @@ -193,7 +193,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 3 +1.8.0b3 December 28, 2010 3 @@ -259,7 +259,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 4 +1.8.0b3 December 28, 2010 4 @@ -325,7 +325,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 5 +1.8.0b3 December 28, 2010 5 @@ -391,7 +391,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 6 +1.8.0b3 December 28, 2010 6 @@ -457,7 +457,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 7 +1.8.0b3 December 28, 2010 7 @@ -523,7 +523,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 8 +1.8.0b3 December 28, 2010 8 @@ -543,6 +543,24 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) If specified, ssuuddoo will close all files descriptors with a value of _n_u_m_b_e_r or higher. + iolog_compress=bool + Set to true if the I/O logging plugins, if any, should + compress the log data. This is a hint to the I/O logging + plugin which may choose to ignore it. + + iolog_dir=string + Fully qualified path to the directory in which I/O logs are + to be stored. This is a hint to the I/O logging plugin + which may choose to ignore it. If no I/O logging plugin is + loaded, this setting has no effect. + + iolog_file=string + File name to use when I/O logging is enabled, relative to + _i_o_l_o_g___d_i_r (may also contain directory components). This is + a hint to the I/O logging plugin which may choose to ignore + it. If no I/O logging plugin is loaded, this setting has + no effect. + iolog_stdin=bool Set to true if the I/O logging plugins, if any, should log the standard input if it is not connected to a terminal @@ -568,28 +586,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) is a hint to the I/O logging plugin which may choose to ignore it. - iolog_ttyout=bool - Set to true if the I/O logging plugins, if any, should log - all terminal output. This only includes output to the - screen, not output to a pipe or file. This is a hint to - the I/O logging plugin which may choose to ignore it. - - iolog_dir=string - Fully qualified path to the directory in which I/O logs are - to be stored. This is a hint to the I/O logging plugin - which may choose to ignore it. If no I/O logging plugin is - loaded, this setting has no effect. - - iolog_file=string - File name to use when I/O logging is enabled, relative to - _i_o_l_o_g___d_i_r (may also contain directory components). This is - a hint to the I/O logging plugin which may choose to ignore - it. If no I/O logging plugin is loaded, this setting has - no effect. -1.8.0b3 December 27, 2010 9 +1.8.0b3 December 28, 2010 9 @@ -598,6 +598,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + iolog_ttyout=bool + Set to true if the I/O logging plugins, if any, should log + all terminal output. This only includes output to the + screen, not output to a pipe or file. This is a hint to + the I/O logging plugin which may choose to ignore it. + use_pty=bool Allocate a pseudo-tty to run the command in, regardless of whether or not I/O logging is in use. By default, ssuuddoo @@ -646,23 +652,23 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) wishes to check against the policy in the same form as what would be passed to the _e_x_e_c_v_e_(_) system call. If the command is permitted by the policy, the fully-qualified path to the - command should be displayed along with any command line - arguments. - validate - int (*validate)(void); +1.8.0b3 December 28, 2010 10 -1.8.0b3 December 27, 2010 10 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + command should be displayed along with any command line + arguments. + validate + int (*validate)(void); The validate function is called when ssuuddoo is run with the -v flag. For policy plugins such as _s_u_d_o_e_r_s that cache authentication @@ -708,20 +714,14 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) _V_e_r_s_i_o_n _m_a_c_r_o_s - #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) - #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) - #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \ - *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \ - } while(0) - #define SUDO_VERSION_SET_MINOR(vp, n) do { \ - *(vp) = (*(vp) & 0xffff0000) | (n); \ - } while(0) - #define SUDO_API_VERSION_MAJOR 1 -1.8.0b3 December 27, 2010 11 + + + +1.8.0b3 December 28, 2010 11 @@ -730,6 +730,16 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16) + #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff) + #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \ + *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \ + } while(0) + #define SUDO_VERSION_SET_MINOR(vp, n) do { \ + *(vp) = (*(vp) & 0xffff0000) | (n); \ + } while(0) + + #define SUDO_API_VERSION_MAJOR 1 #define SUDO_API_VERSION_MINOR 0 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \ SUDO_API_VERSION_MINOR) @@ -775,27 +785,24 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) type The type field should always be set to SUDO_IO_PLUGIN - version - The version field should be set to SUDO_API_VERSION. - - This allows ssuuddoo to determine the API version the plugin was built - against. - - open - +1.8.0b3 December 28, 2010 12 -1.8.0b3 December 27, 2010 12 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + version + The version field should be set to SUDO_API_VERSION. + This allows ssuuddoo to determine the API version the plugin was built + against. + open int (*open)(unsigned int version, sudo_conv_t conversation sudo_printf_t plugin_printf, char * const settings[], char * const user_info[], int argc, char * const argv[], @@ -844,16 +851,9 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) equal sign ('=') since the _n_a_m_e field will never include one itself but the _v_a_l_u_e might. - See the "Policy Plugin API" section for a list of all possible - settings. - user_info - A vector of information about the user running the command in - the form of "name=value" strings. The vector is terminated by - - -1.8.0b3 December 27, 2010 13 +1.8.0b3 December 28, 2010 13 @@ -862,6 +862,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + See the "Policy Plugin API" section for a list of all possible + settings. + + user_info + A vector of information about the user running the command in + the form of "name=value" strings. The vector is terminated by a NULL pointer. When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt @@ -910,16 +916,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) int (*show_version)(int verbose); The show_version function is called by ssuuddoo when the user specifies - the -V option. The plugin may display its version information to - the user via the conversation or plugin_printf function using - SUDO_CONV_INFO_MSG. If the user requests detailed version - information, the verbose flag will be set. - - -1.8.0b3 December 27, 2010 14 +1.8.0b3 December 28, 2010 14 @@ -928,6 +928,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + the -V option. The plugin may display its version information to + the user via the conversation or plugin_printf function using + SUDO_CONV_INFO_MSG. If the user requests detailed version + information, the verbose flag will be set. + log_ttyin int (*log_ttyin)(const char *buf, unsigned int len); @@ -977,15 +982,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) len The length of _b_u_f in bytes. - log_stdout - int (*log_stdout)(const char *buf, unsigned int len); - - The _l_o_g___s_t_d_o_u_t function is only used if the standard output does - not correspond to a tty device. It is called whenever data can be -1.8.0b3 December 27, 2010 15 +1.8.0b3 December 28, 2010 15 @@ -994,6 +994,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + log_stdout + int (*log_stdout)(const char *buf, unsigned int len); + + The _l_o_g___s_t_d_o_u_t function is only used if the standard output does + not correspond to a tty device. It is called whenever data can be read from the command but before it is written to the standard output. This allows the plugin to reject data if it chooses to (for instance if the output contains banned content). Returns 1 if @@ -1046,12 +1051,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - - - - -1.8.0b3 December 27, 2010 16 +1.8.0b3 December 28, 2010 16 @@ -1117,7 +1117,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 17 +1.8.0b3 December 28, 2010 17 @@ -1183,7 +1183,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0b3 December 27, 2010 18 +1.8.0b3 December 28, 2010 18 @@ -1249,6 +1249,6 @@ DDIISSCCLLAAIIMMEERR -1.8.0b3 December 27, 2010 19 +1.8.0b3 December 28, 2010 19 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index 65bb6ee5d..29ae90887 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -139,7 +139,7 @@ .\" ======================================================================== .\" .IX Title "SUDO_PLUGIN @mansectsu@" -.TH SUDO_PLUGIN @mansectsu@ "December 27, 2010" "1.8.0b3" "MAINTENANCE COMMANDS" +.TH SUDO_PLUGIN @mansectsu@ "December 28, 2010" "1.8.0b3" "MAINTENANCE COMMANDS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -603,6 +603,23 @@ enable \fIsudoedit\fR when the user attempts to run an editor. .IX Item "closefrom=number" If specified, \fBsudo\fR will close all files descriptors with a value of \fInumber\fR or higher. +.IP "iolog_compress=bool" 4 +.IX Item "iolog_compress=bool" +Set to true if the I/O logging plugins, if any, should compress the +log data. This is a hint to the I/O logging plugin which may choose +to ignore it. +.IP "iolog_dir=string" 4 +.IX Item "iolog_dir=string" +Fully qualified path to the directory in which I/O logs are to be +stored. This is a hint to the I/O logging plugin which may choose +to ignore it. If no I/O logging plugin is loaded, this setting has +no effect. +.IP "iolog_file=string" 4 +.IX Item "iolog_file=string" +File name to use when I/O logging is enabled, relative to \fIiolog_dir\fR +(may also contain directory components). +This is a hint to the I/O logging plugin which may choose to ignore +it. If no I/O logging plugin is loaded, this setting has no effect. .IP "iolog_stdin=bool" 4 .IX Item "iolog_stdin=bool" Set to true if the I/O logging plugins, if any, should log the @@ -630,18 +647,6 @@ Set to true if the I/O logging plugins, if any, should log all terminal output. This only includes output to the screen, not output to a pipe or file. This is a hint to the I/O logging plugin which may choose to ignore it. -.IP "iolog_dir=string" 4 -.IX Item "iolog_dir=string" -Fully qualified path to the directory in which I/O logs are to be -stored. This is a hint to the I/O logging plugin which may choose -to ignore it. If no I/O logging plugin is loaded, this setting has -no effect. -.IP "iolog_file=string" 4 -.IX Item "iolog_file=string" -File name to use when I/O logging is enabled, relative to \fIiolog_dir\fR -(may also contain directory components). -This is a hint to the I/O logging plugin which may choose to ignore -it. If no I/O logging plugin is loaded, this setting has no effect. .IP "use_pty=bool" 4 .IX Item "use_pty=bool" Allocate a pseudo-tty to run the command in, regardless of whether diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod index 99eebcaf9..0acf78d5f 100644 --- a/doc/sudo_plugin.pod +++ b/doc/sudo_plugin.pod @@ -535,6 +535,26 @@ enable I when the user attempts to run an editor. If specified, B will close all files descriptors with a value of I or higher. +=item iolog_compress=bool + +Set to true if the I/O logging plugins, if any, should compress the +log data. This is a hint to the I/O logging plugin which may choose +to ignore it. + +=item iolog_dir=string + +Fully qualified path to the directory in which I/O logs are to be +stored. This is a hint to the I/O logging plugin which may choose +to ignore it. If no I/O logging plugin is loaded, this setting has +no effect. + +=item iolog_file=string + +File name to use when I/O logging is enabled, relative to I +(may also contain directory components). +This is a hint to the I/O logging plugin which may choose to ignore +it. If no I/O logging plugin is loaded, this setting has no effect. + =item iolog_stdin=bool Set to true if the I/O logging plugins, if any, should log the @@ -567,20 +587,6 @@ terminal output. This only includes output to the screen, not output to a pipe or file. This is a hint to the I/O logging plugin which may choose to ignore it. -=item iolog_dir=string - -Fully qualified path to the directory in which I/O logs are to be -stored. This is a hint to the I/O logging plugin which may choose -to ignore it. If no I/O logging plugin is loaded, this setting has -no effect. - -=item iolog_file=string - -File name to use when I/O logging is enabled, relative to I -(may also contain directory components). -This is a hint to the I/O logging plugin which may choose to ignore -it. If no I/O logging plugin is loaded, this setting has no effect. - =item use_pty=bool Allocate a pseudo-tty to run the command in, regardless of whether -- 2.40.0