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