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