From: Todd C. Miller Date: Tue, 5 Mar 2013 21:38:35 +0000 (-0500) Subject: Document group_file and system_group plugins. X-Git-Tag: SUDO_1_8_7~1^2~184 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7d3ce01a05115b166b278da23bb0097967e057d8;p=sudo Document group_file and system_group plugins. --- diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index ec8a97be0..193da0e8b 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -1258,9 +1258,10 @@ DDEESSCCRRIIPPTTIIOONN SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix group lookups. This can be used to query a group source other than the - standard Unix group database. A sample group plugin is bundled with ssuuddoo - that implements file-based lookups. Third party group plugins include a - QAS AD plugin available from Quest Software. + standard Unix group database. Two sample group plugins are bundled with + ssuuddoo, _g_r_o_u_p___f_i_l_e and _s_y_s_t_e_m___g_r_o_u_p, are detailed in sudoers(4). Third + party group plugins include a QAS AD plugin available from Quest + Software. A group plugin must declare and populate a sudoers_group_plugin struct in the global scope. This structure contains pointers to the functions that @@ -1411,4 +1412,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for complete details. -Sudo 1.8.7 February 24, 2013 Sudo 1.8.7 +Sudo 1.8.7 March 5, 2013 Sudo 1.8.7 diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index fb8508234..0278db655 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -16,7 +16,7 @@ .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.TH "SUDO_PLUGIN" "5" "February 24, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual" +.TH "SUDO_PLUGIN" "5" "March 5, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual" .nh .if n .ad l .SH "NAME" @@ -2279,9 +2279,13 @@ plugin supports its own plugin interface to allow non-Unix group lookups. This can be used to query a group source other than the standard Unix group database. -A sample group plugin is bundled with -\fBsudo\fR -that implements file-based lookups. +Two sample group plugins are bundled with +\fBsudo\fR, +\fIgroup_file\fR +and +\fIsystem_group\fR, +are detailed in +sudoers(@mansectform@). Third party group plugins include a QAS AD plugin available from Quest Software. .PP A group plugin must declare and populate a diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in index 9dbd89bd6..53b54b643 100644 --- a/doc/sudo_plugin.mdoc.in +++ b/doc/sudo_plugin.mdoc.in @@ -14,7 +14,7 @@ .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd February 24, 2013 +.Dd March 5, 2013 .Dt SUDO_PLUGIN @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -1968,9 +1968,13 @@ plugin supports its own plugin interface to allow non-Unix group lookups. This can be used to query a group source other than the standard Unix group database. -A sample group plugin is bundled with -.Nm sudo -that implements file-based lookups. +Two sample group plugins are bundled with +.Nm sudo , +.Em group_file +and +.Em system_group , +are detailed in +.Xr sudoers @mansectform@ . Third party group plugins include a QAS AD plugin available from Quest Software. .Pp A group plugin must declare and populate a diff --git a/doc/sudoers.cat b/doc/sudoers.cat index 0bd7e3161..01576e9ed 100644 --- a/doc/sudoers.cat +++ b/doc/sudoers.cat @@ -243,8 +243,8 @@ SSUUDDOOEERRSS FFIILLEE FFOORRMMAATT characters must be included inside the quotes. The actual nonunix_group and nonunix_gid syntax depends on the underlying - group provider plugin (see the _g_r_o_u_p___p_l_u_g_i_n description below). For - instance, the QAS AD plugin supports the following formats: + group provider plugin. For instance, the QAS AD plugin supports the + following formats: oo Group in the same domain: "%:Group Name" @@ -252,6 +252,8 @@ SSUUDDOOEERRSS FFIILLEE FFOORRMMAATT oo Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" + See _G_R_O_U_P _P_R_O_V_I_D_E_R _P_L_U_G_I_N_S for more information. + Note that quotes around group names are optional. Unquoted strings must use a backslash (`\') to escape spaces and special characters. See _O_t_h_e_r _s_p_e_c_i_a_l _c_h_a_r_a_c_t_e_r_s _a_n_d _r_e_s_e_r_v_e_d _w_o_r_d_s for a list of characters that need @@ -332,8 +334,8 @@ SSUUDDOOEERRSS FFIILLEE FFOORRMMAATT arguments: `,', `:', `=', `\'. The built-in command ``sudoedit'' is used to permit a user to run ssuuddoo with the --ee option (or as ssuuddooeeddiitt). It may take command line arguments just as a normal command does. Note that - ``sudoedit'' is a command built-in to ssuuddoo itself and must be specified - in _s_u_d_o_e_r_s without a leading path. + ``sudoedit'' is a command built into ssuuddoo itself and must be specified in + _s_u_d_o_e_r_s without a leading path. DDeeffaauullttss Certain configuration options may be changed from their default values at @@ -1417,21 +1419,15 @@ SSUUDDOOEERRSS OOPPTTIIOONNSS a % prefix. This is not set by default. group_plugin A string containing a _s_u_d_o_e_r_s group plugin with optional - arguments. This can be used to implement support for the - nonunix_group syntax described earlier. The string should - consist of the plugin path, either fully-qualified or - relative to the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o directory, followed - by any configuration arguments the plugin requires. These + arguments. The string should consist of the plugin path, + either fully-qualified or relative to the + _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o directory, followed by any + configuration arguments the plugin requires. These arguments (if any) will be passed to the plugin's initialization function. If arguments are present, the string must be enclosed in double quotes (""). - For example, given _/_e_t_c_/_s_u_d_o_-_g_r_o_u_p, a group file in Unix - group format, the sample group plugin can be used: - - Defaults group_plugin="group_file.so /etc/sudo-group" - - For more information see sudo_plugin(4). + For more information see GROUP PROVIDER PLUGINS. lecture This option controls when a short lecture will be printed along with the password prompt. It has the following @@ -1568,6 +1564,41 @@ SSUUDDOOEERRSS OOPPTTIIOONNSS variables to keep is displayed when ssuuddoo is run by root with the --VV option. +GGRROOUUPP PPRROOVVIIDDEERR PPLLUUGGIINNSS + The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix + group lookups which can query a group source other than the standard Unix + group database. This can be used to implement support for the + nonunix_group syntax described earlier. + + Group provider plugins are specified via the _g_r_o_u_p___p_l_u_g_i_n Defaults + setting. The argument to _g_r_o_u_p___p_l_u_g_i_n should consist of the plugin path, + either fully-qualified or relative to the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c_/_s_u_d_o + directory, followed by any configuration options the plugin requires. + These options (if specified) will be passed to the plugin's + initialization function. If options are present, the string must be + enclosed in double quotes (""). + + The following group provider plugins are installed by default: + + group_file + The _g_r_o_u_p___f_i_l_e plugin supports an alternate group file that + uses the same syntax as the _/_e_t_c_/_g_r_o_u_p file. The path to the + group file should be specified as an option to the plugin. For + example, if the group file to be used is _/_e_t_c_/_s_u_d_o_-_g_r_o_u_p: + + Defaults group_plugin="group_file.so /etc/sudo-group" + + system_group + The _s_y_s_t_e_m___g_r_o_u_p plugin supports group lookups via the standard + C library functions ggeettggrrnnaamm() and ggeettggrriidd(). This plugin can + be used in instances where the user belongs to groups not + present in the user's supplemental group vector. This plugin + takes no options: + + Defaults group_plugin=system_group.so + + The group provider plugin API is described in detail in sudo_plugin(1m). + LLOOGG FFOORRMMAATT ssuuddooeerrss can log events using either syslog(3) or a simple log file. In each case the log format is almost identical. diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in index bf6d55d8e..2561506ef 100644 --- a/doc/sudoers.man.in +++ b/doc/sudoers.man.in @@ -571,9 +571,7 @@ The actual and \fRnonunix_gid\fR syntax depends on -the underlying group provider plugin (see the -\fIgroup_plugin\fR -description below). +the underlying group provider plugin. For instance, the QAS AD plugin supports the following formats: .TP 6n \fBo\fR @@ -585,6 +583,10 @@ Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" \fBo\fR Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" .PP +See +\fIGROUP PROVIDER PLUGINS\fR +for more information. +.PP Note that quotes around group names are optional. Unquoted strings must use a backslash (`\e') @@ -741,7 +743,7 @@ option (or as It may take command line arguments just as a normal command does. Note that ``\fRsudoedit\fR'' -is a command built-in to +is a command built into \fBsudo\fR itself and must be specified in \fIsudoers\fR @@ -2942,9 +2944,6 @@ group_plugin A string containing a \fIsudoers\fR group plugin with optional arguments. -This can be used to implement support for the -\fRnonunix_group\fR -syntax described earlier. The string should consist of the plugin path, either fully-qualified or relative to the \fI@PLUGINDIR@\fR @@ -2953,29 +2952,14 @@ These arguments (if any) will be passed to the plugin's initialization function. If arguments are present, the string must be enclosed in double quotes (\&""). .sp -For example, given -\fI/etc/sudo-group\fR, -a group file in Unix group format, the sample group plugin can be used: -.RS -.nf -.sp -.RS 0n -Defaults group_plugin="group_file.so /etc/sudo-group" -.RE -.fi -.sp For more information see -sudo_plugin(@mansectform@). -.PP -.RE -.PD 0 +GROUP PROVIDER PLUGINS. .TP 14n lecture This option controls when a short lecture will be printed along with the password prompt. It has the following possible values: .RS -.PD .TP 8n always Always lecture the user. @@ -3263,6 +3247,74 @@ is displayed when is run by root with the \fB\-V\fR option. +.SH "GROUP PROVIDER PLUGINS" +The +\fBsudoers\fR +plugin supports its own plugin interface to allow non-Unix +group lookups which can query a group source other +than the standard Unix group database. +This can be used to implement support for the +\fRnonunix_group\fR +syntax described earlier. +.PP +Group provider plugins are specified via the +\fIgroup_plugin\fR +Defaults setting. +The argument to +\fIgroup_plugin\fR +should consist of the plugin path, either fully-qualified or relative to the +\fI@PLUGINDIR@\fR +directory, followed by any configuration options the plugin requires. +These options (if specified) will be passed to the plugin's initialization +function. +If options are present, the string must be enclosed in double quotes +(\&""). +.PP +The following group provider plugins are installed by default: +.TP 10n +group_file +The +\fIgroup_file\fR +plugin supports an alternate group file that uses the same syntax as the +\fI/etc/group\fR +file. +The path to the group file should be specified as an option +to the plugin. +For example, if the group file to be used is +\fI/etc/sudo-group\fR: +.RS +.nf +.sp +.RS 0n +Defaults group_plugin="group_file.so /etc/sudo-group" +.RE +.fi +.PP +.RE +.PD 0 +.TP 10n +system_group +The +\fIsystem_group\fR +plugin supports group lookups via the standard C library functions +\fBgetgrnam\fR() +and +\fBgetgrid\fR(). +This plugin can be used in instances where the user belongs to +groups not present in the user's supplemental group vector. +This plugin takes no options: +.RS +.nf +.sp +.RS 0n +Defaults group_plugin=system_group.so +.RE +.fi +.RE +.PD +.PP +The group provider plugin API is described in detail in +sudo_plugin(@mansectsu@). .SH "LOG FORMAT" \fBsudoers\fR can log events using either diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in index 452b26c7f..06a788f93 100644 --- a/doc/sudoers.mdoc.in +++ b/doc/sudoers.mdoc.in @@ -549,9 +549,7 @@ The actual and .Li nonunix_gid syntax depends on -the underlying group provider plugin (see the -.Em group_plugin -description below). +the underlying group provider plugin. For instance, the QAS AD plugin supports the following formats: .Bl -bullet -width 4n .It @@ -562,6 +560,10 @@ Group in any domain: "%:Group Name@FULLY.QUALIFIED.DOMAIN" Group SID: "%:S-1-2-34-5678901234-5678901234-5678901234-567" .El .Pp +See +.Sx "GROUP PROVIDER PLUGINS" +for more information. +.Pp Note that quotes around group names are optional. Unquoted strings must use a backslash .Pq Ql \e @@ -709,7 +711,7 @@ option (or as It may take command line arguments just as a normal command does. Note that .Dq Li sudoedit -is a command built-in to +is a command built into .Nm sudo itself and must be specified in .Em sudoers @@ -2741,9 +2743,6 @@ This is not set by default. A string containing a .Em sudoers group plugin with optional arguments. -This can be used to implement support for the -.Li nonunix_group -syntax described earlier. The string should consist of the plugin path, either fully-qualified or relative to the .Pa @PLUGINDIR@ @@ -2752,15 +2751,8 @@ These arguments (if any) will be passed to the plugin's initialization function. If arguments are present, the string must be enclosed in double quotes .Pq \&"" . .Pp -For example, given -.Pa /etc/sudo-group , -a group file in Unix group format, the sample group plugin can be used: -.Bd -literal -Defaults group_plugin="group_file.so /etc/sudo-group" -.Ed -.Pp For more information see -.Xr sudo_plugin @mansectform@ . +.Xr "GROUP PROVIDER PLUGINS" . .It lecture This option controls when a short lecture will be printed along with the password prompt. @@ -3026,6 +3018,61 @@ is run by root with the .Fl V option. .El +.Sh GROUP PROVIDER PLUGINS +The +.Nm sudoers +plugin supports its own plugin interface to allow non-Unix +group lookups which can query a group source other +than the standard Unix group database. +This can be used to implement support for the +.Li nonunix_group +syntax described earlier. +.Pp +Group provider plugins are specified via the +.Em group_plugin +Defaults setting. +The argument to +.Em group_plugin +should consist of the plugin path, either fully-qualified or relative to the +.Pa @PLUGINDIR@ +directory, followed by any configuration options the plugin requires. +These options (if specified) will be passed to the plugin's initialization +function. +If options are present, the string must be enclosed in double quotes +.Pq \&"" . +.Pp +The following group provider plugins are installed by default: +.Bl -tag -width 8n +.It group_file +The +.Em group_file +plugin supports an alternate group file that uses the same syntax as the +.Pa /etc/group +file. +The path to the group file should be specified as an option +to the plugin. +For example, if the group file to be used is +.Pa /etc/sudo-group : +.Bd -literal +Defaults group_plugin="group_file.so /etc/sudo-group" +.Ed +.It system_group +The +.Em system_group +plugin supports group lookups via the standard C library functions +.Fn getgrnam +and +.Fn getgrid . +This plugin can be used in instances where the user belongs to +groups not present in the user's supplemental group vector. +This plugin takes no options: +.Bd -literal +Defaults group_plugin=system_group.so +.Ed +.El +.Pp +The group provider plugin API is described in detail in +.Xr sudo_plugin @mansectsu@ . .Sh LOG FORMAT .Nm sudoers can log events using either