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 de‐
9 fault on systems that support them) or compiled statically into the sudo
10 binary itself. By default, the sudoers plugin provides audit, security
11 policy and I/O logging capabilities. Via the plugin API, sudo can be
12 configured to use alternate plugins provided by third parties. The plug‐
13 ins to be used are specified in the sudo.conf(5) file.
14 The API is versioned with a major and minor number. The minor version
16 number is incremented when additions are made. The major number is in‐
17 cremented when incompatible changes are made. A plugin should be check
18 the version passed to it and make sure that the major version matches.
19 The plugin API is defined by the <sudo_plugin.h> header file.
21 Policy plugin API
23 A policy plugin must declare and populate a struct policy_plugin in the
24 global scope. This structure contains pointers to the functions that im‐
25 plement the sudo policy checks. The name of the symbol should be speci‐
26 fied in sudo.conf(5) along with a path to the plugin so that sudo can
27 load it.
28 struct policy_plugin {
30 #define SUDO_POLICY_PLUGIN 1
31 unsigned int type; /* always SUDO_POLICY_PLUGIN */
32 unsigned int version; /* always SUDO_API_VERSION */
33 int (*open)(unsigned int version, sudo_conv_t conversation,
34 sudo_printf_t sudo_plugin_printf, char * const settings[],
35 char * const user_info[], char * const user_env[],
36 char * const plugin_options[], const char **errstr);
37 void (*close)(int exit_status, int error);
38 int (*show_version)(int verbose);
39 int (*check_policy)(int argc, char * const argv[],
40 char *env_add[], char **command_info[],
41 char **argv_out[], char **user_env_out[], const char **errstr);
42 int (*list)(int argc, char * const argv[], int verbose,
43 const char *user, const char **errstr);
44 int (*validate)(const char **errstr);
45 void (*invalidate)(int rmcred);
46 int (*init_session)(struct passwd *pwd, char **user_env[],
47 const char **errstr);
48 void (*register_hooks)(int version,
49 int (*register_hook)(struct sudo_hook *hook));
50 void (*deregister_hooks)(int version,
51 int (*deregister_hook)(struct sudo_hook *hook));
52 struct sudo_plugin_event * (*event_alloc)(void);
53 };
54 A struct policy_plugin has the following fields:
56 type The type field should always be set to SUDO_POLICY_PLUGIN.
58 version
60 The version field should be set to SUDO_API_VERSION.
61 This allows sudo to determine the API version the plugin was built
63 against.
64 open
66 int (*open)(unsigned int version, sudo_conv_t conversation,
67 sudo_printf_t sudo_plugin_printf, char * const settings[],
68 char * const user_info[], char * const user_env[],
69 char * const plugin_options[], const char **errstr);
70 Returns 1 on success, 0 on failure, -1 if a general error occurred,
72 or -2 if there was a usage error. In the latter case, sudo will
73 print a usage message before it exits. If an error occurs, the
74 plugin may optionally call the conversation() or
75 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
76 additional error information to the user.
77 The function arguments are as follows:
79 version
81 The version passed in by sudo allows the plugin to determine
82 the major and minor version number of the plugin API sup‐
83 ported by sudo.
84 conversation
86 A pointer to the conversation() function that can be used by
87 the plugin to interact with the user (see Conversation API
88 for details). Returns 0 on success and -1 on failure.
89 sudo_plugin_printf
91 A pointer to a printf()-style function that may be used to
92 display informational or error messages (see Conversation API
93 for details). Returns the number of characters printed on
94 success and -1 on failure.
95 settings
97 A vector of user-supplied sudo settings in the form of
98 “name=value” strings. The vector is terminated by a NULL
99 pointer. These settings correspond to options the user spec‐
100 ified when running sudo. As such, they will only be present
101 when the corresponding option has been specified on the com‐
102 mand line.
103 When parsing settings, the plugin should split on the first
105 equal sign (‘=’) since the name field will never include one
106 itself but the value might.
107 The following values may be set by sudo:
109 bsdauth_type=string
111 Authentication type, if specified by the -a option, to
112 use on systems where BSD authentication is supported.
113 closefrom=number
115 If specified, the user has requested via the -C option
116 that sudo close all files descriptors with a value of
117 number or higher. The plugin may optionally pass this,
118 or another value, back in the command_info list.
119 cmnd_chroot=string
121 The root directory (see chroot(2)) to run the command
122 in, as specified by the user via the -R option. The
123 plugin may ignore or restrict the user's ability to
124 specify a new root directory. Only available starting
125 with API version 1.16.
126 cmnd_cwd=string
128 The working directory to run the command in, as speci‐
129 fied by the user via the -D option. The plugin may ig‐
130 nore or restrict the user's ability to specify a new
131 working directory. Only available starting with API
132 version 1.16.
133 debug_flags=string
135 A debug file path name followed by a space and a comma-
136 separated list of debug flags that correspond to the
137 plugin's Debug entry in sudo.conf(5), if there is one.
138 The flags are passed to the plugin exactly as they ap‐
139 pear in sudo.conf(5). The syntax used by sudo and the
140 sudoers plugin is subsystem@priority but a plugin is
141 free to use a different format so long as it does not
142 include a comma (‘,’). Prior to sudo 1.8.12, there was
143 no way to specify plugin-specific debug_flags so the
144 value was always the same as that used by the sudo
145 front-end and did not include a path name, only the
146 flags themselves. As of version 1.7 of the plugin in‐
147 terface, sudo will only pass debug_flags if
148 sudo.conf(5) contains a plugin-specific Debug entry.
149 ignore_ticket=bool
151 Set to true if the user specified the -k option along
152 with a command, indicating that the user wishes to ig‐
153 nore any cached authentication credentials.
154 implied_shell to true. This allows sudo with no argu‐
155 ments to be used similarly to su(1). If the plugin
156 does not to support this usage, it may return a value
157 of -2 from the check_policy() function, which will
158 cause sudo to print a usage message and exit.
159 implied_shell=bool
161 If the user does not specify a program on the command
162 line, sudo will pass the plugin the path to the user's
163 shell and set implied_shell.
164 intercept_ptrace=bool
166 Indicates whether or not the system supports intercept
167 mode using ptrace(2). This is currently only true for
168 Linux systems that support seccomp(2) filtering and the
169 “trap” action. Other systems will use a dynamic shared
170 object to implement intercept. Only available starting
171 with API version 1.19.
172 intercept_setid=bool
174 Indicates whether or not the system supports running
175 set-user-ID and set-group-ID binaries in intercept
176 mode. This is currently only true for Linux systems
177 that support seccomp(2) filtering and the “trap” ac‐
178 tion. On systems that use a dynamic shared object to
179 implement intercept, the dynamic linker (ld.so or the
180 equivalent) will disable preloading of shared objects
181 when executing a set-user-ID or set-group-ID binary.
182 This will disable intercept mode for that program and
183 any other programs that it executes. The policy plugin
184 may refuse to execute a set-user-ID or set-group-ID bi‐
185 nary in intercept mode to avoid this. Only available
186 starting with API version 1.19.
187 login_class=string
189 BSD login class to use when setting resource limits and
190 nice value, if specified by the -c option.
191 login_shell=bool
193 Set to true if the user specified the -i option, indi‐
194 cating that the user wishes to run a login shell.
195 max_groups=int
197 The maximum number of groups a user may belong to.
198 This will only be present if there is a corresponding
199 setting in sudo.conf(5).
200 network_addrs=list
202 A space-separated list of IP network addresses and net‐
203 masks in the form “addr/netmask”, e.g.,
204 “192.168.1.2/255.255.255.0”. The address and netmask
205 pairs may be either IPv4 or IPv6, depending on what the
206 operating system supports. If the address contains a
207 colon (‘:’), it is an IPv6 address, else it is IPv4.
208 noninteractive=bool
210 Set to true if the user specified the -n option, indi‐
211 cating that sudo should operate in non-interactive
212 mode. The plugin may reject a command run in non-in‐
213 teractive mode if user interaction is required.
214 plugin_dir=string
216 The default plugin directory used by the sudo front-
217 end. This is the default directory set at compile time
218 and may not correspond to the directory the running
219 plugin was loaded from. It may be used by a plugin to
220 locate support files.
221 plugin_path=string
223 The path name of plugin loaded by the sudo front-end.
224 The path name will be a fully-qualified unless the
225 plugin was statically compiled into sudo.
226 preserve_environment=bool
228 Set to true if the user specified the -E option, indi‐
229 cating that the user wishes to preserve the environ‐
230 ment.
231 preserve_groups=bool
233 Set to true if the user specified the -P option, indi‐
234 cating that the user wishes to preserve the group vec‐
235 tor instead of setting it based on the runas user.
236 progname=string
238 The command name that sudo was run as, typically “sudo”
239 or “sudoedit”.
240 prompt=string
242 The prompt to use when requesting a password, if speci‐
243 fied via the -p option.
244 remote_host=string
246 The name of the remote host to run the command on, if
247 specified via the -h option. Support for running the
248 command on a remote host is meant to be implemented via
249 a helper program that is executed in place of the user-
250 specified command. The sudo front-end is only capable
251 of executing commands on the local host. Only avail‐
252 able starting with API version 1.4.
253 run_shell=bool
255 Set to true if the user specified the -s option, indi‐
256 cating that the user wishes to run a shell.
257 runas_group=string
259 The group name or group-ID to run the command as, if
260 specified via the -g option.
261 runas_user=string
263 The user name or user-ID to run the command as, if
264 specified via the -u option.
265 selinux_role=string
267 SELinux role to use when executing the command, if
268 specified by the -r option.
269 selinux_type=string
271 SELinux type to use when executing the command, if
272 specified by the -t option.
273 set_home=bool
275 Set to true if the user specified the -H option. If
276 true, set the HOME environment variable to the target
277 user's home directory.
278 sudoedit=bool
280 Set to true when the -e option is specified or if in‐
281 voked as sudoedit. The plugin shall substitute an edi‐
282 tor into argv in the check_policy() function or return
283 -2 with a usage error if the plugin does not support
284 sudoedit. For more information, see the check_policy()
285 section.
286 timeout=string
288 Command timeout specified by the user via the -T op‐
289 tion. Not all plugins support command timeouts and the
290 ability of the user to set a timeout may be restricted
291 by policy. The format of the timeout string is plugin-
292 specific.
293 update_ticket=bool
295 Set to false if the user specified the -N option, indi‐
296 cating that the user wishes to avoid updating any
297 cached authentication credentials. Only available
298 starting with API version 1.20.
299 Additional settings may be added in the future so the plugin
301 should silently ignore settings that it does not recognize.
302 user_info
304 A vector of information about the user running the command in
305 the form of “name=value” strings. The vector is terminated
306 by a NULL pointer.
307 When parsing user_info, the plugin should split on the first
309 equal sign (‘=’) since the name field will never include one
310 itself but the value might.
311 The following values may be set by sudo:
313 cols=int
315 The number of columns the user's terminal supports. If
316 there is no terminal device available, a default value
317 of 80 is used.
318 cwd=string
320 The user's current working directory.
321 egid=gid_t
323 The effective group-ID of the user invoking sudo.
324 euid=uid_t
326 The effective user-ID of the user invoking sudo.
327 gid=gid_t
329 The real group-ID of the user invoking sudo.
330 groups=list
332 The user's supplementary group list formatted as a
333 string of comma-separated group-IDs.
334 host=string
336 The local machine's hostname as returned by the
337 gethostname(2) system call.
338 lines=int
340 The number of lines the user's terminal supports. If
341 there is no terminal device available, a default value
342 of 24 is used.
343 pgid=int
345 The ID of the process group that the running sudo
346 process is a member of. Only available starting with
347 API version 1.2.
348 pid=int
350 The process ID of the running sudo process. Only
351 available starting with API version 1.2.
352 ppid=int
354 The parent process ID of the running sudo process.
355 Only available starting with API version 1.2.
356 rlimit_as=soft,hard
358 The maximum size to which the process's address space
359 may grow (in bytes), if supported by the operating sys‐
360 tem. The soft and hard limits are separated by a
361 comma. A value of “infinity” indicates that there is
362 no limit. Only available starting with API version
363 1.16.
364 rlimit_core=soft,hard
366 The largest size core dump file that may be created (in
367 bytes). The soft and hard limits are separated by a
368 comma. A value of “infinity” indicates that there is
369 no limit. Only available starting with API version
370 1.16.
371 rlimit_cpu=soft,hard
373 The maximum amount of CPU time that the process may use
374 (in seconds). The soft and hard limits are separated
375 by a comma. A value of “infinity” indicates that there
376 is no limit. Only available starting with API version
377 1.16.
378 rlimit_data=soft,hard
380 The maximum size of the data segment for the process
381 (in bytes). The soft and hard limits are separated by
382 a comma. A value of “infinity” indicates that there is
383 no limit. Only available starting with API version
384 1.16.
385 rlimit_fsize=soft,hard
387 The largest size file that the process may create (in
388 bytes). The soft and hard limits are separated by a
389 comma. A value of “infinity” indicates that there is
390 no limit. Only available starting with API version
391 1.16.
392 rlimit_locks=soft,hard
394 The maximum number of locks that the process may estab‐
395 lish, if supported by the operating system. The soft
396 and hard limits are separated by a comma. A value of
397 “infinity” indicates that there is no limit. Only
398 available starting with API version 1.16.
399 rlimit_memlock=soft,hard
401 The maximum size that the process may lock in memory
402 (in bytes), if supported by the operating system. The
403 soft and hard limits are separated by a comma. A value
404 of “infinity” indicates that there is no limit. Only
405 available starting with API version 1.16.
406 rlimit_nofile=soft,hard
408 The maximum number of files that the process may have
409 open. The soft and hard limits are separated by a
410 comma. A value of “infinity” indicates that there is
411 no limit. Only available starting with API version
412 1.16.
413 rlimit_nproc=soft,hard
415 The maximum number of processes that the user may run
416 simultaneously. The soft and hard limits are separated
417 by a comma. A value of “infinity” indicates that there
418 is no limit. Only available starting with API version
419 1.16.
420 rlimit_rss=soft,hard
422 The maximum size to which the process's resident set
423 size may grow (in bytes). The soft and hard limits are
424 separated by a comma. A value of “infinity” indicates
425 that there is no limit. Only available starting with
426 API version 1.16.
427 rlimit_stack=soft,hard
429 The maximum size to which the process's stack may grow
430 (in bytes). The soft and hard limits are separated by
431 a comma. A value of “infinity” indicates that there is
432 no limit. Only available starting with API version
433 1.16.
434 sid=int
436 The session ID of the running sudo process or 0 if sudo
437 is not part of a POSIX job control session. Only
438 available starting with API version 1.2.
439 tcpgid=int
441 The ID of the foreground process group associated with
442 the terminal device associated with the sudo process or
443 0 if there is no terminal present. Only available
444 starting with API version 1.2.
445 tty=string
447 The path to the user's terminal device. If the user
448 has no terminal device associated with the session, the
449 value will be empty, as in ‘tty=’.
450 uid=uid_t
452 The real user-ID of the user invoking sudo.
453 umask=octal
455 The invoking user's file creation mask. Only available
456 starting with API version 1.10.
457 user=string
459 The name of the user invoking sudo.
460 user_env
462 The user's environment in the form of a NULL-terminated
463 vector of “name=value” strings.
464 When parsing user_env, the plugin should split on the first
466 equal sign (‘=’) since the name field will never include one
467 itself but the value might.
468 plugin_options
470 Any (non-comment) strings immediately after the plugin path
471 are passed as arguments to the plugin. These arguments are
472 split on a white space boundary and are passed to the plugin
473 in the form of a NULL-terminated array of strings. If no ar‐
474 guments were specified, plugin_options will be the NULL
475 pointer.
476 The plugin_options parameter is only available starting with
478 API version 1.2. A plugin must check the API version speci‐
479 fied by the sudo front-end before using plugin_options.
480 Failure to do so may result in a crash.
481 errstr
483 If the open() function returns a value other than 1, the
484 plugin may store a message describing the failure or error in
485 errstr. The sudo front-end will then pass this value to any
486 registered audit plugins. The string stored in errstr must
487 remain valid until the plugin's close() function is called.
488 The errstr parameter is only available starting with API ver‐
490 sion 1.15. A plugin must check the API version specified by
491 the sudo front-end before using errstr. Failure to do so may
492 result in a crash.
493 close
495 void (*close)(int exit_status, int error);
496 The close() function is called when sudo is finished, shortly be‐
498 fore it exits. Starting with API version 1.15, close() is called
499 regardless of whether or not a command was actually executed. This
500 makes it possible for plugins to perform cleanup even when a com‐
501 mand was not run. It is not possible to tell whether a command was
502 run based solely on the arguments passed to the close() function.
503 To determine if a command was actually run, the plugin must keep
504 track of whether or not the check_policy() function returned suc‐
505 cessfully.
506 The function arguments are as follows:
508 exit_status
510 The command's exit status, as returned by the wait(2) system
511 call, or zero if no command was run. The value of
512 exit_status is undefined if error is non-zero.
513 error
515 If the command could not be executed, this is set to the
516 value of errno set by the execve(2) system call. The plugin
517 is responsible for displaying error information via the
518 conversation() or sudo_plugin_printf() function. If the com‐
519 mand was successfully executed, the value of error is zero.
520 If no close() function is defined, no I/O logging plugins are
522 loaded, and neither the timeout nor use_pty options are set in the
523 command_info list, the sudo front-end may execute the command di‐
524 rectly instead of running it as a child process.
525 show_version
527 int (*show_version)(int verbose);
528 The show_version() function is called by sudo when the user speci‐
530 fies the -V option. The plugin may display its version information
531 to the user via the conversation() or sudo_plugin_printf() function
532 using SUDO_CONV_INFO_MSG. If the user requests detailed version
533 information, the verbose flag will be non-zero.
534 Returns 1 on success, 0 on failure, -1 if a general error occurred,
536 or -2 if there was a usage error, although the return value is cur‐
537 rently ignored.
538 check_policy
540 int (*check_policy)(int argc, char * const argv[], char *env_add[],
541 char **command_info[], char **argv_out[], char **user_env_out[],
542 const char **errstr);
543 The check_policy() function is called by sudo to determine whether
545 the user is allowed to run the specified commands.
546 If the sudoedit option was enabled in the settings array passed to
548 the open() function, the user has requested sudoedit mode.
549 sudoedit is a mechanism for editing one or more files where an edi‐
550 tor is run with the user's credentials instead of with elevated
551 privileges. sudo achieves this by creating user-writable temporary
552 copies of the files to be edited and then overwriting the originals
553 with the temporary copies after editing is complete. If the plugin
554 supports sudoedit, it should choose the editor to be used, poten‐
555 tially from a variable in the user's environment, such as EDITOR,
556 and include it in argv_out (environment variables may include com‐
557 mand line options). The files to be edited should be copied from
558 argv into argv_out, separated from the editor and its arguments by
559 a ‘--’ element. The ‘--’ will be removed by sudo before the editor
560 is executed. The plugin should also set sudoedit=true in the
561 command_info list.
562 The check_policy() function returns 1 if the command is allowed, 0
564 if not allowed, -1 for a general error, or -2 for a usage error or
565 if sudoedit was specified but is unsupported by the plugin. In the
566 latter case, sudo will print a usage message before it exits. If
567 an error occurs, the plugin may optionally call the conversation()
568 or sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to
569 present additional error information to the user.
570 The function arguments are as follows:
572 argc The number of elements in argv, not counting the final NULL
574 pointer.
575 argv The argument vector describing the command the user wishes to
577 run, in the same form as what would be passed to the
578 execve(2) system call. The vector is terminated by a NULL
579 pointer.
580 env_add
582 Additional environment variables specified by the user on the
583 command line in the form of a NULL-terminated vector of
584 “name=value” strings. The plugin may reject the command if
585 one or more variables are not allowed to be set, or it may
586 silently ignore such variables.
587 When parsing env_add, the plugin should split on the first
589 equal sign (‘=’) since the name field will never include one
590 itself but the value might.
591 command_info
593 Information about the command being run in the form of
594 “name=value” strings. These values are used by sudo to set
595 the execution environment when running a command. The plugin
596 is responsible for creating and populating the vector, which
597 must be terminated with a NULL pointer. The following values
598 are recognized by sudo:
599 apparmor_profile=string
601 AppArmor profile to transition to when executing the
602 command. Only available starting with API version
603 1.19.
604 chroot=string
606 The root directory to use when running the command.
607 closefrom=number
609 If specified, sudo will close all files descriptors
610 with a value of number or higher.
611 command=string
613 Fully qualified path to the command to be executed.
614 cwd=string
616 The current working directory to change to when execut‐
617 ing the command. If sudo is unable to change to the
618 new working directory, the command will not be run un‐
619 less cwd_optional is also set (see below).
620 cwd_optional=bool
622 If set, sudo will treat an inability to change to the
623 new working directory as a non-fatal error. This set‐
624 ting has no effect unless cwd is also set.
625 exec_background=bool
627 By default, sudo runs a command as the foreground
628 process as long as sudo itself is running in the fore‐
629 ground. When exec_background is enabled and the com‐
630 mand is being run in a pseudo-terminal (due to I/O log‐
631 ging or the use_pty setting), the command will be run
632 as a background process. Attempts to read from the
633 controlling terminal (or to change terminal settings)
634 will result in the command being suspended with the
635 SIGTTIN signal (or SIGTTOU in the case of terminal set‐
636 tings). If this happens when sudo is a foreground
637 process, the command will be granted the controlling
638 terminal and resumed in the foreground with no user in‐
639 tervention required. The advantage of initially run‐
640 ning the command in the background is that sudo need
641 not read from the terminal unless the command explic‐
642 itly requests it. Otherwise, any terminal input must
643 be passed to the command, whether it has required it or
644 not (the kernel buffers terminals so it is not possible
645 to tell whether the command really wants the input).
646 This is different from historic sudo behavior or when
647 the command is not being run in a pseudo-terminal.
648 For this to work seamlessly, the operating system must
650 support the automatic restarting of system calls. Un‐
651 fortunately, not all operating systems do this by de‐
652 fault, and even those that do may have bugs. For exam‐
653 ple, macOS fails to restart the tcgetattr() and
654 tcsetattr() system calls (this is a bug in macOS).
655 Furthermore, because this behavior depends on the com‐
656 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
657 grams that catch these signals and suspend themselves
658 with a different signal (usually SIGTOP) will not be
659 automatically foregrounded. Some versions of the linux
660 su(1) command behave this way. Because of this, a
661 plugin should not set exec_background unless it is ex‐
662 plicitly enabled by the administrator and there should
663 be a way to enabled or disable it on a per-command ba‐
664 sis.
665 This setting has no effect unless I/O logging is en‐
667 abled or use_pty is enabled.
668 execfd=number
670 If specified, sudo will use the fexecve(2) system call
671 to execute the command instead of execve(2). The spec‐
672 ified number must refer to an open file descriptor.
673 intercept=bool
675 If set, sudo will intercept attempts to execute a sub‐
676 sequent command and perform a policy check via the pol‐
677 icy plugin's check_policy() function to determine
678 whether or not the command is permitted. This can be
679 used to prevent shell escapes on supported platforms
680 but it has a number of limitations. See Preventing
681 shell escapes in sudoers(5) for details. Only avail‐
682 able starting with API version 1.18.
683 intercept_verify=bool
685 If set, sudo will attempt to verify that a command run
686 in intercept mode has the expected path name, command
687 line arguments and environment. This setting has no
688 effect unless use_ptrace is also enabled. Only avail‐
689 able starting with API version 1.20.
690 iolog_compress=bool
692 Set to true if the I/O logging plugins, if any, should
693 compress the log data. This is a hint to the I/O log‐
694 ging plugin which may choose to ignore it.
695 iolog_group=string
697 The group that will own newly created I/O log files and
698 directories. This is a hint to the I/O logging plugin
699 which may choose to ignore it.
700 iolog_mode=octal
702 The file permission mode to use when creating I/O log
703 files and directories. This is a hint to the I/O log‐
704 ging plugin which may choose to ignore it.
705 iolog_user=string
707 The user that will own newly created I/O log files and
708 directories. This is a hint to the I/O logging plugin
709 which may choose to ignore it.
710 iolog_path=string
712 Fully qualified path to the file or directory in which
713 I/O log is to be stored. This is a hint to the I/O
714 logging plugin which may choose to ignore it. If no
715 I/O logging plugin is loaded, this setting has no ef‐
716 fect.
717 iolog_stdin=bool
719 Set to true if the I/O logging plugins, if any, should
720 log the standard input if it is not connected to a ter‐
721 minal device. This is a hint to the I/O logging plugin
722 which may choose to ignore it.
723 iolog_stdout=bool
725 Set to true if the I/O logging plugins, if any, should
726 log the standard output if it is not connected to a
727 terminal device. This is a hint to the I/O logging
728 plugin which may choose to ignore it.
729 iolog_stderr=bool
731 Set to true if the I/O logging plugins, if any, should
732 log the standard error if it is not connected to a ter‐
733 minal device. This is a hint to the I/O logging plugin
734 which may choose to ignore it.
735 iolog_ttyin=bool
737 Set to true if the I/O logging plugins, if any, should
738 log all terminal input. This only includes input typed
739 by the user and not from a pipe or redirected from a
740 file. This is a hint to the I/O logging plugin which
741 may choose to ignore it.
742 iolog_ttyout=bool
744 Set to true if the I/O logging plugins, if any, should
745 log all terminal output. This only includes output to
746 the screen, not output to a pipe or file. This is a
747 hint to the I/O logging plugin which may choose to ig‐
748 nore it.
749 login_class=string
751 BSD login class to use when setting resource limits and
752 nice value (optional). This option is only set on sys‐
753 tems that support login classes.
754 nice=int
756 Nice value (priority) to use when executing the com‐
757 mand. The nice value, if specified, overrides the pri‐
758 ority associated with the login_class on BSD systems.
759 log_subcmds=bool
761 If set, sudo will call the audit plugin's accept()
762 function to log when the command runs a subsequent com‐
763 mand, if supported by the system. If intercept is also
764 specified, log_subcmds will be ignored. See Preventing
765 shell escapes in sudoers(5) for more information. Only
766 available starting with API version 1.18.
767 noexec=bool
769 If set, prevent the command from executing other pro‐
770 grams.
771 preserve_fds=list
773 A comma-separated list of file descriptors that should
774 be preserved, regardless of the value of the closefrom
775 setting. Only available starting with API version 1.5.
776 preserve_groups=bool
778 If set, sudo will preserve the user's group vector in‐
779 stead of initializing the group vector based on
780 runas_user.
781 rlimit_as=soft,hard
783 The maximum size to which the process's address space
784 may grow (in bytes), if supported by the operating sys‐
785 tem. The soft and hard limits are separated by a
786 comma. If only a single value is specified, both the
787 hard and soft limits are set. A value of “infinity”
788 indicates that there is no limit. A value of “user”
789 will cause the invoking user's resource limit to be
790 preserved. A value of “default” will cause the target
791 user's default resource limit to be used on systems
792 that allow per-user resource limits to be configured.
793 Only available starting with API version 1.18.
794 rlimit_core=soft,hard
796 The largest size core dump file that may be created (in
797 bytes). The soft and hard limits are separated by a
798 comma. If only a single value is specified, both the
799 hard and soft limits are set. A value of “infinity”
800 indicates that there is no limit. A value of “user”
801 will cause the invoking user's resource limit to be
802 preserved. A value of “default” will cause the target
803 user's default resource limit to be used on systems
804 that allow per-user resource limits to be configured.
805 Only available starting with API version 1.18.
806 rlimit_cpu=soft,hard
808 The maximum amount of CPU time that the process may use
809 (in seconds). The soft and hard limits are separated
810 by a comma. If only a single value is specified, both
811 the hard and soft limits are set. A value of
812 “infinity” indicates that there is no limit. A value
813 of “user” will cause the invoking user's resource limit
814 to be preserved. A value of “default” will cause the
815 target user's default resource limit to be used on sys‐
816 tems that allow per-user resource limits to be config‐
817 ured. Only available starting with API version 1.18.
818 rlimit_data=soft,hard
820 The maximum size of the data segment for the process
821 (in bytes). The soft and hard limits are separated by
822 a comma. If only a single value is specified, both the
823 hard and soft limits are set. A value of “infinity”
824 indicates that there is no limit. A value of “user”
825 will cause the invoking user's resource limit to be
826 preserved. A value of “default” will cause the target
827 user's default resource limit to be used on systems
828 that allow per-user resource limits to be configured.
829 Only available starting with API version 1.18.
830 rlimit_fsize=soft,hard
832 The largest size file that the process may create (in
833 bytes). The soft and hard limits are separated by a
834 comma. If only a single value is specified, both the
835 hard and soft limits are set. A value of “infinity”
836 indicates that there is no limit. A value of “user”
837 will cause the invoking user's resource limit to be
838 preserved. A value of “default” will cause the target
839 user's default resource limit to be used on systems
840 that allow per-user resource limits to be configured.
841 Only available starting with API version 1.18.
842 rlimit_locks=soft,hard
844 The maximum number of locks that the process may estab‐
845 lish, if supported by the operating system. The soft
846 and hard limits are separated by a comma. If only a
847 single value is specified, both the hard and soft lim‐
848 its are set. A value of “infinity” indicates that
849 there is no limit. A value of “user” will cause the
850 invoking user's resource limit to be preserved. A
851 value of “default” will cause the target user's default
852 resource limit to be used on systems that allow per-
853 user resource limits to be configured. Only available
854 starting with API version 1.18.
855 rlimit_memlock=soft,hard
857 The maximum size that the process may lock in memory
858 (in bytes), if supported by the operating system. The
859 soft and hard limits are separated by a comma. If only
860 a single value is specified, both the hard and soft
861 limits are set. A value of “infinity” indicates that
862 there is no limit. A value of “user” will cause the
863 invoking user's resource limit to be preserved. A
864 value of “default” will cause the target user's default
865 resource limit to be used on systems that allow per-
866 user resource limits to be configured. Only available
867 starting with API version 1.18.
868 rlimit_nofile=soft,hard
870 The maximum number of files that the process may have
871 open. The soft and hard limits are separated by a
872 comma. If only a single value is specified, both the
873 hard and soft limits are set. A value of “infinity”
874 indicates that there is no limit. A value of “user”
875 will cause the invoking user's resource limit to be
876 preserved. A value of “default” will cause the target
877 user's default resource limit to be used on systems
878 that allow per-user resource limits to be configured.
879 Only available starting with API version 1.18.
880 rlimit_nproc=soft,hard
882 The maximum number of processes that the user may run
883 simultaneously. The soft and hard limits are separated
884 by a comma. If only a single value is specified, both
885 the hard and soft limits are set. A value of
886 “infinity” indicates that there is no limit. A value
887 of “user” will cause the invoking user's resource limit
888 to be preserved. A value of “default” will cause the
889 target user's default resource limit to be used on sys‐
890 tems that allow per-user resource limits to be config‐
891 ured. Only available starting with API version 1.18.
892 rlimit_rss=soft,hard
894 The maximum size to which the process's resident set
895 size may grow (in bytes). The soft and hard limits are
896 separated by a comma. If only a single value is speci‐
897 fied, both the hard and soft limits are set. A value
898 of “infinity” indicates that there is no limit. A
899 value of “user” will cause the invoking user's resource
900 limit to be preserved. A value of “default” will cause
901 the target user's default resource limit to be used on
902 systems that allow per-user resource limits to be con‐
903 figured. Only available starting with API version
904 1.18.
905 rlimit_stack=soft,hard
907 The maximum size to which the process's stack may grow
908 (in bytes). The soft and hard limits are separated by
909 a comma. If only a single value is specified, both the
910 hard and soft limits are set. A value of “infinity”
911 indicates that there is no limit. A value of “user”
912 will cause the invoking user's resource limit to be
913 preserved. A value of “default” will cause the target
914 user's default resource limit to be used on systems
915 that allow per-user resource limits to be configured.
916 Only available starting with API version 1.18.
917 runas_egid=gid
919 Effective group-ID to run the command as. If not spec‐
920 ified, the value of runas_gid is used.
921 runas_euid=uid
923 Effective user-ID to run the command as. If not speci‐
924 fied, the value of runas_uid is used.
925 runas_gid=gid
927 Group-ID to run the command as.
928 runas_group=string
930 The name of the group the command will run as, if it is
931 different from the runas_user's default group. This
932 value is provided for auditing purposes only, the sudo
933 front-end uses runas_egid and runas_gid when executing
934 the command.
935 runas_groups=list
937 The supplementary group vector to use for the command
938 in the form of a comma-separated list of group-IDs. If
939 preserve_groups is set, this option is ignored.
940 runas_uid=uid
942 User-ID to run the command as.
943 runas_user=string
945 The name of the user the command will run as, which
946 should correspond to runas_euid (or runas_uid if
947 runas_euid is not set). This value is provided for au‐
948 diting purposes only, the sudo front-end uses
949 runas_euid and runas_uid when executing the command.
950 selinux_role=string
952 SELinux role to use when executing the command.
953 selinux_type=string
955 SELinux type to use when executing the command.
956 set_utmp=bool
958 Create a utmp (or utmpx) entry when a pseudo-terminal
959 is allocated. By default, the new entry will be a copy
960 of the user's existing utmp entry (if any), with the
961 tty, time, type, and pid fields updated.
962 sudoedit=bool
964 Set to true when in sudoedit mode. The plugin may en‐
965 able sudoedit mode even if sudo was not invoked as
966 sudoedit. This allows the plugin to perform command
967 substitution and transparently enable sudoedit when the
968 user attempts to run an editor.
969 sudoedit_checkdir=bool
971 Set to false to disable directory writability checks in
972 sudoedit. By default, sudoedit 1.8.16 and higher will
973 check all directory components of the path to be edited
974 for writability by the invoking user. Symbolic links
975 will not be followed in writable directories and
976 sudoedit will refuse to edit a file located in a
977 writable directory. These restrictions are not en‐
978 forced when sudoedit is run by root. The
979 sudoedit_checkdir option can be set to false to disable
980 this check. Only available starting with API version
981 1.8.
982 sudoedit_follow=bool
984 Set to true to allow sudoedit to edit files that are
985 symbolic links. By default, sudoedit 1.8.15 and higher
986 will refuse to open a symbolic link. The
987 sudoedit_follow option can be used to restore the older
988 behavior and allow sudoedit to open symbolic links.
989 Only available starting with API version 1.8.
990 timeout=int
992 Command timeout. If non-zero then when the timeout ex‐
993 pires the command will be killed.
994 umask=octal
996 The file creation mask to use when executing the com‐
997 mand. This value may be overridden by PAM or lo‐
998 gin.conf on some systems unless the umask_override op‐
999 tion is also set.
1000 umask_override=bool
1002 Force the value specified by the umask option to over‐
1003 ride any umask set by PAM or login.conf.
1004 use_ptrace=bool
1006 If set, sudo will use ptrace(2) to implement intercept
1007 mode if supported by the system. This setting has no
1008 effect unless intercept is also set. Only available
1009 starting with API version 1.19.
1010 use_pty=bool
1012 Allocate a pseudo-terminal to run the command in, re‐
1013 gardless of whether or not I/O logging is in use. By
1014 default, sudo will only run the command in a pseudo-
1015 terminal when an I/O log plugin is loaded.
1016 utmp_user=string
1018 User name to use when constructing a new utmp (or
1019 utmpx) entry when set_utmp is enabled. This option can
1020 be used to set the user field in the utmp entry to the
1021 user the command runs as rather than the invoking user.
1022 If not set, sudo will base the new entry on the invok‐
1023 ing user's existing entry.
1024 Unsupported values will be ignored.
1026 argv_out
1028 The NULL-terminated argument vector to pass to the execve(2)
1029 system call when executing the command. The plugin is re‐
1030 sponsible for allocating and populating the vector.
1031 user_env_out
1033 The NULL-terminated environment vector to use when executing
1034 the command. The plugin is responsible for allocating and
1035 populating the vector.
1036 errstr
1038 If the check_policy() function returns a value other than 1,
1039 the plugin may store a message describing the failure or er‐
1040 ror in errstr. The sudo front-end will then pass this value
1041 to any registered audit plugins. The string stored in errstr
1042 must remain valid until the plugin's close() function is
1043 called.
1044 The errstr parameter is only available starting with API ver‐
1046 sion 1.15. A plugin must check the API version specified by
1047 the sudo front-end before using errstr. Failure to do so may
1048 result in a crash.
1049 list
1051 int (*list)(int argc, char * const argv[], int verbose,
1052 const char *user, const char **errstr);
1053 List available privileges for the invoking user. Returns 1 on suc‐
1055 cess, 0 on failure, and -1 on error. On error, the plugin may op‐
1056 tionally call the conversation() or sudo_plugin_printf() function
1057 with SUDO_CONF_ERROR_MSG to present additional error information to
1058 the user.
1059 Privileges should be output via the conversation() or
1061 sudo_plugin_printf() function using SUDO_CONV_INFO_MSG.
1062 The function arguments are as follows:
1064 argc The number of elements in argv, not counting the final NULL
1066 pointer.
1067 argv If non-NULL, an argument vector describing a command the user
1069 wishes to check against the policy in the same form as what
1070 would be passed to the execve(2) system call. If the command
1071 is permitted by the policy, the fully-qualified path to the
1072 command should be displayed along with any command line argu‐
1073 ments.
1074 verbose
1076 Flag indicating whether to list in verbose mode or not.
1077 user The name of a different user to list privileges for if the
1079 policy allows it. If NULL, the plugin should list the privi‐
1080 leges of the invoking user.
1081 errstr
1083 If the list() function returns a value other than 1, the
1084 plugin may store a message describing the failure or error in
1085 errstr. The sudo front-end will then pass this value to any
1086 registered audit plugins. The string stored in errstr must
1087 remain valid until the plugin's close() function is called.
1088 The errstr parameter is only available starting with API ver‐
1090 sion 1.15. A plugin must check the API version specified by
1091 the sudo front-end before using errstr. Failure to do so may
1092 result in a crash.
1093 validate
1095 int (*validate)(const char **errstr);
1096 The validate() function is called when sudo is run with the -v op‐
1098 tion. For policy plugins such as sudoers that cache authentication
1099 credentials, this function will validate and cache the credentials.
1100 The validate() function should be NULL if the plugin does not sup‐
1102 port credential caching.
1103 Returns 1 on success, 0 on failure, and -1 on error. On error, the
1105 plugin may optionally call the conversation() or
1106 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1107 additional error information to the user.
1108 The function arguments are as follows:
1110 errstr
1112 If the validate() function returns a value other than 1, the
1113 plugin may store a message describing the failure or error in
1114 errstr. The sudo front-end will then pass this value to any
1115 registered audit plugins. The string stored in errstr must
1116 remain valid until the plugin's close() function is called.
1117 The errstr parameter is only available starting with API ver‐
1119 sion 1.15. A plugin must check the API version specified by
1120 the sudo front-end before using errstr. Failure to do so may
1121 result in a crash.
1122 invalidate
1124 void (*invalidate)(int rmcred);
1125 The invalidate() function is called when sudo is run with the -k or
1127 -K option. For policy plugins such as sudoers that cache authenti‐
1128 cation credentials, this function will invalidate the credentials.
1129 If the rmcred flag is non-zero, the plugin may remove the creden‐
1130 tials instead of simply invalidating them.
1131 The invalidate() function should be NULL if the plugin does not
1133 support credential caching.
1134 init_session
1136 int (*init_session)(struct passwd *pwd, char **user_env[],
1137 const char **errstr);
1138 The init_session() function is called before sudo sets up the exe‐
1140 cution environment for the command. It is run in the parent sudo
1141 process before any user-ID or group-ID changes. This can be used
1142 to perform session setup that is not supported by command_info,
1143 such as opening the PAM session. The close() function can be used
1144 to tear down the session that was opened by init_session().
1145 Returns 1 on success, 0 on failure, and -1 on error. On error, the
1147 plugin may optionally call the conversation() or
1148 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1149 additional error information to the user.
1150 The function arguments are as follows:
1152 pwd If the user-ID the command will run as was found in the pass‐
1154 word database, pwd will describe that user, otherwise it will
1155 be NULL.
1156 user_env_out
1158 The NULL-terminated environment vector to use when executing
1159 the command. This is the same string passed back to the
1160 front-end via the Policy Plugin's user_env_out parameter. If
1161 the init_session() function needs to modify the user environ‐
1162 ment, it should update the pointer stored in user_env_out.
1163 The expected use case is to merge the contents of the PAM en‐
1164 vironment (if any) with the contents of user_env_out. The
1165 user_env_out parameter is only available starting with API
1166 version 1.2. A plugin must check the API version specified
1167 by the sudo front-end before using user_env_out. Failure to
1168 do so may result in a crash.
1169 errstr
1171 If the init_session() function returns a value other than 1,
1172 the plugin may store a message describing the failure or er‐
1173 ror in errstr. The sudo front-end will then pass this value
1174 to any registered audit plugins. The string stored in errstr
1175 must remain valid until the plugin's close() function is
1176 called.
1177 The errstr parameter is only available starting with API ver‐
1179 sion 1.15. A plugin must check the API version specified by
1180 the sudo front-end before using errstr. Failure to do so may
1181 result in a crash.
1182 register_hooks
1184 void (*register_hooks)(int version,
1185 int (*register_hook)(struct sudo_hook *hook));
1186 The register_hooks() function is called by the sudo front-end to
1188 register any hooks the plugin needs. If the plugin does not sup‐
1189 port hooks, register_hooks should be set to the NULL pointer.
1190 The version argument describes the version of the hooks API sup‐
1192 ported by the sudo front-end.
1193 The register_hook() function should be used to register any sup‐
1195 ported hooks the plugin needs. It returns 0 on success, 1 if the
1196 hook type is not supported, and -1 if the major version in struct
1197 sudo_hook does not match the front-end's major hook API version.
1198 See the Hook function API section below for more information about
1200 hooks.
1201 The register_hooks() function is only available starting with API
1203 version 1.2. If the sudo front-end doesn't support API version 1.2
1204 or higher, register_hooks() will not be called.
1205 deregister_hooks
1207 void (*deregister_hooks)(int version,
1208 int (*deregister_hook)(struct sudo_hook *hook));
1209 The deregister_hooks() function is called by the sudo front-end to
1211 deregister any hooks the plugin has registered. If the plugin does
1212 not support hooks, deregister_hooks should be set to the NULL
1213 pointer.
1214 The version argument describes the version of the hooks API sup‐
1216 ported by the sudo front-end.
1217 The deregister_hook() function should be used to deregister any
1219 hooks that were put in place by the register_hook() function. If
1220 the plugin tries to deregister a hook that the front-end does not
1221 support, deregister_hook() will return an error.
1222 See the Hook function API section below for more information about
1224 hooks.
1225 The deregister_hooks() function is only available starting with API
1227 version 1.2. If the sudo front-end doesn't support API version 1.2
1228 or higher, deregister_hooks() will not be called.
1229 event_alloc
1231 struct sudo_plugin_event * (*event_alloc)(void);
1232 The event_alloc() function is used to allocate a struct
1234 sudo_plugin_event which provides access to the main sudo event
1235 loop. Unlike the other fields, the event_alloc pointer is filled
1236 in by the sudo front-end, not by the plugin.
1237 See the Event API section below for more information about events.
1239 The event_alloc() function is only available starting with API ver‐
1241 sion 1.15. If the sudo front-end doesn't support API version 1.15
1242 or higher, event_alloc will not be set.
1243 Policy Plugin Version Macros
1245 /* Plugin API version major/minor. */
1247 #define SUDO_API_VERSION_MAJOR 1
1248 #define SUDO_API_VERSION_MINOR 13
1249 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1250 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
1251 SUDO_API_VERSION_MINOR)
1252 /* Getters and setters for API version */
1254 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1255 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1256 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
1257 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1258 } while(0)
1259 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
1260 *(vp) = (*(vp) & 0xffff0000) | (n); \
1261 } while(0)
1262 I/O plugin API
1264 struct io_plugin {
1265 #define SUDO_IO_PLUGIN 2
1266 unsigned int type; /* always SUDO_IO_PLUGIN */
1267 unsigned int version; /* always SUDO_API_VERSION */
1268 int (*open)(unsigned int version, sudo_conv_t conversation,
1269 sudo_printf_t sudo_plugin_printf, char * const settings[],
1270 char * const user_info[], char * const command_info[],
1271 int argc, char * const argv[], char * const user_env[],
1272 char * const plugin_options[], const char **errstr);
1273 void (*close)(int exit_status, int error); /* wait status or error */
1274 int (*show_version)(int verbose);
1275 int (*log_ttyin)(const char *buf, unsigned int len,
1276 const char **errstr);
1277 int (*log_ttyout)(const char *buf, unsigned int len,
1278 const char **errstr);
1279 int (*log_stdin)(const char *buf, unsigned int len,
1280 const char **errstr);
1281 int (*log_stdout)(const char *buf, unsigned int len,
1282 const char **errstr);
1283 int (*log_stderr)(const char *buf, unsigned int len,
1284 const char **errstr);
1285 void (*register_hooks)(int version,
1286 int (*register_hook)(struct sudo_hook *hook));
1287 void (*deregister_hooks)(int version,
1288 int (*deregister_hook)(struct sudo_hook *hook));
1289 int (*change_winsize)(unsigned int lines, unsigned int cols,
1290 const char **errstr);
1291 int (*log_suspend)(int signo, const char **errstr);
1292 struct sudo_plugin_event * (*event_alloc)(void);
1293 };
1294 When an I/O plugin is loaded, sudo runs the command in a pseudo-terminal.
1296 This makes it possible to log the input and output from the user's ses‐
1297 sion. If any of the standard input, standard output, or standard error
1298 do not correspond to a tty, sudo will open a pipe to capture the I/O for
1299 logging before passing it on.
1300 The log_ttyin() function receives the raw user input from the terminal
1302 device (this will include input even when echo is disabled, such as when
1303 a password is read). The log_ttyout() function receives output from the
1304 pseudo-terminal that is suitable for replaying the user's session at a
1305 later time. The log_stdin(), log_stdout(), and log_stderr() functions
1306 are only called if the standard input, standard output, or standard error
1307 respectively correspond to something other than a tty.
1308 Any of the logging functions may be set to the NULL pointer if no logging
1310 is to be performed. If the open function returns 0, no I/O will be sent
1311 to the plugin.
1312 If a logging function returns an error (-1), the running command will be
1314 terminated and all of the plugin's logging functions will be disabled.
1315 Other I/O logging plugins will still receive any remaining input or out‐
1316 put that has not yet been processed.
1317 If an input logging function rejects the data by returning 0, the command
1319 will be terminated and the data will not be passed to the command, though
1320 it will still be sent to any other I/O logging plugins. If an output
1321 logging function rejects the data by returning 0, the command will be
1322 terminated and the data will not be written to the terminal, though it
1323 will still be sent to any other I/O logging plugins.
1324 A struct audit_plugin has the following fields:
1326 type The type field should always be set to SUDO_IO_PLUGIN.
1328 version
1330 The version field should be set to SUDO_API_VERSION.
1331 This allows sudo to determine the API version the plugin was built
1333 against.
1334 open
1336 int (*open)(unsigned int version, sudo_conv_t conversation,
1337 sudo_printf_t sudo_plugin_printf, char * const settings[],
1338 char * const user_info[], char * const command_info[],
1339 int argc, char * const argv[], char * const user_env[],
1340 char * const plugin_options[]);
1341 The open() function is run before the log_ttyin(), log_ttyout(),
1343 log_stdin(), log_stdout(), log_stderr(), log_suspend(),
1344 change_winsize(), or show_version() functions are called. It is
1345 only called if the version is being requested or if the policy
1346 plugin's check_policy() function has returned successfully. It re‐
1347 turns 1 on success, 0 on failure, -1 if a general error occurred,
1348 or -2 if there was a usage error. In the latter case, sudo will
1349 print a usage message before it exits. If an error occurs, the
1350 plugin may optionally call the conversation() or
1351 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1352 additional error information to the user.
1353 The function arguments are as follows:
1355 version
1357 The version passed in by sudo allows the plugin to determine
1358 the major and minor version number of the plugin API sup‐
1359 ported by sudo.
1360 conversation
1362 A pointer to the conversation() function that may be used by
1363 the Fa(show_version) function to display version information
1364 (see show_version() below). The conversation() function may
1365 also be used to display additional error message to the user.
1366 The conversation() function returns 0 on success and -1 on
1367 failure.
1368 sudo_plugin_printf
1370 A pointer to a printf()-style function that may be used by
1371 the show_version() function to display version information
1372 (see show_version below). The sudo_plugin_printf() function
1373 may also be used to display additional error message to the
1374 user. The sudo_plugin_printf() function returns number of
1375 characters printed on success and -1 on failure.
1376 settings
1378 A vector of user-supplied sudo settings in the form of
1379 “name=value” strings. The vector is terminated by a NULL
1380 pointer. These settings correspond to options the user spec‐
1381 ified when running sudo. As such, they will only be present
1382 when the corresponding option has been specified on the com‐
1383 mand line.
1384 When parsing settings, the plugin should split on the first
1386 equal sign (‘=’) since the name field will never include one
1387 itself but the value might.
1388 See the Policy plugin API section for a list of all possible
1390 settings.
1391 user_info
1393 A vector of information about the user running the command in
1394 the form of “name=value” strings. The vector is terminated
1395 by a NULL pointer.
1396 When parsing user_info, the plugin should split on the first
1398 equal sign (‘=’) since the name field will never include one
1399 itself but the value might.
1400 See the Policy plugin API section for a list of all possible
1402 strings.
1403 command_info
1405 A vector of information describing the command being run in
1406 the form of “name=value” strings. The vector is terminated
1407 by a NULL pointer.
1408 When parsing command_info, the plugin should split on the
1410 first equal sign (‘=’) since the name field will never in‐
1411 clude one itself but the value might.
1412 See the Policy plugin API section for a list of all possible
1414 strings.
1415 argc The number of elements in argv, not counting the final NULL
1417 pointer. It can be zero, such as when sudo is called with
1418 the -V option.
1419 argv If non-NULL, an argument vector describing a command the user
1421 wishes to run in the same form as what would be passed to the
1422 execve(2) system call.
1423 user_env
1425 The user's environment in the form of a NULL-terminated vec‐
1426 tor of “name=value” strings.
1427 When parsing user_env, the plugin should split on the first
1429 equal sign (‘=’) since the name field will never include one
1430 itself but the value might.
1431 plugin_options
1433 Any (non-comment) strings immediately after the plugin path
1434 are treated as arguments to the plugin. These arguments are
1435 split on a white space boundary and are passed to the plugin
1436 in the form of a NULL-terminated array of strings. If no ar‐
1437 guments were specified, plugin_options will be the NULL
1438 pointer.
1439 The plugin_options parameter is only available starting with
1441 API version 1.2. A plugin must check the API version speci‐
1442 fied by the sudo front-end before using plugin_options.
1443 Failure to do so may result in a crash.
1444 errstr
1446 If the open() function returns a value other than 1, the
1447 plugin may store a message describing the failure or error in
1448 errstr. The sudo front-end will then pass this value to any
1449 registered audit plugins. The string stored in errstr must
1450 remain valid until the plugin's close() function is called.
1451 The errstr parameter is only available starting with API ver‐
1453 sion 1.15. A plugin must check the API version specified by
1454 the sudo front-end before using errstr. Failure to do so may
1455 result in a crash.
1456 close
1458 void (*close)(int exit_status, int error);
1459 The close() function is called when sudo is finished, shortly be‐
1461 fore it exits.
1462 The function arguments are as follows:
1464 exit_status
1466 The command's exit status, as returned by the wait(2) system
1467 call, or zero if no command was run. The value of
1468 exit_status is undefined if error is non-zero.
1469 error
1471 If the command could not be executed, this is set to the
1472 value of errno set by the execve(2) system call. If the com‐
1473 mand was successfully executed, the value of error is zero.
1474 show_version
1476 int (*show_version)(int verbose);
1477 The show_version() function is called by sudo when the user speci‐
1479 fies the -V option. The plugin may display its version information
1480 to the user via the conversation() or sudo_plugin_printf() function
1481 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1482 information, the verbose flag will be non-zero.
1483 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1485 or -2 if there was a usage error, although the return value is cur‐
1486 rently ignored.
1487 log_ttyin
1489 int (*log_ttyin)(const char *buf, unsigned int len,
1490 const char **errstr);
1491 The log_ttyin() function is called whenever data can be read from
1493 the user but before it is passed to the running command. This al‐
1494 lows the plugin to reject data if it chooses to (for instance if
1495 the input contains banned content). Returns 1 if the data should
1496 be passed to the command, 0 if the data is rejected (which will
1497 terminate the running command), or -1 if an error occurred.
1498 The function arguments are as follows:
1500 buf The buffer containing user input.
1502 len The length of buf in bytes.
1504 errstr
1506 If the log_ttyin() function returns a value other than 1, the
1507 plugin may store a message describing the failure or error in
1508 errstr. The sudo front-end will then pass this value to any
1509 registered audit plugins. The string stored in errstr must
1510 remain valid until the plugin's close() function is called.
1511 The errstr parameter is only available starting with API ver‐
1513 sion 1.15. A plugin must check the API version specified by
1514 the sudo front-end before using errstr. Failure to do so may
1515 result in a crash.
1516 log_ttyout
1518 int (*log_ttyout)(const char *buf, unsigned int len,
1519 const char **errstr);
1520 The log_ttyout() function is called whenever data can be read from
1522 the command but before it is written to the user's terminal. This
1523 allows the plugin to reject data if it chooses to (for instance if
1524 the output contains banned content). Returns 1 if the data should
1525 be passed to the user, 0 if the data is rejected (which will termi‐
1526 nate the running command), or -1 if an error occurred.
1527 The function arguments are as follows:
1529 buf The buffer containing command output.
1531 len The length of buf in bytes.
1533 errstr
1535 If the log_ttyout() function returns a value other than 1,
1536 the plugin may store a message describing the failure or er‐
1537 ror in errstr. The sudo front-end will then pass this value
1538 to any registered audit plugins. The string stored in errstr
1539 must remain valid until the plugin's close() function is
1540 called.
1541 The errstr parameter is only available starting with API ver‐
1543 sion 1.15. A plugin must check the API version specified by
1544 the sudo front-end before using errstr. Failure to do so may
1545 result in a crash.
1546 log_stdin
1548 int (*log_stdin)(const char *buf, unsigned int len,
1549 const char **errstr);
1550 The log_stdin() function is only used if the standard input does
1552 not correspond to a tty device. It is called whenever data can be
1553 read from the standard input but before it is passed to the running
1554 command. This allows the plugin to reject data if it chooses to
1555 (for instance if the input contains banned content). Returns 1 if
1556 the data should be passed to the command, 0 if the data is rejected
1557 (which will terminate the running command), or -1 if an error oc‐
1558 curred.
1559 The function arguments are as follows:
1561 buf The buffer containing user input.
1563 len The length of buf in bytes.
1565 errstr
1567 If the log_stdin() 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 The errstr parameter is only available starting with API ver‐
1574 sion 1.15. A plugin must check the API version specified by
1575 the sudo front-end before using errstr. Failure to do so may
1576 result in a crash.
1577 log_stdout
1579 int (*log_stdout)(const char *buf, unsigned int len,
1580 const char **errstr);
1581 The log_stdout() function is only used if the standard output does
1583 not correspond to a tty device. It is called whenever data can be
1584 read from the command but before it is written to the standard out‐
1585 put. This allows the plugin to reject data if it chooses to (for
1586 instance if the output contains banned content). Returns 1 if the
1587 data should be passed to the user, 0 if the data is rejected (which
1588 will terminate the running command), or -1 if an error occurred.
1589 The function arguments are as follows:
1591 buf The buffer containing command output.
1593 len The length of buf in bytes.
1595 errstr
1597 If the log_stdout() function returns a value other than 1,
1598 the plugin may store a message describing the failure or er‐
1599 ror in errstr. The sudo front-end will then pass this value
1600 to any registered audit plugins. The string stored in errstr
1601 must remain valid until the plugin's close() function is
1602 called.
1603 The errstr parameter is only available starting with API ver‐
1605 sion 1.15. A plugin must check the API version specified by
1606 the sudo front-end before using errstr. Failure to do so may
1607 result in a crash.
1608 log_stderr
1610 int (*log_stderr)(const char *buf, unsigned int len,
1611 const char **errstr);
1612 The log_stderr() function is only used if the standard error does
1614 not correspond to a tty device. It is called whenever data can be
1615 read from the command but before it is written to the standard er‐
1616 ror. This allows the plugin to reject data if it chooses to (for
1617 instance if the output contains banned content). Returns 1 if the
1618 data should be passed to the user, 0 if the data is rejected (which
1619 will terminate the running command), or -1 if an error occurred.
1620 The function arguments are as follows:
1622 buf The buffer containing command output.
1624 len The length of buf in bytes.
1626 errstr
1628 If the log_stderr() function returns a value other than 1,
1629 the plugin may store a message describing the failure or er‐
1630 ror in errstr. The sudo front-end will then pass this value
1631 to any registered audit plugins. The string stored in errstr
1632 must remain valid until the plugin's close() function is
1633 called.
1634 The errstr parameter is only available starting with API ver‐
1636 sion 1.15. A plugin must check the API version specified by
1637 the sudo front-end before using errstr. Failure to do so may
1638 result in a crash.
1639 register_hooks
1641 See the Policy plugin API section for a description of
1642 register_hooks().
1643 deregister_hooks
1645 See the Policy plugin API section for a description of
1646 deregister_hooks().
1647 change_winsize
1649 int (*change_winsize)(unsigned int lines, unsigned int cols,
1650 const char **errstr);
1651 The change_winsize() function is called whenever the window size of
1653 the terminal changes from the initial values specified in the
1654 user_info list. Returns -1 if an error occurred, in which case no
1655 further calls to change_winsize() will be made,
1656 The function arguments are as follows:
1658 lines
1660 The number of lines (rows) in the re-sized terminal.
1661 cols The number of columns in the re-sized terminal.
1663 errstr
1665 If the change_winsize() function returns a value other than
1666 1, the plugin may store a message describing the failure or
1667 error in errstr. The sudo front-end will then pass this
1668 value to any registered audit plugins. The string stored in
1669 errstr must remain valid until the plugin's close() function
1670 is called.
1671 The errstr parameter is only available starting with API ver‐
1673 sion 1.15. A plugin must check the API version specified by
1674 the sudo front-end before using errstr. Failure to do so may
1675 result in a crash.
1676 log_suspend
1678 int (*log_suspend)(int signo, const char **errstr);
1679 The log_suspend() function is called whenever a command is sus‐
1681 pended or resumed. Logging this information makes it possible to
1682 skip the period of time when the command was suspended during play‐
1683 back of a session. Returns -1 if an error occurred, in which case
1684 no further calls to log_suspend() will be made,
1685 The function arguments are as follows:
1687 signo
1689 The signal that caused the command to be suspended, or
1690 SIGCONT if the command was resumed.
1691 errstr
1693 If the log_suspend() function returns a value other than 1,
1694 the plugin may store a message describing the failure or er‐
1695 ror in errstr. The sudo front-end will then pass this value
1696 to any registered audit plugins. The string stored in errstr
1697 must remain valid until the plugin's close() function is
1698 called.
1699 The errstr parameter is only available starting with API ver‐
1701 sion 1.15. A plugin must check the API version specified by
1702 the sudo front-end before using errstr. Failure to do so may
1703 result in a crash.
1704 event_alloc
1706 struct sudo_plugin_event * (*event_alloc)(void);
1707 The event_alloc() function is used to allocate a struct
1709 sudo_plugin_event which provides access to the main sudo
1710 event loop. Unlike the other fields, the event_alloc()
1711 pointer is filled in by the sudo front-end, not by the
1712 plugin.
1713 See the Event API section below for more information about
1715 events.
1716 The event_alloc() function is only available starting with
1718 API version 1.15. If the sudo front-end doesn't support API
1719 version 1.15 or higher, event_alloc() will not be set.
1720 I/O Plugin Version Macros
1722 Same as for the Policy plugin API.
1724 Audit plugin API
1726 /* Audit plugin close function status types. */
1727 #define SUDO_PLUGIN_NO_STATUS 0
1728 #define SUDO_PLUGIN_WAIT_STATUS 1
1729 #define SUDO_PLUGIN_EXEC_ERROR 2
1730 #define SUDO_PLUGIN_SUDO_ERROR 3
1731 #define SUDO_AUDIT_PLUGIN 3
1733 struct audit_plugin {
1734 unsigned int type; /* always SUDO_AUDIT_PLUGIN */
1735 unsigned int version; /* always SUDO_API_VERSION */
1736 int (*open)(unsigned int version, sudo_conv_t conversation,
1737 sudo_printf_t sudo_plugin_printf, char * const settings[],
1738 char * const user_info[], int submit_optind,
1739 char * const submit_argv[], char * const submit_envp[],
1740 char * const plugin_options[], const char **errstr);
1741 void (*close)(int status_type, int status);
1742 int (*accept)(const char *plugin_name,
1743 unsigned int plugin_type, char * const command_info[],
1744 char * const run_argv[], char * const run_envp[],
1745 const char **errstr);
1746 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1747 const char *audit_msg, char * const command_info[],
1748 const char **errstr);
1749 int (*error)(const char *plugin_name, unsigned int plugin_type,
1750 const char *audit_msg, char * const command_info[],
1751 const char **errstr);
1752 int (*show_version)(int verbose);
1753 void (*register_hooks)(int version,
1754 int (*register_hook)(struct sudo_hook *hook));
1755 void (*deregister_hooks)(int version,
1756 int (*deregister_hook)(struct sudo_hook *hook));
1757 struct sudo_plugin_event * (*event_alloc)(void);
1758 }
1759 An audit plugin can be used to log successful and unsuccessful attempts
1761 to run sudo independent of the policy or any I/O plugins. Multiple audit
1762 plugins may be specified in sudo.conf(5).
1763 A struct audit_plugin has the following fields:
1765 type The type field should always be set to SUDO_AUDIT_PLUGIN.
1767 version
1769 The version field should be set to SUDO_API_VERSION.
1770 This allows sudo to determine the API version the plugin was built
1772 against.
1773 open
1775 int (*open)(unsigned int version, sudo_conv_t conversation,
1776 sudo_printf_t sudo_plugin_printf, char * const settings[],
1777 char * const user_info[], int submit_optind,
1778 char * const submit_argv[], char * const submit_envp[],
1779 char * const plugin_options[], const char **errstr);
1780 The audit open() function is run before any other sudo plugin API
1782 functions. This makes it possible to audit failures in the other
1783 plugins. It returns 1 on success, 0 on failure, -1 if a general
1784 error occurred, or -2 if there was a usage error. In the latter
1785 case, sudo will print a usage message before it exits. If an error
1786 occurs, the plugin may optionally call the conversation() or
1787 plugin_printf() function with SUDO_CONF_ERROR_MSG to present addi‐
1788 tional error information to the user.
1789 The function arguments are as follows:
1791 version
1793 The version passed in by sudo allows the plugin to determine
1794 the major and minor version number of the plugin API sup‐
1795 ported by sudo.
1796 conversation
1798 A pointer to the conversation() function that may be used by
1799 the show_version() function to display version information
1800 (see show_version() below). The conversation() function may
1801 also be used to display additional error message to the user.
1802 The conversation() function returns 0 on success, and -1 on
1803 failure.
1804 plugin_printf
1806 A pointer to a printf()-style function that may be used by
1807 the show_version() function to display version information
1808 (see show_version below). The plugin_printf() function may
1809 also be used to display additional error message to the user.
1810 The plugin_printf() function returns number of characters
1811 printed on success and -1 on failure.
1812 settings
1814 A vector of user-supplied sudo settings in the form of
1815 “name=value” strings. The vector is terminated by a NULL
1816 pointer. These settings correspond to options the user spec‐
1817 ified when running sudo. As such, they will only be present
1818 when the corresponding option has been specified on the com‐
1819 mand line.
1820 When parsing settings, the plugin should split on the first
1822 equal sign (‘=’) since the name field will never include one
1823 itself but the value might.
1824 See the Policy plugin API section for a list of all possible
1826 settings.
1827 user_info
1829 A vector of information about the user running the command in
1830 the form of “name=value” strings. The vector is terminated
1831 by a NULL pointer.
1832 When parsing user_info, the plugin should split on the first
1834 equal sign (‘=’) since the name field will never include one
1835 itself but the value might.
1836 See the Policy plugin API section for a list of all possible
1838 strings.
1839 submit_optind
1841 The index into submit_argv that corresponds to the first en‐
1842 try that is not a command line option. If submit_argv only
1843 consists of options, which may be the case with the -l or -v
1844 options, submit_argv[submit_optind] will evaluate to the NULL
1845 pointer.
1846 submit_argv
1848 The argument vector sudo was invoked with, including all com‐
1849 mand line options. The submit_optind argument can be used to
1850 determine the end of the command line options.
1851 submit_envp
1853 The invoking user's environment in the form of a
1854 NULL-terminated vector of “name=value” strings.
1855 When parsing submit_envp, the plugin should split on the
1857 first equal sign (‘=’) since the name field will never in‐
1858 clude one itself but the value might.
1859 plugin_options
1861 Any (non-comment) strings immediately after the plugin path
1862 are treated as arguments to the plugin. These arguments are
1863 split on a white space boundary and are passed to the plugin
1864 in the form of a NULL-terminated array of strings. If no ar‐
1865 guments were specified, plugin_options will be the NULL
1866 pointer.
1867 errstr
1869 If the open() function returns a value other than 1, the
1870 plugin may store a message describing the failure or error in
1871 errstr. The sudo front-end will then pass this value to any
1872 registered audit plugins. The string stored in errstr must
1873 remain valid until the plugin's close() function is called.
1874 close
1876 void (*close)(int status_type, int status);
1877 The close() function is called when sudo is finished, shortly be‐
1879 fore it exits.
1880 The function arguments are as follows:
1882 status_type
1884 The type of status being passed. One of
1885 SUDO_PLUGIN_NO_STATUS, SUDO_PLUGIN_WAIT_STATUS,
1886 SUDO_PLUGIN_EXEC_ERROR or SUDO_PLUGIN_SUDO_ERROR.
1887 status
1889 Depending on the value of status_type, this value is either
1890 ignored, the command's exit status as returned by the wait(2)
1891 system call, the value of errno set by the execve(2) system
1892 call, or the value of errno resulting from an error in the
1893 sudo front-end.
1894 accept
1896 int (*accept)(const char *plugin_name, unsigned int plugin_type,
1897 char * const command_info[], char * const run_argv[],
1898 char * const run_envp[], const char **errstr);
1899 The accept() function is called when a command or action is ac‐
1901 cepted by a policy or approval plugin. The function arguments are
1902 as follows:
1903 plugin_name
1905 The name of the plugin that accepted the command or “sudo”
1906 for the sudo front-end.
1907 plugin_type
1909 The type of plugin that accepted the command, currently ei‐
1910 ther SUDO_POLICY_PLUGIN, SUDO_POLICY_APPROVAL, or
1911 SUDO_FRONT_END. The accept() function is called multiple
1912 times--once for each policy or approval plugin that succeeds
1913 and once for the sudo front-end. When called on behalf of
1914 the sudo front-end, command_info may include information from
1915 an I/O logging plugin as well.
1916 Typically, an audit plugin is interested in either the accept
1918 status from the sudo front-end or from the various policy and
1919 approval plugins, but not both. It is possible for the pol‐
1920 icy plugin to accept a command that is later rejected by an
1921 approval plugin, in which case the audit plugin's accept()
1922 and reject() functions will both be called.
1923 command_info
1925 An optional vector of information describing the command be‐
1926 ing run in the form of “name=value” strings. The vector is
1927 terminated by a NULL pointer.
1928 When parsing command_info, the plugin should split on the
1930 first equal sign (‘=’) since the name field will never in‐
1931 clude one itself but the value might.
1932 See the Policy plugin API section for a list of all possible
1934 strings.
1935 run_argv
1937 A NULL-terminated argument vector describing a command that
1938 will be run in the same form as what would be passed to the
1939 execve(2) system call.
1940 run_envp
1942 The environment the command will be run with in the form of a
1943 NULL-terminated vector of “name=value” strings.
1944 When parsing run_envp, the plugin should split on the first
1946 equal sign (‘=’) since the name field will never include one
1947 itself but the value might.
1948 errstr
1950 If the accept() function returns a value other than 1, the
1951 plugin may store a message describing the failure or error in
1952 errstr. The sudo front-end will then pass this value to any
1953 registered audit plugins. The string stored in errstr must
1954 remain valid until the plugin's close() function is called.
1955 reject
1957 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1958 const char *audit_msg, char * const command_info[],
1959 const char **errstr);
1960 The reject() function is called when a command or action is re‐
1962 jected by a plugin. The function arguments are as follows:
1963 plugin_name
1965 The name of the plugin that rejected the command.
1966 plugin_type
1968 The type of plugin that rejected the command, currently ei‐
1969 ther SUDO_POLICY_PLUGIN, SUDO_APPROVAL_PLUGIN, or
1970 SUDO_IO_PLUGIN.
1971 Unlike the accept() function, the reject() function is not
1973 called on behalf of the sudo front-end.
1974 audit_msg
1976 An optional string describing the reason the command was re‐
1977 jected by the plugin. If the plugin did not provide a rea‐
1978 son, audit_msg will be the NULL pointer.
1979 command_info
1981 An optional vector of information describing the command be‐
1982 ing run in the form of “name=value” strings. The vector is
1983 terminated by a NULL pointer.
1984 When parsing command_info, the plugin should split on the
1986 first equal sign (‘=’) since the name field will never in‐
1987 clude one itself but the value might.
1988 See the Policy plugin API section for a list of all possible
1990 strings.
1991 errstr
1993 If the reject() function returns a value other than 1, the
1994 plugin may store a message describing the failure or error in
1995 errstr. The sudo front-end will then pass this value to any
1996 registered audit plugins. The string stored in errstr must
1997 remain valid until the plugin's close() function is called.
1998 error
2000 int (*error)(const char *plugin_name, unsigned int plugin_type,
2001 const char *audit_msg, char * const command_info[],
2002 const char **errstr);
2003 The error() function is called when a plugin or the sudo front-end
2005 returns an error. The function arguments are as follows:
2006 plugin_name
2008 The name of the plugin that generated the error or “sudo” for
2009 the sudo front-end.
2010 plugin_type
2012 The type of plugin that generated the error, or
2013 SUDO_FRONT_END for the sudo front-end.
2014 audit_msg
2016 An optional string describing the plugin error. If the
2017 plugin did not provide a description, audit_msg will be the
2018 NULL pointer.
2019 command_info
2021 An optional vector of information describing the command be‐
2022 ing run in the form of “name=value” strings. The vector is
2023 terminated by a NULL pointer.
2024 When parsing command_info, the plugin should split on the
2026 first equal sign (‘=’) since the name field will never in‐
2027 clude one itself but the value might.
2028 See the Policy plugin API section for a list of all possible
2030 strings.
2031 errstr
2033 If the error() function returns a value other than 1, the
2034 plugin may store a message describing the failure or error in
2035 errstr. The sudo front-end will then pass this value to any
2036 registered audit plugins. The string stored in errstr must
2037 remain valid until the plugin's close() function is called.
2038 show_version
2040 int (*show_version)(int verbose);
2041 The show_version() function is called by sudo when the user speci‐
2043 fies the -V option. The plugin may display its version information
2044 to the user via the conversation() or plugin_printf() function us‐
2045 ing SUDO_CONV_INFO_MSG. If the user requests detailed version in‐
2046 formation, the verbose flag will be set.
2047 Returns 1 on success, 0 on failure, -1 if a general error occurred,
2049 or -2 if there was a usage error, although the return value is cur‐
2050 rently ignored.
2051 register_hooks
2053 See the Policy plugin API section for a description of
2054 register_hooks().
2055 deregister_hooks
2057 See the Policy plugin API section for a description of
2058 deregister_hooks().
2059 event_alloc
2061 struct sudo_plugin_event * (*event_alloc)(void);
2062 The event_alloc() function is used to allocate a struct
2064 sudo_plugin_event which provides access to the main sudo event
2065 loop. Unlike the other fields, the event_alloc pointer is filled
2066 in by the sudo front-end, not by the plugin.
2067 See the Event API section below for more information about events.
2069 The event_alloc() function is only available starting with API ver‐
2071 sion 1.17. If the sudo front-end doesn't support API version 1.17
2072 or higher, event_alloc() will not be set.
2073 Approval plugin API
2075 struct approval_plugin {
2076 #define SUDO_APPROVAL_PLUGIN 4
2077 unsigned int type; /* always SUDO_APPROVAL_PLUGIN */
2078 unsigned int version; /* always SUDO_API_VERSION */
2079 int (*open)(unsigned int version, sudo_conv_t conversation,
2080 sudo_printf_t sudo_plugin_printf, char * const settings[],
2081 char * const user_info[], int submit_optind,
2082 char * const submit_argv[], char * const submit_envp[],
2083 char * const plugin_options[], const char **errstr);
2084 void (*close)(void);
2085 int (*check)(char * const command_info[], char * const run_argv[],
2086 char * const run_envp[], const char **errstr);
2087 int (*show_version)(int verbose);
2088 };
2089 An approval plugin can be used to apply extra constraints after a command
2091 has been accepted by the policy plugin. Unlike the other plugin types,
2092 it does not remain open until the command completes. The plugin is
2093 opened before a call to check() or show_version() and closed shortly
2094 thereafter (audit plugin functions must be called before the plugin is
2095 closed). Multiple approval plugins may be specified in sudo.conf(5).
2096 A struct approval_plugin has the following fields:
2098 type The type field should always be set to SUDO_APPROVAL_PLUGIN.
2100 version
2102 The version field should be set to SUDO_API_VERSION.
2103 This allows sudo to determine the API version the plugin was built
2105 against.
2106 open
2108 int (*open)(unsigned int version, sudo_conv_t conversation,
2109 sudo_printf_t sudo_plugin_printf, char * const settings[],
2110 char * const user_info[], int submit_optind,
2111 char * const submit_argv[], char * const submit_envp[],
2112 char * const plugin_options[], const char **errstr);
2113 The approval open() function is run immediately before a call to
2115 the plugin's check() or show_version() functions. It is only
2116 called if the version is being requested or if the policy plugin's
2117 check_policy() function has returned successfully. It returns 1 on
2118 success, 0 on failure, -1 if a general error occurred, or -2 if
2119 there was a usage error. In the latter case, sudo will print a us‐
2120 age message before it exits. If an error occurs, the plugin may
2121 optionally call the conversation() or plugin_printf() function with
2122 SUDO_CONF_ERROR_MSG to present additional error information to the
2123 user.
2124 The function arguments are as follows:
2126 version
2128 The version passed in by sudo allows the plugin to determine
2129 the major and minor version number of the plugin API sup‐
2130 ported by sudo.
2131 conversation
2133 A pointer to the conversation() function that can be used by
2134 the plugin to interact with the user (see Conversation API
2135 for details). Returns 0 on success and -1 on failure.
2136 plugin_printf
2138 A pointer to a printf()-style function that may be used to
2139 display informational or error messages (see Conversation API
2140 for details). Returns the number of characters printed on
2141 success and -1 on failure.
2142 settings
2144 A vector of user-supplied sudo settings in the form of
2145 “name=value” strings. The vector is terminated by a NULL
2146 pointer. These settings correspond to options the user spec‐
2147 ified when running sudo. As such, they will only be present
2148 when the corresponding option has been specified on the com‐
2149 mand line.
2150 When parsing settings, the plugin should split on the first
2152 equal sign (‘=’) since the name field will never include one
2153 itself but the value might.
2154 See the Policy plugin API section for a list of all possible
2156 settings.
2157 user_info
2159 A vector of information about the user running the command in
2160 the form of “name=value” strings. The vector is terminated
2161 by a NULL pointer.
2162 When parsing user_info, the plugin should split on the first
2164 equal sign (‘=’) since the name field will never include one
2165 itself but the value might.
2166 See the Policy plugin API section for a list of all possible
2168 strings.
2169 submit_optind
2171 The index into submit_argv that corresponds to the first en‐
2172 try that is not a command line option. If submit_argv only
2173 consists of options, which may be the case with the -l or -v
2174 options, submit_argv[submit_optind] will evaluate to the NULL
2175 pointer.
2176 submit_argv
2178 The argument vector sudo was invoked with, including all com‐
2179 mand line options. The submit_optind argument can be used to
2180 determine the end of the command line options.
2181 submit_envp
2183 The invoking user's environment in the form of a
2184 NULL-terminated vector of “name=value” strings.
2185 When parsing submit_envp, the plugin should split on the
2187 first equal sign (‘=’) since the name field will never in‐
2188 clude one itself but the value might.
2189 plugin_options
2191 Any (non-comment) strings immediately after the plugin path
2192 are treated as arguments to the plugin. These arguments are
2193 split on a white space boundary and are passed to the plugin
2194 in the form of a NULL-terminated array of strings. If no ar‐
2195 guments were specified, plugin_options will be the NULL
2196 pointer.
2197 errstr
2199 If the open() function returns a value other than 1, the
2200 plugin may store a message describing the failure or error in
2201 errstr. The sudo front-end will then pass this value to any
2202 registered audit plugins. The string stored in errstr must
2203 remain valid until the plugin's close() function is called.
2204 close
2206 void (*close)(void);
2207 The close() function is called after the approval plugin's check()
2209 or show_version() functions have been called. It takes no argu‐
2210 ments. The close() function is typically used to perform plugin-
2211 specific cleanup, such as the freeing of memory objects allocated
2212 by the plugin. If the plugin does not need to perform any cleanup,
2213 close() may be set to the NULL pointer.
2214 check
2216 int (*check)(char * const command_info[], char * const run_argv[],
2217 char * const run_envp[], const char **errstr);
2218 The approval check() function is run after the policy plugin
2220 check_policy() function and before any I/O logging plugins. If
2221 multiple approval plugins are loaded, they must all succeed for the
2222 command to be allowed. It returns 1 on success, 0 on failure, -1
2223 if a general error occurred, or -2 if there was a usage error. In
2224 the latter case, sudo will print a usage message before it exits.
2225 If an error occurs, the plugin may optionally call the
2226 conversation() or plugin_printf() function with SUDO_CONF_ERROR_MSG
2227 to present additional error information to the user.
2228 The function arguments are as follows:
2230 command_info
2232 A vector of information describing the command being run in
2233 the form of “name=value” strings. The vector is terminated
2234 by a NULL pointer.
2235 When parsing command_info, the plugin should split on the
2237 first equal sign (‘=’) since the name field will never in‐
2238 clude one itself but the value might.
2239 See the Policy plugin API section for a list of all possible
2241 strings.
2242 run_argv
2244 A NULL-terminated argument vector describing a command that
2245 will be run in the same form as what would be passed to the
2246 execve(2) system call.
2247 run_envp
2249 The environment the command will be run with in the form of a
2250 NULL-terminated vector of “name=value” strings.
2251 When parsing run_envp, the plugin should split on the first
2253 equal sign (‘=’) since the name field will never include one
2254 itself but the value might.
2255 errstr
2257 If the open() function returns a value other than 1, the
2258 plugin may store a message describing the failure or error in
2259 errstr. The sudo front-end will then pass this value to any
2260 registered audit plugins. The string stored in errstr must
2261 remain valid until the plugin's close() function is called.
2262 show_version
2264 int (*show_version)(int verbose);
2265 The show_version() function is called by sudo when the user speci‐
2267 fies the -V option. The plugin may display its version information
2268 to the user via the conversation() or plugin_printf() function us‐
2269 ing SUDO_CONV_INFO_MSG. If the user requests detailed version in‐
2270 formation, the verbose flag will be set.
2271 Returns 1 on success, 0 on failure, -1 if a general error occurred,
2273 or -2 if there was a usage error, although the return value is cur‐
2274 rently ignored.
2275 Signal handlers
2277 The sudo front-end installs default signal handlers to trap common sig‐
2278 nals while the plugin functions are run. The following signals are
2279 trapped by default before the command is executed:
2280 • SIGALRM
2282 • SIGHUP
2283 • SIGINT
2284 • SIGPIPE
2285 • SIGQUIT
2286 • SIGTERM
2287 • SIGTSTP
2288 • SIGUSR1
2289 • SIGUSR2
2290 If a fatal signal is received before the command is executed, sudo will
2292 call the plugin's close() function with an exit status of 128 plus the
2293 value of the signal that was received. This allows for consistent log‐
2294 ging of commands killed by a signal for plugins that log such information
2295 in their close() function. An exception to this is SIGPIPE, which is ig‐
2296 nored until the command is executed.
2297 A plugin may temporarily install its own signal handlers but must restore
2299 the original handler before the plugin function returns.
2300 Hook function API
2302 Beginning with plugin API version 1.2, it is possible to install hooks
2303 for certain functions called by the sudo front-end.
2304 Currently, the only supported hooks relate to the handling of environment
2306 variables. Hooks can be used to intercept attempts to get, set, or re‐
2307 move environment variables so that these changes can be reflected in the
2308 version of the environment that is used to execute a command. A future
2309 version of the API will support hooking internal sudo front-end functions
2310 as well.
2311 Hook structure
2313 Hooks in sudo are described by the following structure:
2315 typedef int (*sudo_hook_fn_t)();
2317 struct sudo_hook {
2319 unsigned int hook_version;
2320 unsigned int hook_type;
2321 sudo_hook_fn_t hook_fn;
2322 void *closure;
2323 };
2324 A struct sudo_hook has the following fields:
2326 hook_version
2328 The hook_version field should be set to SUDO_HOOK_VERSION.
2329 hook_type
2331 The hook_type field may be one of the following supported hook
2332 types:
2333 SUDO_HOOK_SETENV
2335 The C library setenv(3) function. Any registered hooks will
2336 run before the C library implementation. The hook_fn field
2337 should be a function that matches the following typedef:
2338 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
2340 const char *value, int overwrite, void *closure);
2341 If the registered hook does not match the typedef the results
2343 are unspecified.
2344 SUDO_HOOK_UNSETENV
2346 The C library unsetenv(3) function. Any registered hooks
2347 will run before the C library implementation. The hook_fn
2348 field should be a function that matches the following type‐
2349 def:
2350 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2352 void *closure);
2353 SUDO_HOOK_GETENV
2355 The C library getenv(3) function. Any registered hooks will
2356 run before the C library implementation. The hook_fn field
2357 should be a function that matches the following typedef:
2358 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2360 char **value, void *closure);
2361 If the registered hook does not match the typedef the results
2363 are unspecified.
2364 SUDO_HOOK_PUTENV
2366 The C library putenv(3) function. Any registered hooks will
2367 run before the C library implementation. The hook_fn field
2368 should be a function that matches the following typedef:
2369 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2371 void *closure);
2372 If the registered hook does not match the typedef the results
2374 are unspecified.
2375 hook_fn
2377 sudo_hook_fn_t hook_fn;
2378 The hook_fn field should be set to the plugin's hook implementa‐
2380 tion. The actual function arguments will vary depending on the
2381 hook_type (see hook_type above). In all cases, the closure field
2382 of struct sudo_hook is passed as the last function parameter. This
2383 can be used to pass arbitrary data to the plugin's hook implementa‐
2384 tion.
2385 The function return value may be one of the following:
2387 SUDO_HOOK_RET_ERROR
2389 The hook function encountered an error.
2390 SUDO_HOOK_RET_NEXT
2392 The hook completed without error, go on to the next hook (in‐
2393 cluding the system implementation if applicable). For exam‐
2394 ple, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if the
2395 specified variable was not found in the private copy of the
2396 environment.
2397 SUDO_HOOK_RET_STOP
2399 The hook completed without error, stop processing hooks for
2400 this invocation. This can be used to replace the system im‐
2401 plementation. For example, a setenv hook that operates on a
2402 private copy of the environment but leaves environ unchanged.
2403 Care must be taken when hooking C library functions, it is very easy to
2405 create an infinite loop. For example, a getenv(3) hook that calls the
2406 snprintf(3) function may create a loop if the snprintf(3) implementation
2407 calls getenv(3) to check the locale. To prevent this, you may wish to
2408 use a static variable in the hook function to guard against nested calls.
2409 For example:
2410 static int in_progress = 0; /* avoid recursion */
2412 if (in_progress)
2413 return SUDO_HOOK_RET_NEXT;
2414 in_progress = 1;
2415 ...
2416 in_progress = 0;
2417 return SUDO_HOOK_RET_STOP;
2418 Hook API Version Macros
2420 /* Hook API version major/minor */
2422 #define SUDO_HOOK_VERSION_MAJOR 1
2423 #define SUDO_HOOK_VERSION_MINOR 0
2424 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
2425 SUDO_HOOK_VERSION_MINOR)
2426 For getters and setters see the Policy plugin API.
2428 Event API
2430 When sudo runs a command, it uses an event loop to service signals and
2431 I/O. Events may be triggered based on time, a file or socket descriptor
2432 becoming ready, or due to receipt of a signal. Starting with API version
2433 1.15, it is possible for a plugin to participate in this event loop by
2434 calling the event_alloc() function.
2435 Event structure
2437 Events are described by the following structure:
2439 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure);
2441 struct sudo_plugin_event {
2443 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2444 sudo_plugin_ev_callback_t callback, void *closure);
2445 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2446 int (*del)(struct sudo_plugin_event *pev);
2447 int (*pending)(struct sudo_plugin_event *pev, int events,
2448 struct timespec *ts);
2449 int (*fd)(struct sudo_plugin_event *pev);
2450 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2451 void (*loopbreak)(struct sudo_plugin_event *pev);
2452 void (*free)(struct sudo_plugin_event *pev);
2453 };
2454 A struct sudo_plugin_event contains the following function pointers:
2456 set
2458 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2459 sudo_plugin_ev_callback_t callback, void *closure);
2460 The set() function takes the following arguments:
2462 struct sudo_plugin_event *pev
2464 A pointer to the struct sudo_plugin_event itself.
2465 fd The file or socket descriptor for I/O-based events or the
2467 signal number for signal events. For time-based events, fd
2468 must be -1.
2469 events
2471 The following values determine what will trigger the event
2472 callback:
2473 SUDO_PLUGIN_EV_TIMEOUT
2475 callback is run after the specified timeout expires
2476 SUDO_PLUGIN_EV_READ
2478 callback is run when the file descriptor is readable
2479 SUDO_PLUGIN_EV_WRITE
2481 callback is run when the file descriptor is writable
2482 SUDO_PLUGIN_EV_PERSIST
2484 event is persistent and remains enabled until explic‐
2485 itly deleted
2486 SUDO_PLUGIN_EV_SIGNAL
2488 callback is run when the specified signal is received
2489 The SUDO_PLUGIN_EV_PERSIST flag may be ORed with any of the
2491 event types. It is also possible to OR SUDO_PLUGIN_EV_READ
2492 and SUDO_PLUGIN_EV_WRITE together to run the callback when a
2493 descriptor is ready to be either read from or written to.
2494 All other event values are mutually exclusive.
2495 sudo_plugin_ev_callback_t callback
2497 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what,
2498 void *closure);
2499 The function to call when an event is triggered. The
2501 callback() function is run with the following arguments:
2502 fd The file or socket descriptor for I/O-based events or
2504 the signal number for signal events.
2505 what The event type that triggered that callback. For
2507 events that have multiple event types (for example
2508 SUDO_PLUGIN_EV_READ and SUDO_PLUGIN_EV_WRITE) or have
2509 an associated timeout, what can be used to determine
2510 why the callback was run.
2511 closure
2513 The generic pointer that was specified in the set()
2514 function.
2515 closure
2517 A generic pointer that will be passed to the callback func‐
2518 tion.
2519 The set() function returns 1 on success, and -1 if a error oc‐
2521 curred.
2522 add
2524 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2525 The add() function adds the event pev to sudo's event loop. The
2527 event must have previously been initialized via the set() function.
2528 If the timeout argument is not NULL, it should specify a (relative)
2529 timeout after which the event will be triggered if the main event
2530 criteria has not been met. This is often used to implement an I/O
2531 timeout where the event will fire if a descriptor is not ready
2532 within a certain time period. If the event is already present in
2533 the event loop, its timeout will be adjusted to match the new
2534 value, if any.
2535 The add() function returns 1 on success, and -1 if a error oc‐
2537 curred.
2538 del
2540 int (*del)(struct sudo_plugin_event *pev);
2541 The del() function deletes the event pev from sudo's event loop.
2543 Deleted events can be added back via the add() function.
2544 The del() function returns 1 on success, and -1 if a error oc‐
2546 curred.
2547 pending
2549 int (*pending)(struct sudo_plugin_event *pev, int events,
2550 struct timespec *ts);
2551 The pending() function can be used to determine whether one or more
2553 events is pending. The events argument specifies which events to
2554 check for. See the set() function for a list of valid event types.
2555 If SUDO_PLUGIN_EV_TIMEOUT is specified in events, the event has an
2556 associated timeout and the ts pointer is non-NULL, it will be
2557 filled in with the remaining time.
2558 fd
2560 int (*fd)(struct sudo_plugin_event *pev);
2561 The fd() function returns the descriptor or signal number associ‐
2563 ated with the event pev.
2564 setbase
2566 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2567 The setbase() function sets the underlying event base for pev to
2569 the specified value. This can be used to move an event created via
2570 event_alloc() to a new event loop allocated by sudo's event subsys‐
2571 tem. If base is NULL, pev's event base is reset to the default
2572 value, which corresponds to sudo's main event loop. Using this
2573 function requires linking the plugin with the sudo_util library.
2574 It is unlikely to be used outside of the sudoers plugin.
2575 loopbreak
2577 void (*loopbreak)(struct sudo_plugin_event *pev);
2578 The loopbreak() function causes sudo's event loop to exit immedi‐
2580 ately and the running command to be terminated.
2581 free
2583 void (*free)(struct sudo_plugin_event *pev);
2584 The free() function deletes the event pev from the event loop and
2586 frees the memory associated with it.
2587 Remote command execution
2589 The sudo front-end does not support running remote commands. However,
2590 starting with sudo 1.8.8, the -h option may be used to specify a remote
2591 host that is passed to the policy plugin. A plugin may also accept a
2592 runas_user in the form of “user@hostname” which will work with older ver‐
2593 sions of sudo. It is anticipated that remote commands will be supported
2594 by executing a “helper” program. The policy plugin should setup the exe‐
2595 cution environment such that the sudo front-end will run the helper
2596 which, in turn, will connect to the remote host and run the command.
2597 For example, the policy plugin could utilize ssh to perform remote com‐
2599 mand execution. The helper program would be responsible for running ssh
2600 with the proper options to use a private key or certificate that the re‐
2601 mote host will accept and run a program on the remote host that would
2602 setup the execution environment accordingly.
2603 Remote sudoedit functionality must be handled by the policy plugin, not
2605 sudo itself as the front-end has no knowledge that a remote command is
2606 being executed. This may be addressed in a future revision of the plugin
2607 API.
2608 Conversation API
2610 If the plugin needs to interact with the user, it may do so via the
2611 conversation() function. A plugin should not attempt to read directly
2612 from the standard input or the user's terminal (neither of which are
2613 guaranteed to exist). The caller must include a trailing newline in msg
2614 if one is to be printed.
2615 A printf()-style function is also available that can be used to display
2617 informational or error messages to the user, which is usually more conve‐
2618 nient for simple messages where no use input is required.
2619 Conversation function structures
2621 The conversation function takes as arguments pointers to the following
2623 structures:
2624 struct sudo_conv_message {
2626 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2627 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2628 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2629 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2630 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2631 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2632 #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */
2633 int msg_type;
2634 int timeout;
2635 const char *msg;
2636 };
2637 #define SUDO_CONV_REPL_MAX 1023
2639 struct sudo_conv_reply {
2641 char *reply;
2642 };
2643 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
2645 struct sudo_conv_callback {
2646 unsigned int version;
2647 void *closure;
2648 sudo_conv_callback_fn_t on_suspend;
2649 sudo_conv_callback_fn_t on_resume;
2650 };
2651 Pointers to the conversation() and printf()-style functions are passed in
2653 to the plugin's open() function when the plugin is initialized. The fol‐
2654 lowing type definitions can be used in the declaration of the open()
2655 function:
2656 typedef int (*sudo_conv_t)(int num_msgs,
2658 const struct sudo_conv_message msgs[],
2659 struct sudo_conv_reply replies[], struct sudo_conv_callback *callback);
2660 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2662 To use the conversation() function, the plugin must pass an array of
2664 struct sudo_conv_message and struct sudo_conv_reply. There must be a
2665 struct sudo_conv_message and struct sudo_conv_reply for each message in
2666 the conversation, that is, both arrays must have the same number of ele‐
2667 ments. Each struct sudo_conv_reply must have its reply member initial‐
2668 ized to NULL. The struct sudo_conv_callback pointer, if not NULL, should
2669 contain function pointers to be called when the sudo process is suspended
2670 and/or resumed during conversation input. The on_suspend and on_resume
2671 functions are called with the signal that caused sudo to be suspended and
2672 the closure pointer from the struct sudo_conv_callback. These functions
2673 should return 0 on success and -1 on error. On error, the conversation
2674 will end and the conversation function will return a value of -1. The
2675 intended use is to allow the plugin to release resources, such as locks,
2676 that should not be held indefinitely while suspended and then reacquire
2677 them when the process is resumed. The functions are not actually invoked
2678 from within a signal handler.
2679 The msg_type must be set to one of the following values:
2681 SUDO_CONV_PROMPT_ECHO_OFF
2683 Prompt the user for input with echo disabled; this is generally
2684 used for passwords. The reply will be stored in the replies array,
2685 and it will never be NULL.
2686 SUDO_CONV_PROMPT_ECHO_ON
2688 Prompt the user for input with echo enabled. The reply will be
2689 stored in the replies array, and it will never be NULL.
2690 SUDO_CONV_ERROR_MSG
2692 Display an error message. The message is written to the standard
2693 error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
2694 is written to the user's terminal if possible.
2695 SUDO_CONV_INFO_MSG
2697 Display a message. The message is written to the standard output
2698 unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
2699 written to the user's terminal if possible.
2700 SUDO_CONV_PROMPT_MASK
2702 Prompt the user for input but echo an asterisk character for each
2703 character read. The reply will be stored in the replies array, and
2704 it will never be NULL. This can be used to provide visual feedback
2705 to the user while reading sensitive information that should not be
2706 displayed.
2707 In addition to the above values, the following flag bits may also be set:
2709 SUDO_CONV_PROMPT_ECHO_OK
2711 Allow input to be read when echo cannot be disabled when the mes‐
2712 sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
2713 By default, sudo will refuse to read input if the echo cannot be
2714 disabled for those message types.
2715 SUDO_CONV_PREFER_TTY
2717 When displaying a message via SUDO_CONV_ERROR_MSG or
2718 SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
2719 nal. If the terminal is unavailable, the standard error or stan‐
2720 dard output will be used, depending upon whether
2721 SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used. The user's
2722 terminal is always used when possible for input, this flag is only
2723 used for output.
2724 The timeout in seconds until the prompt will wait for no more input. A
2726 zero value implies an infinite timeout.
2727 The plugin is responsible for freeing the reply buffer located in each
2729 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
2730 the maximum length of the reply buffer (not including the trailing NUL
2731 character). In practical terms, this is the longest password sudo will
2732 support.
2733 The printf()-style function uses the same underlying mechanism as the
2735 conversation() function but only supports SUDO_CONV_INFO_MSG and
2736 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
2737 nient than using the conversation() function if no user reply is needed
2738 and supports standard printf() escape sequences.
2739 See the sample plugin for an example of the conversation() function us‐
2741 age.
2742 Plugin invocation order
2744 As of sudo 1.9.0, the plugin open() and close() functions are called in
2745 the following order:
2746 1. audit open
2748 2. policy open
2750 3. approval open
2752 4. approval close
2754 5. I/O log open
2756 6. command runs
2758 7. command exits
2760 8. I/O log close
2762 9. policy close
2764 10. audit close
2766 11. sudo exits
2768 Prior to sudo 1.9.0, the I/O log close() function was called after the
2770 policy close() function.
2771 Sudoers group plugin API
2773 The sudoers plugin supports its own plugin interface to allow non-Unix
2774 group lookups. This can be used to query a group source other than the
2775 standard Unix group database. Two sample group plugins are bundled with
2776 sudo, group_file, and system_group, are detailed in sudoers(5). Third
2777 party group plugins include a QAS AD plugin available from Quest Soft‐
2778 ware.
2779 A group plugin must declare and populate a struct sudoers_group_plugin in
2781 the global scope. This structure contains pointers to the functions that
2782 implement plugin initialization, cleanup, and group lookup.
2783 struct sudoers_group_plugin {
2785 unsigned int version;
2786 int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2787 char *const argv[]);
2788 void (*cleanup)(void);
2789 int (*query)(const char *user, const char *group,
2790 const struct passwd *pwd);
2791 };
2792 A struct sudoers_group_plugin has the following fields:
2794 version
2796 The version field should be set to GROUP_API_VERSION.
2797 This allows sudoers to determine the API version the group plugin
2799 was built against.
2800 init
2802 int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2803 char *const argv[]);
2804 The init() function is called after sudoers has been parsed but be‐
2806 fore any policy checks. It returns 1 on success, 0 on failure (or
2807 if the plugin is not configured), and -1 if a error occurred. If
2808 an error occurs, the plugin may call the plugin_printf() function
2809 with SUDO_CONF_ERROR_MSG to present additional error information to
2810 the user.
2811 The function arguments are as follows:
2813 version
2815 The version passed in by sudoers allows the plugin to deter‐
2816 mine the major and minor version number of the group plugin
2817 API supported by sudoers.
2818 plugin_printf
2820 A pointer to a printf()-style function that may be used to
2821 display informational or error message to the user. Returns
2822 the number of characters printed on success and -1 on fail‐
2823 ure.
2824 argv A NULL-terminated array of arguments generated from the
2826 group_plugin option in sudoers. If no arguments were given,
2827 argv will be NULL.
2828 cleanup
2830 void (*cleanup)();
2831 The cleanup() function is called when sudoers has finished its
2833 group checks. The plugin should free any memory it has allocated
2834 and close open file handles.
2835 query
2837 int (*query)(const char *user, const char *group,
2838 const struct passwd *pwd);
2839 The query() function is used to ask the group plugin whether user
2841 is a member of group.
2842 The function arguments are as follows:
2844 user The name of the user being looked up in the external group
2846 database.
2847 group
2849 The name of the group being queried.
2850 pwd The password database entry for user, if any. If user is not
2852 present in the password database, pwd will be NULL.
2853 Group API Version Macros
2855 /* Sudoers group plugin version major/minor */
2857 #define GROUP_API_VERSION_MAJOR 1
2858 #define GROUP_API_VERSION_MINOR 0
2859 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
2860 GROUP_API_VERSION_MINOR)
2861 For getters and setters see the Policy plugin API.
2862
2864 The following revisions have been made to the Sudo Plugin API.
2865 Version 1.0
2867 Initial API version.
2868 Version 1.1 (sudo 1.8.0)
2870 The I/O logging plugin's open() function was modified to take the
2871 command_info list as an argument.
2872 Version 1.2 (sudo 1.8.5)
2874 The Policy and I/O logging plugins' open() functions are now passed
2875 a list of plugin parameters if any are specified in sudo.conf(5).
2876 A simple hooks API has been introduced to allow plugins to hook in
2878 to the system's environment handling functions.
2879 The init_session() Policy plugin function is now passed a pointer
2881 to the user environment which can be updated as needed. This can
2882 be used to merge in environment variables stored in the PAM handle
2883 before a command is run.
2884 Version 1.3 (sudo 1.8.7)
2886 Support for the exec_background entry has been added to the
2887 command_info list.
2888 The max_groups and plugin_dir entries were added to the settings
2890 list.
2891 The version() and close() functions are now optional. Previously,
2893 a missing version() or close() function would result in a crash.
2894 If no policy plugin close() function is defined, a default close()
2895 function will be provided by the sudo front-end that displays a
2896 warning if the command could not be executed.
2897 The sudo front-end now installs default signal handlers to trap
2899 common signals while the plugin functions are run.
2900 Version 1.4 (sudo 1.8.8)
2902 The remote_host entry was added to the settings list.
2903 Version 1.5 (sudo 1.8.9)
2905 The preserve_fds entry was added to the command_info list.
2906 Version 1.6 (sudo 1.8.11)
2908 The behavior when an I/O logging plugin returns an error (-1) has
2909 changed. Previously, the sudo front-end took no action when the
2910 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
2911 log_stderr() function returned an error.
2912 The behavior when an I/O logging plugin returns 0 has changed.
2914 Previously, output from the command would be displayed to the ter‐
2915 minal even if an output logging function returned 0.
2916 Version 1.7 (sudo 1.8.12)
2918 The plugin_path entry was added to the settings list.
2919 The debug_flags entry now starts with a debug file path name and
2921 may occur multiple times if there are multiple plugin-specific De‐
2922 bug lines in the sudo.conf(5) file.
2923 Version 1.8 (sudo 1.8.15)
2925 The sudoedit_checkdir and sudoedit_follow entries were added to the
2926 command_info list. The default value of sudoedit_checkdir was
2927 changed to true in sudo 1.8.16.
2928 The sudo conversation() function now takes a pointer to a struct
2930 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
2931 tion has been updated to match. The plugin must specify that it
2932 supports plugin API version 1.8 or higher to receive a conversation
2933 function pointer that supports this argument.
2934 Version 1.9 (sudo 1.8.16)
2936 The execfd entry was added to the command_info list.
2937 Version 1.10 (sudo 1.8.19)
2939 The umask entry was added to the user_info list. The iolog_group,
2940 iolog_mode, and iolog_user entries were added to the command_info
2941 list.
2942 Version 1.11 (sudo 1.8.20)
2944 The timeout entry was added to the settings list.
2945 Version 1.12 (sudo 1.8.21)
2947 The change_winsize() function was added to struct io_plugin.
2948 Version 1.13 (sudo 1.8.26)
2950 The log_suspend() function was added to struct io_plugin.
2951 Version 1.14 (sudo 1.8.29)
2953 The umask_override entry was added to the command_info list.
2954 Version 1.15 (sudo 1.9.0)
2956 The cwd_optional entry was added to the command_info list.
2957 The event_alloc() function was added to struct policy_plugin and
2959 struct io_plugin.
2960 The errstr argument was added to the policy and I/O plugin func‐
2962 tions which the plugin function can use to return an error string.
2963 This string may be used by the audit plugin to report failure or
2964 error conditions set by the other plugins.
2965 The close() function is now is called regardless of whether or not
2967 a command was actually executed. This makes it possible for plug‐
2968 ins to perform cleanup even when a command was not run.
2969 SUDO_CONV_REPL_MAX has increased from 255 to 1023 bytes.
2971 Support for audit and approval plugins was added.
2973 Version 1.16 (sudo 1.9.3)
2975 Initial resource limit values were added to the user_info list.
2976 The cmnd_chroot and cmnd_cwd entries were added to the settings
2978 list.
2979 Version 1.17 (sudo 1.9.4)
2981 The event_alloc() function was added to struct audit_plugin and
2982 struct approval_plugin.
2983 Version 1.18 (sudo 1.9.9)
2985 The policy may now set resource limit values in the command_info
2986 list. The intercept and log_subcmds entries were added to the
2987 command_info list.
2988 Version 1.19 (sudo 1.9.11)
2990 The intercept_ptrace and intercept_setid entries were added to the
2991 settings list. The apparmor_profile and use_ptrace entries were
2992 added to the command_info list.
2993 Version 1.20 (sudo 1.9.12)
2995 The update_ticket entry was added to the settings list. The
2996 intercept_verify entry was added to the command_info list.
2997
2999 sudo.conf(5), sudoers(5), sudo(8)
3000
3002 Many people have worked on sudo over the years; this version consists of
3003 code written primarily by:
3004 Todd C. Miller
3006 See the CONTRIBUTORS.md file in the sudo distribution
3008 (https://www.sudo.ws/about/contributors/) for an exhaustive list of peo‐
3009 ple who have contributed to sudo.
3010
3012 If you believe you have found a bug in sudo, you can submit a bug report
3013 at https://bugzilla.sudo.ws/
3014
3016 Limited free support is available via the sudo-users mailing list, see
3017 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
3018 the archives.
3019
3021 sudo is provided “AS IS” and any express or implied warranties, includ‐
3022 ing, but not limited to, the implied warranties of merchantability and
3023 fitness for a particular purpose are disclaimed. See the LICENSE.md file
3024 distributed with sudo or https://www.sudo.ws/about/license/ for complete
3025 details.
3026Sudo 1.9.12p2 October 7, 2022 Sudo 1.9.12p2