Annotation of embedaddon/sudo/doc/sudo_plugin.man.in, revision 1.1.1.5
1.1.1.3 misho 1: .\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
2: .\" IT IS GENERATED AUTOMATICALLY FROM sudo_plugin.mdoc.in
3: .\"
1.1.1.4 misho 4: .\" Copyright (c) 2009-2013 Todd C. Miller <Todd.Miller@courtesan.com>
1.1.1.3 misho 5: .\"
1.1 misho 6: .\" Permission to use, copy, modify, and distribute this software for any
7: .\" purpose with or without fee is hereby granted, provided that the above
8: .\" copyright notice and this permission notice appear in all copies.
1.1.1.3 misho 9: .\"
1.1 misho 10: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
18: .\"
1.1.1.5 ! misho 19: .TH "SUDO_PLUGIN" "5" "August 16, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
1.1 misho 20: .nh
1.1.1.3 misho 21: .if n .ad l
1.1 misho 22: .SH "NAME"
1.1.1.3 misho 23: \fBsudo_plugin\fR
24: \- Sudo Plugin API
1.1 misho 25: .SH "DESCRIPTION"
1.1.1.3 misho 26: Starting with version 1.8,
27: \fBsudo\fR
28: supports a plugin API
29: for policy and session logging.
30: By default, the
1.1.1.4 misho 31: \fBsudoers\fR
1.1.1.3 misho 32: policy plugin and an associated I/O logging plugin are used.
33: Via the plugin API,
34: \fBsudo\fR
35: can be configured to use alternate policy and/or I/O logging plugins
36: provided by third parties.
1.1.1.4 misho 37: The plugins to be used are specified in the
38: sudo.conf(@mansectform@)
1.1.1.3 misho 39: file.
40: .PP
41: The API is versioned with a major and minor number.
42: The minor version number is incremented when additions are made.
43: The major number is incremented when incompatible changes are made.
44: A plugin should be check the version passed to it and make sure that the
1.1 misho 45: major version matches.
46: .PP
1.1.1.3 misho 47: The plugin API is defined by the
48: \fRsudo_plugin.h\fR
49: header file.
50: .SS "Policy plugin API"
51: A policy plugin must declare and populate a
52: \fRpolicy_plugin\fR
53: struct in the global scope.
54: This structure contains pointers to the functions that implement the
55: \fBsudo\fR
56: policy checks.
57: The name of the symbol should be specified in
1.1.1.4 misho 58: sudo.conf(@mansectform@)
1.1.1.3 misho 59: along with a path to the plugin so that
60: \fBsudo\fR
61: can load it.
62: .nf
63: .sp
64: .RS 0n
65: struct policy_plugin {
66: #define SUDO_POLICY_PLUGIN 1
67: unsigned int type; /* always SUDO_POLICY_PLUGIN */
68: unsigned int version; /* always SUDO_API_VERSION */
69: int (*open)(unsigned int version, sudo_conv_t conversation,
70: sudo_printf_t plugin_printf, char * const settings[],
71: char * const user_info[], char * const user_env[],
72: char * const plugin_options[]);
73: void (*close)(int exit_status, int error);
74: int (*show_version)(int verbose);
75: int (*check_policy)(int argc, char * const argv[],
76: char *env_add[], char **command_info[],
77: char **argv_out[], char **user_env_out[]);
78: int (*list)(int argc, char * const argv[], int verbose,
79: const char *list_user);
80: int (*validate)(void);
81: void (*invalidate)(int remove);
82: int (*init_session)(struct passwd *pwd, char **user_env[]);
83: void (*register_hooks)(int version,
84: int (*register_hook)(struct sudo_hook *hook));
85: void (*deregister_hooks)(int version,
86: int (*deregister_hook)(struct sudo_hook *hook));
87: };
88: .RE
89: .fi
1.1 misho 90: .PP
91: The policy_plugin struct has the following fields:
1.1.1.3 misho 92: .TP 6n
93: type
94: The
95: \fRtype\fR
96: field should always be set to SUDO_POLICY_PLUGIN.
97: .TP 6n
98: version
99: The
100: \fRversion\fR
101: field should be set to
102: \fRSUDO_API_VERSION\fR.
103: .sp
104: This allows
105: \fBsudo\fR
106: to determine the API version the plugin was
1.1 misho 107: built against.
1.1.1.3 misho 108: .TP 6n
109: open
110: .RS
111: .nf
112: .RS 0n
113: int (*open)(unsigned int version, sudo_conv_t conversation,
114: sudo_printf_t plugin_printf, char * const settings[],
115: char * const user_info[], char * const user_env[],
116: char * const plugin_options[]);
117: .RE
118: .fi
119: .sp
1.1 misho 120: Returns 1 on success, 0 on failure, \-1 if a general error occurred,
1.1.1.3 misho 121: or \-2 if there was a usage error.
122: In the latter case,
123: \fBsudo\fR
124: will print a usage message before it exits.
125: If an error occurs, the plugin may optionally call the
126: \fBconversation\fR()
127: or
128: \fBplugin_printf\fR()
129: function with
130: \fRSUDO_CONF_ERROR_MSG\fR
131: to present additional error information to the user.
132: .sp
1.1 misho 133: The function arguments are as follows:
1.1.1.3 misho 134: .TP 6n
135: version
136: The version passed in by
137: \fBsudo\fR
138: allows the plugin to determine the
139: major and minor version number of the plugin API supported by
140: \fBsudo\fR.
141: .TP 6n
142: conversation
143: A pointer to the
144: \fBconversation\fR()
145: function that can be used by the plugin to interact with the user (see below).
1.1 misho 146: Returns 0 on success and \-1 on failure.
1.1.1.3 misho 147: .TP 6n
148: plugin_printf
149: A pointer to a
150: \fBprintf\fR()-style
151: function that may be used to display informational or error messages
152: (see below).
1.1 misho 153: Returns the number of characters printed on success and \-1 on failure.
1.1.1.3 misho 154: .TP 6n
155: settings
156: A vector of user-supplied
157: \fBsudo\fR
158: settings in the form of
159: ``name=value''
160: strings.
161: The vector is terminated by a
162: \fRNULL\fR
163: pointer.
164: These settings correspond to flags the user specified when running
165: \fBsudo\fR.
1.1 misho 166: As such, they will only be present when the corresponding flag has
167: been specified on the command line.
1.1.1.3 misho 168: .sp
169: When parsing
170: \fIsettings\fR,
171: the plugin should split on the
172: \fBfirst\fR
173: equal sign
174: (`=')
175: since the
176: \fIname\fR
177: field will never include one
178: itself but the
179: \fIvalue\fR
180: might.
181: .RS
182: .TP 6n
1.1.1.4 misho 183: bsdauth_type=string
184: Authentication type, if specified by the
185: \fB\-a\fR
186: flag, to use on
187: systems where BSD authentication is supported.
188: .TP 6n
189: closefrom=number
190: If specified, the user has requested via the
191: \fB\-C\fR
192: flag that
193: \fBsudo\fR
194: close all files descriptors with a value of
195: \fInumber\fR
196: or higher.
197: The plugin may optionally pass this, or another value, back in the
198: \fIcommand_info\fR
199: list.
200: .TP 6n
1.1.1.3 misho 201: debug_flags=string
202: A comma-separated list of debug flags that correspond to
203: \fBsudo\fR's
204: \fRDebug\fR
205: entry in
1.1.1.4 misho 206: sudo.conf(@mansectform@),
1.1.1.3 misho 207: if there is one.
208: The flags are passed to the plugin as they appear in
1.1.1.4 misho 209: sudo.conf(@mansectform@).
1.1.1.3 misho 210: The syntax used by
211: \fBsudo\fR
212: and the
1.1.1.4 misho 213: \fBsudoers\fR
1.1.1.3 misho 214: plugin is
215: \fIsubsystem\fR@\fIpriority\fR
216: but the plugin is free to use a different
217: format so long as it does not include a comma
218: (`,\&').
1.1.1.2 misho 219: There is not currently a way to specify a set of debug flags specific
1.1.1.3 misho 220: to the plugin--the flags are shared by
221: \fBsudo\fR
222: and the plugin.
223: .TP 6n
224: debug_level=number
225: This setting has been deprecated in favor of
226: \fIdebug_flags\fR.
227: .TP 6n
1.1.1.4 misho 228: ignore_ticket=bool
1.1.1.3 misho 229: Set to true if the user specified the
1.1.1.4 misho 230: \fB\-k\fR
231: flag along with a
232: command, indicating that the user wishes to ignore any cached
233: authentication credentials.
1.1.1.3 misho 234: \fIimplied_shell\fR
235: to true.
236: This allows
237: \fBsudo\fR
238: with no arguments
239: to be used similarly to
240: su(1).
241: If the plugin does not to support this usage, it may return a value of \-2
242: from the
243: \fBcheck_policy\fR()
244: function, which will cause
245: \fBsudo\fR
246: to print a usage message and
1.1 misho 247: exit.
1.1.1.3 misho 248: .TP 6n
1.1.1.4 misho 249: implied_shell=bool
250: If the user does not specify a program on the command line,
1.1.1.3 misho 251: \fBsudo\fR
1.1.1.4 misho 252: will pass the plugin the path to the user's shell and set
1.1.1.3 misho 253: .TP 6n
254: login_class=string
255: BSD login class to use when setting resource limits and nice value,
256: if specified by the
257: \fB\-c\fR
258: flag.
259: .TP 6n
1.1.1.4 misho 260: login_shell=bool
261: Set to true if the user specified the
262: \fB\-i\fR
263: flag, indicating that
264: the user wishes to run a login shell.
1.1.1.3 misho 265: .TP 6n
1.1.1.4 misho 266: max_groups=int
267: The maximum number of groups a user may belong to.
268: This will only be present if there is a corresponding setting in
269: sudo.conf(@mansectform@).
1.1.1.3 misho 270: .TP 6n
271: network_addrs=list
272: A space-separated list of IP network addresses and netmasks in the
273: form
274: ``addr/netmask'',
275: e.g.\&
276: ``192.168.1.2/255.255.255.0''.
277: The address and netmask pairs may be either IPv4 or IPv6, depending on
278: what the operating system supports.
279: If the address contains a colon
280: (`:\&'),
1.1 misho 281: it is an IPv6 address, else it is IPv4.
1.1.1.3 misho 282: .TP 6n
1.1.1.4 misho 283: noninteractive=bool
284: Set to true if the user specified the
285: \fB\-n\fR
286: flag, indicating that
287: \fBsudo\fR
288: should operate in non-interactive mode.
289: The plugin may reject a command run in non-interactive mode if user
290: interaction is required.
291: .TP 6n
292: plugin_dir=string
293: The default plugin directory used by the
294: \fBsudo\fR
295: front end.
296: This is the default directory set at compile time and may not
297: correspond to the directory the running plugin was loaded from.
298: It may be used by a plugin to locate support files.
299: .TP 6n
300: preserve_environment=bool
301: Set to true if the user specified the
302: \fB\-E\fR
303: flag, indicating that
304: the user wishes to preserve the environment.
305: .TP 6n
306: preserve_groups=bool
307: Set to true if the user specified the
308: \fB\-P\fR
309: flag, indicating that
310: the user wishes to preserve the group vector instead of setting it
311: based on the runas user.
312: .TP 6n
1.1.1.3 misho 313: progname=string
314: The command name that sudo was run as, typically
315: ``sudo''
316: or
317: ``sudoedit''.
318: .TP 6n
1.1.1.4 misho 319: prompt=string
320: The prompt to use when requesting a password, if specified via
321: the
322: \fB\-p\fR
323: flag.
324: .TP 6n
1.1.1.5 ! misho 325: remote_host=string
! 326: The name of the remote host to run the command on, if specified via
! 327: the
! 328: \fB\-h\fR
! 329: option.
! 330: Support for running the command on a remote host is meant to be implemented
! 331: via a helper program that is executed in place of the user-specified command.
! 332: The
! 333: \fBsudo\fR
! 334: front end is only capable of executing commands on the local host.
! 335: Only available starting with API version 1.4.
! 336: .TP 6n
1.1.1.4 misho 337: run_shell=bool
338: Set to true if the user specified the
339: \fB\-s\fR
1.1.1.5 ! misho 340: flag, indicating that the user wishes to run a shell.
1.1.1.4 misho 341: .TP 6n
342: runas_group=string
1.1.1.5 ! misho 343: The group name or gid to run the command as, if specified via
1.1.1.4 misho 344: the
345: \fB\-g\fR
346: flag.
347: .TP 6n
348: runas_user=string
1.1.1.5 ! misho 349: The user name or uid to run the command as, if specified via the
1.1.1.4 misho 350: \fB\-u\fR
351: flag.
352: .TP 6n
353: selinux_role=string
354: SELinux role to use when executing the command, if specified by
355: the
356: \fB\-r\fR
357: flag.
358: .TP 6n
359: selinux_type=string
360: SELinux type to use when executing the command, if specified by
361: the
362: \fB\-t\fR
363: flag.
364: .TP 6n
365: set_home=bool
366: Set to true if the user specified the
367: \fB\-H\fR
368: flag.
369: If true, set the
370: \fRHOME\fR
371: environment variable to the target user's home directory.
372: .TP 6n
1.1.1.3 misho 373: sudoedit=bool
374: Set to true when the
375: \fB\-e\fR
376: flag is is specified or if invoked as
377: \fBsudoedit\fR.
378: The plugin shall substitute an editor into
379: \fIargv\fR
380: in the
381: \fBcheck_policy\fR()
382: function or return \-2 with a usage error
383: if the plugin does not support
384: \fIsudoedit\fR.
385: For more information, see the
386: \fIcheck_policy\fR
387: section.
388: .PP
1.1 misho 389: Additional settings may be added in the future so the plugin should
390: silently ignore settings that it does not recognize.
1.1.1.3 misho 391: .PP
1.1 misho 392: .RE
1.1.1.3 misho 393: .PD 0
394: .TP 6n
395: user_info
1.1 misho 396: A vector of information about the user running the command in the form of
1.1.1.3 misho 397: ``name=value''
398: strings.
399: The vector is terminated by a
400: \fRNULL\fR
401: pointer.
402: .sp
403: When parsing
404: \fIuser_info\fR,
405: the plugin should split on the
406: \fBfirst\fR
407: equal sign
408: (`=')
409: since the
410: \fIname\fR
411: field will never include one
412: itself but the
413: \fIvalue\fR
414: might.
415: .RS
416: .PD
417: .TP 6n
1.1.1.4 misho 418: cols=int
419: The number of columns the user's terminal supports.
420: If there is no terminal device available, a default value of 80 is used.
421: .TP 6n
422: cwd=string
423: The user's current working directory.
424: .TP 6n
425: egid=gid_t
426: The effective group ID of the user invoking
427: \fBsudo\fR.
428: .TP 6n
429: euid=uid_t
430: The effective user ID of the user invoking
431: \fBsudo\fR.
432: .TP 6n
433: gid=gid_t
434: The real group ID of the user invoking
435: \fBsudo\fR.
436: .TP 6n
437: groups=list
438: The user's supplementary group list formatted as a string of
439: comma-separated group IDs.
440: .TP 6n
441: host=string
442: The local machine's hostname as returned by the
443: gethostname(2)
444: system call.
445: .TP 6n
446: lines=int
447: The number of lines the user's terminal supports.
448: If there is
449: no terminal device available, a default value of 24 is used.
450: .TP 6n
451: pgid=int
452: The ID of the process group that the running
453: \fBsudo\fR
454: process is a member of.
1.1.1.5 ! misho 455: Only available starting with API version 1.2.
1.1.1.4 misho 456: .TP 6n
1.1.1.3 misho 457: pid=int
458: The process ID of the running
459: \fBsudo\fR
460: process.
1.1.1.5 ! misho 461: Only available starting with API version 1.2.
1.1.1.3 misho 462: .TP 6n
1.1.1.4 misho 463: plugin_options
464: Any (non-comment) strings immediately after the plugin path are
465: passed as arguments to the plugin.
466: These arguments are split on a white space boundary and are passed to
467: the plugin in the form of a
468: \fRNULL\fR-terminated
469: array of strings.
470: If no arguments were
471: specified,
472: \fIplugin_options\fR
473: will be the
474: \fRNULL\fR
475: pointer.
476: .sp
477: NOTE: the
478: \fIplugin_options\fR
479: parameter is only available starting with
480: API version 1.2.
481: A plugin
482: \fBmust\fR
483: check the API version specified
484: by the
485: \fBsudo\fR
486: front end before using
487: \fIplugin_options\fR.
488: Failure to do so may result in a crash.
489: .TP 6n
1.1.1.3 misho 490: ppid=int
491: The parent process ID of the running
492: \fBsudo\fR
493: process.
1.1.1.5 ! misho 494: Only available starting with API version 1.2.
1.1.1.3 misho 495: .TP 6n
496: sid=int
497: The session ID of the running
498: \fBsudo\fR
499: process or 0 if
500: \fBsudo\fR
1.1.1.4 misho 501: is not part of a POSIX job control session.
1.1.1.5 ! misho 502: Only available starting with API version 1.2.
1.1.1.3 misho 503: .TP 6n
504: tcpgid=int
1.1.1.4 misho 505: The ID of the foreground process group associated with the terminal
506: device associated with the
1.1.1.3 misho 507: \fBsudo\fR
508: process or \-1 if there is no
1.1.1.2 misho 509: terminal present.
1.1.1.5 ! misho 510: Only available starting with API version 1.2.
1.1.1.3 misho 511: .TP 6n
512: tty=string
513: The path to the user's terminal device.
514: If the user has no terminal device associated with the session,
515: the value will be empty, as in
516: ``\fRtty=\fR''.
517: .TP 6n
1.1.1.4 misho 518: uid=uid_t
519: The real user ID of the user invoking
520: \fBsudo\fR.
521: .TP 6n
522: user=string
523: The name of the user invoking
524: \fBsudo\fR.
1.1.1.3 misho 525: .PP
526: .RE
527: .PD 0
528: .TP 6n
529: user_env
530: The user's environment in the form of a
531: \fRNULL\fR-terminated vector of
532: ``name=value''
533: strings.
534: .sp
535: When parsing
536: \fIuser_env\fR,
537: the plugin should split on the
538: \fBfirst\fR
539: equal sign
540: (`=')
541: since the
542: \fIname\fR
543: field will never include one
544: itself but the
545: \fIvalue\fR
546: might.
547: .PD
548: .PP
549: .RE
550: .PD 0
551: .TP 6n
552: close
553: .br
554: .RS
555: .nf
556: .RS 0n
557: void (*close)(int exit_status, int error);
558: .RE
559: .fi
560: .sp
561: The
562: \fBclose\fR()
563: function is called when the command being run by
564: \fBsudo\fR
1.1 misho 565: finishes.
1.1.1.3 misho 566: .sp
1.1 misho 567: The function arguments are as follows:
1.1.1.3 misho 568: .PD
569: .TP 6n
570: exit_status
571: The command's exit status, as returned by the
572: wait(2)
573: system call.
574: The value of
575: \fRexit_status\fR
576: is undefined if
577: \fRerror\fR
578: is non-zero.
579: .TP 6n
580: error
581: .br
1.1 misho 582: If the command could not be executed, this is set to the value of
1.1.1.3 misho 583: \fRerrno\fR
584: set by the
585: execve(2)
586: system call.
587: The plugin is responsible for displaying error information via the
588: \fBconversation\fR()
589: or
590: \fBplugin_printf\fR()
591: function.
592: If the command was successfully executed, the value of
593: \fRerror\fR
594: is 0.
595: .PP
1.1.1.4 misho 596: If no
597: \fBclose\fR()
598: function is defined, no I/O logging plugins are loaded,
599: and neither the
600: \fItimeout\fR
601: not
602: \fIuse_pty\fR
603: options are set in the
604: \fRcommand_info\fR
605: list, the
606: \fBsudo\fR
607: front end may execute the command directly instead of running
608: it as a child process.
609: .PP
1.1.1.3 misho 610: .RE
611: .PD 0
612: .TP 6n
613: show_version
614: .RS
615: .nf
616: .RS 0n
617: int (*show_version)(int verbose);
618: .RE
619: .fi
620: .sp
621: The
622: \fBshow_version\fR()
623: function is called by
624: \fBsudo\fR
625: when the user specifies
626: the
627: \fB\-V\fR
628: option.
629: The plugin may display its version information to the user via the
630: \fBconversation\fR()
631: or
632: \fBplugin_printf\fR()
633: function using
634: \fRSUDO_CONV_INFO_MSG\fR.
635: If the user requests detailed version information, the verbose flag will be set.
636: .PD
637: .PP
638: .RE
639: .PD 0
640: .TP 6n
641: check_policy
642: .RS
643: .nf
644: .RS 0n
645: int (*check_policy)(int argc, char * const argv[]
646: char *env_add[], char **command_info[],
647: char **argv_out[], char **user_env_out[]);
648: .RE
649: .fi
650: .sp
651: The
652: \fBcheck_policy\fR()
653: function is called by
654: \fBsudo\fR
655: to determine
1.1 misho 656: whether the user is allowed to run the specified commands.
1.1.1.3 misho 657: .sp
658: If the
659: \fIsudoedit\fR
660: option was enabled in the
661: \fIsettings\fR
662: array
663: passed to the
664: \fBopen\fR()
665: function, the user has requested
666: \fIsudoedit\fR
667: mode.
668: \fIsudoedit\fR
669: is a mechanism for editing one or more files
1.1 misho 670: where an editor is run with the user's credentials instead of with
1.1.1.3 misho 671: elevated privileges.
672: \fBsudo\fR
673: achieves this by creating user-writable
1.1 misho 674: temporary copies of the files to be edited and then overwriting the
1.1.1.3 misho 675: originals with the temporary copies after editing is complete.
676: If the plugin supports
677: \fIsudoedit\fR,
678: it should choose the editor to be used, potentially from a variable
679: in the user's environment, such as
680: \fREDITOR\fR,
681: and include it in
682: \fIargv_out\fR
683: (note that environment
684: variables may include command line flags).
685: The files to be edited should be copied from
686: \fIargv\fR
687: into
688: \fIargv_out\fR,
689: separated from the
690: editor and its arguments by a
691: ``\fR--\fR''
692: element.
693: The
694: ``\fR--\fR''
695: will
696: be removed by
697: \fBsudo\fR
698: before the editor is executed.
699: The plugin should also set
700: \fIsudoedit=true\fR
701: in the
702: \fIcommand_info\fR
703: list.
704: .sp
705: The
706: \fBcheck_policy\fR()
707: function returns 1 if the command is allowed,
1.1 misho 708: 0 if not allowed, \-1 for a general error, or \-2 for a usage error
1.1.1.3 misho 709: or if
710: \fIsudoedit\fR
711: was specified but is unsupported by the plugin.
712: In the latter case,
713: \fBsudo\fR
714: will print a usage message before it
715: exits.
716: If an error occurs, the plugin may optionally call the
717: \fBconversation\fR()
718: or
719: \fBplugin_printf\fR()
720: function with
721: \fRSUDO_CONF_ERROR_MSG\fR
1.1 misho 722: to present additional error information to the user.
1.1.1.3 misho 723: .sp
1.1 misho 724: The function arguments are as follows:
1.1.1.3 misho 725: .PD
726: .TP 6n
727: argc
728: The number of elements in
729: \fIargv\fR,
730: not counting the final
731: \fRNULL\fR
1.1 misho 732: pointer.
1.1.1.3 misho 733: .TP 6n
734: argv
1.1 misho 735: The argument vector describing the command the user wishes to run,
1.1.1.3 misho 736: in the same form as what would be passed to the
737: execve(2)
738: system call.
739: The vector is terminated by a
740: \fRNULL\fR
741: pointer.
742: .TP 6n
743: env_add
1.1 misho 744: Additional environment variables specified by the user on the command
1.1.1.3 misho 745: line in the form of a
746: \fRNULL\fR-terminated
747: vector of
748: ``name=value''
749: strings.
750: The plugin may reject the command if one or more variables
1.1 misho 751: are not allowed to be set, or it may silently ignore such variables.
1.1.1.3 misho 752: .sp
753: When parsing
754: \fIenv_add\fR,
755: the plugin should split on the
756: \fBfirst\fR
757: equal sign
758: (`=')
759: since the
760: \fIname\fR
761: field will never include one
762: itself but the
763: \fIvalue\fR
764: might.
765: .TP 6n
766: command_info
767: Information about the command being run in the form of
768: ``name=value''
769: strings.
770: These values are used by
771: \fBsudo\fR
772: to set the execution
773: environment when running a command.
774: The plugin is responsible for creating and populating the vector,
775: which must be terminated with a
776: \fRNULL\fR
777: pointer.
778: The following values are recognized by
779: \fBsudo\fR:
780: .RS
781: .TP 6n
782: chroot=string
1.1 misho 783: The root directory to use when running the command.
1.1.1.3 misho 784: .TP 6n
785: closefrom=number
786: If specified,
787: \fBsudo\fR
788: will close all files descriptors with a value
789: of
790: \fInumber\fR
791: or higher.
792: .TP 6n
1.1.1.4 misho 793: command=string
794: Fully qualified path to the command to be executed.
795: .TP 6n
796: cwd=string
797: The current working directory to change to when executing the command.
798: .TP 6n
799: exec_background=bool
800: By default,
801: \fBsudo\fR
802: runs a command as the foreground process as long as
803: \fBsudo\fR
804: itself is running in the foreground.
805: When
806: \fIexec_background\fR
807: is enabled and the command is being run in a pty (due to I/O logging
808: or the
809: \fIuse_pty\fR
810: setting), the command will be run as a background process.
811: Attempts to read from the controlling terminal (or to change terminal
812: settings) will result in the command being suspended with the
813: \fRSIGTTIN\fR
814: signal (or
815: \fRSIGTTOU\fR
816: in the case of terminal settings).
817: If this happens when
818: \fBsudo\fR
819: is a foreground process, the command will be granted the controlling terminal
820: and resumed in the foreground with no user intervention required.
821: The advantage of initially running the command in the background is that
822: \fBsudo\fR
823: need not read from the terminal unless the command explicitly requests it.
824: Otherwise, any terminal input must be passed to the command, whether it
825: has required it or not (the kernel buffers terminals so it is not possible
826: to tell whether the command really wants the input).
827: This is different from historic
828: \fIsudo\fR
829: behavior or when the command is not being run in a pty.
830: .sp
831: For this to work seamlessly, the operating system must support the
832: automatic restarting of system calls.
833: Unfortunately, not all operating systems do this by default,
834: and even those that do may have bugs.
835: For example, Mac OS X fails to restart the
836: \fBtcgetattr\fR()
837: and
838: \fBtcsetattr\fR()
839: system calls (this is a bug in Mac OS X).
840: Furthermore, because this behavior depends on the command stopping with the
841: \fRSIGTTIN\fR
842: or
843: \fRSIGTTOU\fR
844: signals, programs that catch these signals and suspend themselves
845: with a different signal (usually
846: \fRSIGTOP\fR)
847: will not be automatically foregrounded.
848: Some versions of the linux
849: su(1)
850: command behave this way.
851: Because of this, a plugin should not set
852: \fIexec_background\fR
853: unless it is explicitly enabled by the administrator and there should
854: be a way to enabled or disable it on a per-command basis.
855: .sp
856: This setting has no effect unless I/O logging is enabled or
857: \fIuse_pty\fR
858: is enabled.
859: .TP 6n
1.1.1.3 misho 860: iolog_compress=bool
1.1 misho 861: Set to true if the I/O logging plugins, if any, should compress the
1.1.1.3 misho 862: log data.
863: This is a hint to the I/O logging plugin which may choose to ignore it.
864: .TP 6n
865: iolog_path=string
1.1 misho 866: Fully qualified path to the file or directory in which I/O log is
1.1.1.3 misho 867: to be stored.
868: This is a hint to the I/O logging plugin which may choose to ignore it.
869: If no I/O logging plugin is loaded, this setting has no effect.
870: .TP 6n
871: iolog_stdin=bool
1.1 misho 872: Set to true if the I/O logging plugins, if any, should log the
1.1.1.3 misho 873: standard input if it is not connected to a terminal device.
874: This is a hint to the I/O logging plugin which may choose to ignore it.
875: .TP 6n
876: iolog_stdout=bool
1.1 misho 877: Set to true if the I/O logging plugins, if any, should log the
1.1.1.3 misho 878: standard output if it is not connected to a terminal device.
879: This is a hint to the I/O logging plugin which may choose to ignore it.
880: .TP 6n
881: iolog_stderr=bool
1.1 misho 882: Set to true if the I/O logging plugins, if any, should log the
1.1.1.3 misho 883: standard error if it is not connected to a terminal device.
884: This is a hint to the I/O logging plugin which may choose to ignore it.
885: .TP 6n
886: iolog_ttyin=bool
1.1 misho 887: Set to true if the I/O logging plugins, if any, should log all
1.1.1.3 misho 888: terminal input.
889: This only includes input typed by the user and not from a pipe or
890: redirected from a file.
891: This is a hint to the I/O logging plugin which may choose to ignore it.
892: .TP 6n
893: iolog_ttyout=bool
1.1 misho 894: Set to true if the I/O logging plugins, if any, should log all
1.1.1.3 misho 895: terminal output.
896: This only includes output to the screen, not output to a pipe or file.
897: This is a hint to the I/O logging plugin which may choose to ignore it.
898: .TP 6n
1.1.1.4 misho 899: login_class=string
900: BSD login class to use when setting resource limits and nice value
901: (optional).
902: This option is only set on systems that support login classes.
903: .TP 6n
904: nice=int
905: Nice value (priority) to use when executing the command.
906: The nice value, if specified, overrides the priority associated with the
907: \fIlogin_class\fR
908: on BSD systems.
909: .TP 6n
910: noexec=bool
911: If set, prevent the command from executing other programs.
912: .TP 6n
913: preserve_groups=bool
914: If set,
915: \fBsudo\fR
916: will preserve the user's group vector instead of
917: initializing the group vector based on
918: \fRrunas_user\fR.
919: .TP 6n
920: runas_egid=gid
921: Effective group ID to run the command as.
922: If not specified, the value of
923: \fIrunas_gid\fR
924: is used.
925: .TP 6n
926: runas_euid=uid
927: Effective user ID to run the command as.
928: If not specified, the value of
929: \fIrunas_uid\fR
930: is used.
931: .TP 6n
932: runas_gid=gid
933: Group ID to run the command as.
934: .TP 6n
935: runas_groups=list
936: The supplementary group vector to use for the command in the form
937: of a comma-separated list of group IDs.
938: If
939: \fIpreserve_groups\fR
940: is set, this option is ignored.
941: .TP 6n
942: runas_uid=uid
943: User ID to run the command as.
944: .TP 6n
945: selinux_role=string
946: SELinux role to use when executing the command.
947: .TP 6n
948: selinux_type=string
949: SELinux type to use when executing the command.
950: .TP 6n
951: set_utmp=bool
952: Create a utmp (or utmpx) entry when a pseudo-tty is allocated.
953: By default, the new entry will be a copy of the user's existing utmp
954: entry (if any), with the tty, time, type and pid fields updated.
955: .TP 6n
956: sudoedit=bool
957: Set to true when in
958: \fIsudoedit\fR
959: mode.
960: The plugin may enable
961: \fIsudoedit\fR
962: mode even if
963: \fBsudo\fR
964: was not invoked as
965: \fBsudoedit\fR.
966: This allows the plugin to perform command substitution and transparently
967: enable
968: \fIsudoedit\fR
969: when the user attempts to run an editor.
970: .TP 6n
971: timeout=int
972: Command timeout.
973: If non-zero then when the timeout expires the command will be killed.
974: .TP 6n
975: umask=octal
976: The file creation mask to use when executing the command.
977: .TP 6n
1.1.1.3 misho 978: use_pty=bool
1.1 misho 979: Allocate a pseudo-tty to run the command in, regardless of whether
1.1.1.3 misho 980: or not I/O logging is in use.
981: By default,
982: \fBsudo\fR
983: will only run
1.1 misho 984: the command in a pty when an I/O log plugin is loaded.
1.1.1.3 misho 985: .TP 6n
986: utmp_user=string
1.1 misho 987: User name to use when constructing a new utmp (or utmpx) entry when
1.1.1.3 misho 988: \fIset_utmp\fR
989: is enabled.
990: This option can be used to set the user field in the utmp entry to
991: the user the command runs as rather than the invoking user.
992: If not set,
993: \fBsudo\fR
994: will base the new entry on
1.1 misho 995: the invoking user's existing entry.
1.1.1.3 misho 996: .PP
1.1 misho 997: Unsupported values will be ignored.
1.1.1.3 misho 998: .PP
1.1 misho 999: .RE
1.1.1.3 misho 1000: .PD 0
1001: .TP 6n
1002: argv_out
1003: The
1004: \fRNULL\fR-terminated
1005: argument vector to pass to the
1006: execve(2)
1007: system call when executing the command.
1008: The plugin is responsible for allocating and populating the vector.
1009: .PD
1010: .TP 6n
1011: user_env_out
1012: The
1013: \fRNULL\fR-terminated
1014: environment vector to use when executing the command.
1015: The plugin is responsible for allocating and populating the vector.
1016: .PP
1017: .RE
1018: .PD 0
1019: .TP 6n
1020: list
1021: .RS
1022: .nf
1023: .RS 0n
1024: int (*list)(int verbose, const char *list_user,
1025: int argc, char * const argv[]);
1026: .RE
1027: .fi
1028: .sp
1029: List available privileges for the invoking user.
1030: Returns 1 on success, 0 on failure and \-1 on error.
1031: On error, the plugin may optionally call the
1032: \fBconversation\fR()
1033: or
1034: \fBplugin_printf\fR()
1035: function with
1036: \fRSUDO_CONF_ERROR_MSG\fR
1037: to present additional error information to
1.1 misho 1038: the user.
1.1.1.3 misho 1039: .sp
1040: Privileges should be output via the
1041: \fBconversation\fR()
1042: or
1043: \fBplugin_printf\fR()
1044: function using
1045: \fRSUDO_CONV_INFO_MSG\fR,
1046: .PD
1047: .TP 6n
1048: verbose
1.1 misho 1049: Flag indicating whether to list in verbose mode or not.
1.1.1.3 misho 1050: .TP 6n
1051: list_user
1.1 misho 1052: The name of a different user to list privileges for if the policy
1.1.1.3 misho 1053: allows it.
1054: If
1055: \fRNULL\fR,
1056: the plugin should list the privileges of the invoking user.
1057: .TP 6n
1058: argc
1059: The number of elements in
1060: \fIargv\fR,
1061: not counting the final
1062: \fRNULL\fR
1.1 misho 1063: pointer.
1.1.1.3 misho 1064: .TP 6n
1065: argv
1066: If
1067: non-\fRNULL\fR,
1068: an argument vector describing a command the user
1.1 misho 1069: wishes to check against the policy in the same form as what would
1.1.1.3 misho 1070: be passed to the
1071: execve(2)
1072: system call.
1073: If the command is permitted by the policy, the fully-qualified path
1074: to the command should be displayed along with any command line arguments.
1075: .PP
1076: .RE
1077: .PD 0
1078: .TP 6n
1079: validate
1080: .RS
1081: .nf
1082: .RS 0n
1083: int (*validate)(void);
1084: .RE
1085: .fi
1086: .sp
1087: The
1088: \fBvalidate\fR()
1089: function is called when
1090: \fBsudo\fR
1091: is run with the
1092: \fB\-v\fR
1093: flag.
1094: For policy plugins such as
1.1.1.4 misho 1095: \fBsudoers\fR
1.1.1.3 misho 1096: that cache
1.1 misho 1097: authentication credentials, this function will validate and cache
1098: the credentials.
1.1.1.3 misho 1099: .sp
1100: The
1101: \fBvalidate\fR()
1102: function should be
1103: \fRNULL\fR
1104: if the plugin does not support credential caching.
1105: .sp
1.1 misho 1106: Returns 1 on success, 0 on failure and \-1 on error.
1.1.1.3 misho 1107: On error, the plugin may optionally call the
1108: \fBconversation\fR()
1109: or
1110: \fBplugin_printf\fR()
1111: function with
1112: \fRSUDO_CONF_ERROR_MSG\fR
1113: to present additional
1.1 misho 1114: error information to the user.
1.1.1.3 misho 1115: .PD
1116: .PP
1117: .RE
1118: .PD 0
1119: .TP 6n
1120: invalidate
1121: .RS
1122: .nf
1123: .RS 0n
1124: void (*invalidate)(int remove);
1125: .RE
1126: .fi
1127: .sp
1128: The
1129: \fBinvalidate\fR()
1130: function is called when
1131: \fBsudo\fR
1132: is called with
1133: the
1134: \fB\-k\fR
1135: or
1136: \fB\-K\fR
1137: flag.
1138: For policy plugins such as
1.1.1.4 misho 1139: \fBsudoers\fR
1.1.1.3 misho 1140: that
1.1 misho 1141: cache authentication credentials, this function will invalidate the
1.1.1.3 misho 1142: credentials.
1143: If the
1144: \fIremove\fR
1145: flag is set, the plugin may remove
1.1 misho 1146: the credentials instead of simply invalidating them.
1.1.1.3 misho 1147: .sp
1148: The
1149: \fBinvalidate\fR()
1150: function should be
1151: \fRNULL\fR
1152: if the plugin does not support credential caching.
1153: .PD
1154: .PP
1155: .RE
1156: .PD 0
1157: .TP 6n
1158: init_session
1159: .RS
1160: .nf
1161: .RS 0n
1162: int (*init_session)(struct passwd *pwd, char **user_envp[);
1163: .RE
1164: .fi
1165: .sp
1166: The
1167: \fBinit_session\fR()
1168: function is called before
1169: \fBsudo\fR
1170: sets up the
1171: execution environment for the command.
1172: It is run in the parent
1173: \fBsudo\fR
1174: process and before any uid or gid changes.
1175: This can be used to perform session setup that is not supported by
1176: \fIcommand_info\fR,
1177: such as opening the PAM session.
1178: The
1179: \fBclose\fR()
1180: function can be
1181: used to tear down the session that was opened by
1182: \fRinit_session\fR.
1183: .sp
1184: The
1185: \fIpwd\fR
1186: argument points to a passwd struct for the user the
1.1 misho 1187: command will be run as if the uid the command will run as was found
1.1.1.3 misho 1188: in the password database, otherwise it will be
1189: \fRNULL\fR.
1190: .sp
1191: The
1192: \fIuser_env\fR
1193: argument points to the environment the command will
1194: run in, in the form of a
1195: \fRNULL\fR-terminated
1196: vector of
1197: ``name=value''
1198: strings.
1199: This is the same string passed back to the front end via
1200: the Policy Plugin's
1201: \fIuser_env_out\fR
1202: parameter.
1203: If the
1204: \fBinit_session\fR()
1.1.1.2 misho 1205: function needs to modify the user environment, it should update the
1.1.1.3 misho 1206: pointer stored in
1207: \fIuser_env\fR.
1208: The expected use case is to merge the contents of the PAM environment
1209: (if any) with the contents of
1210: \fIuser_env\fR.
1211: NOTE: the
1212: \fIuser_env\fR
1213: parameter is only available
1214: starting with API version 1.2.
1215: A plugin
1216: \fBmust\fR
1217: check the API
1218: version specified by the
1219: \fBsudo\fR
1220: front end before using
1221: \fIuser_env\fR.
1.1.1.2 misho 1222: Failure to do so may result in a crash.
1.1.1.3 misho 1223: .sp
1.1 misho 1224: Returns 1 on success, 0 on failure and \-1 on error.
1.1.1.3 misho 1225: On error, the plugin may optionally call the
1226: \fBconversation\fR()
1227: or
1228: \fBplugin_printf\fR()
1229: function with
1230: \fRSUDO_CONF_ERROR_MSG\fR
1231: to present additional
1.1 misho 1232: error information to the user.
1.1.1.3 misho 1233: .PD
1234: .PP
1235: .RE
1236: .PD 0
1237: .TP 6n
1238: register_hooks
1239: .RS
1240: .nf
1241: .RS 0n
1242: void (*register_hooks)(int version,
1243: int (*register_hook)(struct sudo_hook *hook));
1244: .RE
1245: .fi
1246: .sp
1247: The
1248: \fBregister_hooks\fR()
1249: function is called by the sudo front end to
1250: register any hooks the plugin needs.
1251: If the plugin does not support hooks,
1252: \fRregister_hooks\fR
1253: should be set to the
1254: \fRNULL\fR
1255: pointer.
1256: .sp
1257: The
1258: \fIversion\fR
1259: argument describes the version of the hooks API
1260: supported by the
1261: \fBsudo\fR
1262: front end.
1263: .sp
1264: The
1265: \fBregister_hook\fR()
1266: function should be used to register any supported
1267: hooks the plugin needs.
1268: It returns 0 on success, 1 if the hook type is not supported and \-1
1269: if the major version in
1270: \fRstruct hook\fR
1271: does not match the front end's major hook API version.
1272: .sp
1273: See the
1274: \fIHook function API\fR
1275: section below for more information
1.1.1.2 misho 1276: about hooks.
1.1.1.3 misho 1277: .sp
1278: NOTE: the
1279: \fBregister_hooks\fR()
1280: function is only available starting
1281: with API version 1.2.
1282: If the
1283: \fBsudo\fR
1284: front end doesn't support API
1285: version 1.2 or higher,
1286: \fRregister_hooks\fR
1287: will not be called.
1288: .PD
1289: .PP
1290: .RE
1291: .PD 0
1292: .TP 6n
1293: deregister_hooks
1294: .RS
1295: .nf
1296: .RS 0n
1297: void (*deregister_hooks)(int version,
1298: int (*deregister_hook)(struct sudo_hook *hook));
1299: .RE
1300: .fi
1301: .sp
1302: The
1303: \fBderegister_hooks\fR()
1304: function is called by the sudo front end
1305: to deregister any hooks the plugin has registered.
1306: If the plugin does not support hooks,
1307: \fRderegister_hooks\fR
1308: should be set to the
1309: \fRNULL\fR
1310: pointer.
1311: .sp
1312: The
1313: \fIversion\fR
1314: argument describes the version of the hooks API
1315: supported by the
1316: \fBsudo\fR
1317: front end.
1318: .sp
1319: The
1320: \fBderegister_hook\fR()
1321: function should be used to deregister any
1322: hooks that were put in place by the
1323: \fBregister_hook\fR()
1324: function.
1325: If the plugin tries to deregister a hook that the front end does not support,
1326: \fRderegister_hook\fR
1327: will return an error.
1328: .sp
1329: See the
1330: \fIHook function API\fR
1331: section below for more information
1.1.1.2 misho 1332: about hooks.
1.1.1.3 misho 1333: .sp
1334: NOTE: the
1335: \fBderegister_hooks\fR()
1336: function is only available starting
1337: with API version 1.2.
1338: If the
1339: \fBsudo\fR
1340: front end doesn't support API
1341: version 1.2 or higher,
1342: \fRderegister_hooks\fR
1343: will not be called.
1344: .RE
1345: .PD
1.1 misho 1346: .PP
1.1.1.2 misho 1347: \fIPolicy Plugin Version Macros\fR
1.1.1.3 misho 1348: .nf
1349: .sp
1350: .RS 0n
1351: /* Plugin API version major/minor. */
1352: #define SUDO_API_VERSION_MAJOR 1
1353: #define SUDO_API_VERSION_MINOR 2
1354: #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1355: #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e
1356: SUDO_API_VERSION_MINOR)
1357:
1358: /* Getters and setters for API version */
1359: #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1360: #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1361: #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
1362: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1363: } while(0)
1364: #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
1365: *(vp) = (*(vp) & 0xffff0000) | (n); \e
1366: } while(0)
1367: .RE
1368: .fi
1369: .SS "I/O plugin API"
1370: .nf
1371: .RS 0n
1372: struct io_plugin {
1373: #define SUDO_IO_PLUGIN 2
1374: unsigned int type; /* always SUDO_IO_PLUGIN */
1375: unsigned int version; /* always SUDO_API_VERSION */
1.1.1.4 misho 1376: int (*open)(unsigned int version, sudo_conv_t conversation,
1.1.1.3 misho 1377: sudo_printf_t plugin_printf, char * const settings[],
1.1.1.4 misho 1378: char * const user_info[], char * const command_info[],
1379: int argc, char * const argv[], char * const user_env[],
1380: char * const plugin_options[]);
1.1.1.3 misho 1381: void (*close)(int exit_status, int error); /* wait status or error */
1382: int (*show_version)(int verbose);
1383: int (*log_ttyin)(const char *buf, unsigned int len);
1384: int (*log_ttyout)(const char *buf, unsigned int len);
1385: int (*log_stdin)(const char *buf, unsigned int len);
1386: int (*log_stdout)(const char *buf, unsigned int len);
1387: int (*log_stderr)(const char *buf, unsigned int len);
1388: void (*register_hooks)(int version,
1389: int (*register_hook)(struct sudo_hook *hook));
1390: void (*deregister_hooks)(int version,
1391: int (*deregister_hook)(struct sudo_hook *hook));
1392: };
1393: .RE
1394: .fi
1.1 misho 1395: .PP
1.1.1.3 misho 1396: When an I/O plugin is loaded,
1397: \fBsudo\fR
1398: runs the command in a pseudo-tty.
1.1 misho 1399: This makes it possible to log the input and output from the user's
1.1.1.3 misho 1400: session.
1401: If any of the standard input, standard output or standard error do not
1402: correspond to a tty,
1403: \fBsudo\fR
1404: will open a pipe to capture
1.1 misho 1405: the I/O for logging before passing it on.
1406: .PP
1407: The log_ttyin function receives the raw user input from the terminal
1408: device (note that this will include input even when echo is disabled,
1.1.1.3 misho 1409: such as when a password is read).
1410: The log_ttyout function receives output from the pseudo-tty that is
1411: suitable for replaying the user's session at a later time.
1412: The
1413: \fBlog_stdin\fR(),
1414: \fBlog_stdout\fR()
1415: and
1416: \fBlog_stderr\fR()
1.1 misho 1417: functions are only called if the standard input, standard output
1418: or standard error respectively correspond to something other than
1419: a tty.
1420: .PP
1.1.1.3 misho 1421: Any of the logging functions may be set to the
1422: \fRNULL\fR
1423: pointer if no logging is to be performed.
1424: If the open function returns 0, no I/O will be sent to the plugin.
1.1 misho 1425: .PP
1426: The io_plugin struct has the following fields:
1.1.1.3 misho 1427: .TP 6n
1428: type
1429: The
1430: \fRtype\fR
1431: field should always be set to
1432: \fRSUDO_IO_PLUGIN\fR.
1433: .TP 6n
1434: version
1435: The
1436: \fRversion\fR
1437: field should be set to
1438: \fRSUDO_API_VERSION\fR.
1439: .sp
1440: This allows
1441: \fBsudo\fR
1442: to determine the API version the plugin was
1.1 misho 1443: built against.
1.1.1.3 misho 1444: .TP 6n
1445: open
1446: .RS
1447: .nf
1448: .RS 0n
1.1.1.4 misho 1449: int (*open)(unsigned int version, sudo_conv_t conversation,
1.1.1.3 misho 1450: sudo_printf_t plugin_printf, char * const settings[],
1451: char * const user_info[], int argc, char * const argv[],
1452: char * const user_env[], char * const plugin_options[]);
1453: .RE
1454: .fi
1455: .sp
1456: The
1457: \fBopen\fR()
1458: function is run before the
1459: \fBlog_input\fR(),
1460: \fBlog_output\fR()
1461: or
1462: \fBshow_version\fR()
1463: functions are called.
1464: It is only called if the version is being requested or the
1465: \fBcheck_policy\fR()
1466: function has
1467: returned successfully.
1468: It returns 1 on success, 0 on failure, \-1 if a general error occurred,
1469: or \-2 if there was a usage error.
1470: In the latter case,
1471: \fBsudo\fR
1472: will print a usage message before it exits.
1473: If an error occurs, the plugin may optionally call the
1474: \fBconversation\fR()
1475: or
1476: \fBplugin_printf\fR()
1477: function with
1478: \fRSUDO_CONF_ERROR_MSG\fR
1479: to present
1.1 misho 1480: additional error information to the user.
1.1.1.3 misho 1481: .sp
1.1 misho 1482: The function arguments are as follows:
1.1.1.3 misho 1483: .TP 6n
1484: version
1485: The version passed in by
1486: \fBsudo\fR
1487: allows the plugin to determine the
1488: major and minor version number of the plugin API supported by
1489: \fBsudo\fR.
1490: .TP 6n
1491: conversation
1492: A pointer to the
1493: \fBconversation\fR()
1494: function that may be used by the
1495: \fBshow_version\fR()
1496: function to display version information (see
1497: \fBshow_version\fR()
1498: below).
1499: The
1500: \fBconversation\fR()
1501: function may also be used to display additional error message to the user.
1502: The
1503: \fBconversation\fR()
1504: function returns 0 on success and \-1 on failure.
1505: .TP 6n
1506: plugin_printf
1507: A pointer to a
1508: \fBprintf\fR()-style
1509: function that may be used by the
1510: \fBshow_version\fR()
1511: function to display version information (see
1512: show_version below).
1513: The
1514: \fBplugin_printf\fR()
1515: function may also be used to display additional error message to the user.
1516: The
1517: \fBplugin_printf\fR()
1518: function returns number of characters printed on success and \-1 on failure.
1519: .TP 6n
1520: settings
1521: A vector of user-supplied
1522: \fBsudo\fR
1523: settings in the form of
1524: ``name=value''
1525: strings.
1526: The vector is terminated by a
1527: \fRNULL\fR
1528: pointer.
1529: These settings correspond to flags the user specified when running
1530: \fBsudo\fR.
1.1 misho 1531: As such, they will only be present when the corresponding flag has
1532: been specified on the command line.
1.1.1.3 misho 1533: .sp
1534: When parsing
1535: \fIsettings\fR,
1536: the plugin should split on the
1537: \fBfirst\fR
1538: equal sign
1539: (`=')
1540: since the
1541: \fIname\fR
1542: field will never include one
1543: itself but the
1544: \fIvalue\fR
1545: might.
1546: .sp
1547: See the
1548: \fIPolicy plugin API\fR
1549: section for a list of all possible settings.
1550: .TP 6n
1551: user_info
1.1 misho 1552: A vector of information about the user running the command in the form of
1.1.1.3 misho 1553: ``name=value''
1554: strings.
1555: The vector is terminated by a
1556: \fRNULL\fR
1.1 misho 1557: pointer.
1.1.1.3 misho 1558: .sp
1559: When parsing
1560: \fIuser_info\fR,
1561: the plugin should split on the
1562: \fBfirst\fR
1563: equal sign
1564: (`=')
1565: since the
1566: \fIname\fR
1567: field will never include one
1568: itself but the
1569: \fIvalue\fR
1570: might.
1571: .sp
1572: See the
1573: \fIPolicy plugin API\fR
1574: section for a list of all possible strings.
1575: .TP 6n
1576: argc
1577: The number of elements in
1578: \fIargv\fR,
1579: not counting the final
1580: \fRNULL\fR
1581: pointer.
1582: .TP 6n
1583: argv
1584: If
1585: non-\fRNULL\fR,
1586: an argument vector describing a command the user
1.1 misho 1587: wishes to run in the same form as what would be passed to the
1.1.1.3 misho 1588: execve(2)
1589: system call.
1590: .TP 6n
1591: user_env
1592: The user's environment in the form of a
1593: \fRNULL\fR-terminated
1594: vector of
1595: ``name=value''
1596: strings.
1597: .sp
1598: When parsing
1599: \fIuser_env\fR,
1600: the plugin should split on the
1601: \fBfirst\fR
1602: equal sign
1603: (`=')
1604: since the
1605: \fIname\fR
1606: field will never include one
1607: itself but the
1608: \fIvalue\fR
1609: might.
1610: .TP 6n
1611: plugin_options
1.1.1.2 misho 1612: Any (non-comment) strings immediately after the plugin path are
1.1.1.3 misho 1613: treated as arguments to the plugin.
1614: These arguments are split on a white space boundary and are passed to
1615: the plugin in the form of a
1616: \fRNULL\fR-terminated
1617: array of strings.
1618: If no arguments were specified,
1619: \fIplugin_options\fR
1620: will be the
1621: \fRNULL\fR
1622: pointer.
1623: .sp
1624: NOTE: the
1625: \fIplugin_options\fR
1626: parameter is only available starting with
1627: API version 1.2.
1628: A plugin
1629: \fBmust\fR
1630: check the API version specified
1631: by the
1632: \fBsudo\fR
1633: front end before using
1634: \fIplugin_options\fR.
1635: Failure to do so may result in a crash.
1636: .PP
1637: .RE
1638: .PD 0
1639: .TP 6n
1640: close
1641: .br
1642: .RS
1643: .nf
1644: .RS 0n
1645: void (*close)(int exit_status, int error);
1646: .RE
1647: .fi
1648: .sp
1649: The
1650: \fBclose\fR()
1651: function is called when the command being run by
1652: \fBsudo\fR
1.1 misho 1653: finishes.
1.1.1.3 misho 1654: .sp
1.1 misho 1655: The function arguments are as follows:
1.1.1.3 misho 1656: .PD
1657: .TP 6n
1658: exit_status
1659: The command's exit status, as returned by the
1660: wait(2)
1661: system call.
1662: The value of
1663: \fRexit_status\fR
1664: is undefined if
1665: \fRerror\fR
1666: is non-zero.
1667: .TP 6n
1668: error
1669: .br
1.1 misho 1670: If the command could not be executed, this is set to the value of
1.1.1.3 misho 1671: \fRerrno\fR
1672: set by the
1673: execve(2)
1674: system call.
1675: If the command was successfully executed, the value of
1676: \fRerror\fR
1677: is 0.
1678: .PP
1.1 misho 1679: .RE
1.1.1.3 misho 1680: .PD 0
1681: .TP 6n
1682: show_version
1683: .RS
1684: .nf
1685: .RS 0n
1686: int (*show_version)(int verbose);
1687: .RE
1688: .fi
1689: .sp
1690: The
1691: \fBshow_version\fR()
1692: function is called by
1693: \fBsudo\fR
1694: when the user specifies
1695: the
1696: \fB\-V\fR
1697: option.
1698: The plugin may display its version information to the user via the
1699: \fBconversation\fR()
1700: or
1701: \fBplugin_printf\fR()
1702: function using
1703: \fRSUDO_CONV_INFO_MSG\fR.
1704: If the user requests detailed version information, the verbose flag will be set.
1705: .PD
1706: .PP
1707: .RE
1708: .PD 0
1709: .TP 6n
1710: log_ttyin
1711: .RS
1712: .nf
1713: .RS 0n
1714: int (*log_ttyin)(const char *buf, unsigned int len);
1.1 misho 1715: .RE
1.1.1.3 misho 1716: .fi
1717: .sp
1718: The
1719: \fBlog_ttyin\fR()
1720: function is called whenever data can be read from
1721: the user but before it is passed to the running command.
1722: This allows the plugin to reject data if it chooses to (for instance
1723: if the input contains banned content).
1724: Returns 1 if the data should be passed to the command, 0 if the data
1725: is rejected (which will terminate the command) or \-1 if an error occurred.
1726: .sp
1.1 misho 1727: The function arguments are as follows:
1.1.1.3 misho 1728: .PD
1729: .TP 6n
1730: buf
1.1 misho 1731: The buffer containing user input.
1.1.1.3 misho 1732: .TP 6n
1733: len
1734: The length of
1735: \fIbuf\fR
1736: in bytes.
1737: .PP
1738: .RE
1739: .PD 0
1740: .TP 6n
1741: log_ttyout
1742: .RS
1743: .nf
1744: .RS 0n
1745: int (*log_ttyout)(const char *buf, unsigned int len);
1746: .RE
1747: .fi
1748: .sp
1749: The
1750: \fBlog_ttyout\fR()
1751: function is called whenever data can be read from
1752: the command but before it is written to the user's terminal.
1753: This allows the plugin to reject data if it chooses to (for instance
1754: if the output contains banned content).
1755: Returns 1 if the data should be passed to the user, 0 if the data is rejected
1756: (which will terminate the command) or \-1 if an error occurred.
1757: .sp
1.1 misho 1758: The function arguments are as follows:
1.1.1.3 misho 1759: .PD
1760: .TP 6n
1761: buf
1.1 misho 1762: The buffer containing command output.
1.1.1.3 misho 1763: .TP 6n
1764: len
1765: The length of
1766: \fIbuf\fR
1767: in bytes.
1768: .PP
1769: .RE
1770: .PD 0
1771: .TP 6n
1772: log_stdin
1773: .RS
1774: .nf
1775: .RS 0n
1776: int (*log_stdin)(const char *buf, unsigned int len);
1777: .RE
1778: .fi
1779: .sp
1780: The
1781: \fBlog_stdin\fR()
1782: function is only used if the standard input does
1783: not correspond to a tty device.
1784: It is called whenever data can be read from the standard input but
1785: before it is passed to the running command.
1786: This allows the plugin to reject data if it chooses to
1787: (for instance if the input contains banned content).
1788: Returns 1 if the data should be passed to the command, 0 if the data is
1789: rejected (which will terminate the command) or \-1 if an error occurred.
1790: .sp
1.1 misho 1791: The function arguments are as follows:
1.1.1.3 misho 1792: .PD
1793: .TP 6n
1794: buf
1.1 misho 1795: The buffer containing user input.
1.1.1.3 misho 1796: .TP 6n
1797: len
1798: The length of
1799: \fIbuf\fR
1800: in bytes.
1801: .PP
1802: .RE
1803: .PD 0
1804: .TP 6n
1805: log_stdout
1806: .RS
1807: .nf
1808: .RS 0n
1809: int (*log_stdout)(const char *buf, unsigned int len);
1810: .RE
1811: .fi
1812: .sp
1813: The
1814: \fBlog_stdout\fR()
1815: function is only used if the standard output does not correspond
1816: to a tty device.
1817: It is called whenever data can be read from the command but before
1818: it is written to the standard output.
1819: This allows the plugin to reject data if it chooses to
1820: (for instance if the output contains banned content).
1821: Returns 1 if the data should be passed to the user, 0 if the data is
1822: rejected (which will terminate the command) or \-1 if an error occurred.
1823: .sp
1.1 misho 1824: The function arguments are as follows:
1.1.1.3 misho 1825: .PD
1826: .TP 6n
1827: buf
1.1 misho 1828: The buffer containing command output.
1.1.1.3 misho 1829: .TP 6n
1830: len
1831: The length of
1832: \fIbuf\fR
1833: in bytes.
1834: .PP
1835: .RE
1836: .PD 0
1837: .TP 6n
1838: log_stderr
1839: .RS
1840: .nf
1841: .RS 0n
1842: int (*log_stderr)(const char *buf, unsigned int len);
1843: .RE
1844: .fi
1845: .sp
1846: The
1847: \fBlog_stderr\fR()
1848: function is only used if the standard error does
1849: not correspond to a tty device.
1850: It is called whenever data can be read from the command but before it
1851: is written to the standard error.
1852: This allows the plugin to reject data if it chooses to
1853: (for instance if the output contains banned content).
1854: Returns 1 if the data should be passed to the user, 0 if the data is
1855: rejected (which will terminate the command) or \-1 if an error occurred.
1856: .sp
1.1 misho 1857: The function arguments are as follows:
1.1.1.3 misho 1858: .PD
1859: .TP 6n
1860: buf
1.1 misho 1861: The buffer containing command output.
1.1.1.3 misho 1862: .TP 6n
1863: len
1864: The length of
1865: \fIbuf\fR
1866: in bytes.
1867: .PP
1868: .RE
1869: .PD 0
1870: .TP 6n
1871: register_hooks
1872: See the
1873: \fIPolicy plugin API\fR
1874: section for a description of
1875: \fRregister_hooks\fR.
1876: .PD
1877: .TP 6n
1878: deregister_hooks
1879: See the
1880: \fIPolicy plugin API\fR
1881: section for a description of
1882: \fRderegister_hooks.\fR
1.1 misho 1883: .PP
1.1.1.2 misho 1884: \fII/O Plugin Version Macros\fR
1.1 misho 1885: .PP
1.1.1.3 misho 1886: Same as for the
1887: \fIPolicy plugin API\fR.
1.1.1.4 misho 1888: .SS "Signal handlers"
1889: The
1890: \fBsudo\fR
1891: front end installs default signal handlers to trap common signals
1892: while the plugin functions are run.
1893: The following signals are trapped by default before the command is
1894: executed:
1895: .TP 4n
1896: \fBo\fR
1897: \fRSIGALRM\fR
1898: .PD 0
1899: .TP 4n
1900: \fBo\fR
1901: \fRSIGHUP\fR
1902: .TP 4n
1903: \fBo\fR
1904: \fRSIGINT\fR
1905: .TP 4n
1906: \fBo\fR
1907: \fRSIGQUIT\fR
1908: .TP 4n
1909: \fBo\fR
1910: \fRSIGTERM\fR
1911: .TP 4n
1912: \fBo\fR
1913: \fRSIGTSTP\fR
1914: .TP 4n
1915: \fBo\fR
1916: \fRSIGUSR1\fR
1917: .TP 4n
1918: \fBo\fR
1919: \fRSIGUSR2\fR
1920: .PD
1921: .PP
1922: If a fatal signal is received before the command is executed,
1923: \fBsudo\fR
1924: will call the plugin's
1925: \fBclose\fR()
1926: function with an exit status of 128 plus the value of the signal
1927: that was received.
1928: This allows for consistent logging of commands killed by a signal
1929: for plugins that log such information in their
1930: \fBclose\fR()
1931: function.
1932: .PP
1933: A plugin may temporarily install its own signal handlers but must
1934: restore the original handler before the plugin function returns.
1.1.1.3 misho 1935: .SS "Hook function API"
1936: Beginning with plugin API version 1.2, it is possible to install
1937: hooks for certain functions called by the
1938: \fBsudo\fR
1939: front end.
1.1.1.2 misho 1940: .PP
1941: Currently, the only supported hooks relate to the handling of
1.1.1.3 misho 1942: environment variables.
1943: Hooks can be used to intercept attempts to get, set, or remove
1944: environment variables so that these changes can be reflected in
1945: the version of the environment that is used to execute a command.
1946: A future version of the API will support hooking internal
1947: \fBsudo\fR
1948: front end functions as well.
1.1.1.2 misho 1949: .PP
1950: \fIHook structure\fR
1951: .PP
1.1.1.3 misho 1952: Hooks in
1953: \fBsudo\fR
1954: are described by the following structure:
1955: .nf
1956: .sp
1957: .RS 0n
1958: typedef int (*sudo_hook_fn_t)();
1959:
1960: struct sudo_hook {
1961: int hook_version;
1962: int hook_type;
1963: sudo_hook_fn_t hook_fn;
1964: void *closure;
1965: };
1966: .RE
1967: .fi
1.1.1.2 misho 1968: .PP
1.1.1.3 misho 1969: The
1970: \fRsudo_hook\fR
1971: structure has the following fields:
1972: .TP 6n
1973: hook_version
1974: The
1975: \fRhook_version\fR
1976: field should be set to
1977: \fRSUDO_HOOK_VERSION\fR.
1978: .TP 6n
1979: hook_type
1980: The
1981: \fRhook_type\fR
1982: field may be one of the following supported hook types:
1983: .RS
1984: .TP 6n
1985: \fRSUDO_HOOK_SETENV\fR
1986: The C library
1987: setenv(3)
1988: function.
1989: Any registered hooks will run before the C library implementation.
1990: The
1991: \fRhook_fn\fR
1992: field should
1.1.1.2 misho 1993: be a function that matches the following typedef:
1.1.1.3 misho 1994: .RS
1995: .nf
1996: .sp
1997: .RS 0n
1998: typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1999: const char *value, int overwrite, void *closure);
2000: .RE
2001: .fi
2002: .sp
1.1.1.2 misho 2003: If the registered hook does not match the typedef the results are
2004: unspecified.
1.1.1.3 misho 2005: .PP
2006: .RE
2007: .PD 0
2008: .TP 6n
2009: \fRSUDO_HOOK_UNSETENV\fR
2010: The C library
2011: unsetenv(3)
2012: function.
2013: Any registered hooks will run before the C library implementation.
2014: The
2015: \fRhook_fn\fR
2016: field should
1.1.1.2 misho 2017: be a function that matches the following typedef:
1.1.1.3 misho 2018: .RS
2019: .nf
2020: .sp
2021: .RS 0n
2022: typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2023: void *closure);
2024: .RE
2025: .fi
2026: .PD
2027: .PP
2028: .RE
2029: .PD 0
2030: .TP 6n
2031: \fRSUDO_HOOK_GETENV\fR
2032: The C library
2033: getenv(3)
2034: function.
2035: Any registered hooks will run before the C library implementation.
2036: The
2037: \fRhook_fn\fR
2038: field should
1.1.1.2 misho 2039: be a function that matches the following typedef:
1.1.1.3 misho 2040: .RS
2041: .nf
2042: .sp
2043: .RS 0n
2044: typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2045: char **value, void *closure);
2046: .RE
2047: .fi
2048: .sp
1.1.1.2 misho 2049: If the registered hook does not match the typedef the results are
2050: unspecified.
1.1.1.3 misho 2051: .PD
2052: .PP
2053: .RE
2054: .PD 0
2055: .TP 6n
2056: \fRSUDO_HOOK_PUTENV\fR
2057: The C library
2058: putenv(3)
2059: function.
2060: Any registered hooks will run before the C library implementation.
2061: The
2062: \fRhook_fn\fR
2063: field should
1.1.1.2 misho 2064: be a function that matches the following typedef:
1.1.1.3 misho 2065: .RS
2066: .nf
2067: .sp
2068: .RS 0n
2069: typedef int (*sudo_hook_fn_putenv_t)(char *string,
2070: void *closure);
2071: .RE
2072: .fi
2073: .sp
1.1.1.2 misho 2074: If the registered hook does not match the typedef the results are
2075: unspecified.
2076: .RE
1.1.1.3 misho 2077: .PD
2078: .PP
1.1.1.2 misho 2079: .RE
1.1.1.3 misho 2080: .PD 0
2081: .TP 6n
2082: hook_fn
2083: sudo_hook_fn_t hook_fn;
2084: .sp
2085: The
2086: \fRhook_fn\fR
2087: field should be set to the plugin's hook implementation.
2088: The actual function arguments will vary depending on the
2089: \fRhook_type\fR
2090: (see
2091: \fRhook_type\fR
2092: above).
2093: In all cases, the
2094: \fRclosure\fR
2095: field of
2096: \fRstruct sudo_hook\fR
2097: is passed as the last function parameter.
2098: This can be used to pass arbitrary data to the plugin's hook implementation.
2099: .sp
1.1.1.2 misho 2100: The function return value may be one of the following:
1.1.1.3 misho 2101: .RS
2102: .PD
2103: .TP 6n
2104: \fRSUDO_HOOK_RET_ERROR\fR
1.1.1.2 misho 2105: The hook function encountered an error.
1.1.1.3 misho 2106: .TP 6n
2107: \fRSUDO_HOOK_RET_NEXT\fR
1.1.1.2 misho 2108: The hook completed without error, go on to the next hook (including
1.1.1.3 misho 2109: the native implementation if applicable).
2110: For example, a
2111: getenv(3)
2112: hook might return
2113: \fRSUDO_HOOK_RET_NEXT\fR
2114: if the specified variable was not found in the private copy of the environment.
2115: .TP 6n
2116: \fRSUDO_HOOK_RET_STOP\fR
2117: The hook completed without error, stop processing hooks for this invocation.
2118: This can be used to replace the native implementation.
2119: For example, a
2120: \fRsetenv\fR
2121: hook that operates on a private copy of
2122: the environment but leaves
2123: \fRenviron\fR
2124: unchanged.
1.1.1.2 misho 2125: .RE
2126: .PP
2127: Note that it is very easy to create an infinite loop when hooking
1.1.1.3 misho 2128: C library functions.
2129: For example, a
2130: getenv(3)
2131: hook that calls the
2132: snprintf(3)
2133: function may create a loop if the
2134: snprintf(3)
2135: implementation calls
2136: getenv(3)
2137: to check the locale.
2138: To prevent this, you may wish to use a static variable in the hook
2139: function to guard against nested calls.
2140: For example:
2141: .nf
2142: .sp
2143: .RS 0n
2144: static int in_progress = 0; /* avoid recursion */
2145: if (in_progress)
2146: return SUDO_HOOK_RET_NEXT;
2147: in_progress = 1;
2148: \&...
2149: in_progress = 0;
2150: return SUDO_HOOK_RET_STOP;
2151: .RE
2152: .fi
2153: .PP
2154: \fIHook API Version Macros\fR
2155: .nf
2156: .sp
2157: .RS 0n
2158: /* Hook API version major/minor */
2159: #define SUDO_HOOK_VERSION_MAJOR 1
2160: #define SUDO_HOOK_VERSION_MINOR 0
2161: #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
2162: #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e
2163: SUDO_HOOK_VERSION_MINOR)
2164:
2165: /* Getters and setters for hook API version */
2166: #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
2167: #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
2168: #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e
2169: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2170: } while(0)
2171: #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e
2172: *(vp) = (*(vp) & 0xffff0000) | (n); \e
2173: } while(0)
2174: .RE
2175: .fi
1.1.1.5 ! misho 2176: .SS "Remote command execution"
! 2177: The
! 2178: \fBsudo\fR
! 2179: front end does not have native support for running remote commands.
! 2180: However, starting with
! 2181: \fBsudo\fR
! 2182: 1.8.8, the
! 2183: \fB\-h\fR
! 2184: option may be used to specify a remote host that is passed
! 2185: to the policy plugin.
! 2186: A plugin may also accept a
! 2187: \fIrunas_user\fR
! 2188: in the form of
! 2189: ``user@hostname''
! 2190: which will work with older versions of
! 2191: \fBsudo\fR.
! 2192: It is anticipated that remote commands will be supported by executing a
! 2193: ``helper''
! 2194: program.
! 2195: The policy plugin should setup the execution environment such that the
! 2196: \fBsudo\fR
! 2197: front end will run the helper which, in turn, will connect to the
! 2198: remote host and run the command.
! 2199: .PP
! 2200: For example, the policy plugin could utilize
! 2201: \fBssh\fR
! 2202: to perform remote command execution.
! 2203: The helper program would be responsible for running
! 2204: \fBssh\fR
! 2205: with the proper options to use a private key or certificate
! 2206: that the remote host will accept and run a program
! 2207: on the remote host that would setup the execution environment
! 2208: accordingly.
! 2209: .PP
! 2210: Note that remote
! 2211: \fBsudoedit\fR
! 2212: functionality must be handled by the policy plugin, not
! 2213: \fBsudo\fR
! 2214: itself as the front end has no knowledge that a remote command is
! 2215: being executed.
! 2216: This may be addressed in a future revision of the plugin API.
1.1.1.3 misho 2217: .SS "Conversation API"
1.1 misho 2218: If the plugin needs to interact with the user, it may do so via the
1.1.1.3 misho 2219: \fBconversation\fR()
2220: function.
2221: A plugin should not attempt to read directly from the standard input
2222: or the user's tty (neither of which are guaranteed to exist).
2223: The caller must include a trailing newline in
2224: \fRmsg\fR
2225: if one is to be printed.
2226: .PP
2227: A
2228: \fBprintf\fR()-style
2229: function is also available that can be used to display informational
2230: or error messages to the user, which is usually more convenient for
2231: simple messages where no use input is required.
2232: .nf
2233: .sp
2234: .RS 0n
2235: struct sudo_conv_message {
2236: #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2237: #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2238: #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2239: #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2240: #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2241: #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
2242: #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2243: int msg_type;
2244: int timeout;
2245: const char *msg;
2246: };
2247:
1.1.1.5 ! misho 2248: #define SUDO_CONV_REPL_MAX 255
! 2249:
1.1.1.3 misho 2250: struct sudo_conv_reply {
2251: char *reply;
2252: };
2253:
2254: typedef int (*sudo_conv_t)(int num_msgs,
2255: const struct sudo_conv_message msgs[],
2256: struct sudo_conv_reply replies[]);
2257:
2258: typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2259: .RE
2260: .fi
2261: .PP
2262: Pointers to the
2263: \fBconversation\fR()
2264: and
2265: \fBprintf\fR()-style
2266: functions are passed
2267: in to the plugin's
2268: \fBopen\fR()
2269: function when the plugin is initialized.
2270: .PP
2271: To use the
2272: \fBconversation\fR()
2273: function, the plugin must pass an array of
2274: \fRsudo_conv_message\fR
2275: and
2276: \fRsudo_conv_reply\fR
2277: structures.
2278: There must be a
2279: \fRstruct sudo_conv_message\fR
2280: and
2281: \fRstruct sudo_conv_reply\fR
2282: for
2283: each message in the conversation.
1.1.1.5 ! misho 2284: The plugin is responsible for freeing the reply buffer located in each
1.1.1.3 misho 2285: \fRstruct sudo_conv_reply\fR,
1.1.1.5 ! misho 2286: if it is not
! 2287: \fRNULL\fR.
! 2288: \fRSUDO_CONV_REPL_MAX\fR
! 2289: represents the maximum length of the reply buffer (not including
! 2290: the trailing NUL character).
! 2291: In practical terms, this is the longest password
! 2292: \fBsudo\fR
! 2293: will support.
! 2294: It is also useful as a maximum value for the
! 2295: \fBmemset_s\fR()
! 2296: function when clearing passwords filled in by the conversation function.
1.1 misho 2297: .PP
1.1.1.3 misho 2298: The
2299: \fBprintf\fR()-style
2300: function uses the same underlying mechanism as the
2301: \fBconversation\fR()
2302: function but only supports
2303: \fRSUDO_CONV_INFO_MSG\fR,
2304: \fRSUDO_CONV_ERROR_MSG\fR
2305: and
2306: \fRSUDO_CONV_DEBUG_MSG\fR
2307: for the
2308: \fImsg_type\fR
2309: parameter.
2310: It can be more convenient than using the
2311: \fBconversation\fR()
2312: function if no user reply is needed and supports standard
2313: \fBprintf\fR()
1.1.1.2 misho 2314: escape sequences.
2315: .PP
1.1.1.3 misho 2316: Unlike,
2317: \fRSUDO_CONV_INFO_MSG\fR
2318: and
2319: Dv SUDO_CONV_ERROR_MSG ,
2320: messages
2321: sent with the
2322: \fRSUDO_CONV_DEBUG_MSG\fR
2323: \fImsg_type\fR
2324: are not directly
2325: user-visible.
2326: Instead, they are logged to the file specified in the
2327: \fRDebug\fR
2328: statement (if any) in the
1.1.1.4 misho 2329: sudo.conf(@mansectform@).
1.1.1.3 misho 2330: file.
2331: This allows a plugin to log debugging information and is intended
2332: to be used in conjunction with the
2333: \fIdebug_flags\fR
2334: setting.
2335: .PP
2336: See the sample plugin for an example of the
2337: \fBconversation\fR()
2338: function usage.
2339: .SS "Sudoers group plugin API"
2340: The
1.1.1.4 misho 2341: \fBsudoers\fR
2342: plugin supports its own plugin interface to allow non-Unix
1.1.1.3 misho 2343: group lookups.
2344: This can be used to query a group source other than the standard Unix
2345: group database.
1.1.1.4 misho 2346: Two sample group plugins are bundled with
2347: \fBsudo\fR,
2348: \fIgroup_file\fR
2349: and
2350: \fIsystem_group\fR,
2351: are detailed in
2352: sudoers(@mansectform@).
1.1.1.3 misho 2353: Third party group plugins include a QAS AD plugin available from Quest Software.
2354: .PP
2355: A group plugin must declare and populate a
2356: \fRsudoers_group_plugin\fR
2357: struct in the global scope.
2358: This structure contains pointers to the functions that implement plugin
2359: initialization, cleanup and group lookup.
2360: .nf
2361: .sp
2362: .RS 0n
2363: struct sudoers_group_plugin {
2364: unsigned int version;
2365: int (*init)(int version, sudo_printf_t sudo_printf,
2366: char *const argv[]);
2367: void (*cleanup)(void);
2368: int (*query)(const char *user, const char *group,
2369: const struct passwd *pwd);
2370: };
2371: .RE
2372: .fi
2373: .PP
2374: The
2375: \fRsudoers_group_plugin\fR
2376: struct has the following fields:
2377: .TP 6n
2378: version
2379: The
2380: \fRversion\fR
2381: field should be set to GROUP_API_VERSION.
2382: .sp
2383: This allows
1.1.1.4 misho 2384: \fBsudoers\fR
1.1.1.3 misho 2385: to determine the API version the group plugin
1.1 misho 2386: was built against.
1.1.1.3 misho 2387: .TP 6n
2388: init
2389: .RS
2390: .nf
2391: .RS 0n
2392: int (*init)(int version, sudo_printf_t plugin_printf,
2393: char *const argv[]);
2394: .RE
2395: .fi
2396: .sp
2397: The
2398: \fBinit\fR()
2399: function is called after
2400: \fIsudoers\fR
2401: has been parsed but
2402: before any policy checks.
2403: It returns 1 on success, 0 on failure (or if the plugin is not configured),
2404: and \-1 if a error occurred.
2405: If an error occurs, the plugin may call the
2406: \fBplugin_printf\fR()
2407: function with
2408: \fRSUDO_CONF_ERROR_MSG\fR
2409: to present additional error information
1.1 misho 2410: to the user.
1.1.1.3 misho 2411: .sp
1.1 misho 2412: The function arguments are as follows:
1.1.1.3 misho 2413: .TP 6n
2414: version
2415: The version passed in by
1.1.1.4 misho 2416: \fBsudoers\fR
1.1.1.3 misho 2417: allows the plugin to determine the
2418: major and minor version number of the group plugin API supported by
1.1.1.4 misho 2419: \fBsudoers\fR.
1.1.1.3 misho 2420: .TP 6n
2421: plugin_printf
2422: A pointer to a
2423: \fBprintf\fR()-style
2424: function that may be used to display informational or error message to the user.
1.1 misho 2425: Returns the number of characters printed on success and \-1 on failure.
1.1.1.3 misho 2426: .TP 6n
2427: argv
2428: A
2429: \fRNULL\fR-terminated
2430: array of arguments generated from the
2431: \fIgroup_plugin\fR
2432: option in
2433: \fIsudoers\fR.
2434: If no arguments were given,
2435: \fIargv\fR
2436: will be
2437: \fRNULL\fR.
2438: .PP
2439: .RE
2440: .PD 0
2441: .TP 6n
2442: cleanup
2443: .RS
2444: .nf
2445: .RS 0n
2446: void (*cleanup)();
2447: .RE
2448: .fi
2449: .sp
2450: The
2451: \fBcleanup\fR()
2452: function is called when
1.1.1.4 misho 2453: \fBsudoers\fR
1.1.1.3 misho 2454: has finished its
2455: group checks.
2456: The plugin should free any memory it has allocated and close open file handles.
2457: .PD
2458: .PP
2459: .RE
2460: .PD 0
2461: .TP 6n
2462: query
2463: .br
2464: .RS
2465: .nf
2466: .RS 0n
2467: int (*query)(const char *user, const char *group,
2468: const struct passwd *pwd);
2469: .RE
2470: .fi
2471: .sp
2472: The
2473: \fBquery\fR()
2474: function is used to ask the group plugin whether
2475: \fIuser\fR
2476: is a member of
2477: \fIgroup\fR.
2478: .sp
1.1 misho 2479: The function arguments are as follows:
1.1.1.3 misho 2480: .PD
2481: .TP 6n
2482: user
1.1 misho 2483: The name of the user being looked up in the external group database.
1.1.1.3 misho 2484: .TP 6n
2485: group
2486: .br
1.1 misho 2487: The name of the group being queried.
1.1.1.3 misho 2488: .TP 6n
2489: pwd
2490: The password database entry for
2491: \fIuser\fR,
2492: if any.
2493: If
2494: \fIuser\fR
2495: is not
2496: present in the password database,
2497: \fIpwd\fR
2498: will be
2499: \fRNULL\fR.
2500: .RE
2501: .PP
2502: \fIGroup API Version Macros\fR
2503: .nf
2504: .sp
2505: .RS 0n
2506: /* Sudoers group plugin version major/minor */
2507: #define GROUP_API_VERSION_MAJOR 1
2508: #define GROUP_API_VERSION_MINOR 0
2509: #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
2510: GROUP_API_VERSION_MINOR)
2511:
2512: /* Getters and setters for group version */
2513: #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
2514: #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
2515: #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
2516: *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2517: } while(0)
2518: #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
2519: *(vp) = (*(vp) & 0xffff0000) | (n); \e
2520: } while(0)
2521: .RE
2522: .fi
1.1.1.2 misho 2523: .SH "PLUGIN API CHANGELOG"
1.1.1.3 misho 2524: The following revisions have been made to the Sudo Plugin API.
2525: .TP 6n
2526: Version 1.0
2527: Initial API version.
2528: .TP 6n
1.1.1.4 misho 2529: Version 1.1 (sudo 1.8.0)
1.1.1.3 misho 2530: The I/O logging plugin's
2531: \fBopen\fR()
2532: function was modified to take the
2533: \fRcommand_info\fR
2534: list as an argument.
2535: .TP 6n
1.1.1.4 misho 2536: Version 1.2 (sudo 1.8.5)
1.1.1.3 misho 2537: The Policy and I/O logging plugins'
2538: \fBopen\fR()
2539: functions are now passed
1.1.1.4 misho 2540: a list of plugin parameters if any are specified in
2541: sudo.conf(@mansectform@).
1.1.1.3 misho 2542: .sp
2543: A simple hooks API has been introduced to allow plugins to hook in to the
1.1.1.2 misho 2544: system's environment handling functions.
1.1.1.3 misho 2545: .sp
2546: The
2547: \fRinit_session\fR
2548: Policy plugin function is now passed a pointer
2549: to the user environment which can be updated as needed.
2550: This can be used to merge in environment variables stored in the PAM
2551: handle before a command is run.
1.1.1.4 misho 2552: .TP 6n
2553: Version 1.3 (sudo 1.8.7)
2554: Support for the
2555: \fIexec_background\fR
2556: entry has been added to the
2557: \fRcommand_info\fR
2558: list.
2559: .sp
2560: The
2561: \fImax_groups\fR
2562: and
2563: \fIplugin_dir\fR
2564: entries were added to the
2565: \fRsettings\fR
2566: list.
2567: .sp
2568: The
2569: \fBversion\fR()
2570: and
2571: \fBclose\fR()
2572: functions are now optional.
2573: Previously, a missing
2574: \fBversion\fR()
2575: or
2576: \fBclose\fR()
2577: function would result in a crash.
2578: If no policy plugin
2579: \fBclose\fR()
2580: function is defined, a default
2581: \fBclose\fR()
2582: function will be provided by the
2583: \fBsudo\fR
2584: front end that displays a warning if the command could not be
2585: executed.
2586: .sp
2587: The
2588: \fBsudo\fR
2589: front end now installs default signal handlers to trap common signals
2590: while the plugin functions are run.
1.1.1.5 ! misho 2591: .TP 6n
! 2592: Version 1.4 (sudo 1.8.8)
! 2593: The
! 2594: \fIremote_host\fR
! 2595: entry was added to the
! 2596: \fRsettings\fR
! 2597: list.
1.1 misho 2598: .SH "SEE ALSO"
1.1.1.4 misho 2599: sudo.conf(@mansectform@),
1.1.1.3 misho 2600: sudoers(@mansectform@),
2601: sudo(@mansectsu@)
1.1 misho 2602: .SH "BUGS"
1.1.1.3 misho 2603: If you feel you have found a bug in
2604: \fBsudo\fR,
2605: please submit a bug report at http://www.sudo.ws/sudo/bugs/
1.1 misho 2606: .SH "SUPPORT"
1.1.1.3 misho 2607: Limited free support is available via the sudo-users mailing list,
2608: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1.1 misho 2609: search the archives.
2610: .SH "DISCLAIMER"
1.1.1.3 misho 2611: \fBsudo\fR
2612: is provided
2613: ``AS IS''
2614: and any express or implied warranties, including, but not limited
2615: to, the implied warranties of merchantability and fitness for a
2616: particular purpose are disclaimed.
2617: See the LICENSE file distributed with
2618: \fBsudo\fR
2619: or http://www.sudo.ws/sudo/license.html 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