Annotation of embedaddon/sudo/doc/sudo_plugin.man.in, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2009-2011 Todd C. Miller <Todd.Miller@courtesan.com>
2: .\"
3: .\" Permission to use, copy, modify, and distribute this software for any
4: .\" purpose with or without fee is hereby granted, provided that the above
5: .\" copyright notice and this permission notice appear in all copies.
6: .\"
7: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
15: .\"
16: .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
17: .\"
18: .\" Standard preamble:
19: .\" ========================================================================
20: .de Sp \" Vertical space (when we can't use .PP)
21: .if t .sp .5v
22: .if n .sp
23: ..
24: .de Vb \" Begin verbatim text
25: .ft CW
26: .nf
27: .ne \\$1
28: ..
29: .de Ve \" End verbatim text
30: .ft R
31: .fi
32: ..
33: .\" Set up some character translations and predefined strings. \*(-- will
34: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
35: .\" double quote, and \*(R" will give a right double quote. \*(C+ will
36: .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
37: .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
38: .\" nothing in troff, for use with C<>.
39: .tr \(*W-
40: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
41: .ie n \{\
42: . ds -- \(*W-
43: . ds PI pi
44: . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45: . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46: . ds L" ""
47: . ds R" ""
48: . ds C`
49: . ds C'
50: 'br\}
51: .el\{\
52: . ds -- \|\(em\|
53: . ds PI \(*p
54: . ds L" ``
55: . ds R" ''
56: 'br\}
57: .\"
58: .\" Escape single quotes in literal strings from groff's Unicode transform.
59: .ie \n(.g .ds Aq \(aq
60: .el .ds Aq '
61: .\"
62: .\" If the F register is turned on, we'll generate index entries on stderr for
63: .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
64: .\" entries marked with X<> in POD. Of course, you'll have to process the
65: .\" output yourself in some meaningful fashion.
66: .ie \nF \{\
67: . de IX
68: . tm Index:\\$1\t\\n%\t"\\$2"
69: ..
70: . nr % 0
71: . rr F
72: .\}
73: .el \{\
74: . de IX
75: ..
76: .\}
77: .\"
78: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
79: .\" Fear. Run. Save yourself. No user-serviceable parts.
80: . \" fudge factors for nroff and troff
81: .if n \{\
82: . ds #H 0
83: . ds #V .8m
84: . ds #F .3m
85: . ds #[ \f1
86: . ds #] \fP
87: .\}
88: .if t \{\
89: . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
90: . ds #V .6m
91: . ds #F 0
92: . ds #[ \&
93: . ds #] \&
94: .\}
95: . \" simple accents for nroff and troff
96: .if n \{\
97: . ds ' \&
98: . ds ` \&
99: . ds ^ \&
100: . ds , \&
101: . ds ~ ~
102: . ds /
103: .\}
104: .if t \{\
105: . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
106: . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
107: . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
108: . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
109: . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
110: . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
111: .\}
112: . \" troff and (daisy-wheel) nroff accents
113: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
114: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
115: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
116: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
117: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
118: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
119: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
120: .ds ae a\h'-(\w'a'u*4/10)'e
121: .ds Ae A\h'-(\w'A'u*4/10)'E
122: . \" corrections for vroff
123: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
124: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
125: . \" for low resolution devices (crt and lpr)
126: .if \n(.H>23 .if \n(.V>19 \
127: \{\
128: . ds : e
129: . ds 8 ss
130: . ds o a
131: . ds d- d\h'-1'\(ga
132: . ds D- D\h'-1'\(hy
133: . ds th \o'bp'
134: . ds Th \o'LP'
135: . ds ae ae
136: . ds Ae AE
137: .\}
138: .rm #[ #] #H #V #F C
139: .\" ========================================================================
140: .\"
141: .IX Title "SUDO_PLUGIN @mansectsu@"
142: .TH SUDO_PLUGIN @mansectsu@ "September 16, 2011" "1.8.3" "MAINTENANCE COMMANDS"
143: .\" For nroff, turn off justification. Always turn off hyphenation; it makes
144: .\" way too many mistakes in technical documents.
145: .if n .ad l
146: .nh
147: .SH "NAME"
148: sudo_plugin \- Sudo Plugin API
149: .SH "DESCRIPTION"
150: .IX Header "DESCRIPTION"
151: Starting with version 1.8, \fBsudo\fR supports a plugin \s-1API\s0
152: for policy and session logging. By default, the \fIsudoers\fR policy
153: plugin and an associated I/O logging plugin are used. Via the plugin
154: \&\s-1API\s0, \fBsudo\fR can be configured to use alternate policy and/or I/O
155: logging plugins provided by third parties. The plugins to be used
156: are specified via the \fI@sysconfdir@/sudo.conf\fR file.
157: .PP
158: The \s-1API\s0 is versioned with a major and minor number. The minor
159: version number is incremented when additions are made. The major
160: number is incremented when incompatible changes are made. A plugin
161: should be check the version passed to it and make sure that the
162: major version matches.
163: .PP
164: The plugin \s-1API\s0 is defined by the \f(CW\*(C`sudo_plugin.h\*(C'\fR header file.
165: .SS "The sudo.conf File"
166: .IX Subsection "The sudo.conf File"
167: The \fI@sysconfdir@/sudo.conf\fR file contains plugin configuration directives.
168: Currently, the only supported keyword is the \f(CW\*(C`Plugin\*(C'\fR directive,
169: which causes a plugin plugin to be loaded.
170: .PP
171: A \f(CW\*(C`Plugin\*(C'\fR line consists of the \f(CW\*(C`Plugin\*(C'\fR keyword, followed by the
172: \&\fIsymbol_name\fR and the \fIpath\fR to the shared object containing the
173: plugin. The \fIsymbol_name\fR is the name of the \f(CW\*(C`struct policy_plugin\*(C'\fR
174: or \f(CW\*(C`struct io_plugin\*(C'\fR in the plugin shared object. The \fIpath\fR
175: may be fully qualified or relative. If not fully qualified it is
176: relative to the \fI@prefix@/libexec\fR directory. Any additional
177: parameters after the \fIpath\fR are ignored. Lines that don't begin
178: with \f(CW\*(C`Plugin\*(C'\fR or \f(CW\*(C`Path\*(C'\fR are silently ignored.
179: .PP
180: The same shared object may contain multiple plugins, each with a
181: different symbol name. The shared object file must be owned by uid
182: 0 and only writable by its owner. Because of ambiguities that arise
183: from composite policies, only a single policy plugin may be specified.
184: This limitation does not apply to I/O plugins.
185: .PP
186: .Vb 10
187: \& #
188: \& # Default @sysconfdir@/sudo.conf file
189: \& #
190: \& # Format:
191: \& # Plugin plugin_name plugin_path
192: \& # Path askpass /path/to/askpass
193: \& #
194: \& # The plugin_path is relative to @prefix@/libexec unless
195: \& # fully qualified.
196: \& # The plugin_name corresponds to a global symbol in the plugin
197: \& # that contains the plugin interface structure.
198: \& #
199: \& Plugin sudoers_policy sudoers.so
200: \& Plugin sudoers_io sudoers.so
201: .Ve
202: .SS "Policy Plugin \s-1API\s0"
203: .IX Subsection "Policy Plugin API"
204: A policy plugin must declare and populate a \f(CW\*(C`policy_plugin\*(C'\fR struct
205: in the global scope. This structure contains pointers to the functions
206: that implement the \fBsudo\fR policy checks. The name of the symbol should
207: be specified in \fI@sysconfdir@/sudo.conf\fR along with a path to the plugin
208: so that \fBsudo\fR can load it.
209: .PP
210: .Vb 10
211: \& struct policy_plugin {
212: \& #define SUDO_POLICY_PLUGIN 1
213: \& unsigned int type; /* always SUDO_POLICY_PLUGIN */
214: \& unsigned int version; /* always SUDO_API_VERSION */
215: \& int (*open)(unsigned int version, sudo_conv_t conversation,
216: \& sudo_printf_t plugin_printf, char * const settings[],
217: \& char * const user_info[], char * const user_env[]);
218: \& void (*close)(int exit_status, int error);
219: \& int (*show_version)(int verbose);
220: \& int (*check_policy)(int argc, char * const argv[],
221: \& char *env_add[], char **command_info[],
222: \& char **argv_out[], char **user_env_out[]);
223: \& int (*list)(int argc, char * const argv[], int verbose,
224: \& const char *list_user);
225: \& int (*validate)(void);
226: \& void (*invalidate)(int remove);
227: \& int (*init_session)(struct passwd *pwd);
228: \& };
229: .Ve
230: .PP
231: The policy_plugin struct has the following fields:
232: .IP "type" 4
233: .IX Item "type"
234: The \f(CW\*(C`type\*(C'\fR field should always be set to \s-1SUDO_POLICY_PLUGIN\s0.
235: .IP "version" 4
236: .IX Item "version"
237: The \f(CW\*(C`version\*(C'\fR field should be set to \s-1SUDO_API_VERSION\s0.
238: .Sp
239: This allows \fBsudo\fR to determine the \s-1API\s0 version the plugin was
240: built against.
241: .IP "open" 4
242: .IX Item "open"
243: .Vb 3
244: \& int (*open)(unsigned int version, sudo_conv_t conversation,
245: \& sudo_printf_t plugin_printf, char * const settings[],
246: \& char * const user_info[], char * const user_env[]);
247: .Ve
248: .Sp
249: Returns 1 on success, 0 on failure, \-1 if a general error occurred,
250: or \-2 if there was a usage error. In the latter case, \fBsudo\fR will
251: print a usage message before it exits. If an error occurs, the
252: plugin may optionally call the conversation or plugin_printf function
253: with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional error information
254: to the user.
255: .Sp
256: The function arguments are as follows:
257: .RS 4
258: .IP "version" 4
259: .IX Item "version"
260: The version passed in by \fBsudo\fR allows the plugin to determine the
261: major and minor version number of the plugin \s-1API\s0 supported by
262: \&\fBsudo\fR.
263: .IP "conversation" 4
264: .IX Item "conversation"
265: A pointer to the conversation function that can be used by the
266: plugin to interact with the user (see below).
267: Returns 0 on success and \-1 on failure.
268: .IP "plugin_printf" 4
269: .IX Item "plugin_printf"
270: A pointer to a printf-style function that may be used to display
271: informational or error messages (see below).
272: Returns the number of characters printed on success and \-1 on failure.
273: .IP "settings" 4
274: .IX Item "settings"
275: A vector of user-supplied \fBsudo\fR settings in the form of \*(L"name=value\*(R"
276: strings. The vector is terminated by a \f(CW\*(C`NULL\*(C'\fR pointer. These
277: settings correspond to flags the user specified when running \fBsudo\fR.
278: As such, they will only be present when the corresponding flag has
279: been specified on the command line.
280: .Sp
281: When parsing \fIsettings\fR, the plugin should split on the \fBfirst\fR
282: equal sign ('=') since the \fIname\fR field will never include one
283: itself but the \fIvalue\fR might.
284: .RS 4
285: .IP "debug_level=number" 4
286: .IX Item "debug_level=number"
287: A numeric debug level, from 1\-9, if specified via the \f(CW\*(C`\-D\*(C'\fR flag.
288: .IP "runas_user=string" 4
289: .IX Item "runas_user=string"
290: The user name or uid to to run the command as, if specified via the
291: \&\f(CW\*(C`\-u\*(C'\fR flag.
292: .IP "runas_group=string" 4
293: .IX Item "runas_group=string"
294: The group name or gid to to run the command as, if specified via
295: the \f(CW\*(C`\-g\*(C'\fR flag.
296: .IP "prompt=string" 4
297: .IX Item "prompt=string"
298: The prompt to use when requesting a password, if specified via
299: the \f(CW\*(C`\-p\*(C'\fR flag.
300: .IP "set_home=bool" 4
301: .IX Item "set_home=bool"
302: Set to true if the user specified the \f(CW\*(C`\-H\*(C'\fR flag. If true, set the
303: \&\f(CW\*(C`HOME\*(C'\fR environment variable to the target user's home directory.
304: .IP "preserve_environment=bool" 4
305: .IX Item "preserve_environment=bool"
306: Set to true if the user specified the \f(CW\*(C`\-E\*(C'\fR flag, indicating that
307: the user wishes to preserve the environment.
308: .IP "run_shell=bool" 4
309: .IX Item "run_shell=bool"
310: Set to true if the user specified the \f(CW\*(C`\-s\*(C'\fR flag, indicating that
311: the user wishes to run a shell.
312: .IP "login_shell=bool" 4
313: .IX Item "login_shell=bool"
314: Set to true if the user specified the \f(CW\*(C`\-i\*(C'\fR flag, indicating that
315: the user wishes to run a login shell.
316: .IP "implied_shell=bool" 4
317: .IX Item "implied_shell=bool"
318: If the user does not specify a program on the command line, \fBsudo\fR
319: will pass the plugin the path to the user's shell and set
320: \&\fIimplied_shell\fR to true. This allows \fBsudo\fR with no arguments
321: to be used similarly to \fIsu\fR\|(1). If the plugin does not to support
322: this usage, it may return a value of \-2 from the \f(CW\*(C`check_policy\*(C'\fR
323: function, which will cause \fBsudo\fR to print a usage message and
324: exit.
325: .IP "preserve_groups=bool" 4
326: .IX Item "preserve_groups=bool"
327: Set to true if the user specified the \f(CW\*(C`\-P\*(C'\fR flag, indicating that
328: the user wishes to preserve the group vector instead of setting it
329: based on the runas user.
330: .IP "ignore_ticket=bool" 4
331: .IX Item "ignore_ticket=bool"
332: Set to true if the user specified the \f(CW\*(C`\-k\*(C'\fR flag along with a
333: command, indicating that the user wishes to ignore any cached
334: authentication credentials.
335: .IP "noninteractive=bool" 4
336: .IX Item "noninteractive=bool"
337: Set to true if the user specified the \f(CW\*(C`\-n\*(C'\fR flag, indicating that
338: \&\fBsudo\fR should operate in non-interactive mode. The plugin may
339: reject a command run in non-interactive mode if user interaction
340: is required.
341: .IP "login_class=string" 4
342: .IX Item "login_class=string"
343: \&\s-1BSD\s0 login class to use when setting resource limits and nice value,
344: if specified by the \f(CW\*(C`\-c\*(C'\fR flag.
345: .IP "selinux_role=string" 4
346: .IX Item "selinux_role=string"
347: SELinux role to use when executing the command, if specified by
348: the \f(CW\*(C`\-r\*(C'\fR flag.
349: .IP "selinux_type=string" 4
350: .IX Item "selinux_type=string"
351: SELinux type to use when executing the command, if specified by
352: the \f(CW\*(C`\-t\*(C'\fR flag.
353: .IP "bsdauth_type=string" 4
354: .IX Item "bsdauth_type=string"
355: Authentication type, if specified by the \f(CW\*(C`\-a\*(C'\fR flag, to use on
356: systems where \s-1BSD\s0 authentication is supported.
357: .IP "network_addrs=list" 4
358: .IX Item "network_addrs=list"
359: A space-separated list of \s-1IP\s0 network addresses and netmasks in the
360: form \*(L"addr/netmask\*(R", e.g. \*(L"192.168.1.2/255.255.255.0\*(R". The address
361: and netmask pairs may be either IPv4 or IPv6, depending on what the
362: operating system supports. If the address contains a colon (':'),
363: it is an IPv6 address, else it is IPv4.
364: .IP "progname=string" 4
365: .IX Item "progname=string"
366: The command name that sudo was run as, typically \*(L"sudo\*(R" or \*(L"sudoedit\*(R".
367: .IP "sudoedit=bool" 4
368: .IX Item "sudoedit=bool"
369: Set to true when the \f(CW\*(C`\-e\*(C'\fR flag is is specified or if invoked as
370: \&\fBsudoedit\fR. The plugin shall substitute an editor into \fIargv\fR
371: in the \fIcheck_policy\fR function or return \f(CW\*(C`\-2\*(C'\fR with a usage error
372: if the plugin does not support \fIsudoedit\fR. For more information,
373: see the \fIcheck_policy\fR section.
374: .IP "closefrom=number" 4
375: .IX Item "closefrom=number"
376: If specified, the user has requested via the \f(CW\*(C`\-C\*(C'\fR flag that \fBsudo\fR
377: close all files descriptors with a value of \fInumber\fR or higher.
378: The plugin may optionally pass this, or another value, back in the
379: \&\fIcommand_info\fR list.
380: .RE
381: .RS 4
382: .Sp
383: Additional settings may be added in the future so the plugin should
384: silently ignore settings that it does not recognize.
385: .RE
386: .IP "user_info" 4
387: .IX Item "user_info"
388: A vector of information about the user running the command in the form of
389: \&\*(L"name=value\*(R" strings. The vector is terminated by a \f(CW\*(C`NULL\*(C'\fR pointer.
390: .Sp
391: When parsing \fIuser_info\fR, the plugin should split on the \fBfirst\fR
392: equal sign ('=') since the \fIname\fR field will never include one
393: itself but the \fIvalue\fR might.
394: .RS 4
395: .IP "user=string" 4
396: .IX Item "user=string"
397: The name of the user invoking \fBsudo\fR.
398: .IP "uid=uid_t" 4
399: .IX Item "uid=uid_t"
400: The real user \s-1ID\s0 of the user invoking \fBsudo\fR.
401: .IP "gid=gid_t" 4
402: .IX Item "gid=gid_t"
403: The real group \s-1ID\s0 of the user invoking \fBsudo\fR.
404: .IP "groups=list" 4
405: .IX Item "groups=list"
406: The user's supplementary group list formatted as a string of
407: comma-separated group IDs.
408: .IP "cwd=string" 4
409: .IX Item "cwd=string"
410: The user's current working directory.
411: .IP "tty=string" 4
412: .IX Item "tty=string"
413: The path to the user's terminal device. If the user has no terminal
414: device associated with the session, the value will be empty, as in
415: \&\f(CW\*(C`tty=\*(C'\fR.
416: .IP "host=string" 4
417: .IX Item "host=string"
418: The local machine's hostname as returned by the \f(CW\*(C`gethostname()\*(C'\fR
419: system call.
420: .IP "lines=int" 4
421: .IX Item "lines=int"
422: The number of lines the user's terminal supports. If there is
423: no terminal device available, a default value of 24 is used.
424: .IP "cols=int" 4
425: .IX Item "cols=int"
426: The number of columns the user's terminal supports. If there is
427: no terminal device available, a default value of 80 is used.
428: .RE
429: .RS 4
430: .RE
431: .IP "user_env" 4
432: .IX Item "user_env"
433: The user's environment in the form of a \f(CW\*(C`NULL\*(C'\fR\-terminated vector of
434: \&\*(L"name=value\*(R" strings.
435: .Sp
436: When parsing \fIuser_env\fR, the plugin should split on the \fBfirst\fR
437: equal sign ('=') since the \fIname\fR field will never include one
438: itself but the \fIvalue\fR might.
439: .RE
440: .RS 4
441: .RE
442: .IP "close" 4
443: .IX Item "close"
444: .Vb 1
445: \& void (*close)(int exit_status, int error);
446: .Ve
447: .Sp
448: The \f(CW\*(C`close\*(C'\fR function is called when the command being run by \fBsudo\fR
449: finishes.
450: .Sp
451: The function arguments are as follows:
452: .RS 4
453: .IP "exit_status" 4
454: .IX Item "exit_status"
455: The command's exit status, as returned by the \fIwait\fR\|(2) system call.
456: The value of \f(CW\*(C`exit_status\*(C'\fR is undefined if \f(CW\*(C`error\*(C'\fR is non-zero.
457: .IP "error" 4
458: .IX Item "error"
459: If the command could not be executed, this is set to the value of
460: \&\f(CW\*(C`errno\*(C'\fR set by the \fIexecve\fR\|(2) system call. The plugin is responsible
461: for displaying error information via the conversation or plugin_printf
462: function. If the command was successfully executed, the value of
463: \&\f(CW\*(C`error\*(C'\fR is 0.
464: .RE
465: .RS 4
466: .RE
467: .IP "show_version" 4
468: .IX Item "show_version"
469: .Vb 1
470: \& int (*show_version)(int verbose);
471: .Ve
472: .Sp
473: The \f(CW\*(C`show_version\*(C'\fR function is called by \fBsudo\fR when the user specifies
474: the \f(CW\*(C`\-V\*(C'\fR option. The plugin may display its version information
475: to the user via the conversation or plugin_printf function using
476: \&\f(CW\*(C`SUDO_CONV_INFO_MSG\*(C'\fR. If the user requests detailed version
477: information, the verbose flag will be set.
478: .IP "check_policy" 4
479: .IX Item "check_policy"
480: .Vb 3
481: \& int (*check_policy)(int argc, char * const argv[]
482: \& char *env_add[], char **command_info[],
483: \& char **argv_out[], char **user_env_out[]);
484: .Ve
485: .Sp
486: The \fIcheck_policy\fR function is called by \fBsudo\fR to determine
487: whether the user is allowed to run the specified commands.
488: .Sp
489: If the \fIsudoedit\fR option was enabled in the \fIsettings\fR array
490: passed to the \fIopen\fR function, the user has requested \fIsudoedit\fR
491: mode. \fIsudoedit\fR is a mechanism for editing one or more files
492: where an editor is run with the user's credentials instead of with
493: elevated privileges. \fBsudo\fR achieves this by creating user-writable
494: temporary copies of the files to be edited and then overwriting the
495: originals with the temporary copies after editing is complete. If
496: the plugin supports \fBsudoedit\fR, it should choose the editor to be
497: used, potentially from a variable in the user's environment, such
498: as \f(CW\*(C`EDITOR\*(C'\fR, and include it in \fIargv_out\fR (note that environment
499: variables may include command line flags). The files to be edited
500: should be copied from \fIargv\fR into \fIargv_out\fR, separated from the
501: editor and its arguments by a \f(CW"\-\-"\fR element. The \f(CW"\-\-"\fR will
502: be removed by \fBsudo\fR before the editor is executed. The plugin
503: should also set \fIsudoedit=true\fR in the \fIcommand_info\fR list.
504: .Sp
505: The \fIcheck_policy\fR function returns 1 if the command is allowed,
506: 0 if not allowed, \-1 for a general error, or \-2 for a usage error
507: or if \fBsudoedit\fR was specified but is unsupported by the plugin.
508: In the latter case, \fBsudo\fR will print a usage message before it
509: exits. If an error occurs, the plugin may optionally call the
510: conversation or plugin_printf function with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR
511: to present additional error information to the user.
512: .Sp
513: The function arguments are as follows:
514: .RS 4
515: .IP "argc" 4
516: .IX Item "argc"
517: The number of elements in \fIargv\fR, not counting the final \f(CW\*(C`NULL\*(C'\fR
518: pointer.
519: .IP "argv" 4
520: .IX Item "argv"
521: The argument vector describing the command the user wishes to run,
522: in the same form as what would be passed to the \fIexecve()\fR system
523: call. The vector is terminated by a \f(CW\*(C`NULL\*(C'\fR pointer.
524: .IP "env_add" 4
525: .IX Item "env_add"
526: Additional environment variables specified by the user on the command
527: line in the form of a \f(CW\*(C`NULL\*(C'\fR\-terminated vector of \*(L"name=value\*(R"
528: strings. The plugin may reject the command if one or more variables
529: are not allowed to be set, or it may silently ignore such variables.
530: .Sp
531: When parsing \fIenv_add\fR, the plugin should split on the \fBfirst\fR
532: equal sign ('=') since the \fIname\fR field will never include one
533: itself but the \fIvalue\fR might.
534: .IP "command_info" 4
535: .IX Item "command_info"
536: Information about the command being run in the form of \*(L"name=value\*(R"
537: strings. These values are used by \fBsudo\fR to set the execution
538: environment when running a command. The plugin is responsible for
539: creating and populating the vector, which must be terminated with
540: a \f(CW\*(C`NULL\*(C'\fR pointer. The following values are recognized by \fBsudo\fR:
541: .RS 4
542: .IP "command=string" 4
543: .IX Item "command=string"
544: Fully qualified path to the command to be executed.
545: .IP "runas_uid=uid" 4
546: .IX Item "runas_uid=uid"
547: User \s-1ID\s0 to run the command as.
548: .IP "runas_euid=uid" 4
549: .IX Item "runas_euid=uid"
550: Effective user \s-1ID\s0 to run the command as.
551: If not specified, the value of \fIrunas_uid\fR is used.
552: .IP "runas_gid=gid" 4
553: .IX Item "runas_gid=gid"
554: Group \s-1ID\s0 to run the command as.
555: .IP "runas_egid=gid" 4
556: .IX Item "runas_egid=gid"
557: Effective group \s-1ID\s0 to run the command as.
558: If not specified, the value of \fIrunas_gid\fR is used.
559: .IP "runas_groups=list" 4
560: .IX Item "runas_groups=list"
561: The supplementary group vector to use for the command in the form
562: of a comma-separated list of group IDs. If \fIpreserve_groups\fR
563: is set, this option is ignored.
564: .IP "login_class=string" 4
565: .IX Item "login_class=string"
566: \&\s-1BSD\s0 login class to use when setting resource limits and nice value
567: (optional). This option is only set on systems that support login
568: classes.
569: .IP "preserve_groups=bool" 4
570: .IX Item "preserve_groups=bool"
571: If set, \fBsudo\fR will preserve the user's group vector instead of
572: initializing the group vector based on \f(CW\*(C`runas_user\*(C'\fR.
573: .IP "cwd=string" 4
574: .IX Item "cwd=string"
575: The current working directory to change to when executing the command.
576: .IP "noexec=bool" 4
577: .IX Item "noexec=bool"
578: If set, prevent the command from executing other programs.
579: .IP "chroot=string" 4
580: .IX Item "chroot=string"
581: The root directory to use when running the command.
582: .IP "nice=int" 4
583: .IX Item "nice=int"
584: Nice value (priority) to use when executing the command. The nice
585: value, if specified, overrides the priority associated with the
586: \&\fIlogin_class\fR on \s-1BSD\s0 systems.
587: .IP "umask=octal" 4
588: .IX Item "umask=octal"
589: The file creation mask to use when executing the command.
590: .IP "selinux_role=string" 4
591: .IX Item "selinux_role=string"
592: SELinux role to use when executing the command.
593: .IP "selinux_type=string" 4
594: .IX Item "selinux_type=string"
595: SELinux type to use when executing the command.
596: .IP "timeout=int" 4
597: .IX Item "timeout=int"
598: Command timeout. If non-zero then when the timeout expires the
599: command will be killed.
600: .IP "sudoedit=bool" 4
601: .IX Item "sudoedit=bool"
602: Set to true when in \fIsudoedit\fR mode. The plugin may enable
603: \&\fIsudoedit\fR mode even if \fBsudo\fR was not invoked as \fBsudoedit\fR.
604: This allows the plugin to perform command substitution and transparently
605: enable \fIsudoedit\fR when the user attempts to run an editor.
606: .IP "closefrom=number" 4
607: .IX Item "closefrom=number"
608: If specified, \fBsudo\fR will close all files descriptors with a value
609: of \fInumber\fR or higher.
610: .IP "iolog_compress=bool" 4
611: .IX Item "iolog_compress=bool"
612: Set to true if the I/O logging plugins, if any, should compress the
613: log data. This is a hint to the I/O logging plugin which may choose
614: to ignore it.
615: .IP "iolog_path=string" 4
616: .IX Item "iolog_path=string"
617: Fully qualified path to the file or directory in which I/O log is
618: to be stored. This is a hint to the I/O logging plugin which may
619: choose to ignore it. If no I/O logging plugin is loaded, this
620: setting has no effect.
621: .IP "iolog_stdin=bool" 4
622: .IX Item "iolog_stdin=bool"
623: Set to true if the I/O logging plugins, if any, should log the
624: standard input if it is not connected to a terminal device. This
625: is a hint to the I/O logging plugin which may choose to ignore it.
626: .IP "iolog_stdout=bool" 4
627: .IX Item "iolog_stdout=bool"
628: Set to true if the I/O logging plugins, if any, should log the
629: standard output if it is not connected to a terminal device. This
630: is a hint to the I/O logging plugin which may choose to ignore it.
631: .IP "iolog_stderr=bool" 4
632: .IX Item "iolog_stderr=bool"
633: Set to true if the I/O logging plugins, if any, should log the
634: standard error if it is not connected to a terminal device. This
635: is a hint to the I/O logging plugin which may choose to ignore it.
636: .IP "iolog_ttyin=bool" 4
637: .IX Item "iolog_ttyin=bool"
638: Set to true if the I/O logging plugins, if any, should log all
639: terminal input. This only includes input typed by the user and not
640: from a pipe or redirected from a file. This is a hint to the I/O
641: logging plugin which may choose to ignore it.
642: .IP "iolog_ttyout=bool" 4
643: .IX Item "iolog_ttyout=bool"
644: Set to true if the I/O logging plugins, if any, should log all
645: terminal output. This only includes output to the screen, not
646: output to a pipe or file. This is a hint to the I/O logging plugin
647: which may choose to ignore it.
648: .IP "use_pty=bool" 4
649: .IX Item "use_pty=bool"
650: Allocate a pseudo-tty to run the command in, regardless of whether
651: or not I/O logging is in use. By default, \fBsudo\fR will only run
652: the command in a pty when an I/O log plugin is loaded.
653: .IP "set_utmp=bool" 4
654: .IX Item "set_utmp=bool"
655: Create a utmp (or utmpx) entry when a pseudo-tty is allocated. By
656: default, the new entry will be a copy of the user's existing utmp
657: entry (if any), with the tty, time, type and pid fields updated.
658: .IP "utmp_user=string" 4
659: .IX Item "utmp_user=string"
660: User name to use when constructing a new utmp (or utmpx) entry when
661: \&\fIset_utmp\fR is enabled. This option can be used to set the user
662: field in the utmp entry to the user the command runs as rather than
663: the invoking user. If not set, \fBsudo\fR will base the new entry on
664: the invoking user's existing entry.
665: .RE
666: .RS 4
667: .Sp
668: Unsupported values will be ignored.
669: .RE
670: .IP "argv_out" 4
671: .IX Item "argv_out"
672: The \f(CW\*(C`NULL\*(C'\fR\-terminated argument vector to pass to the \fIexecve()\fR
673: system call when executing the command. The plugin is responsible
674: for allocating and populating the vector.
675: .IP "user_env_out" 4
676: .IX Item "user_env_out"
677: The \f(CW\*(C`NULL\*(C'\fR\-terminated environment vector to use when executing the
678: command. The plugin is responsible for allocating and populating
679: the vector.
680: .RE
681: .RS 4
682: .RE
683: .IP "list" 4
684: .IX Item "list"
685: .Vb 2
686: \& int (*list)(int verbose, const char *list_user,
687: \& int argc, char * const argv[]);
688: .Ve
689: .Sp
690: List available privileges for the invoking user. Returns 1 on
691: success, 0 on failure and \-1 on error. On error, the plugin may
692: optionally call the conversation or plugin_printf function with
693: \&\f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional error information to
694: the user.
695: .Sp
696: Privileges should be output via the conversation or plugin_printf
697: function using \f(CW\*(C`SUDO_CONV_INFO_MSG\*(C'\fR.
698: .RS 4
699: .IP "verbose" 4
700: .IX Item "verbose"
701: Flag indicating whether to list in verbose mode or not.
702: .IP "list_user" 4
703: .IX Item "list_user"
704: The name of a different user to list privileges for if the policy
705: allows it. If \f(CW\*(C`NULL\*(C'\fR, the plugin should list the privileges of
706: the invoking user.
707: .IP "argc" 4
708: .IX Item "argc"
709: The number of elements in \fIargv\fR, not counting the final \f(CW\*(C`NULL\*(C'\fR
710: pointer.
711: .IP "argv" 4
712: .IX Item "argv"
713: If non\-\f(CW\*(C`NULL\*(C'\fR, an argument vector describing a command the user
714: wishes to check against the policy in the same form as what would
715: be passed to the \fIexecve()\fR system call. If the command is permitted
716: by the policy, the fully-qualified path to the command should be
717: displayed along with any command line arguments.
718: .RE
719: .RS 4
720: .RE
721: .IP "validate" 4
722: .IX Item "validate"
723: .Vb 1
724: \& int (*validate)(void);
725: .Ve
726: .Sp
727: The \f(CW\*(C`validate\*(C'\fR function is called when \fBsudo\fR is run with the
728: \&\f(CW\*(C`\-v\*(C'\fR flag. For policy plugins such as \fIsudoers\fR that cache
729: authentication credentials, this function will validate and cache
730: the credentials.
731: .Sp
732: The \f(CW\*(C`validate\*(C'\fR function should be \f(CW\*(C`NULL\*(C'\fR if the plugin does not
733: support credential caching.
734: .Sp
735: Returns 1 on success, 0 on failure and \-1 on error.
736: On error, the plugin may optionally call the conversation or plugin_printf
737: function with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional
738: error information to the user.
739: .IP "invalidate" 4
740: .IX Item "invalidate"
741: .Vb 1
742: \& void (*invalidate)(int remove);
743: .Ve
744: .Sp
745: The \f(CW\*(C`invalidate\*(C'\fR function is called when \fBsudo\fR is called with
746: the \f(CW\*(C`\-k\*(C'\fR or \f(CW\*(C`\-K\*(C'\fR flag. For policy plugins such as \fIsudoers\fR that
747: cache authentication credentials, this function will invalidate the
748: credentials. If the \fIremove\fR flag is set, the plugin may remove
749: the credentials instead of simply invalidating them.
750: .Sp
751: The \f(CW\*(C`invalidate\*(C'\fR function should be \f(CW\*(C`NULL\*(C'\fR if the plugin does not
752: support credential caching.
753: .IP "init_session" 4
754: .IX Item "init_session"
755: .Vb 1
756: \& int (*init_session)(struct passwd *pwd);
757: .Ve
758: .Sp
759: The \f(CW\*(C`init_session\*(C'\fR function is called when \fBsudo\fR sets up the
760: execution environment for the command, immediately before the
761: contents of the \fIcommand_info\fR list are applied (before the uid
762: changes). This can be used to do session setup that is not supported
763: by \fIcommand_info\fR, such as opening the \s-1PAM\s0 session.
764: .Sp
765: The \fIpwd\fR argument points to a passwd struct for the user the
766: command will be run as if the uid the command will run as was found
767: in the password database, otherwise it will be \s-1NULL\s0.
768: .Sp
769: Returns 1 on success, 0 on failure and \-1 on error.
770: On error, the plugin may optionally call the conversation or plugin_printf
771: function with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional
772: error information to the user.
773: .PP
774: \fIVersion macros\fR
775: .IX Subsection "Version macros"
776: .PP
777: .Vb 8
778: \& #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
779: \& #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
780: \& #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
781: \& *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
782: \& } while(0)
783: \& #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
784: \& *(vp) = (*(vp) & 0xffff0000) | (n); \e
785: \& } while(0)
786: \&
787: \& #define SUDO_API_VERSION_MAJOR 1
788: \& #define SUDO_API_VERSION_MINOR 0
789: \& #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \e
790: \& SUDO_API_VERSION_MINOR)
791: .Ve
792: .SS "I/O Plugin \s-1API\s0"
793: .IX Subsection "I/O Plugin API"
794: .Vb 10
795: \& struct io_plugin {
796: \& #define SUDO_IO_PLUGIN 2
797: \& unsigned int type; /* always SUDO_IO_PLUGIN */
798: \& unsigned int version; /* always SUDO_API_VERSION */
799: \& int (*open)(unsigned int version, sudo_conv_t conversation
800: \& sudo_printf_t plugin_printf, char * const settings[],
801: \& char * const user_info[], int argc, char * const argv[],
802: \& char * const user_env[]);
803: \& void (*close)(int exit_status, int error); /* wait status or error */
804: \& int (*show_version)(int verbose);
805: \& int (*log_ttyin)(const char *buf, unsigned int len);
806: \& int (*log_ttyout)(const char *buf, unsigned int len);
807: \& int (*log_stdin)(const char *buf, unsigned int len);
808: \& int (*log_stdout)(const char *buf, unsigned int len);
809: \& int (*log_stderr)(const char *buf, unsigned int len);
810: \& };
811: .Ve
812: .PP
813: When an I/O plugin is loaded, \fBsudo\fR runs the command in a pseudo-tty.
814: This makes it possible to log the input and output from the user's
815: session. If any of the standard input, standard output or standard
816: error do not correspond to a tty, \fBsudo\fR will open a pipe to capture
817: the I/O for logging before passing it on.
818: .PP
819: The log_ttyin function receives the raw user input from the terminal
820: device (note that this will include input even when echo is disabled,
821: such as when a password is read). The log_ttyout function receives
822: output from the pseudo-tty that is suitable for replaying the user's
823: session at a later time. The log_stdin, log_stdout and log_stderr
824: functions are only called if the standard input, standard output
825: or standard error respectively correspond to something other than
826: a tty.
827: .PP
828: Any of the logging functions may be set to the \s-1NULL\s0
829: pointer if no logging is to be performed. If the open function
830: returns \f(CW0\fR, no I/O will be sent to the plugin.
831: .PP
832: The io_plugin struct has the following fields:
833: .IP "type" 4
834: .IX Item "type"
835: The \f(CW\*(C`type\*(C'\fR field should always be set to \s-1SUDO_IO_PLUGIN\s0
836: .IP "version" 4
837: .IX Item "version"
838: The \f(CW\*(C`version\*(C'\fR field should be set to \s-1SUDO_API_VERSION\s0.
839: .Sp
840: This allows \fBsudo\fR to determine the \s-1API\s0 version the plugin was
841: built against.
842: .IP "open" 4
843: .IX Item "open"
844: .Vb 4
845: \& int (*open)(unsigned int version, sudo_conv_t conversation
846: \& sudo_printf_t plugin_printf, char * const settings[],
847: \& char * const user_info[], int argc, char * const argv[],
848: \& char * const user_env[]);
849: .Ve
850: .Sp
851: The \fIopen\fR function is run before the \fIlog_input\fR, \fIlog_output\fR
852: or \fIshow_version\fR functions are called. It is only called if the
853: version is being requested or the \fIcheck_policy\fR function has
854: returned successfully. It returns 1 on success, 0 on failure, \-1
855: if a general error occurred, or \-2 if there was a usage error. In
856: the latter case, \fBsudo\fR will print a usage message before it exits.
857: If an error occurs, the plugin may optionally call the conversation
858: or plugin_printf function with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present
859: additional error information to the user.
860: .Sp
861: The function arguments are as follows:
862: .RS 4
863: .IP "version" 4
864: .IX Item "version"
865: The version passed in by \fBsudo\fR allows the plugin to determine the
866: major and minor version number of the plugin \s-1API\s0 supported by
867: \&\fBsudo\fR.
868: .IP "conversation" 4
869: .IX Item "conversation"
870: A pointer to the conversation function that may be used by the
871: \&\fIshow_version\fR function to display version information (see
872: show_version below). The conversation function may also be used
873: to display additional error message to the user.
874: The conversation function returns 0 on success and \-1 on failure.
875: .IP "plugin_printf" 4
876: .IX Item "plugin_printf"
877: A pointer to a printf-style function that may be used by the
878: \&\fIshow_version\fR function to display version information (see
879: show_version below). The plugin_printf function may also be used
880: to display additional error message to the user.
881: The plugin_printf function returns number of characters printed on
882: success and \-1 on failure.
883: .IP "settings" 4
884: .IX Item "settings"
885: A vector of user-supplied \fBsudo\fR settings in the form of \*(L"name=value\*(R"
886: strings. The vector is terminated by a \f(CW\*(C`NULL\*(C'\fR pointer. These
887: settings correspond to flags the user specified when running \fBsudo\fR.
888: As such, they will only be present when the corresponding flag has
889: been specified on the command line.
890: .Sp
891: When parsing \fIsettings\fR, the plugin should split on the \fBfirst\fR
892: equal sign ('=') since the \fIname\fR field will never include one
893: itself but the \fIvalue\fR might.
894: .Sp
895: See the \*(L"Policy Plugin \s-1API\s0\*(R" section for a list of all possible settings.
896: .IP "user_info" 4
897: .IX Item "user_info"
898: A vector of information about the user running the command in the form of
899: \&\*(L"name=value\*(R" strings. The vector is terminated by a \f(CW\*(C`NULL\*(C'\fR pointer.
900: .Sp
901: When parsing \fIuser_info\fR, the plugin should split on the \fBfirst\fR
902: equal sign ('=') since the \fIname\fR field will never include one
903: itself but the \fIvalue\fR might.
904: .Sp
905: See the \*(L"Policy Plugin \s-1API\s0\*(R" section for a list of all possible strings.
906: .IP "argc" 4
907: .IX Item "argc"
908: The number of elements in \fIargv\fR, not counting the final \f(CW\*(C`NULL\*(C'\fR
909: pointer.
910: .IP "argv" 4
911: .IX Item "argv"
912: If non\-\f(CW\*(C`NULL\*(C'\fR, an argument vector describing a command the user
913: wishes to run in the same form as what would be passed to the
914: \&\fIexecve()\fR system call.
915: .IP "user_env" 4
916: .IX Item "user_env"
917: The user's environment in the form of a \f(CW\*(C`NULL\*(C'\fR\-terminated vector of
918: \&\*(L"name=value\*(R" strings.
919: .Sp
920: When parsing \fIuser_env\fR, the plugin should split on the \fBfirst\fR
921: equal sign ('=') since the \fIname\fR field will never include one
922: itself but the \fIvalue\fR might.
923: .RE
924: .RS 4
925: .RE
926: .IP "close" 4
927: .IX Item "close"
928: .Vb 1
929: \& void (*close)(int exit_status, int error);
930: .Ve
931: .Sp
932: The \f(CW\*(C`close\*(C'\fR function is called when the command being run by \fBsudo\fR
933: finishes.
934: .Sp
935: The function arguments are as follows:
936: .RS 4
937: .IP "exit_status" 4
938: .IX Item "exit_status"
939: The command's exit status, as returned by the \fIwait\fR\|(2) system call.
940: The value of \f(CW\*(C`exit_status\*(C'\fR is undefined if \f(CW\*(C`error\*(C'\fR is non-zero.
941: .IP "error" 4
942: .IX Item "error"
943: If the command could not be executed, this is set to the value of
944: \&\f(CW\*(C`errno\*(C'\fR set by the \fIexecve\fR\|(2) system call. If the command was
945: successfully executed, the value of \f(CW\*(C`error\*(C'\fR is 0.
946: .RE
947: .RS 4
948: .RE
949: .IP "show_version" 4
950: .IX Item "show_version"
951: .Vb 1
952: \& int (*show_version)(int verbose);
953: .Ve
954: .Sp
955: The \f(CW\*(C`show_version\*(C'\fR function is called by \fBsudo\fR when the user specifies
956: the \f(CW\*(C`\-V\*(C'\fR option. The plugin may display its version information
957: to the user via the conversation or plugin_printf function using
958: \&\f(CW\*(C`SUDO_CONV_INFO_MSG\*(C'\fR. If the user requests detailed version
959: information, the verbose flag will be set.
960: .IP "log_ttyin" 4
961: .IX Item "log_ttyin"
962: .Vb 1
963: \& int (*log_ttyin)(const char *buf, unsigned int len);
964: .Ve
965: .Sp
966: The \fIlog_ttyin\fR function is called whenever data can be read from
967: the user but before it is passed to the running command. This
968: allows the plugin to reject data if it chooses to (for instance
969: if the input contains banned content). Returns \f(CW1\fR if the data
970: should be passed to the command, \f(CW0\fR if the data is rejected
971: (which will terminate the command) or \f(CW\*(C`\-1\*(C'\fR if an error occurred.
972: .Sp
973: The function arguments are as follows:
974: .RS 4
975: .IP "buf" 4
976: .IX Item "buf"
977: The buffer containing user input.
978: .IP "len" 4
979: .IX Item "len"
980: The length of \fIbuf\fR in bytes.
981: .RE
982: .RS 4
983: .RE
984: .IP "log_ttyout" 4
985: .IX Item "log_ttyout"
986: .Vb 1
987: \& int (*log_ttyout)(const char *buf, unsigned int len);
988: .Ve
989: .Sp
990: The \fIlog_ttyout\fR function is called whenever data can be read from
991: the command but before it is written to the user's terminal. This
992: allows the plugin to reject data if it chooses to (for instance
993: if the output contains banned content). Returns \f(CW1\fR if the data
994: should be passed to the user, \f(CW0\fR if the data is rejected
995: (which will terminate the command) or \f(CW\*(C`\-1\*(C'\fR if an error occurred.
996: .Sp
997: The function arguments are as follows:
998: .RS 4
999: .IP "buf" 4
1000: .IX Item "buf"
1001: The buffer containing command output.
1002: .IP "len" 4
1003: .IX Item "len"
1004: The length of \fIbuf\fR in bytes.
1005: .RE
1006: .RS 4
1007: .RE
1008: .IP "log_stdin" 4
1009: .IX Item "log_stdin"
1010: .Vb 1
1011: \& int (*log_stdin)(const char *buf, unsigned int len);
1012: .Ve
1013: .Sp
1014: The \fIlog_stdin\fR function is only used if the standard input does
1015: not correspond to a tty device. It is called whenever data can be
1016: read from the standard input but before it is passed to the running
1017: command. This allows the plugin to reject data if it chooses to
1018: (for instance if the input contains banned content). Returns \f(CW1\fR
1019: if the data should be passed to the command, \f(CW0\fR if the data is
1020: rejected (which will terminate the command) or \f(CW\*(C`\-1\*(C'\fR if an error
1021: occurred.
1022: .Sp
1023: The function arguments are as follows:
1024: .RS 4
1025: .IP "buf" 4
1026: .IX Item "buf"
1027: The buffer containing user input.
1028: .IP "len" 4
1029: .IX Item "len"
1030: The length of \fIbuf\fR in bytes.
1031: .RE
1032: .RS 4
1033: .RE
1034: .IP "log_stdout" 4
1035: .IX Item "log_stdout"
1036: .Vb 1
1037: \& int (*log_stdout)(const char *buf, unsigned int len);
1038: .Ve
1039: .Sp
1040: The \fIlog_stdout\fR function is only used if the standard output does
1041: not correspond to a tty device. It is called whenever data can be
1042: read from the command but before it is written to the standard
1043: output. This allows the plugin to reject data if it chooses to
1044: (for instance if the output contains banned content). Returns \f(CW1\fR
1045: if the data should be passed to the user, \f(CW0\fR if the data is
1046: rejected (which will terminate the command) or \f(CW\*(C`\-1\*(C'\fR if an error
1047: occurred.
1048: .Sp
1049: The function arguments are as follows:
1050: .RS 4
1051: .IP "buf" 4
1052: .IX Item "buf"
1053: The buffer containing command output.
1054: .IP "len" 4
1055: .IX Item "len"
1056: The length of \fIbuf\fR in bytes.
1057: .RE
1058: .RS 4
1059: .RE
1060: .IP "log_stderr" 4
1061: .IX Item "log_stderr"
1062: .Vb 1
1063: \& int (*log_stderr)(const char *buf, unsigned int len);
1064: .Ve
1065: .Sp
1066: The \fIlog_stderr\fR function is only used if the standard error does
1067: not correspond to a tty device. It is called whenever data can be
1068: read from the command but before it is written to the standard
1069: error. This allows the plugin to reject data if it chooses to
1070: (for instance if the output contains banned content). Returns \f(CW1\fR
1071: if the data should be passed to the user, \f(CW0\fR if the data is
1072: rejected (which will terminate the command) or \f(CW\*(C`\-1\*(C'\fR if an error
1073: occurred.
1074: .Sp
1075: The function arguments are as follows:
1076: .RS 4
1077: .IP "buf" 4
1078: .IX Item "buf"
1079: The buffer containing command output.
1080: .IP "len" 4
1081: .IX Item "len"
1082: The length of \fIbuf\fR in bytes.
1083: .RE
1084: .RS 4
1085: .RE
1086: .PP
1087: \fIVersion macros\fR
1088: .IX Subsection "Version macros"
1089: .PP
1090: Same as for the \*(L"Policy Plugin \s-1API\s0\*(R".
1091: .SS "Conversation \s-1API\s0"
1092: .IX Subsection "Conversation API"
1093: If the plugin needs to interact with the user, it may do so via the
1094: conversation function. A plugin should not attempt to read directly
1095: from the standard input or the user's tty (neither of which are
1096: guaranteed to exist). The caller must include a trailing newline
1097: in \f(CW\*(C`msg\*(C'\fR if one is to be printed.
1098: .PP
1099: A printf-style function is also available that can be used to display
1100: informational or error messages to the user, which is usually more
1101: convenient for simple messages where no use input is required.
1102: .PP
1103: .Vb 11
1104: \& struct sudo_conv_message {
1105: \& #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1106: \& #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1107: \& #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1108: \& #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1109: \& #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1110: \& #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1111: \& int msg_type;
1112: \& int timeout;
1113: \& const char *msg;
1114: \& };
1115: \&
1116: \& struct sudo_conv_reply {
1117: \& char *reply;
1118: \& };
1119: \&
1120: \& typedef int (*sudo_conv_t)(int num_msgs,
1121: \& const struct sudo_conv_message msgs[],
1122: \& struct sudo_conv_reply replies[]);
1123: \&
1124: \& typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1125: .Ve
1126: .PP
1127: Pointers to the conversation and printf-style functions are passed
1128: in to the plugin's \f(CW\*(C`open\*(C'\fR function when the plugin is initialized.
1129: .PP
1130: To use the conversation function, the plugin must pass an array of
1131: \&\f(CW\*(C`sudo_conv_message\*(C'\fR and \f(CW\*(C`sudo_conv_reply\*(C'\fR structures. There must
1132: be a \f(CW\*(C`struct sudo_conv_message\*(C'\fR and \f(CW\*(C`struct sudo_conv_reply\*(C'\fR for
1133: each message in the conversation. The plugin is responsible for
1134: freeing the reply buffer filled in to the \f(CW\*(C`struct sudo_conv_reply\*(C'\fR,
1135: if any.
1136: .PP
1137: The printf-style function uses the same underlying mechanism as the
1138: conversation function but only supports \f(CW\*(C`SUDO_CONV_INFO_MSG\*(C'\fR and
1139: \&\f(CW\*(C`SUDO_CONV_ERROR_MSG\*(C'\fR for the \fImsg_type\fR parameter. It can be
1140: more convenient than using the conversation function if no user
1141: reply is needed and supports standard \fIprintf()\fR escape sequences.
1142: .PP
1143: See the sample plugin for an example of the conversation function usage.
1144: .SS "Sudoers Group Plugin \s-1API\s0"
1145: .IX Subsection "Sudoers Group Plugin API"
1146: The \fIsudoers\fR module supports a plugin interface to allow non-Unix
1147: group lookups. This can be used to query a group source other than
1148: the standard Unix group database. A sample group plugin is bundled
1149: with \fBsudo\fR that implements file-based lookups. Third party group
1150: plugins include a \s-1QAS\s0 \s-1AD\s0 plugin available from Quest Software.
1151: .PP
1152: A group plugin must declare and populate a \f(CW\*(C`sudoers_group_plugin\*(C'\fR
1153: struct in the global scope. This structure contains pointers to
1154: the functions that implement plugin initialization, cleanup and
1155: group lookup.
1156: .PP
1157: .Vb 8
1158: \& struct sudoers_group_plugin {
1159: \& unsigned int version;
1160: \& int (*init)(int version, sudo_printf_t sudo_printf,
1161: \& char *const argv[]);
1162: \& void (*cleanup)(void);
1163: \& int (*query)(const char *user, const char *group,
1164: \& const struct passwd *pwd);
1165: \&};
1166: .Ve
1167: .PP
1168: The \f(CW\*(C`sudoers_group_plugin\*(C'\fR struct has the following fields:
1169: .IP "version" 4
1170: .IX Item "version"
1171: The \f(CW\*(C`version\*(C'\fR field should be set to \s-1GROUP_API_VERSION\s0.
1172: .Sp
1173: This allows \fIsudoers\fR to determine the \s-1API\s0 version the group plugin
1174: was built against.
1175: .IP "init" 4
1176: .IX Item "init"
1177: .Vb 2
1178: \& int (*init)(int version, sudo_printf_t plugin_printf,
1179: \& char *const argv[]);
1180: .Ve
1181: .Sp
1182: The \fIinit\fR function is called after \fIsudoers\fR has been parsed but
1183: before any policy checks. It returns 1 on success, 0 on failure
1184: (or if the plugin is not configured), and \-1 if a error occurred.
1185: If an error occurs, the plugin may call the plugin_printf function
1186: with \f(CW\*(C`SUDO_CONF_ERROR_MSG\*(C'\fR to present additional error information
1187: to the user.
1188: .Sp
1189: The function arguments are as follows:
1190: .RS 4
1191: .IP "version" 4
1192: .IX Item "version"
1193: The version passed in by \fIsudoers\fR allows the plugin to determine the
1194: major and minor version number of the group plugin \s-1API\s0 supported by
1195: \&\fIsudoers\fR.
1196: .IP "plugin_printf" 4
1197: .IX Item "plugin_printf"
1198: A pointer to a printf-style function that may be used to display
1199: informational or error message to the user.
1200: Returns the number of characters printed on success and \-1 on failure.
1201: .IP "argv" 4
1202: .IX Item "argv"
1203: A NULL-terminated array of arguments generated from the \fIgroup_plugin\fR
1204: option in \fIsudoers\fR. If no arguments were given, \fIargv\fR will be
1205: \&\s-1NULL\s0.
1206: .RE
1207: .RS 4
1208: .RE
1209: .IP "cleanup" 4
1210: .IX Item "cleanup"
1211: .Vb 1
1212: \& void (*cleanup)();
1213: .Ve
1214: .Sp
1215: The \fIcleanup\fR function is called when \fIsudoers\fR has finished its
1216: group checks. The plugin should free any memory it has allocated
1217: and close open file handles.
1218: .IP "query" 4
1219: .IX Item "query"
1220: .Vb 2
1221: \& int (*query)(const char *user, const char *group,
1222: \& const struct passwd *pwd);
1223: .Ve
1224: .Sp
1225: The \fIquery\fR function is used to ask the group plugin whether \fIuser\fR
1226: is a member of \fIgroup\fR.
1227: .Sp
1228: The function arguments are as follows:
1229: .RS 4
1230: .IP "user" 4
1231: .IX Item "user"
1232: The name of the user being looked up in the external group database.
1233: .IP "group" 4
1234: .IX Item "group"
1235: The name of the group being queried.
1236: .IP "pwd" 4
1237: .IX Item "pwd"
1238: The password database entry for \fIuser\fR, if any. If \fIuser\fR is not
1239: present in the password database, \fIpwd\fR will be \f(CW\*(C`NULL\*(C'\fR.
1240: .RE
1241: .RS 4
1242: .RE
1243: .PP
1244: \fIVersion Macros\fR
1245: .IX Subsection "Version Macros"
1246: .PP
1247: .Vb 5
1248: \& /* Sudoers group plugin version major/minor */
1249: \& #define GROUP_API_VERSION_MAJOR 1
1250: \& #define GROUP_API_VERSION_MINOR 0
1251: \& #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
1252: \& GROUP_API_VERSION_MINOR)
1253: \&
1254: \& /* Getters and setters for group version */
1255: \& #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1256: \& #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1257: \& #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
1258: \& *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1259: \& } while(0)
1260: \& #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
1261: \& *(vp) = (*(vp) & 0xffff0000) | (n); \e
1262: \& } while(0)
1263: .Ve
1264: .SH "SEE ALSO"
1265: .IX Header "SEE ALSO"
1266: \&\fIsudoers\fR\|(@mansectform@), \fIsudo\fR\|(@mansectsu@)
1267: .SH "BUGS"
1268: .IX Header "BUGS"
1269: If you feel you have found a bug in \fBsudo\fR, please submit a bug report
1270: at http://www.sudo.ws/sudo/bugs/
1271: .SH "SUPPORT"
1272: .IX Header "SUPPORT"
1273: Limited free support is available via the sudo-workers mailing list,
1274: see http://www.sudo.ws/mailman/listinfo/sudo\-workers to subscribe or
1275: search the archives.
1276: .SH "DISCLAIMER"
1277: .IX Header "DISCLAIMER"
1278: \&\fBsudo\fR is provided ``\s-1AS\s0 \s-1IS\s0'' and any express or implied warranties,
1279: including, but not limited to, the implied warranties of merchantability
1280: and fitness for a particular purpose are disclaimed. See the \s-1LICENSE\s0
1281: file distributed with \fBsudo\fR or http://www.sudo.ws/sudo/license.html
1282: for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to sudo_plugin.man.in CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc