1SUDO_PLUGIN(5) BSD File Formats Manual SUDO_PLUGIN(5)
2
4 sudo_plugin — Sudo Plugin API
5
7 Starting with version 1.8, sudo supports a plugin API for policy and ses‐
8 sion logging. Plugins may be compiled as dynamic shared objects (the
9 default on systems that support them) or compiled statically into the
10 sudo binary itself. By default, the sudoers policy plugin and an associ‐
11 ated I/O logging plugin are used. Via the plugin API, sudo can be con‐
12 figured to use alternate policy and/or I/O logging plugins provided by
13 third parties. The plugins to be used are specified in the sudo.conf(5)
14 file.
15 The API is versioned with a major and minor number. The minor version
17 number is incremented when additions are made. The major number is
18 incremented when incompatible changes are made. A plugin should be check
19 the version passed to it and make sure that the major version matches.
20 The plugin API is defined by the sudo_plugin.h header file.
22 Policy plugin API
24 A policy plugin must declare and populate a policy_plugin struct in the
25 global scope. This structure contains pointers to the functions that
26 implement the sudo policy checks. The name of the symbol should be spec‐
27 ified in sudo.conf(5) along with a path to the plugin so that sudo can
28 load it.
29 struct policy_plugin {
31 #define SUDO_POLICY_PLUGIN 1
32 unsigned int type; /* always SUDO_POLICY_PLUGIN */
33 unsigned int version; /* always SUDO_API_VERSION */
34 int (*open)(unsigned int version, sudo_conv_t conversation,
35 sudo_printf_t plugin_printf, char * const settings[],
36 char * const user_info[], char * const user_env[],
37 char * const plugin_options[], const char **errstr);
38 void (*close)(int exit_status, int error);
39 int (*show_version)(int verbose);
40 int (*check_policy)(int argc, char * const argv[],
41 char *env_add[], char **command_info[],
42 char **argv_out[], char **user_env_out[], const char **errstr);
43 int (*list)(int argc, char * const argv[], int verbose,
44 const char *list_user, const char **errstr);
45 int (*validate)(const char **errstr);
46 void (*invalidate)(int remove);
47 int (*init_session)(struct passwd *pwd, char **user_env[],
48 const char **errstr);
49 void (*register_hooks)(int version,
50 int (*register_hook)(struct sudo_hook *hook));
51 void (*deregister_hooks)(int version,
52 int (*deregister_hook)(struct sudo_hook *hook));
53 struct sudo_plugin_event * (*event_alloc)(void);
54 };
55 The policy_plugin struct has the following fields:
57 type The type field should always be set to SUDO_POLICY_PLUGIN.
59 version
61 The version field should be set to SUDO_API_VERSION.
62 This allows sudo to determine the API version the plugin was built
64 against.
65 open
67 int (*open)(unsigned int version, sudo_conv_t conversation,
68 sudo_printf_t plugin_printf, char * const settings[],
69 char * const user_info[], char * const user_env[],
70 char * const plugin_options[], const char **errstr);
71 Returns 1 on success, 0 on failure, -1 if a general error occurred,
73 or -2 if there was a usage error. In the latter case, sudo will
74 print a usage message before it exits. If an error occurs, the
75 plugin may optionally call the conversation() or plugin_printf()
76 function with SUDO_CONF_ERROR_MSG to present additional error
77 information to the user.
78 The function arguments are as follows:
80 version
82 The version passed in by sudo allows the plugin to determine
83 the major and minor version number of the plugin API sup‐
84 ported by sudo.
85 conversation
87 A pointer to the conversation() function that can be used by
88 the plugin to interact with the user (see Conversation API
89 for details). Returns 0 on success and -1 on failure.
90 plugin_printf
92 A pointer to a printf()-style function that may be used to
93 display informational or error messages (see Conversation API
94 for details). Returns the number of characters printed on
95 success and -1 on failure.
96 settings
98 A vector of user-supplied sudo settings in the form of
99 “name=value” strings. The vector is terminated by a NULL
100 pointer. These settings correspond to options the user spec‐
101 ified when running sudo. As such, they will only be present
102 when the corresponding option has been specified on the com‐
103 mand line.
104 When parsing settings, the plugin should split on the first
106 equal sign (‘=’) since the name field will never include one
107 itself but the value might.
108 The following values may be set by sudo:
110 bsdauth_type=string
112 Authentication type, if specified by the -a option, to
113 use on systems where BSD authentication is supported.
114 closefrom=number
116 If specified, the user has requested via the -C option
117 that sudo close all files descriptors with a value of
118 number or higher. The plugin may optionally pass this,
119 or another value, back in the command_info list.
120 debug_flags=string
122 A debug file path name followed by a space and a comma-
123 separated list of debug flags that correspond to the
124 plugin's Debug entry in sudo.conf(5), if there is one.
125 The flags are passed to the plugin exactly as they
126 appear in sudo.conf(5). The syntax used by sudo and
127 the sudoers plugin is subsystem@priority but a plugin
128 is free to use a different format so long as it does
129 not include a comma (‘,’). Prior to sudo 1.8.12, there
130 was no way to specify plugin-specific debug_flags so
131 the value was always the same as that used by the sudo
132 front end and did not include a path name, only the
133 flags themselves. As of version 1.7 of the plugin
134 interface, sudo will only pass debug_flags if
135 sudo.conf(5) contains a plugin-specific Debug entry.
136 debug_level=number
138 This setting has been deprecated in favor of
139 debug_flags.
140 ignore_ticket=bool
142 Set to true if the user specified the -k option along
143 with a command, indicating that the user wishes to
144 ignore any cached authentication credentials.
145 implied_shell to true. This allows sudo with no argu‐
146 ments to be used similarly to su(1). If the plugin
147 does not to support this usage, it may return a value
148 of -2 from the check_policy() function, which will
149 cause sudo to print a usage message and exit.
150 implied_shell=bool
152 If the user does not specify a program on the command
153 line, sudo will pass the plugin the path to the user's
154 shell and set
155 login_class=string
157 BSD login class to use when setting resource limits and
158 nice value, if specified by the -c option.
159 login_shell=bool
161 Set to true if the user specified the -i option, indi‐
162 cating that the user wishes to run a login shell.
163 max_groups=int
165 The maximum number of groups a user may belong to.
166 This will only be present if there is a corresponding
167 setting in sudo.conf(5).
168 network_addrs=list
170 A space-separated list of IP network addresses and net‐
171 masks in the form “addr/netmask”, e.g.,
172 “192.168.1.2/255.255.255.0”. The address and netmask
173 pairs may be either IPv4 or IPv6, depending on what the
174 operating system supports. If the address contains a
175 colon (‘:’), it is an IPv6 address, else it is IPv4.
176 noninteractive=bool
178 Set to true if the user specified the -n option, indi‐
179 cating that sudo should operate in non-interactive
180 mode. The plugin may reject a command run in non-
181 interactive mode if user interaction is required.
182 plugin_dir=string
184 The default plugin directory used by the sudo front
185 end. This is the default directory set at compile time
186 and may not correspond to the directory the running
187 plugin was loaded from. It may be used by a plugin to
188 locate support files.
189 plugin_path=string
191 The path name of plugin loaded by the sudo front end.
192 The path name will be a fully-qualified unless the
193 plugin was statically compiled into sudo.
194 preserve_environment=bool
196 Set to true if the user specified the -E option, indi‐
197 cating that the user wishes to preserve the environ‐
198 ment.
199 preserve_groups=bool
201 Set to true if the user specified the -P option, indi‐
202 cating that the user wishes to preserve the group vec‐
203 tor instead of setting it based on the runas user.
204 progname=string
206 The command name that sudo was run as, typically “sudo”
207 or “sudoedit”.
208 prompt=string
210 The prompt to use when requesting a password, if speci‐
211 fied via the -p option.
212 remote_host=string
214 The name of the remote host to run the command on, if
215 specified via the -h option. Support for running the
216 command on a remote host is meant to be implemented via
217 a helper program that is executed in place of the user-
218 specified command. The sudo front end is only capable
219 of executing commands on the local host. Only avail‐
220 able starting with API version 1.4.
221 run_shell=bool
223 Set to true if the user specified the -s option, indi‐
224 cating that the user wishes to run a shell.
225 runas_group=string
227 The group name or gid to run the command as, if speci‐
228 fied via the -g option.
229 runas_user=string
231 The user name or uid to run the command as, if speci‐
232 fied via the -u option.
233 selinux_role=string
235 SELinux role to use when executing the command, if
236 specified by the -r option.
237 selinux_type=string
239 SELinux type to use when executing the command, if
240 specified by the -t option.
241 set_home=bool
243 Set to true if the user specified the -H option. If
244 true, set the HOME environment variable to the target
245 user's home directory.
246 sudoedit=bool
248 Set to true when the -e option is specified or if
249 invoked as sudoedit. The plugin shall substitute an
250 editor into argv in the check_policy() function or
251 return -2 with a usage error if the plugin does not
252 support sudoedit. For more information, see the
253 check_policy section.
254 timeout=string
256 User-specified command timeout. Not all plugins sup‐
257 port command timeouts and the ability for the user to
258 set a timeout may be restricted by policy. The format
259 of the timeout string is plugin-specific.
260 Additional settings may be added in the future so the plugin
262 should silently ignore settings that it does not recognize.
263 user_info
265 A vector of information about the user running the command in
266 the form of “name=value” strings. The vector is terminated
267 by a NULL pointer.
268 When parsing user_info, the plugin should split on the first
270 equal sign (‘=’) since the name field will never include one
271 itself but the value might.
272 The following values may be set by sudo:
274 cols=int
276 The number of columns the user's terminal supports. If
277 there is no terminal device available, a default value
278 of 80 is used.
279 cwd=string
281 The user's current working directory.
282 egid=gid_t
284 The effective group-ID of the user invoking sudo.
285 euid=uid_t
287 The effective user-ID of the user invoking sudo.
288 gid=gid_t
290 The real group-ID of the user invoking sudo.
291 groups=list
293 The user's supplementary group list formatted as a
294 string of comma-separated group-IDs.
295 host=string
297 The local machine's hostname as returned by the
298 gethostname(2) system call.
299 lines=int
301 The number of lines the user's terminal supports. If
302 there is no terminal device available, a default value
303 of 24 is used.
304 pgid=int
306 The ID of the process group that the running sudo
307 process is a member of. Only available starting with
308 API version 1.2.
309 pid=int
311 The process ID of the running sudo process. Only
312 available starting with API version 1.2.
313 ppid=int
315 The parent process ID of the running sudo process.
316 Only available starting with API version 1.2.
317 sid=int
319 The session ID of the running sudo process or 0 if sudo
320 is not part of a POSIX job control session. Only
321 available starting with API version 1.2.
322 tcpgid=int
324 The ID of the foreground process group associated with
325 the terminal device associated with the sudo process or
326 0 if there is no terminal present. Only available
327 starting with API version 1.2.
328 tty=string
330 The path to the user's terminal device. If the user
331 has no terminal device associated with the session, the
332 value will be empty, as in “tty=”.
333 uid=uid_t
335 The real user-ID of the user invoking sudo.
336 umask=octal
338 The invoking user's file creation mask. Only available
339 starting with API version 1.10.
340 user=string
342 The name of the user invoking sudo.
343 user_env
345 The user's environment in the form of a NULL-terminated
346 vector of “name=value” strings.
347 When parsing user_env, the plugin should split on the first
349 equal sign (‘=’) since the name field will never include one
350 itself but the value might.
351 plugin_options
353 Any (non-comment) strings immediately after the plugin path
354 are passed as arguments to the plugin. These arguments are
355 split on a white space boundary and are passed to the plugin
356 in the form of a NULL-terminated array of strings. If no
357 arguments were specified, plugin_options will be the NULL
358 pointer.
359 NOTE: the plugin_options parameter is only available starting
361 with API version 1.2. A plugin must check the API version
362 specified by the sudo front end before using plugin_options.
363 Failure to do so may result in a crash.
364 errstr
366 If the open() function returns a value other than 1, the
367 plugin may store a message describing the failure or error in
368 errstr. The sudo front end will then pass this value to any
369 registered audit plugins. The string stored in errstr must
370 remain valid until the plugin's close() function is called.
371 NOTE: the errstr parameter is only available starting with
373 API version 1.15. A plugin must check the API version speci‐
374 fied by the sudo front end before using errstr. Failure to
375 do so may result in a crash.
376 close
378 void (*close)(int exit_status, int error);
379 The close() function is called when sudo is finished, shortly
381 before it exits. Starting with API version 1.15, close() is called
382 regardless of whether or not a command was actually executed. This
383 makes it possible for plugins to perform cleanup even when a com‐
384 mand was not run. It is not possible to tell whether a command was
385 run based solely on the arguments passed to the close() function.
386 To determine if a command was actually run, the plugin must keep
387 track of whether or not the check_policy() function returned suc‐
388 cessfully.
389 The function arguments are as follows:
391 exit_status
393 The command's exit status, as returned by the wait(2) system
394 call, or zero if no command was run. The value of
395 exit_status is undefined if error is non-zero.
396 error
398 If the command could not be executed, this is set to the
399 value of errno set by the execve(2) system call. The plugin
400 is responsible for displaying error information via the
401 conversation() or plugin_printf() function. If the command
402 was successfully executed, the value of error is zero.
403 If no close() function is defined, no I/O logging plugins are
405 loaded, and neither the timeout not use_pty options are set in the
406 command_info list, the sudo front end may execute the command
407 directly instead of running it as a child process.
408 show_version
410 int (*show_version)(int verbose);
411 The show_version() function is called by sudo when the user speci‐
413 fies the -V option. The plugin may display its version information
414 to the user via the conversation() or plugin_printf() function
415 using SUDO_CONV_INFO_MSG. If the user requests detailed version
416 information, the verbose flag will be set.
417 Returns 1 on success, 0 on failure, -1 if a general error occurred,
419 or -2 if there was a usage error, although the return value is cur‐
420 rently ignored.
421 check_policy
423 int (*check_policy)(int argc, char * const argv[], char *env_add[],
424 char **command_info[], char **argv_out[], char **user_env_out[],
425 const char **errstr);
426 The check_policy() function is called by sudo to determine whether
428 the user is allowed to run the specified commands.
429 If the sudoedit option was enabled in the settings array passed to
431 the open() function, the user has requested sudoedit mode.
432 sudoedit is a mechanism for editing one or more files where an edi‐
433 tor is run with the user's credentials instead of with elevated
434 privileges. sudo achieves this by creating user-writable temporary
435 copies of the files to be edited and then overwriting the originals
436 with the temporary copies after editing is complete. If the plugin
437 supports sudoedit, it should choose the editor to be used, poten‐
438 tially from a variable in the user's environment, such as EDITOR,
439 and include it in argv_out (note that environment variables may
440 include command line options). The files to be edited should be
441 copied from argv into argv_out, separated from the editor and its
442 arguments by a “--” element. The “--” will be removed by sudo
443 before the editor is executed. The plugin should also set
444 sudoedit=true in the command_info list.
445 The check_policy() function returns 1 if the command is allowed, 0
447 if not allowed, -1 for a general error, or -2 for a usage error or
448 if sudoedit was specified but is unsupported by the plugin. In the
449 latter case, sudo will print a usage message before it exits. If
450 an error occurs, the plugin may optionally call the conversation()
451 or plugin_printf() function with SUDO_CONF_ERROR_MSG to present
452 additional error information to the user.
453 The function arguments are as follows:
455 argc The number of elements in argv, not counting the final NULL
457 pointer.
458 argv The argument vector describing the command the user wishes to
460 run, in the same form as what would be passed to the
461 execve(2) system call. The vector is terminated by a NULL
462 pointer.
463 env_add
465 Additional environment variables specified by the user on the
466 command line in the form of a NULL-terminated vector of
467 “name=value” strings. The plugin may reject the command if
468 one or more variables are not allowed to be set, or it may
469 silently ignore such variables.
470 When parsing env_add, the plugin should split on the first
472 equal sign (‘=’) since the name field will never include one
473 itself but the value might.
474 command_info
476 Information about the command being run in the form of
477 “name=value” strings. These values are used by sudo to set
478 the execution environment when running a command. The plugin
479 is responsible for creating and populating the vector, which
480 must be terminated with a NULL pointer. The following values
481 are recognized by sudo:
482 chroot=string
484 The root directory to use when running the command.
485 closefrom=number
487 If specified, sudo will close all files descriptors
488 with a value of number or higher.
489 command=string
491 Fully qualified path to the command to be executed.
492 cwd=string
494 The current working directory to change to when execut‐
495 ing the command.
496 exec_background=bool
498 By default, sudo runs a command as the foreground
499 process as long as sudo itself is running in the fore‐
500 ground. When exec_background is enabled and the com‐
501 mand is being run in a pseudo-terminal (due to I/O log‐
502 ging or the use_pty setting), the command will be run
503 as a background process. Attempts to read from the
504 controlling terminal (or to change terminal settings)
505 will result in the command being suspended with the
506 SIGTTIN signal (or SIGTTOU in the case of terminal set‐
507 tings). If this happens when sudo is a foreground
508 process, the command will be granted the controlling
509 terminal and resumed in the foreground with no user
510 intervention required. The advantage of initially run‐
511 ning the command in the background is that sudo need
512 not read from the terminal unless the command explic‐
513 itly requests it. Otherwise, any terminal input must
514 be passed to the command, whether it has required it or
515 not (the kernel buffers terminals so it is not possible
516 to tell whether the command really wants the input).
517 This is different from historic sudo behavior or when
518 the command is not being run in a pseudo-terminal.
519 For this to work seamlessly, the operating system must
521 support the automatic restarting of system calls.
522 Unfortunately, not all operating systems do this by
523 default, and even those that do may have bugs. For
524 example, macOS fails to restart the tcgetattr() and
525 tcsetattr() system calls (this is a bug in macOS).
526 Furthermore, because this behavior depends on the com‐
527 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
528 grams that catch these signals and suspend themselves
529 with a different signal (usually SIGTOP) will not be
530 automatically foregrounded. Some versions of the linux
531 su(1) command behave this way. Because of this, a
532 plugin should not set exec_background unless it is
533 explicitly enabled by the administrator and there
534 should be a way to enabled or disable it on a per-com‐
535 mand basis.
536 This setting has no effect unless I/O logging is
538 enabled or use_pty is enabled.
539 execfd=number
541 If specified, sudo will use the fexecve(2) system call
542 to execute the command instead of execve(2). The spec‐
543 ified number must refer to an open file descriptor.
544 iolog_compress=bool
546 Set to true if the I/O logging plugins, if any, should
547 compress the log data. This is a hint to the I/O log‐
548 ging plugin which may choose to ignore it.
549 iolog_group=string
551 The group that will own newly created I/O log files and
552 directories. This is a hint to the I/O logging plugin
553 which may choose to ignore it.
554 iolog_mode=octal
556 The file permission mode to use when creating I/O log
557 files and directories. This is a hint to the I/O log‐
558 ging plugin which may choose to ignore it.
559 iolog_user=string
561 The user that will own newly created I/O log files and
562 directories. This is a hint to the I/O logging plugin
563 which may choose to ignore it.
564 iolog_path=string
566 Fully qualified path to the file or directory in which
567 I/O log is to be stored. This is a hint to the I/O
568 logging plugin which may choose to ignore it. If no
569 I/O logging plugin is loaded, this setting has no
570 effect.
571 iolog_stdin=bool
573 Set to true if the I/O logging plugins, if any, should
574 log the standard input if it is not connected to a ter‐
575 minal device. This is a hint to the I/O logging plugin
576 which may choose to ignore it.
577 iolog_stdout=bool
579 Set to true if the I/O logging plugins, if any, should
580 log the standard output if it is not connected to a
581 terminal device. This is a hint to the I/O logging
582 plugin which may choose to ignore it.
583 iolog_stderr=bool
585 Set to true if the I/O logging plugins, if any, should
586 log the standard error if it is not connected to a ter‐
587 minal device. This is a hint to the I/O logging plugin
588 which may choose to ignore it.
589 iolog_ttyin=bool
591 Set to true if the I/O logging plugins, if any, should
592 log all terminal input. This only includes input typed
593 by the user and not from a pipe or redirected from a
594 file. This is a hint to the I/O logging plugin which
595 may choose to ignore it.
596 iolog_ttyout=bool
598 Set to true if the I/O logging plugins, if any, should
599 log all terminal output. This only includes output to
600 the screen, not output to a pipe or file. This is a
601 hint to the I/O logging plugin which may choose to
602 ignore it.
603 login_class=string
605 BSD login class to use when setting resource limits and
606 nice value (optional). This option is only set on sys‐
607 tems that support login classes.
608 nice=int
610 Nice value (priority) to use when executing the com‐
611 mand. The nice value, if specified, overrides the pri‐
612 ority associated with the login_class on BSD systems.
613 noexec=bool
615 If set, prevent the command from executing other pro‐
616 grams.
617 preserve_fds=list
619 A comma-separated list of file descriptors that should
620 be preserved, regardless of the value of the closefrom
621 setting. Only available starting with API version 1.5.
622 preserve_groups=bool
624 If set, sudo will preserve the user's group vector
625 instead of initializing the group vector based on
626 runas_user.
627 runas_egid=gid
629 Effective group-ID to run the command as. If not spec‐
630 ified, the value of runas_gid is used.
631 runas_euid=uid
633 Effective user-ID to run the command as. If not speci‐
634 fied, the value of runas_uid is used.
635 runas_gid=gid
637 Group-ID to run the command as.
638 runas_group=string
640 The name of the group the command will run as, if it is
641 different from the runas_user's default group. This
642 value is provided for auditing purposes only, the sudo
643 front-end uses runas_egid and runas_gid when executing
644 the command.
645 runas_groups=list
647 The supplementary group vector to use for the command
648 in the form of a comma-separated list of group-IDs. If
649 preserve_groups is set, this option is ignored.
650 runas_uid=uid
652 User-ID to run the command as.
653 runas_user=string
655 The name of the user the command will run as, which
656 should correspond to runas_euid (or runas_uid if
657 runas_euid is not set). This value is provided for
658 auditing purposes only, the sudo front-end uses
659 runas_euid and runas_uid when executing the command.
660 selinux_role=string
662 SELinux role to use when executing the command.
663 selinux_type=string
665 SELinux type to use when executing the command.
666 set_utmp=bool
668 Create a utmp (or utmpx) entry when a pseudo-terminal
669 is allocated. By default, the new entry will be a copy
670 of the user's existing utmp entry (if any), with the
671 tty, time, type and pid fields updated.
672 sudoedit=bool
674 Set to true when in sudoedit mode. The plugin may
675 enable sudoedit mode even if sudo was not invoked as
676 sudoedit. This allows the plugin to perform command
677 substitution and transparently enable sudoedit when the
678 user attempts to run an editor.
679 sudoedit_checkdir=bool
681 Set to false to disable directory writability checks in
682 sudoedit. By default, sudoedit 1.8.16 and higher will
683 check all directory components of the path to be edited
684 for writability by the invoking user. Symbolic links
685 will not be followed in writable directories and
686 sudoedit will refuse to edit a file located in a
687 writable directory. These restrictions are not
688 enforced when sudoedit is run by root. The
689 sudoedit_follow option can be set to false to disable
690 this check. Only available starting with API version
691 1.8.
692 sudoedit_follow=bool
694 Set to true to allow sudoedit to edit files that are
695 symbolic links. By default, sudoedit 1.8.15 and higher
696 will refuse to open a symbolic link. The
697 sudoedit_follow option can be used to restore the older
698 behavior and allow sudoedit to open symbolic links.
699 Only available starting with API version 1.8.
700 timeout=int
702 Command timeout. If non-zero then when the timeout
703 expires the command will be killed.
704 umask=octal
706 The file creation mask to use when executing the com‐
707 mand. This value may be overridden by PAM or
708 login.conf on some systems unless the umask_override
709 option is also set.
710 umask_override=bool
712 Force the value specified by the umask option to over‐
713 ride any umask set by PAM or login.conf.
714 use_pty=bool
716 Allocate a pseudo-terminal to run the command in,
717 regardless of whether or not I/O logging is in use. By
718 default, sudo will only run the command in a pseudo-
719 terminal when an I/O log plugin is loaded.
720 utmp_user=string
722 User name to use when constructing a new utmp (or
723 utmpx) entry when set_utmp is enabled. This option can
724 be used to set the user field in the utmp entry to the
725 user the command runs as rather than the invoking user.
726 If not set, sudo will base the new entry on the invok‐
727 ing user's existing entry.
728 Unsupported values will be ignored.
730 argv_out
732 The NULL-terminated argument vector to pass to the execve(2)
733 system call when executing the command. The plugin is
734 responsible for allocating and populating the vector.
735 user_env_out
737 The NULL-terminated environment vector to use when executing
738 the command. The plugin is responsible for allocating and
739 populating the vector.
740 errstr
742 If the check_policy() function returns a value other than 1,
743 the plugin may store a message describing the failure or
744 error in errstr. The sudo front end will then pass this
745 value to any registered audit plugins. The string stored in
746 errstr must remain valid until the plugin's close() function
747 is called.
748 NOTE: the errstr parameter is only available starting with
750 API version 1.15. A plugin must check the API version speci‐
751 fied by the sudo front end before using errstr. Failure to
752 do so may result in a crash.
753 list
755 int (*list)(int argc, char * const argv[], int verbose,
756 const char *list_user, const char **errstr);
757 List available privileges for the invoking user. Returns 1 on suc‐
759 cess, 0 on failure and -1 on error. On error, the plugin may
760 optionally call the conversation() or plugin_printf() function with
761 SUDO_CONF_ERROR_MSG to present additional error information to the
762 user.
763 Privileges should be output via the conversation() or
765 plugin_printf() function using SUDO_CONV_INFO_MSG.
766 The function arguments are as follows:
768 argc The number of elements in argv, not counting the final NULL
770 pointer.
771 argv If non-NULL, an argument vector describing a command the user
773 wishes to check against the policy in the same form as what
774 would be passed to the execve(2) system call. If the command
775 is permitted by the policy, the fully-qualified path to the
776 command should be displayed along with any command line argu‐
777 ments.
778 verbose
780 Flag indicating whether to list in verbose mode or not.
781 list_user
783 The name of a different user to list privileges for if the
784 policy allows it. If NULL, the plugin should list the privi‐
785 leges of the invoking user.
786 errstr
788 If the list() function returns a value other than 1, the
789 plugin may store a message describing the failure or error in
790 errstr. The sudo front end will then pass this value to any
791 registered audit plugins. The string stored in errstr must
792 remain valid until the plugin's close() function is called.
793 NOTE: the errstr parameter is only available starting with
795 API version 1.15. A plugin must check the API version speci‐
796 fied by the sudo front end before using errstr. Failure to
797 do so may result in a crash.
798 validate
800 int (*validate)(const char **errstr);
801 The validate() function is called when sudo is run with the -v
803 option. For policy plugins such as sudoers that cache authentica‐
804 tion credentials, this function will validate and cache the creden‐
805 tials.
806 The validate() function should be NULL if the plugin does not sup‐
808 port credential caching.
809 Returns 1 on success, 0 on failure and -1 on error. On error, the
811 plugin may optionally call the conversation() or plugin_printf()
812 function with SUDO_CONF_ERROR_MSG to present additional error
813 information to the user.
814 The function arguments are as follows:
816 errstr
818 If the validate() function returns a value other than 1, the
819 plugin may store a message describing the failure or error in
820 errstr. The sudo front end will then pass this value to any
821 registered audit plugins. The string stored in errstr must
822 remain valid until the plugin's close() function is called.
823 NOTE: the errstr parameter is only available starting with
825 API version 1.15. A plugin must check the API version speci‐
826 fied by the sudo front end before using errstr. Failure to
827 do so may result in a crash.
828 invalidate
830 void (*invalidate)(int remove);
831 The invalidate() function is called when sudo is run with the -k or
833 -K option. For policy plugins such as sudoers that cache authenti‐
834 cation credentials, this function will invalidate the credentials.
835 If the remove flag is set, the plugin may remove the credentials
836 instead of simply invalidating them.
837 The invalidate() function should be NULL if the plugin does not
839 support credential caching.
840 init_session
842 int (*init_session)(struct passwd *pwd, char **user_env_out[]);
843 The init_session() function is called before sudo sets up the exe‐
845 cution environment for the command. It is run in the parent sudo
846 process and before any uid or gid changes. This can be used to
847 perform session setup that is not supported by command_info, such
848 as opening the PAM session. The close() function can be used to
849 tear down the session that was opened by init_session.
850 The pwd argument points to a passwd struct for the user the command
852 will be run as if the uid the command will run as was found in the
853 password database, otherwise it will be NULL.
854 The user_env_out argument points to the environment the command
856 will run in, in the form of a NULL-terminated vector of
857 “name=value” strings. This is the same string passed back to the
858 front end via the Policy Plugin's user_env_out parameter. If the
859 init_session() function needs to modify the user environment, it
860 should update the pointer stored in user_env_out. The expected use
861 case is to merge the contents of the PAM environment (if any) with
862 the contents of user_env_out. NOTE: the user_env_out parameter is
863 only available starting with API version 1.2. A plugin must check
864 the API version specified by the sudo front end before using
865 user_env_out. Failure to do so may result in a crash.
866 Returns 1 on success, 0 on failure and -1 on error. On error, the
868 plugin may optionally call the conversation() or plugin_printf()
869 function with SUDO_CONF_ERROR_MSG to present additional error
870 information to the user.
871 register_hooks
873 void (*register_hooks)(int version,
874 int (*register_hook)(struct sudo_hook *hook));
875 The register_hooks() function is called by the sudo front end to
877 register any hooks the plugin needs. If the plugin does not sup‐
878 port hooks, register_hooks should be set to the NULL pointer.
879 The version argument describes the version of the hooks API sup‐
881 ported by the sudo front end.
882 The register_hook() function should be used to register any sup‐
884 ported hooks the plugin needs. It returns 0 on success, 1 if the
885 hook type is not supported and -1 if the major version in struct
886 hook does not match the front end's major hook API version.
887 See the Hook function API section below for more information about
889 hooks.
890 NOTE: the register_hooks() function is only available starting with
892 API version 1.2. If the sudo front end doesn't support API version
893 1.2 or higher, register_hooks will not be called.
894 deregister_hooks
896 void (*deregister_hooks)(int version,
897 int (*deregister_hook)(struct sudo_hook *hook));
898 The deregister_hooks() function is called by the sudo front end to
900 deregister any hooks the plugin has registered. If the plugin does
901 not support hooks, deregister_hooks should be set to the NULL
902 pointer.
903 The version argument describes the version of the hooks API sup‐
905 ported by the sudo front end.
906 The deregister_hook() function should be used to deregister any
908 hooks that were put in place by the register_hook() function. If
909 the plugin tries to deregister a hook that the front end does not
910 support, deregister_hook will return an error.
911 See the Hook function API section below for more information about
913 hooks.
914 NOTE: the deregister_hooks() function is only available starting
916 with API version 1.2. If the sudo front end doesn't support API
917 version 1.2 or higher, deregister_hooks will not be called.
918 event_alloc
920 struct sudo_plugin_event * (*event_alloc)(void);
921 The event_alloc() function is used to allocate a struct
923 sudo_plugin_event which provides access to the main sudo event
924 loop. Unlike the other fields, the event_alloc() pointer is filled
925 in by the sudo front end, not by the plugin.
926 See the Event API section below for more information about events.
928 NOTE: the event_alloc() function is only available starting with
930 API version 1.15. If the sudo front end doesn't support API ver‐
931 sion 1.15 or higher, event_alloc() will not be set.
932 errstr
934 If the init_session() function returns a value other than 1, the
935 plugin may store a message describing the failure or error in
936 errstr. The sudo front end will then pass this value to any regis‐
937 tered audit plugins. The string stored in errstr must remain valid
938 until the plugin's close() function is called.
939 NOTE: the errstr parameter is only available starting with API ver‐
941 sion 1.15. A plugin must check the API version specified by the
942 sudo front end before using errstr. Failure to do so may result in
943 a crash.
944 Policy Plugin Version Macros
946 /* Plugin API version major/minor. */
948 #define SUDO_API_VERSION_MAJOR 1
949 #define SUDO_API_VERSION_MINOR 13
950 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
951 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
952 SUDO_API_VERSION_MINOR)
953 /* Getters and setters for API version */
955 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
956 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
957 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
958 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
959 } while(0)
960 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
961 *(vp) = (*(vp) & 0xffff0000) | (n); \
962 } while(0)
963 I/O plugin API
965 struct io_plugin {
966 #define SUDO_IO_PLUGIN 2
967 unsigned int type; /* always SUDO_IO_PLUGIN */
968 unsigned int version; /* always SUDO_API_VERSION */
969 int (*open)(unsigned int version, sudo_conv_t conversation,
970 sudo_printf_t plugin_printf, char * const settings[],
971 char * const user_info[], char * const command_info[],
972 int argc, char * const argv[], char * const user_env[],
973 char * const plugin_options[], const char **errstr);
974 void (*close)(int exit_status, int error); /* wait status or error */
975 int (*show_version)(int verbose);
976 int (*log_ttyin)(const char *buf, unsigned int len,
977 const char **errstr);
978 int (*log_ttyout)(const char *buf, unsigned int len,
979 const char **errstr);
980 int (*log_stdin)(const char *buf, unsigned int len,
981 const char **errstr);
982 int (*log_stdout)(const char *buf, unsigned int len,
983 const char **errstr);
984 int (*log_stderr)(const char *buf, unsigned int len,
985 const char **errstr);
986 void (*register_hooks)(int version,
987 int (*register_hook)(struct sudo_hook *hook));
988 void (*deregister_hooks)(int version,
989 int (*deregister_hook)(struct sudo_hook *hook));
990 int (*change_winsize)(unsigned int lines, unsigned int cols,
991 const char **errstr);
992 int (*log_suspend)(int signo, const char **errstr);
993 struct sudo_plugin_event * (*event_alloc)(void);
994 };
995 When an I/O plugin is loaded, sudo runs the command in a pseudo-terminal.
997 This makes it possible to log the input and output from the user's ses‐
998 sion. If any of the standard input, standard output or standard error do
999 not correspond to a tty, sudo will open a pipe to capture the I/O for
1000 logging before passing it on.
1001 The log_ttyin function receives the raw user input from the terminal
1003 device (note that this will include input even when echo is disabled,
1004 such as when a password is read). The log_ttyout function receives out‐
1005 put from the pseudo-terminal that is suitable for replaying the user's
1006 session at a later time. The log_stdin(), log_stdout() and log_stderr()
1007 functions are only called if the standard input, standard output or stan‐
1008 dard error respectively correspond to something other than a tty.
1009 Any of the logging functions may be set to the NULL pointer if no logging
1011 is to be performed. If the open function returns 0, no I/O will be sent
1012 to the plugin.
1013 If a logging function returns an error (-1), the running command will be
1015 terminated and all of the plugin's logging functions will be disabled.
1016 Other I/O logging plugins will still receive any remaining input or out‐
1017 put that has not yet been processed.
1018 If an input logging function rejects the data by returning 0, the command
1020 will be terminated and the data will not be passed to the command, though
1021 it will still be sent to any other I/O logging plugins. If an output
1022 logging function rejects the data by returning 0, the command will be
1023 terminated and the data will not be written to the terminal, though it
1024 will still be sent to any other I/O logging plugins.
1025 The audit_plugin struct has the following fields:
1027 type The type field should always be set to SUDO_IO_PLUGIN.
1029 version
1031 The version field should be set to SUDO_API_VERSION.
1032 This allows sudo to determine the API version the plugin was built
1034 against.
1035 open
1037 int (*open)(unsigned int version, sudo_conv_t conversation,
1038 sudo_printf_t plugin_printf, char * const settings[],
1039 char * const user_info[], char * const command_info[],
1040 int argc, char * const argv[], char * const user_env[],
1041 char * const plugin_options[]);
1042 The open() function is run before the log_ttyin(), log_ttyout(),
1044 log_stdin(), log_stdout(), log_stderr(), log_suspend(),
1045 change_winsize(), or show_version() functions are called. It is
1046 only called if the version is being requested or if the policy
1047 plugin's check_policy() function has returned successfully. It
1048 returns 1 on success, 0 on failure, -1 if a general error occurred,
1049 or -2 if there was a usage error. In the latter case, sudo will
1050 print a usage message before it exits. If an error occurs, the
1051 plugin may optionally call the conversation() or plugin_printf()
1052 function with SUDO_CONF_ERROR_MSG to present additional error
1053 information to the user.
1054 The function arguments are as follows:
1056 version
1058 The version passed in by sudo allows the plugin to determine
1059 the major and minor version number of the plugin API sup‐
1060 ported by sudo.
1061 conversation
1063 A pointer to the conversation() function that may be used by
1064 the show_version() function to display version information
1065 (see show_version() below). The conversation() function may
1066 also be used to display additional error message to the user.
1067 The conversation() function returns 0 on success and -1 on
1068 failure.
1069 plugin_printf
1071 A pointer to a printf()-style function that may be used by
1072 the show_version() function to display version information
1073 (see show_version below). The plugin_printf() function may
1074 also be used to display additional error message to the user.
1075 The plugin_printf() function returns number of characters
1076 printed on success and -1 on failure.
1077 settings
1079 A vector of user-supplied sudo settings in the form of
1080 “name=value” strings. The vector is terminated by a NULL
1081 pointer. These settings correspond to options the user spec‐
1082 ified when running sudo. As such, they will only be present
1083 when the corresponding option has been specified on the com‐
1084 mand line.
1085 When parsing settings, the plugin should split on the first
1087 equal sign (‘=’) since the name field will never include one
1088 itself but the value might.
1089 See the Policy plugin API section for a list of all possible
1091 settings.
1092 user_info
1094 A vector of information about the user running the command in
1095 the form of “name=value” strings. The vector is terminated
1096 by a NULL pointer.
1097 When parsing user_info, the plugin should split on the first
1099 equal sign (‘=’) since the name field will never include one
1100 itself but the value might.
1101 See the Policy plugin API section for a list of all possible
1103 strings.
1104 command_info
1106 A vector of information describing the command being run in
1107 the form of “name=value” strings. The vector is terminated
1108 by a NULL pointer.
1109 When parsing command_info, the plugin should split on the
1111 first equal sign (‘=’) since the name field will never
1112 include one itself but the value might.
1113 See the Policy plugin API section for a list of all possible
1115 strings.
1116 argc The number of elements in argv, not counting the final NULL
1118 pointer. It can be zero, when sudo is called with -V.
1119 argv If non-NULL, an argument vector describing a command the user
1121 wishes to run in the same form as what would be passed to the
1122 execve(2) system call.
1123 user_env
1125 The user's environment in the form of a NULL-terminated vec‐
1126 tor of “name=value” strings.
1127 When parsing user_env, the plugin should split on the first
1129 equal sign (‘=’) since the name field will never include one
1130 itself but the value might.
1131 plugin_options
1133 Any (non-comment) strings immediately after the plugin path
1134 are treated as arguments to the plugin. These arguments are
1135 split on a white space boundary and are passed to the plugin
1136 in the form of a NULL-terminated array of strings. If no
1137 arguments were specified, plugin_options will be the NULL
1138 pointer.
1139 NOTE: the plugin_options parameter is only available starting
1141 with API version 1.2. A plugin must check the API version
1142 specified by the sudo front end before using plugin_options.
1143 Failure to do so may result in a crash.
1144 errstr
1146 If the open() function returns a value other than 1, the
1147 plugin may store a message describing the failure or error in
1148 errstr. The sudo front end will then pass this value to any
1149 registered audit plugins. The string stored in errstr must
1150 remain valid until the plugin's close() function is called.
1151 NOTE: the errstr parameter is only available starting with
1153 API version 1.15. A plugin must check the API version speci‐
1154 fied by the sudo front end before using errstr. Failure to
1155 do so may result in a crash.
1156 close
1158 void (*close)(int exit_status, int error);
1159 The close() function is called when sudo is finished, shortly
1161 before it exits.
1162 The function arguments are as follows:
1164 exit_status
1166 The command's exit status, as returned by the wait(2) system
1167 call, or zero if no command was run. The value of
1168 exit_status is undefined if error is non-zero.
1169 error
1171 If the command could not be executed, this is set to the
1172 value of errno set by the execve(2) system call. If the com‐
1173 mand was successfully executed, the value of error is zero.
1174 show_version
1176 int (*show_version)(int verbose);
1177 The show_version() function is called by sudo when the user speci‐
1179 fies the -V option. The plugin may display its version information
1180 to the user via the conversation() or plugin_printf() function
1181 using SUDO_CONV_INFO_MSG.
1182 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1184 or -2 if there was a usage error, although the return value is cur‐
1185 rently ignored.
1186 log_ttyin
1188 int (*log_ttyin)(const char *buf, unsigned int len,
1189 const char **errstr);
1190 The log_ttyin() function is called whenever data can be read from
1192 the user but before it is passed to the running command. This
1193 allows the plugin to reject data if it chooses to (for instance if
1194 the input contains banned content). Returns 1 if the data should
1195 be passed to the command, 0 if the data is rejected (which will
1196 terminate the running command) or -1 if an error occurred.
1197 The function arguments are as follows:
1199 buf The buffer containing user input.
1201 len The length of buf in bytes.
1203 errstr
1205 If the log_ttyin() function returns a value other than 1, the
1206 plugin may store a message describing the failure or error in
1207 errstr. The sudo front end will then pass this value to any
1208 registered audit plugins. The string stored in errstr must
1209 remain valid until the plugin's close() function is called.
1210 NOTE: the errstr parameter is only available starting with
1212 API version 1.15. A plugin must check the API version speci‐
1213 fied by the sudo front end before using errstr. Failure to
1214 do so may result in a crash.
1215 log_ttyout
1217 int (*log_ttyout)(const char *buf, unsigned int len,
1218 const char **errstr);
1219 The log_ttyout() function is called whenever data can be read from
1221 the command but before it is written to the user's terminal. This
1222 allows the plugin to reject data if it chooses to (for instance if
1223 the output contains banned content). Returns 1 if the data should
1224 be passed to the user, 0 if the data is rejected (which will termi‐
1225 nate the running command) or -1 if an error occurred.
1226 The function arguments are as follows:
1228 buf The buffer containing command output.
1230 len The length of buf in bytes.
1232 errstr
1234 If the log_ttyout() function returns a value other than 1,
1235 the plugin may store a message describing the failure or
1236 error in errstr. The sudo front end will then pass this
1237 value to any registered audit plugins. The string stored in
1238 errstr must remain valid until the plugin's close() function
1239 is called.
1240 NOTE: the errstr parameter is only available starting with
1242 API version 1.15. A plugin must check the API version speci‐
1243 fied by the sudo front end before using errstr. Failure to
1244 do so may result in a crash.
1245 log_stdin
1247 int (*log_stdin)(const char *buf, unsigned int len,
1248 const char **errstr);
1249 The log_stdin() function is only used if the standard input does
1251 not correspond to a tty device. It is called whenever data can be
1252 read from the standard input but before it is passed to the running
1253 command. This allows the plugin to reject data if it chooses to
1254 (for instance if the input contains banned content). Returns 1 if
1255 the data should be passed to the command, 0 if the data is rejected
1256 (which will terminate the running command) or -1 if an error
1257 occurred.
1258 The function arguments are as follows:
1260 buf The buffer containing user input.
1262 len The length of buf in bytes.
1264 errstr
1266 If the log_stdin() function returns a value other than 1, the
1267 plugin may store a message describing the failure or error in
1268 errstr. The sudo front end will then pass this value to any
1269 registered audit plugins. The string stored in errstr must
1270 remain valid until the plugin's close() function is called.
1271 NOTE: the errstr parameter is only available starting with
1273 API version 1.15. A plugin must check the API version speci‐
1274 fied by the sudo front end before using errstr. Failure to
1275 do so may result in a crash.
1276 log_stdout
1278 int (*log_stdout)(const char *buf, unsigned int len,
1279 const char **errstr);
1280 The log_stdout() function is only used if the standard output does
1282 not correspond to a tty device. It is called whenever data can be
1283 read from the command but before it is written to the standard out‐
1284 put. This allows the plugin to reject data if it chooses to (for
1285 instance if the output contains banned content). Returns 1 if the
1286 data should be passed to the user, 0 if the data is rejected (which
1287 will terminate the running command) or -1 if an error occurred.
1288 The function arguments are as follows:
1290 buf The buffer containing command output.
1292 len The length of buf in bytes.
1294 errstr
1296 If the log_stdout() function returns a value other than 1,
1297 the plugin may store a message describing the failure or
1298 error in errstr. The sudo front end will then pass this
1299 value to any registered audit plugins. The string stored in
1300 errstr must remain valid until the plugin's close() function
1301 is called.
1302 NOTE: the errstr parameter is only available starting with
1304 API version 1.15. A plugin must check the API version speci‐
1305 fied by the sudo front end before using errstr. Failure to
1306 do so may result in a crash.
1307 log_stderr
1309 int (*log_stderr)(const char *buf, unsigned int len,
1310 const char **errstr);
1311 The log_stderr() function is only used if the standard error does
1313 not correspond to a tty device. It is called whenever data can be
1314 read from the command but before it is written to the standard
1315 error. This allows the plugin to reject data if it chooses to (for
1316 instance if the output contains banned content). Returns 1 if the
1317 data should be passed to the user, 0 if the data is rejected (which
1318 will terminate the running command) or -1 if an error occurred.
1319 The function arguments are as follows:
1321 buf The buffer containing command output.
1323 len The length of buf in bytes.
1325 errstr
1327 If the log_stderr() function returns a value other than 1,
1328 the plugin may store a message describing the failure or
1329 error in errstr. The sudo front end will then pass this
1330 value to any registered audit plugins. The string stored in
1331 errstr must remain valid until the plugin's close() function
1332 is called.
1333 NOTE: the errstr parameter is only available starting with
1335 API version 1.15. A plugin must check the API version speci‐
1336 fied by the sudo front end before using errstr. Failure to
1337 do so may result in a crash.
1338 register_hooks
1340 See the Policy plugin API section for a description of
1341 register_hooks.
1342 deregister_hooks
1344 See the Policy plugin API section for a description of
1345 deregister_hooks.
1346 change_winsize
1348 int (*change_winsize)(unsigned int lines, unsigned int cols,
1349 const char **errstr);
1350 The change_winsize() function is called whenever the window size of
1352 the terminal changes from the initial values specified in the
1353 user_info list. Returns -1 if an error occurred, in which case no
1354 further calls to change_winsize() will be made,
1355 The function arguments are as follows:
1357 lines
1359 The number of lines (rows) in the re-sized terminal.
1360 cols The number of columns in the re-sized terminal.
1362 errstr
1364 If the change_winsize() function returns a value other than
1365 1, the plugin may store a message describing the failure or
1366 error in errstr. The sudo front end will then pass this
1367 value to any registered audit plugins. The string stored in
1368 errstr must remain valid until the plugin's close() function
1369 is called.
1370 NOTE: the errstr parameter is only available starting with
1372 API version 1.15. A plugin must check the API version speci‐
1373 fied by the sudo front end before using errstr. Failure to
1374 do so may result in a crash.
1375 log_suspend
1377 int (*log_suspend)(int signo, const char **errstr);
1378 The log_suspend() function is called whenever a command is sus‐
1380 pended or resumed. Logging this information makes it possible to
1381 skip the period of time when the command was suspended during play‐
1382 back of a session. Returns -1 if an error occurred, in which case
1383 no further calls to log_suspend() will be made,
1384 The function arguments are as follows:
1386 signo
1388 The signal that caused the command to be suspended, or
1389 SIGCONT if the command was resumed.
1390 errstr
1392 If the log_suspend() function returns a value other than 1,
1393 the plugin may store a message describing the failure or
1394 error in errstr. The sudo front end will then pass this
1395 value to any registered audit plugins. The string stored in
1396 errstr must remain valid until the plugin's close() function
1397 is called.
1398 NOTE: the errstr parameter is only available starting with
1400 API version 1.15. A plugin must check the API version speci‐
1401 fied by the sudo front end before using errstr. Failure to
1402 do so may result in a crash.
1403 event_alloc
1405 struct sudo_plugin_event * (*event_alloc)(void);
1406 The event_alloc() function is used to allocate a struct
1408 sudo_plugin_event which provides access to the main sudo
1409 event loop. Unlike the other fields, the event_alloc()
1410 pointer is filled in by the sudo front end, not by the plug‐
1411 in.
1412 See the Event API section below for more information about
1414 events.
1415 NOTE: the event_alloc() function is only available starting
1417 with API version 1.15. If the sudo front end doesn't support
1418 API version 1.15 or higher, event_alloc() will not be set.
1419 I/O Plugin Version Macros
1421 Same as for the Policy plugin API.
1423 Audit plugin API
1425 /* Audit plugin close function status types. */
1426 #define SUDO_PLUGIN_NO_STATUS 0
1427 #define SUDO_PLUGIN_WAIT_STATUS 1
1428 #define SUDO_PLUGIN_EXEC_ERROR 2
1429 #define SUDO_PLUGIN_SUDO_ERROR 3
1430 #define SUDO_AUDIT_PLUGIN 3
1432 struct audit_plugin {
1433 unsigned int type; /* always SUDO_AUDIT_PLUGIN */
1434 unsigned int version; /* always SUDO_API_VERSION */
1435 int (*open)(unsigned int version, sudo_conv_t conversation,
1436 sudo_printf_t sudo_printf, char * const settings[],
1437 char * const user_info[], int submit_optind,
1438 char * const submit_argv[], char * const submit_envp[],
1439 char * const plugin_options[], const char **errstr);
1440 void (*close)(int status_type, int status);
1441 int (*accept)(const char *plugin_name,
1442 unsigned int plugin_type, char * const command_info[],
1443 char * const run_argv[], char * const run_envp[],
1444 const char **errstr);
1445 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1446 const char *audit_msg, char * const command_info[],
1447 const char **errstr);
1448 int (*error)(const char *plugin_name, unsigned int plugin_type,
1449 const char *audit_msg, char * const command_info[],
1450 const char **errstr);
1451 int (*show_version)(int verbose);
1452 void (*register_hooks)(int version,
1453 int (*register_hook)(struct sudo_hook *hook));
1454 void (*deregister_hooks)(int version,
1455 int (*deregister_hook)(struct sudo_hook *hook));
1456 }
1457 An audit plugin can be used to log successful and unsuccessful attempts
1459 to run sudo independent of the policy or any I/O plugins. Multiple audit
1460 plugins may be specified in sudo.conf(5).
1461 The audit_plugin struct has the following fields:
1463 type The type field should always be set to SUDO_AUDIT_PLUGIN.
1465 version
1467 The version field should be set to SUDO_API_VERSION.
1468 This allows sudo to determine the API version the plugin was built
1470 against.
1471 open
1473 int (*open)(unsigned int version, sudo_conv_t conversation,
1474 sudo_printf_t sudo_printf, char * const settings[],
1475 char * const user_info[], int submit_optind,
1476 char * const submit_argv[], char * const submit_envp[],
1477 char * const plugin_options[], const char **errstr);
1478 The audit open() function is run before any other sudo plugin API
1480 functions. This makes it possible to audit failures in the other
1481 plugins. It returns 1 on success, 0 on failure, -1 if a general
1482 error occurred, or -2 if there was a usage error. In the latter
1483 case, sudo will print a usage message before it exits. If an error
1484 occurs, the plugin may optionally call the conversation() or
1485 plugin_printf() function with SUDO_CONF_ERROR_MSG to present addi‐
1486 tional error information to the user.
1487 The function arguments are as follows:
1489 version
1491 The version passed in by sudo allows the plugin to determine
1492 the major and minor version number of the plugin API sup‐
1493 ported by sudo.
1494 conversation
1496 A pointer to the conversation() function that may be used by
1497 the show_version() function to display version information
1498 (see show_version() below). The conversation() function may
1499 also be used to display additional error message to the user.
1500 The conversation() function returns 0 on success and -1 on
1501 failure.
1502 plugin_printf
1504 A pointer to a printf()-style function that may be used by
1505 the show_version() function to display version information
1506 (see show_version below). The plugin_printf() function may
1507 also be used to display additional error message to the user.
1508 The plugin_printf() function returns number of characters
1509 printed on success and -1 on failure.
1510 settings
1512 A vector of user-supplied sudo settings in the form of
1513 “name=value” strings. The vector is terminated by a NULL
1514 pointer. These settings correspond to options the user spec‐
1515 ified when running sudo. As such, they will only be present
1516 when the corresponding option has been specified on the com‐
1517 mand line.
1518 When parsing settings, the plugin should split on the first
1520 equal sign (‘=’) since the name field will never include one
1521 itself but the value might.
1522 See the Policy plugin API section for a list of all possible
1524 settings.
1525 user_info
1527 A vector of information about the user running the command in
1528 the form of “name=value” strings. The vector is terminated
1529 by a NULL pointer.
1530 When parsing user_info, the plugin should split on the first
1532 equal sign (‘=’) since the name field will never include one
1533 itself but the value might.
1534 See the Policy plugin API section for a list of all possible
1536 strings.
1537 submit_optind
1539 The index into submit_argv that corresponds to the first
1540 entry that is not a command line option. If submit_argv only
1541 consists of options, which may be the case with the -l or -v
1542 options, submit_argv[submit_optind] will evaluate to the NULL
1543 pointer.
1544 submit_argv
1546 The argument vector sudo was invoked with, including all com‐
1547 mand line options. The submit_optind argument can be used to
1548 determine the end of the command line options.
1549 submit_envp
1551 The invoking user's environment in the form of a
1552 NULL-terminated vector of “name=value” strings.
1553 When parsing submit_envp, the plugin should split on the
1555 first equal sign (‘=’) since the name field will never
1556 include one itself but the value might.
1557 plugin_options
1559 Any (non-comment) strings immediately after the plugin path
1560 are treated as arguments to the plugin. These arguments are
1561 split on a white space boundary and are passed to the plugin
1562 in the form of a NULL-terminated array of strings. If no
1563 arguments were specified, plugin_options will be the NULL
1564 pointer.
1565 errstr
1567 If the open() function returns a value other than 1, the
1568 plugin may store a message describing the failure or error in
1569 errstr. The sudo front end will then pass this value to any
1570 registered audit plugins. The string stored in errstr must
1571 remain valid until the plugin's close() function is called.
1572 close
1574 void (*close)(int status_type, int status);
1575 The close() function is called when sudo is finished, shortly
1577 before it exits.
1578 The function arguments are as follows:
1580 status_type
1582 The type of status being passed. One of
1583 SUDO_PLUGIN_NO_STATUS, SUDO_PLUGIN_WAIT_STATUS,
1584 SUDO_PLUGIN_EXEC_ERROR or SUDO_PLUGIN_SUDO_ERROR.
1585 status
1587 Depending on the value of status_type, this value is either
1588 ignored, the command's exit status as returned by the wait(2)
1589 system call, the value of errno set by the execve(2) system
1590 call, or the value of errno resulting from an error in the
1591 sudo front end.
1592 accept
1594 int (*accept)(const char *plugin_name, unsigned int plugin_type,
1595 char * const command_info[], char * const run_argv[],
1596 char * const run_envp[], const char **errstr);
1597 The accept() function is called when a command or action is
1599 accepted by the policy plugin. The function arguments are as fol‐
1600 lows:
1601 plugin_name
1603 The name of the plugin that accepted the command.
1604 plugin_type
1606 The type of plugin that accepted the command, currently
1607 always SUDO_POLICY_PLUGIN.
1608 command_info
1610 A vector of information describing the command being run in
1611 the form of “name=value” strings. The vector is terminated
1612 by a NULL pointer.
1613 When parsing command_info, the plugin should split on the
1615 first equal sign (‘=’) since the name field will never
1616 include one itself but the value might.
1617 See the Policy plugin API section for a list of all possible
1619 strings.
1620 run_argv
1622 A NULL-terminated argument vector describing a command that
1623 will be run in the same form as what would be passed to the
1624 execve(2) system call.
1625 run_envp
1627 The environment the command will be run with in the form of a
1628 NULL-terminated vector of “name=value” strings.
1629 When parsing run_envp, the plugin should split on the first
1631 equal sign (‘=’) since the name field will never include one
1632 itself but the value might.
1633 errstr
1635 If the accept() function returns a value other than 1, the
1636 plugin may store a message describing the failure or error in
1637 errstr. The sudo front end will then pass this value to any
1638 registered audit plugins. The string stored in errstr must
1639 remain valid until the plugin's close() function is called.
1640 reject
1642 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1643 const char *audit_msg, char * const command_info[],
1644 const char **errstr);
1645 The reject() function is called when a command or action is
1647 rejected by a plugin. The function arguments are as follows:
1648 plugin_name
1650 The name of the plugin that accepted the command.
1651 plugin_type
1653 The type of plugin that accepted the command, currently
1654 either SUDO_POLICY_PLUGIN or SUDO_IO_PLUGIN.
1655 audit_msg
1657 An optional string describing the reason the command was
1658 rejected by the plugin. If the plugin did not provide a rea‐
1659 son, audit_msg will be the NULL pointer.
1660 command_info
1662 A vector of information describing the command being run in
1663 the form of “name=value” strings. The vector is terminated
1664 by a NULL pointer.
1665 When parsing command_info, the plugin should split on the
1667 first equal sign (‘=’) since the name field will never
1668 include one itself but the value might.
1669 See the Policy plugin API section for a list of all possible
1671 strings.
1672 errstr
1674 If the reject() function returns a value other than 1, the
1675 plugin may store a message describing the failure or error in
1676 errstr. The sudo front end will then pass this value to any
1677 registered audit plugins. The string stored in errstr must
1678 remain valid until the plugin's close() function is called.
1679 error
1681 int (*error)(const char *plugin_name, unsigned int plugin_type,
1682 const char *audit_msg, char * const command_info[],
1683 const char **errstr);
1684 The error() function is called when a plugin returns an error. The
1686 function arguments are as follows:
1687 plugin_name
1689 The name of the plugin that accepted the command.
1690 plugin_type
1692 The type of plugin that accepted the command, currently
1693 either SUDO_POLICY_PLUGIN or SUDO_IO_PLUGIN.
1694 audit_msg
1696 An optional string describing the plugin error. If the plug‐
1697 in did not provide a description, audit_msg will be the NULL
1698 pointer.
1699 command_info
1701 A vector of information describing the command being run in
1702 the form of “name=value” strings. The vector is terminated
1703 by a NULL pointer.
1704 When parsing command_info, the plugin should split on the
1706 first equal sign (‘=’) since the name field will never
1707 include one itself but the value might.
1708 See the Policy plugin API section for a list of all possible
1710 strings.
1711 errstr
1713 If the error() function returns a value other than 1, the
1714 plugin may store a message describing the failure or error in
1715 errstr. The sudo front end will then pass this value to any
1716 registered audit plugins. The string stored in errstr must
1717 remain valid until the plugin's close() function is called.
1718 show_version
1720 int (*show_version)(int verbose);
1721 The show_version() function is called by sudo when the user speci‐
1723 fies the -V option. The plugin may display its version information
1724 to the user via the conversation() or plugin_printf() function
1725 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1726 information, the verbose flag will be set.
1727 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1729 or -2 if there was a usage error, although the return value is cur‐
1730 rently ignored.
1731 register_hooks
1733 See the Policy plugin API section for a description of
1734 register_hooks.
1735 deregister_hooks
1737 See the Policy plugin API section for a description of
1738 deregister_hooks.
1739 Approval plugin API
1741 struct approval_plugin {
1742 #define SUDO_APPROVAL_PLUGIN 4
1743 unsigned int type; /* always SUDO_APPROVAL_PLUGIN */
1744 unsigned int version; /* always SUDO_API_VERSION */
1745 int (*open)(unsigned int version, sudo_conv_t conversation,
1746 sudo_printf_t sudo_printf, char * const settings[],
1747 char * const user_info[], int submit_optind,
1748 char * const submit_argv[], char * const submit_envp[],
1749 char * const plugin_options[], const char **errstr);
1750 void (*close)(void);
1751 int (*check)(char * const command_info[], char * const run_argv[],
1752 char * const run_envp[], const char **errstr);
1753 int (*show_version)(int verbose);
1754 };
1755 An approval plugin can be used to apply extra constraints after a command
1757 has been accepted by the policy plugin. Unlike the other plugin types,
1758 it does not remain open until the command completes. The plugin is
1759 opened before a call to check() or show_version() and closed shortly
1760 thereafter (audit plugin functions must be called before the plugin is
1761 closed). Multiple approval plugins may be specified in sudo.conf(5).
1762 The approval_plugin struct has the following fields:
1764 type The type field should always be set to SUDO_APPROVAL_PLUGIN.
1766 version
1768 The version field should be set to SUDO_API_VERSION.
1769 This allows sudo to determine the API version the plugin was built
1771 against.
1772 open
1774 int (*open)(unsigned int version, sudo_conv_t conversation,
1775 sudo_printf_t sudo_printf, char * const settings[],
1776 char * const user_info[], int submit_optind,
1777 char * const submit_argv[], char * const submit_envp[],
1778 char * const plugin_options[], const char **errstr);
1779 The approval open() function is run immediately before a call to
1781 the plugin's check() or show_version() functions. It is only
1782 called if the version is being requested or if the policy plugin's
1783 check_policy() function has returned successfully. It returns 1 on
1784 success, 0 on failure, -1 if a general error occurred, or -2 if
1785 there was a usage error. In the latter case, sudo will print a
1786 usage message before it exits. If an error occurs, the plugin may
1787 optionally call the conversation() or plugin_printf() function with
1788 SUDO_CONF_ERROR_MSG to present additional error information to the
1789 user.
1790 The function arguments are as follows:
1792 version
1794 The version passed in by sudo allows the plugin to determine
1795 the major and minor version number of the plugin API sup‐
1796 ported by sudo.
1797 conversation
1799 A pointer to the conversation() function that can be used by
1800 the plugin to interact with the user (see Conversation API
1801 for details). Returns 0 on success and -1 on failure.
1802 plugin_printf
1804 A pointer to a printf()-style function that may be used to
1805 display informational or error messages (see Conversation API
1806 for details). Returns the number of characters printed on
1807 success and -1 on failure.
1808 settings
1810 A vector of user-supplied sudo settings in the form of
1811 “name=value” strings. The vector is terminated by a NULL
1812 pointer. These settings correspond to options the user spec‐
1813 ified when running sudo. As such, they will only be present
1814 when the corresponding option has been specified on the com‐
1815 mand line.
1816 When parsing settings, the plugin should split on the first
1818 equal sign (‘=’) since the name field will never include one
1819 itself but the value might.
1820 See the Policy plugin API section for a list of all possible
1822 settings.
1823 user_info
1825 A vector of information about the user running the command in
1826 the form of “name=value” strings. The vector is terminated
1827 by a NULL pointer.
1828 When parsing user_info, the plugin should split on the first
1830 equal sign (‘=’) since the name field will never include one
1831 itself but the value might.
1832 See the Policy plugin API section for a list of all possible
1834 strings.
1835 submit_optind
1837 The index into submit_argv that corresponds to the first
1838 entry that is not a command line option. If submit_argv only
1839 consists of options, which may be the case with the -l or -v
1840 options, submit_argv[submit_optind] will evaluate to the NULL
1841 pointer.
1842 submit_argv
1844 The argument vector sudo was invoked with, including all com‐
1845 mand line options. The submit_optind argument can be used to
1846 determine the end of the command line options.
1847 submit_envp
1849 The invoking user's environment in the form of a
1850 NULL-terminated vector of “name=value” strings.
1851 When parsing submit_envp, the plugin should split on the
1853 first equal sign (‘=’) since the name field will never
1854 include one itself but the value might.
1855 plugin_options
1857 Any (non-comment) strings immediately after the plugin path
1858 are treated as arguments to the plugin. These arguments are
1859 split on a white space boundary and are passed to the plugin
1860 in the form of a NULL-terminated array of strings. If no
1861 arguments were specified, plugin_options will be the NULL
1862 pointer.
1863 errstr
1865 If the open() function returns a value other than 1, the
1866 plugin may store a message describing the failure or error in
1867 errstr. The sudo front end will then pass this value to any
1868 registered audit plugins. The string stored in errstr must
1869 remain valid until the plugin's close() function is called.
1870 close
1872 void (*close)(void);
1873 The close() function is called after the approval plugin's check()
1875 or show_version() functions have been called. It takes no argu‐
1876 ments. The close() function is typically used to perform plugin-
1877 specific cleanup, such as the freeing of memory objects allocated
1878 by the plugin. If the plugin does not need to perform any cleanup,
1879 close() may be set to the NULL pointer.
1880 check
1882 int (*check)(char * const command_info[], char * const run_argv[],
1883 char * const run_envp[], const char **errstr);
1884 The approval check() function is run after the policy plugin
1886 check_policy() function and before any I/O logging plugins. If
1887 multiple approval plugins are loaded, they must all succeed for the
1888 command to be allowed. It returns 1 on success, 0 on failure, -1
1889 if a general error occurred, or -2 if there was a usage error. In
1890 the latter case, sudo will print a usage message before it exits.
1891 If an error occurs, the plugin may optionally call the
1892 conversation() or plugin_printf() function with SUDO_CONF_ERROR_MSG
1893 to present additional error information to the user.
1894 The function arguments are as follows:
1896 command_info
1898 A vector of information describing the command being run in
1899 the form of “name=value” strings. The vector is terminated
1900 by a NULL pointer.
1901 When parsing command_info, the plugin should split on the
1903 first equal sign (‘=’) since the name field will never
1904 include one itself but the value might.
1905 See the Policy plugin API section for a list of all possible
1907 strings.
1908 run_argv
1910 A NULL-terminated argument vector describing a command that
1911 will be run in the same form as what would be passed to the
1912 execve(2) system call.
1913 run_envp
1915 The environment the command will be run with in the form of a
1916 NULL-terminated vector of “name=value” strings.
1917 When parsing run_envp, the plugin should split on the first
1919 equal sign (‘=’) since the name field will never include one
1920 itself but the value might.
1921 errstr
1923 If the open() function returns a value other than 1, the
1924 plugin may store a message describing the failure or error in
1925 errstr. The sudo front end will then pass this value to any
1926 registered audit plugins. The string stored in errstr must
1927 remain valid until the plugin's close() function is called.
1928 show_version
1930 int (*show_version)(int verbose);
1931 The show_version() function is called by sudo when the user speci‐
1933 fies the -V option. The plugin may display its version information
1934 to the user via the conversation() or plugin_printf() function
1935 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1936 information, the verbose flag will be set.
1937 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1939 or -2 if there was a usage error, although the return value is cur‐
1940 rently ignored.
1941 Signal handlers
1943 The sudo front end installs default signal handlers to trap common sig‐
1944 nals while the plugin functions are run. The following signals are
1945 trapped by default before the command is executed:
1946 · SIGALRM
1948 · SIGHUP
1949 · SIGINT
1950 · SIGPIPE
1951 · SIGQUIT
1952 · SIGTERM
1953 · SIGTSTP
1954 · SIGUSR1
1955 · SIGUSR2
1956 If a fatal signal is received before the command is executed, sudo will
1958 call the plugin's close() function with an exit status of 128 plus the
1959 value of the signal that was received. This allows for consistent log‐
1960 ging of commands killed by a signal for plugins that log such information
1961 in their close() function. An exception to this is SIGPIPE, which is
1962 ignored until the command is executed.
1963 A plugin may temporarily install its own signal handlers but must restore
1965 the original handler before the plugin function returns.
1966 Hook function API
1968 Beginning with plugin API version 1.2, it is possible to install hooks
1969 for certain functions called by the sudo front end.
1970 Currently, the only supported hooks relate to the handling of environment
1972 variables. Hooks can be used to intercept attempts to get, set, or
1973 remove environment variables so that these changes can be reflected in
1974 the version of the environment that is used to execute a command. A
1975 future version of the API will support hooking internal sudo front end
1976 functions as well.
1977 Hook structure
1979 Hooks in sudo are described by the following structure:
1981 typedef int (*sudo_hook_fn_t)();
1983 struct sudo_hook {
1985 unsigned int hook_version;
1986 unsigned int hook_type;
1987 sudo_hook_fn_t hook_fn;
1988 void *closure;
1989 };
1990 The sudo_hook structure has the following fields:
1992 hook_version
1994 The hook_version field should be set to SUDO_HOOK_VERSION.
1995 hook_type
1997 The hook_type field may be one of the following supported hook
1998 types:
1999 SUDO_HOOK_SETENV
2001 The C library setenv(3) function. Any registered hooks will
2002 run before the C library implementation. The hook_fn field
2003 should be a function that matches the following typedef:
2004 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
2006 const char *value, int overwrite, void *closure);
2007 If the registered hook does not match the typedef the results
2009 are unspecified.
2010 SUDO_HOOK_UNSETENV
2012 The C library unsetenv(3) function. Any registered hooks
2013 will run before the C library implementation. The hook_fn
2014 field should be a function that matches the following type‐
2015 def:
2016 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2018 void *closure);
2019 SUDO_HOOK_GETENV
2021 The C library getenv(3) function. Any registered hooks will
2022 run before the C library implementation. The hook_fn field
2023 should be a function that matches the following typedef:
2024 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2026 char **value, void *closure);
2027 If the registered hook does not match the typedef the results
2029 are unspecified.
2030 SUDO_HOOK_PUTENV
2032 The C library putenv(3) function. Any registered hooks will
2033 run before the C library implementation. The hook_fn field
2034 should be a function that matches the following typedef:
2035 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2037 void *closure);
2038 If the registered hook does not match the typedef the results
2040 are unspecified.
2041 hook_fn
2043 sudo_hook_fn_t hook_fn;
2044 The hook_fn field should be set to the plugin's hook implementa‐
2046 tion. The actual function arguments will vary depending on the
2047 hook_type (see hook_type above). In all cases, the closure field
2048 of struct sudo_hook is passed as the last function parameter. This
2049 can be used to pass arbitrary data to the plugin's hook implementa‐
2050 tion.
2051 The function return value may be one of the following:
2053 SUDO_HOOK_RET_ERROR
2055 The hook function encountered an error.
2056 SUDO_HOOK_RET_NEXT
2058 The hook completed without error, go on to the next hook
2059 (including the native implementation if applicable). For
2060 example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
2061 the specified variable was not found in the private copy of
2062 the environment.
2063 SUDO_HOOK_RET_STOP
2065 The hook completed without error, stop processing hooks for
2066 this invocation. This can be used to replace the native
2067 implementation. For example, a setenv hook that operates on
2068 a private copy of the environment but leaves environ
2069 unchanged.
2070 Note that it is very easy to create an infinite loop when hooking C
2072 library functions. For example, a getenv(3) hook that calls the
2073 snprintf(3) function may create a loop if the snprintf(3) implementation
2074 calls getenv(3) to check the locale. To prevent this, you may wish to
2075 use a static variable in the hook function to guard against nested calls.
2076 For example:
2077 static int in_progress = 0; /* avoid recursion */
2079 if (in_progress)
2080 return SUDO_HOOK_RET_NEXT;
2081 in_progress = 1;
2082 ...
2083 in_progress = 0;
2084 return SUDO_HOOK_RET_STOP;
2085 Hook API Version Macros
2087 /* Hook API version major/minor */
2089 #define SUDO_HOOK_VERSION_MAJOR 1
2090 #define SUDO_HOOK_VERSION_MINOR 0
2091 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
2092 SUDO_HOOK_VERSION_MINOR)
2093 For getters and setters see the Policy plugin API.
2095 Event API
2097 When sudo runs a command, it uses an event loop to service signals and
2098 I/O. Events may be triggered based on time, a file or socket descriptor
2099 becoming ready, or due to receipt of a signal. Starting with API version
2100 1.15, it is possible for a plugin to participate in this event loop by
2101 calling the event_alloc() function.
2102 Event structure
2104 Events are described by the following structure:
2106 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure);
2108 struct sudo_plugin_event {
2110 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2111 sudo_plugin_ev_callback_t callback, void *closure);
2112 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2113 int (*del)(struct sudo_plugin_event *pev);
2114 int (*pending)(struct sudo_plugin_event *pev, int events,
2115 struct timespec *ts);
2116 int (*fd)(struct sudo_plugin_event *pev);
2117 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2118 void (*loopbreak)(struct sudo_plugin_event *pev);
2119 void (*free)(struct sudo_plugin_event *pev);
2120 };
2121 The sudo_plugin_event struct contains the following function pointers:
2123 set()
2125 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2126 sudo_plugin_ev_callback_t callback, void *closure);
2127 The set() function takes the following arguments:
2129 struct sudo_plugin_event *pev
2131 A pointer to the struct sudo_plugin_event itself.
2132 fd The file or socket descriptor for I/O-based events or the
2134 signal number for signal events. For time-based events, fd
2135 must be -1.
2136 events
2138 The following values determine what will trigger the event
2139 callback:
2140 SUDO_PLUGIN_EV_TIMEOUT
2142 callback is run after the specified timeout expires
2143 SUDO_PLUGIN_EV_READ
2145 callback is run when the file descriptor is readable
2146 SUDO_PLUGIN_EV_WRITE
2148 callback is run when the file descriptor is writable
2149 SUDO_PLUGIN_EV_PERSIST
2151 event is persistent and remains enabled until explic‐
2152 itly deleted
2153 SUDO_PLUGIN_EV_SIGNAL
2155 callback is run when the specified signal is received
2156 The SUDO_PLUGIN_EV_PERSIST flag may be ORed with any of the
2158 event types. It is also possible to OR SUDO_PLUGIN_EV_READ
2159 and SUDO_PLUGIN_EV_WRITE together to run the callback when a
2160 descriptor is ready to be either read from or written to.
2161 All other event values are mutually exclusive.
2162 sudo_plugin_ev_callback_t callback
2164 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what,
2165 void *closure);
2166 The function to call when an event is triggered. The
2168 callback() function is run with the following arguments:
2169 fd The file or socket descriptor for I/O-based events or
2171 the signal number for signal events.
2172 what The event type that triggered that callback. For
2174 events that have multiple event types (for example
2175 SUDO_PLUGIN_EV_READ and SUDO_PLUGIN_EV_WRITE) or have
2176 an associated timeout, what can be used to determine
2177 why the callback was run.
2178 closure
2180 The generic pointer that was specified in the set()
2181 function.
2182 closure
2184 A generic pointer that will be passed to the callback func‐
2185 tion.
2186 The set() function returns 1 on success, and -1 if a error
2188 occurred.
2189 add()
2191 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2192 The add() function adds the event pev to sudo's event loop. The
2194 event must have previously been initialized via the set() function.
2195 If the timeout argument is not NULL, it should specify a (relative)
2196 timeout after which the event will be triggered if the main event
2197 criteria has not been met. This is often used to implement an I/O
2198 timeout where the event will fire if a descriptor is not ready
2199 within a certain time period. If the event is already present in
2200 the event loop, its timeout will be adjusted to match the new
2201 value, if any.
2202 The add() function returns 1 on success, and -1 if a error
2204 occurred.
2205 del()
2207 int (*del)(struct sudo_plugin_event *pev);
2208 The del() function deletes the event pev from sudo's event loop.
2210 Deleted events can be added back via the add() function.
2211 The del() function returns 1 on success, and -1 if a error
2213 occurred.
2214 pending()
2216 int (*pending)(struct sudo_plugin_event *pev, int events,
2217 struct timespec *ts);
2218 The pending() function can be used to determine whether one or more
2220 events is pending. The events argument specifies which events to
2221 check for. See the set() function for a list of valid event types.
2222 If SUDO_PLUGIN_EV_TIMEOUT is specified in events, the event has an
2223 associated timeout and the ts pointer is non-NULL, it will be
2224 filled in with the remaining time.
2225 fd()
2227 int (*fd)(struct sudo_plugin_event *pev);
2228 The fd() function returns the descriptor or signal number associ‐
2230 ated with the event pev.
2231 setbase()
2233 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2234 The setbase() function sets the underlying event base for pev to
2236 the specified value. This can be used to move an event created via
2237 event_alloc() to a new event loop allocated by sudo's event subsys‐
2238 tem. If base is NULL, pev's event base is reset to the default
2239 value, which corresponds to sudo's main event loop. Using this
2240 function requires linking the plugin with the sudo_util library.
2241 It is unlikely to be used outside of the sudoers plugin.
2242 loopbreak()
2244 void (*loopbreak)(struct sudo_plugin_event *pev);
2245 The loopbreak() function causes sudo's event loop to exit immedi‐
2247 ately and the running command to be terminated.
2248 free()
2250 void (*free)(struct sudo_plugin_event *pev);
2251 The free() function deletes the event pev from the event loop and
2253 frees the memory associated with it.
2254 Remote command execution
2256 The sudo front end does not have native support for running remote com‐
2257 mands. However, starting with sudo 1.8.8, the -h option may be used to
2258 specify a remote host that is passed to the policy plugin. A plugin may
2259 also accept a runas_user in the form of “user@hostname” which will work
2260 with older versions of sudo. It is anticipated that remote commands will
2261 be supported by executing a “helper” program. The policy plugin should
2262 setup the execution environment such that the sudo front end will run the
2263 helper which, in turn, will connect to the remote host and run the com‐
2264 mand.
2265 For example, the policy plugin could utilize ssh to perform remote com‐
2267 mand execution. The helper program would be responsible for running ssh
2268 with the proper options to use a private key or certificate that the
2269 remote host will accept and run a program on the remote host that would
2270 setup the execution environment accordingly.
2271 Note that remote sudoedit functionality must be handled by the policy
2273 plugin, not sudo itself as the front end has no knowledge that a remote
2274 command is being executed. This may be addressed in a future revision of
2275 the plugin API.
2276 Conversation API
2278 If the plugin needs to interact with the user, it may do so via the
2279 conversation() function. A plugin should not attempt to read directly
2280 from the standard input or the user's tty (neither of which are guaran‐
2281 teed to exist). The caller must include a trailing newline in msg if one
2282 is to be printed.
2283 A printf()-style function is also available that can be used to display
2285 informational or error messages to the user, which is usually more conve‐
2286 nient for simple messages where no use input is required.
2287 Conversation function structures
2289 The conversation function takes as arguments pointers to the following
2291 structures:
2292 struct sudo_conv_message {
2294 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2295 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2296 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2297 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2298 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2299 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2300 #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */
2301 int msg_type;
2302 int timeout;
2303 const char *msg;
2304 };
2305 #define SUDO_CONV_REPL_MAX 1023
2307 struct sudo_conv_reply {
2309 char *reply;
2310 };
2311 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
2313 struct sudo_conv_callback {
2314 unsigned int version;
2315 void *closure;
2316 sudo_conv_callback_fn_t on_suspend;
2317 sudo_conv_callback_fn_t on_resume;
2318 };
2319 Pointers to the conversation() and printf()-style functions are passed in
2321 to the plugin's open() function when the plugin is initialized. The fol‐
2322 lowing type definitions can be used in the declaration of the open()
2323 function:
2324 typedef int (*sudo_conv_t)(int num_msgs,
2326 const struct sudo_conv_message msgs[],
2327 struct sudo_conv_reply replies[], struct sudo_conv_callback *callback);
2328 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2330 To use the conversation() function, the plugin must pass an array of
2332 sudo_conv_message and sudo_conv_reply structures. There must be a struct
2333 sudo_conv_message and struct sudo_conv_reply for each message in the con‐
2334 versation, that is, both arrays must have the same number of elements.
2335 Each struct sudo_conv_reply must have its reply member initialized to
2336 NULL. The struct sudo_conv_callback pointer, if not NULL, should contain
2337 function pointers to be called when the sudo process is suspended and/or
2338 resumed during conversation input. The on_suspend and on_resume func‐
2339 tions are called with the signal that caused sudo to be suspended and the
2340 closure pointer from the struct sudo_conv_callback. These functions
2341 should return 0 on success and -1 on error. On error, the conversation
2342 will end and the conversation function will return a value of -1. The
2343 intended use is to allow the plugin to release resources, such as locks,
2344 that should not be held indefinitely while suspended and then reacquire
2345 them when the process is resumed. Note that the functions are not actu‐
2346 ally invoked from within a signal handler.
2347 The msg_type must be set to one of the following values:
2349 SUDO_CONV_PROMPT_ECHO_OFF
2351 Prompt the user for input with echo disabled; this is generally
2352 used for passwords. The reply will be stored in the replies array,
2353 and it will never be NULL.
2354 SUDO_CONV_PROMPT_ECHO_ON
2356 Prompt the user for input with echo enabled. The reply will be
2357 stored in the replies array, and it will never be NULL.
2358 SUDO_CONV_ERROR_MSG
2360 Display an error message. The message is written to the standard
2361 error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
2362 is written to the user's terminal if possible.
2363 SUDO_CONV_INFO_MSG
2365 Display a message. The message is written to the standard output
2366 unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
2367 written to the user's terminal if possible.
2368 SUDO_CONV_PROMPT_MASK
2370 Prompt the user for input but echo an asterisk character for each
2371 character read. The reply will be stored in the replies array, and
2372 it will never be NULL. This can be used to provide visual feedback
2373 to the user while reading sensitive information that should not be
2374 displayed.
2375 In addition to the above values, the following flag bits may also be set:
2377 SUDO_CONV_PROMPT_ECHO_OK
2379 Allow input to be read when echo cannot be disabled when the mes‐
2380 sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
2381 By default, sudo will refuse to read input if the echo cannot be
2382 disabled for those message types.
2383 SUDO_CONV_PREFER_TTY
2385 When displaying a message via SUDO_CONV_ERROR_MSG or
2386 SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
2387 nal. If the terminal is unavailable, the standard error or stan‐
2388 dard output will be used, depending upon whether The user's termi‐
2389 nal is always used when possible for input, this flag is only used
2390 for output. SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used.
2391 The timeout in seconds until the prompt will wait for no more input. A
2393 zero value implies an infinite timeout.
2394 The plugin is responsible for freeing the reply buffer located in each
2396 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
2397 the maximum length of the reply buffer (not including the trailing NUL
2398 character). In practical terms, this is the longest password sudo will
2399 support. It is also useful as a maximum value for the memset_s() func‐
2400 tion when clearing passwords filled in by the conversation function.
2401 The printf()-style function uses the same underlying mechanism as the
2403 conversation() function but only supports SUDO_CONV_INFO_MSG and
2404 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
2405 nient than using the conversation() function if no user reply is needed
2406 and supports standard printf() escape sequences.
2407 See the sample plugin for an example of the conversation() function
2409 usage.
2410 Sudoers group plugin API
2412 The sudoers plugin supports its own plugin interface to allow non-Unix
2413 group lookups. This can be used to query a group source other than the
2414 standard Unix group database. Two sample group plugins are bundled with
2415 sudo, group_file and system_group, are detailed in sudoers(5). Third
2416 party group plugins include a QAS AD plugin available from Quest Soft‐
2417 ware.
2418 A group plugin must declare and populate a sudoers_group_plugin struct in
2420 the global scope. This structure contains pointers to the functions that
2421 implement plugin initialization, cleanup and group lookup.
2422 struct sudoers_group_plugin {
2424 unsigned int version;
2425 int (*init)(int version, sudo_printf_t sudo_printf,
2426 char *const argv[]);
2427 void (*cleanup)(void);
2428 int (*query)(const char *user, const char *group,
2429 const struct passwd *pwd);
2430 };
2431 The sudoers_group_plugin struct has the following fields:
2433 version
2435 The version field should be set to GROUP_API_VERSION.
2436 This allows sudoers to determine the API version the group plugin
2438 was built against.
2439 init
2441 int (*init)(int version, sudo_printf_t plugin_printf,
2442 char *const argv[]);
2443 The init() function is called after sudoers has been parsed but
2445 before any policy checks. It returns 1 on success, 0 on failure
2446 (or if the plugin is not configured), and -1 if a error occurred.
2447 If an error occurs, the plugin may call the plugin_printf() func‐
2448 tion with SUDO_CONF_ERROR_MSG to present additional error informa‐
2449 tion to the user.
2450 The function arguments are as follows:
2452 version
2454 The version passed in by sudoers allows the plugin to deter‐
2455 mine the major and minor version number of the group plugin
2456 API supported by sudoers.
2457 plugin_printf
2459 A pointer to a printf()-style function that may be used to
2460 display informational or error message to the user. Returns
2461 the number of characters printed on success and -1 on fail‐
2462 ure.
2463 argv A NULL-terminated array of arguments generated from the
2465 group_plugin option in sudoers. If no arguments were given,
2466 argv will be NULL.
2467 cleanup
2469 void (*cleanup)();
2470 The cleanup() function is called when sudoers has finished its
2472 group checks. The plugin should free any memory it has allocated
2473 and close open file handles.
2474 query
2476 int (*query)(const char *user, const char *group,
2477 const struct passwd *pwd);
2478 The query() function is used to ask the group plugin whether user
2480 is a member of group.
2481 The function arguments are as follows:
2483 user The name of the user being looked up in the external group
2485 database.
2486 group
2488 The name of the group being queried.
2489 pwd The password database entry for user, if any. If user is not
2491 present in the password database, pwd will be NULL.
2492 Group API Version Macros
2494 /* Sudoers group plugin version major/minor */
2496 #define GROUP_API_VERSION_MAJOR 1
2497 #define GROUP_API_VERSION_MINOR 0
2498 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
2499 GROUP_API_VERSION_MINOR)
2500 For getters and setters see the Policy plugin API.
2501
2503 The following revisions have been made to the Sudo Plugin API.
2504 Version 1.0
2506 Initial API version.
2507 Version 1.1 (sudo 1.8.0)
2509 The I/O logging plugin's open() function was modified to take the
2510 command_info list as an argument.
2511 Version 1.2 (sudo 1.8.5)
2513 The Policy and I/O logging plugins' open() functions are now passed
2514 a list of plugin parameters if any are specified in sudo.conf(5).
2515 A simple hooks API has been introduced to allow plugins to hook in
2517 to the system's environment handling functions.
2518 The init_session Policy plugin function is now passed a pointer to
2520 the user environment which can be updated as needed. This can be
2521 used to merge in environment variables stored in the PAM handle
2522 before a command is run.
2523 Version 1.3 (sudo 1.8.7)
2525 Support for the exec_background entry has been added to the
2526 command_info list.
2527 The max_groups and plugin_dir entries were added to the settings
2529 list.
2530 The version() and close() functions are now optional. Previously,
2532 a missing version() or close() function would result in a crash.
2533 If no policy plugin close() function is defined, a default close()
2534 function will be provided by the sudo front end that displays a
2535 warning if the command could not be executed.
2536 The sudo front end now installs default signal handlers to trap
2538 common signals while the plugin functions are run.
2539 Version 1.4 (sudo 1.8.8)
2541 The remote_host entry was added to the settings list.
2542 Version 1.5 (sudo 1.8.9)
2544 The preserve_fds entry was added to the command_info list.
2545 Version 1.6 (sudo 1.8.11)
2547 The behavior when an I/O logging plugin returns an error (-1) has
2548 changed. Previously, the sudo front end took no action when the
2549 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
2550 log_stderr() function returned an error.
2551 The behavior when an I/O logging plugin returns 0 has changed.
2553 Previously, output from the command would be displayed to the ter‐
2554 minal even if an output logging function returned 0.
2555 Version 1.7 (sudo 1.8.12)
2557 The plugin_path entry was added to the settings list.
2558 The debug_flags entry now starts with a debug file path name and
2560 may occur multiple times if there are multiple plugin-specific
2561 Debug lines in the sudo.conf(5) file.
2562 Version 1.8 (sudo 1.8.15)
2564 The sudoedit_checkdir and sudoedit_follow entries were added to the
2565 command_info list. The default value of sudoedit_checkdir was
2566 changed to true in sudo 1.8.16.
2567 The sudo conversation function now takes a pointer to a struct
2569 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
2570 tion has been updated to match. The plugin must specify that it
2571 supports plugin API version 1.8 or higher to receive a conversation
2572 function pointer that supports this argument.
2573 Version 1.9 (sudo 1.8.16)
2575 The execfd entry was added to the command_info list.
2576 Version 1.10 (sudo 1.8.19)
2578 The umask entry was added to the user_info list. The iolog_group,
2579 iolog_mode, and iolog_user entries were added to the command_info
2580 list.
2581 Version 1.11 (sudo 1.8.20)
2583 The timeout entry was added to the settings list.
2584 Version 1.12 (sudo 1.8.21)
2586 The change_winsize field was added to the io_plugin struct.
2587 Version 1.13 (sudo 1.8.26)
2589 The log_suspend field was added to the io_plugin struct.
2590 Version 1.14 (sudo 1.8.29)
2592 The umask_override entry was added to the command_info list.
2593 Version 1.15 (sudo 1.9.0)
2595 The event_alloc field was added to the policy_plugin and io_plugin
2596 structs.
2597 The errstr argument was added to the policy and I/O plugin func‐
2599 tions which the plugin function can use to return an error string.
2600 This string may be used by the audit plugin to report failure or
2601 error conditions set by the other plugins.
2602 The close() function is now is called regardless of whether or not
2604 a command was actually executed. This makes it possible for plug‐
2605 ins to perform cleanup even when a command was not run.
2606 SUDO_CONV_REPL_MAX has increased from 255 to 1023 bytes.
2608 Support for audit and approval plugins was added.
2610
2612 sudo.conf(5), sudoers(5), sudo(8)
2613
2615 Many people have worked on sudo over the years; this version consists of
2616 code written primarily by:
2617 Todd C. Miller
2619 See the CONTRIBUTORS file in the sudo distribution
2621 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
2622 who have contributed to sudo.
2623
2625 If you feel you have found a bug in sudo, please submit a bug report at
2626 https://bugzilla.sudo.ws/
2627
2629 Limited free support is available via the sudo-users mailing list, see
2630 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
2631 the archives.
2632
2634 sudo is provided “AS IS” and any express or implied warranties, includ‐
2635 ing, but not limited to, the implied warranties of merchantability and
2636 fitness for a particular purpose are disclaimed. See the LICENSE file
2637 distributed with sudo or https://www.sudo.ws/license.html for complete
2638 details.
2639Sudo 1.9.0b4 February 10, 2020 Sudo 1.9.0b4