From 18cd91d56e810e13bcef969061966c72e76b3b7f Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Fri, 19 Mar 2010 07:56:06 -0400 Subject: [PATCH] Document progname in settings --- doc/sudo_plugin.cat | 128 ++++++++++++++++++++--------------------- doc/sudo_plugin.man.in | 5 +- doc/sudo_plugin.pod | 4 ++ 3 files changed, 72 insertions(+), 65 deletions(-) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 883257579..a6dd702e4 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -61,7 +61,7 @@ SSuuddoo PPlluuggiinn AAPPII -1.8.0a1 March 17, 2010 1 +1.8.0a1 March 19, 2010 1 @@ -127,7 +127,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0a1 March 17, 2010 2 +1.8.0a1 March 19, 2010 2 @@ -193,7 +193,7 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -1.8.0a1 March 17, 2010 3 +1.8.0a1 March 19, 2010 3 @@ -210,6 +210,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) Authentication type, if specified by the -a flag, to use on systems where BSD authentication is supported. + progname=string + The command name that sudo was run as, typically "sudo" or + "sudoedit". + Additional settings may be added in the future so the plugin should silently ignore settings that it does not recognize. @@ -252,14 +256,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) is no terminal device available, a default value of 24 is used. - cols=int - The number of columns the user's terminal supports. If - there is no terminal device available, a default value of - 80 is used. -1.8.0a1 March 17, 2010 4 +1.8.0a1 March 19, 2010 4 @@ -268,6 +268,11 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + cols=int + The number of columns the user's terminal supports. If + there is no terminal device available, a default value of + 80 is used. + user_env The user's environment in the form of a NULL-terminated vector of "name=value" strings. @@ -317,15 +322,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_CONF_ERROR_MSG to present additional error information to the user. - The function arguments are as follows: - - argc - The number of elements in _a_r_g_v, not counting the final NULL - pointer. -1.8.0a1 March 17, 2010 5 +1.8.0a1 March 19, 2010 5 @@ -334,6 +334,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + The function arguments are as follows: + + argc + The number of elements in _a_r_g_v, not counting the final NULL + pointer. + argv The argument vector describing the command the user wishes to run, in the same form as what would be passed to the _e_x_e_c_v_e_(_) @@ -382,16 +388,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) login_class=login_class BSD login class to use when setting resource limits and - nice value (optional). This option is only set on systems - that support login classes. - preserve_groups=bool - If set, ssuuddoo will preserve the user's group vector instead - of initializing the group vector based on runas_user. - -1.8.0a1 March 17, 2010 6 +1.8.0a1 March 19, 2010 6 @@ -400,6 +400,13 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + nice value (optional). This option is only set on systems + that support login classes. + + preserve_groups=bool + If set, ssuuddoo will preserve the user's group vector instead + of initializing the group vector based on runas_user. + cwd=string The current working directory to change to when executing the command. @@ -447,24 +454,25 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) List available privileges for the invoking user. Returns 1 on success, 0 on failure and -1 on error. On error, the plugin may optionally call the conversation function with SUDO_CONF_ERROR_MSG - to present additional error information to the user. - Privileges should be output via the conversation function using - SUDO_CONV_INFO_MSG. - verbose - Flag indicating whether to list in verbose mode or not. +1.8.0a1 March 19, 2010 7 -1.8.0a1 March 17, 2010 7 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + to present additional error information to the user. + + Privileges should be output via the conversation function using + SUDO_CONV_INFO_MSG. + verbose + Flag indicating whether to list in verbose mode or not. list_user The name of a different user to list privileges for if the @@ -512,18 +520,10 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) _C_o_n_v_e_r_s_a_t_i_o_n _A_P_I - If the plugin needs to interact with the user or display informational - or error messages, it may do so via the conversation function. A - plugin should not attempt to read directly from the standard input or - the user's tty (neither of which are guaranteed to exist). The caller - must include a trailing newline in msg if they want one to be printed. - - - -1.8.0a1 March 17, 2010 8 +1.8.0a1 March 19, 2010 8 @@ -532,6 +532,12 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + If the plugin needs to interact with the user or display informational + or error messages, it may do so via the conversation function. A + plugin should not attempt to read directly from the standard input or + the user's tty (neither of which are guaranteed to exist). The caller + must include a trailing newline in msg if they want one to be printed. + struct sudo_conv_message { #define SUDO_CONV_PROMPT_ECHO_OFF 1 #define SUDO_CONV_PROMPT_ECHO_ON 2 @@ -580,23 +586,24 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) disabled, such as passwords). The log_output function receives output from the pseudo-tty that is suitable for replaying the user's session at a later time. Either log_input or log_output may be NULL. If the - open function returns 0, no I/O will be sent to the plugin. - The io_plugin struct has the following fields: - type - The type field should always be set to SUDO_IO_PLUGIN +1.8.0a1 March 19, 2010 9 -1.8.0a1 March 17, 2010 9 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + open function returns 0, no I/O will be sent to the plugin. + + The io_plugin struct has the following fields: + type + The type field should always be set to SUDO_IO_PLUGIN version The version field should be set to SUDO_API_VERSION. @@ -646,23 +653,23 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) 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 - 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 - strings. +1.8.0a1 March 19, 2010 10 -1.8.0a1 March 17, 2010 10 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + When parsing _u_s_e_r___i_n_f_o, the plugin should split on the ffiirrsstt + 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 + strings. user_env The user's environment in the form of a NULL-terminated vector @@ -711,24 +718,24 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) The function arguments are as follows: - buf The buffer containing user input. - len The length of _b_u_f in bytes. - log_output - int (*log_output)(const char *buf, unsigned int len); +1.8.0a1 March 19, 2010 11 -1.8.0a1 March 17, 2010 11 +SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + buf The buffer containing user input. -SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) + len The length of _b_u_f in bytes. + log_output + int (*log_output)(const char *buf, unsigned int len); The _l_o_g___o_u_t_p_u_t function is called whenever data can be read from the command but before it is written to the user's terminal. This @@ -780,13 +787,6 @@ SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m) - - - - - - - -1.8.0a1 March 17, 2010 12 +1.8.0a1 March 19, 2010 12 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index 4173e931b..8dd462c15 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@ "March 17, 2010" "1.8.0a1" "MAINTENANCE COMMANDS" +.TH SUDO_PLUGIN @mansectsu@ "March 19, 2010" "1.8.0a1" "MAINTENANCE COMMANDS" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -321,6 +321,9 @@ the \f(CW\*(C`\-t\*(C'\fR flag. .IX Item "bsdauth_type=string" Authentication type, if specified by the \f(CW\*(C`\-a\*(C'\fR flag, to use on systems where \s-1BSD\s0 authentication is supported. +.IP "progname=string" 4 +.IX Item "progname=string" +The command name that sudo was run as, typically \*(L"sudo\*(R" or \*(L"sudoedit\*(R". .RE .RS 4 .Sp diff --git a/doc/sudo_plugin.pod b/doc/sudo_plugin.pod index 2cfe58cec..8f3dbb378 100644 --- a/doc/sudo_plugin.pod +++ b/doc/sudo_plugin.pod @@ -212,6 +212,10 @@ the C<-t> flag. Authentication type, if specified by the C<-a> flag, to use on systems where BSD authentication is supported. +=item progname=string + +The command name that sudo was run as, typically "sudo" or "sudoedit". + =back Additional settings may be added in the future so the plugin should -- 2.40.0