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 must set sudoedit=true in the command_info
555 list. The plugin is responsible for choosing the editor to be
556 used, potentially from a variable in the user's environment, such
557 as EDITOR, and should be stored in argv_out (environment variables
558 may include command line options). The files to be edited should
559 be copied from argv to argv_out, separated from the editor and its
560 arguments by a ‘--’ element. The ‘--’ will be removed by sudo be‐
561 fore the editor is executed. The plugin may also set
562 sudoedit_nfiles to the number of files to be edited in the
563 command_info list; this will only be used by the sudo front-end
564 starting with API version 1.21.
565 The check_policy() function returns 1 if the command is allowed, 0
567 if not allowed, -1 for a general error, or -2 for a usage error or
568 if sudoedit was specified but is unsupported by the plugin. In the
569 latter case, sudo will print a usage message before it exits. If
570 an error occurs, the plugin may optionally call the conversation()
571 or sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to
572 present additional error information to the user.
573 The function arguments are as follows:
575 argc The number of elements in argv, not counting the final NULL
577 pointer.
578 argv The argument vector describing the command the user wishes to
580 run, in the same form as what would be passed to the
581 execve(2) system call. The vector is terminated by a NULL
582 pointer.
583 env_add
585 Additional environment variables specified by the user on the
586 command line in the form of a NULL-terminated vector of
587 “name=value” strings. The plugin may reject the command if
588 one or more variables are not allowed to be set, or it may
589 silently ignore such variables.
590 When parsing env_add, the plugin should split on the first
592 equal sign (‘=’) since the name field will never include one
593 itself but the value might.
594 command_info
596 Information about the command being run in the form of
597 “name=value” strings. These values are used by sudo to set
598 the execution environment when running a command. The plugin
599 is responsible for creating and populating the vector, which
600 must be terminated with a NULL pointer. The following values
601 are recognized by sudo:
602 apparmor_profile=string
604 AppArmor profile to transition to when executing the
605 command. Only available starting with API version
606 1.19.
607 chroot=string
609 The root directory to use when running the command.
610 closefrom=number
612 If specified, sudo will close all files descriptors
613 with a value of number or higher.
614 command=string
616 Fully qualified path to the command to be executed.
617 cwd=string
619 The current working directory to change to when execut‐
620 ing the command. If sudo is unable to change to the
621 new working directory, the command will not be run un‐
622 less cwd_optional is also set (see below).
623 cwd_optional=bool
625 If set, sudo will treat an inability to change to the
626 new working directory as a non-fatal error. This set‐
627 ting has no effect unless cwd is also set.
628 exec_background=bool
630 By default, sudo runs a command as the foreground
631 process as long as sudo itself is running in the fore‐
632 ground. When exec_background is enabled and the com‐
633 mand is being run in a pseudo-terminal (due to I/O log‐
634 ging or the use_pty setting), the command will be run
635 as a background process. Attempts to read from the
636 controlling terminal (or to change terminal settings)
637 will result in the command being suspended with the
638 SIGTTIN signal (or SIGTTOU in the case of terminal set‐
639 tings). If this happens when sudo is a foreground
640 process, the command will be granted the controlling
641 terminal and resumed in the foreground with no user in‐
642 tervention required. The advantage of initially run‐
643 ning the command in the background is that sudo need
644 not read from the terminal unless the command explic‐
645 itly requests it. Otherwise, any terminal input must
646 be passed to the command, whether it has required it or
647 not (the kernel buffers terminals so it is not possible
648 to tell whether the command really wants the input).
649 This is different from historic sudo behavior or when
650 the command is not being run in a pseudo-terminal.
651 For this to work seamlessly, the operating system must
653 support the automatic restarting of system calls. Un‐
654 fortunately, not all operating systems do this by de‐
655 fault, and even those that do may have bugs. For exam‐
656 ple, macOS fails to restart the tcgetattr() and
657 tcsetattr() system calls (this is a bug in macOS).
658 Furthermore, because this behavior depends on the com‐
659 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
660 grams that catch these signals and suspend themselves
661 with a different signal (usually SIGTOP) will not be
662 automatically foregrounded. Some versions of the linux
663 su(1) command behave this way. Because of this, a
664 plugin should not set exec_background unless it is ex‐
665 plicitly enabled by the administrator and there should
666 be a way to enabled or disable it on a per-command ba‐
667 sis.
668 This setting has no effect unless I/O logging is en‐
670 abled or use_pty is enabled.
671 execfd=number
673 If specified, sudo will use the fexecve(2) system call
674 to execute the command instead of execve(2). The spec‐
675 ified number must refer to an open file descriptor.
676 intercept=bool
678 If set, sudo will intercept attempts to execute a sub‐
679 sequent command and perform a policy check via the pol‐
680 icy plugin's check_policy() function to determine
681 whether or not the command is permitted. This can be
682 used to prevent shell escapes on supported platforms
683 but it has a number of limitations. See Preventing
684 shell escapes in sudoers(5) for details. Only avail‐
685 able starting with API version 1.18.
686 intercept_verify=bool
688 If set, sudo will attempt to verify that a command run
689 in intercept mode has the expected path name, command
690 line arguments and environment. This setting has no
691 effect unless use_ptrace is also enabled. Only avail‐
692 able starting with API version 1.20.
693 iolog_compress=bool
695 Set to true if the I/O logging plugins, if any, should
696 compress the log data. This is a hint to the I/O log‐
697 ging plugin which may choose to ignore it.
698 iolog_group=string
700 The group that will own newly created I/O log files and
701 directories. This is a hint to the I/O logging plugin
702 which may choose to ignore it.
703 iolog_mode=octal
705 The file permission mode to use when creating I/O log
706 files and directories. This is a hint to the I/O log‐
707 ging plugin which may choose to ignore it.
708 iolog_user=string
710 The user that will own newly created I/O log files and
711 directories. This is a hint to the I/O logging plugin
712 which may choose to ignore it.
713 iolog_path=string
715 Fully qualified path to the file or directory in which
716 I/O log is to be stored. This is a hint to the I/O
717 logging plugin which may choose to ignore it. If no
718 I/O logging plugin is loaded, this setting has no ef‐
719 fect.
720 iolog_stdin=bool
722 Set to true if the I/O logging plugins, if any, should
723 log the standard input if it is not connected to a ter‐
724 minal device. This is a hint to the I/O logging plugin
725 which may choose to ignore it.
726 iolog_stdout=bool
728 Set to true if the I/O logging plugins, if any, should
729 log the standard output if it is not connected to a
730 terminal device. This is a hint to the I/O logging
731 plugin which may choose to ignore it.
732 iolog_stderr=bool
734 Set to true if the I/O logging plugins, if any, should
735 log the standard error if it is not connected to a ter‐
736 minal device. This is a hint to the I/O logging plugin
737 which may choose to ignore it.
738 iolog_ttyin=bool
740 Set to true if the I/O logging plugins, if any, should
741 log all terminal input. This only includes input typed
742 by the user and not from a pipe or redirected from a
743 file. This is a hint to the I/O logging plugin which
744 may choose to ignore it.
745 iolog_ttyout=bool
747 Set to true if the I/O logging plugins, if any, should
748 log all terminal output. This only includes output to
749 the screen, not output to a pipe or file. This is a
750 hint to the I/O logging plugin which may choose to ig‐
751 nore it.
752 login_class=string
754 BSD login class to use when setting resource limits and
755 nice value (optional). This option is only set on sys‐
756 tems that support login classes.
757 nice=int
759 Nice value (priority) to use when executing the com‐
760 mand. The nice value, if specified, overrides the pri‐
761 ority associated with the login_class on BSD systems.
762 log_subcmds=bool
764 If set, sudo will call the audit plugin's accept()
765 function to log when the command runs a subsequent com‐
766 mand, if supported by the system. If intercept is also
767 specified, log_subcmds will be ignored. See Preventing
768 shell escapes in sudoers(5) for more information. Only
769 available starting with API version 1.18.
770 noexec=bool
772 If set, prevent the command from executing other pro‐
773 grams.
774 preserve_fds=list
776 A comma-separated list of file descriptors that should
777 be preserved, regardless of the value of the closefrom
778 setting. Only available starting with API version 1.5.
779 preserve_groups=bool
781 If set, sudo will preserve the user's group vector in‐
782 stead of initializing the group vector based on
783 runas_user.
784 rlimit_as=soft,hard
786 The maximum size to which the process's address space
787 may grow (in bytes), if supported by the operating sys‐
788 tem. The soft and hard limits are separated by a
789 comma. If only a single value is specified, both the
790 hard and soft limits are set. A value of “infinity”
791 indicates that there is no limit. A value of “user”
792 will cause the invoking user's resource limit to be
793 preserved. A value of “default” will cause the target
794 user's default resource limit to be used on systems
795 that allow per-user resource limits to be configured.
796 Only available starting with API version 1.18.
797 rlimit_core=soft,hard
799 The largest size core dump file that may be created (in
800 bytes). The soft and hard limits are separated by a
801 comma. If only a single value is specified, both the
802 hard and soft limits are set. A value of “infinity”
803 indicates that there is no limit. A value of “user”
804 will cause the invoking user's resource limit to be
805 preserved. A value of “default” will cause the target
806 user's default resource limit to be used on systems
807 that allow per-user resource limits to be configured.
808 Only available starting with API version 1.18.
809 rlimit_cpu=soft,hard
811 The maximum amount of CPU time that the process may use
812 (in seconds). The soft and hard limits are separated
813 by a comma. If only a single value is specified, both
814 the hard and soft limits are set. A value of
815 “infinity” indicates that there is no limit. A value
816 of “user” will cause the invoking user's resource limit
817 to be preserved. A value of “default” will cause the
818 target user's default resource limit to be used on sys‐
819 tems that allow per-user resource limits to be config‐
820 ured. Only available starting with API version 1.18.
821 rlimit_data=soft,hard
823 The maximum size of the data segment for the process
824 (in bytes). The soft and hard limits are separated by
825 a comma. If only a single value is specified, both the
826 hard and soft limits are set. A value of “infinity”
827 indicates that there is no limit. A value of “user”
828 will cause the invoking user's resource limit to be
829 preserved. A value of “default” will cause the target
830 user's default resource limit to be used on systems
831 that allow per-user resource limits to be configured.
832 Only available starting with API version 1.18.
833 rlimit_fsize=soft,hard
835 The largest size file that the process may create (in
836 bytes). The soft and hard limits are separated by a
837 comma. If only a single value is specified, both the
838 hard and soft limits are set. A value of “infinity”
839 indicates that there is no limit. A value of “user”
840 will cause the invoking user's resource limit to be
841 preserved. A value of “default” will cause the target
842 user's default resource limit to be used on systems
843 that allow per-user resource limits to be configured.
844 Only available starting with API version 1.18.
845 rlimit_locks=soft,hard
847 The maximum number of locks that the process may estab‐
848 lish, if supported by the operating system. The soft
849 and hard limits are separated by a comma. If only a
850 single value is specified, both the hard and soft lim‐
851 its are set. A value of “infinity” indicates that
852 there is no limit. A value of “user” will cause the
853 invoking user's resource limit to be preserved. A
854 value of “default” will cause the target user's default
855 resource limit to be used on systems that allow per-
856 user resource limits to be configured. Only available
857 starting with API version 1.18.
858 rlimit_memlock=soft,hard
860 The maximum size that the process may lock in memory
861 (in bytes), if supported by the operating system. The
862 soft and hard limits are separated by a comma. If only
863 a single value is specified, both the hard and soft
864 limits are set. A value of “infinity” indicates that
865 there is no limit. A value of “user” will cause the
866 invoking user's resource limit to be preserved. A
867 value of “default” will cause the target user's default
868 resource limit to be used on systems that allow per-
869 user resource limits to be configured. Only available
870 starting with API version 1.18.
871 rlimit_nofile=soft,hard
873 The maximum number of files that the process may have
874 open. The soft and hard limits are separated by a
875 comma. If only a single value is specified, both the
876 hard and soft limits are set. A value of “infinity”
877 indicates that there is no limit. A value of “user”
878 will cause the invoking user's resource limit to be
879 preserved. A value of “default” will cause the target
880 user's default resource limit to be used on systems
881 that allow per-user resource limits to be configured.
882 Only available starting with API version 1.18.
883 rlimit_nproc=soft,hard
885 The maximum number of processes that the user may run
886 simultaneously. The soft and hard limits are separated
887 by a comma. If only a single value is specified, both
888 the hard and soft limits are set. A value of
889 “infinity” indicates that there is no limit. A value
890 of “user” will cause the invoking user's resource limit
891 to be preserved. A value of “default” will cause the
892 target user's default resource limit to be used on sys‐
893 tems that allow per-user resource limits to be config‐
894 ured. Only available starting with API version 1.18.
895 rlimit_rss=soft,hard
897 The maximum size to which the process's resident set
898 size may grow (in bytes). The soft and hard limits are
899 separated by a comma. If only a single value is speci‐
900 fied, both the hard and soft limits are set. A value
901 of “infinity” indicates that there is no limit. A
902 value of “user” will cause the invoking user's resource
903 limit to be preserved. A value of “default” will cause
904 the target user's default resource limit to be used on
905 systems that allow per-user resource limits to be con‐
906 figured. Only available starting with API version
907 1.18.
908 rlimit_stack=soft,hard
910 The maximum size to which the process's stack may grow
911 (in bytes). The soft and hard limits are separated by
912 a comma. If only a single value is specified, both the
913 hard and soft limits are set. A value of “infinity”
914 indicates that there is no limit. A value of “user”
915 will cause the invoking user's resource limit to be
916 preserved. A value of “default” will cause the target
917 user's default resource limit to be used on systems
918 that allow per-user resource limits to be configured.
919 Only available starting with API version 1.18.
920 runas_egid=gid
922 Effective group-ID to run the command as. If not spec‐
923 ified, the value of runas_gid is used.
924 runas_euid=uid
926 Effective user-ID to run the command as. If not speci‐
927 fied, the value of runas_uid is used.
928 runas_gid=gid
930 Group-ID to run the command as.
931 runas_group=string
933 The name of the group the command will run as, if it is
934 different from the runas_user's default group. This
935 value is provided for auditing purposes only, the sudo
936 front-end uses runas_egid and runas_gid when executing
937 the command.
938 runas_groups=list
940 The supplementary group vector to use for the command
941 in the form of a comma-separated list of group-IDs. If
942 preserve_groups is set, this option is ignored.
943 runas_uid=uid
945 User-ID to run the command as.
946 runas_user=string
948 The name of the user the command will run as, which
949 should correspond to runas_euid (or runas_uid if
950 runas_euid is not set). This value is provided for au‐
951 diting purposes only, the sudo front-end uses
952 runas_euid and runas_uid when executing the command.
953 selinux_role=string
955 SELinux role to use when executing the command.
956 selinux_type=string
958 SELinux type to use when executing the command.
959 set_utmp=bool
961 Create a utmp (or utmpx) entry when a pseudo-terminal
962 is allocated. By default, the new entry will be a copy
963 of the user's existing utmp entry (if any), with the
964 tty, time, type, and pid fields updated.
965 sudoedit=bool
967 Set to true when in sudoedit mode. The plugin may en‐
968 able sudoedit mode even if sudo was not invoked as
969 sudoedit. This allows the plugin to perform command
970 substitution and transparently enable sudoedit when the
971 user attempts to run an editor.
972 sudoedit_checkdir=bool
974 Set to false to disable directory writability checks in
975 sudoedit. By default, sudoedit 1.8.16 and higher will
976 check all directory components of the path to be edited
977 for writability by the invoking user. Symbolic links
978 will not be followed in writable directories and
979 sudoedit will refuse to edit a file located in a
980 writable directory. These restrictions are not en‐
981 forced when sudoedit is run by root. The
982 sudoedit_checkdir option can be set to false to disable
983 this check. Only available starting with API version
984 1.8.
985 sudoedit_follow=bool
987 Set to true to allow sudoedit to edit files that are
988 symbolic links. By default, sudoedit 1.8.15 and higher
989 will refuse to open a symbolic link. The
990 sudoedit_follow option can be used to restore the older
991 behavior and allow sudoedit to open symbolic links.
992 Only available starting with API version 1.8.
993 sudoedit_nfiles=number
995 The number of files to be edited by the user. If
996 present, this is will be used by the sudo front-end to
997 determine which elements of the argv_out vector are
998 files to be edited. The ‘--’ element must immediately
999 precede the first file to be editied. If
1000 sudoedit_nfiles is not specified, the sudo front-end
1001 will use the position of the ‘--’ element to determine
1002 where the file list begins. Only available starting
1003 with API version 1.21.
1004 timeout=int
1006 Command timeout. If non-zero then when the timeout ex‐
1007 pires the command will be killed.
1008 umask=octal
1010 The file creation mask to use when executing the com‐
1011 mand. This value may be overridden by PAM or lo‐
1012 gin.conf on some systems unless the umask_override op‐
1013 tion is also set.
1014 umask_override=bool
1016 Force the value specified by the umask option to over‐
1017 ride any umask set by PAM or login.conf.
1018 use_ptrace=bool
1020 If set, sudo will use ptrace(2) to implement intercept
1021 mode if supported by the system. This setting has no
1022 effect unless intercept is also set. Only available
1023 starting with API version 1.19.
1024 use_pty=bool
1026 Allocate a pseudo-terminal to run the command in, re‐
1027 gardless of whether or not I/O logging is in use. By
1028 default, sudo will only run the command in a pseudo-
1029 terminal when an I/O log plugin is loaded.
1030 utmp_user=string
1032 User name to use when constructing a new utmp (or
1033 utmpx) entry when set_utmp is enabled. This option can
1034 be used to set the user field in the utmp entry to the
1035 user the command runs as rather than the invoking user.
1036 If not set, sudo will base the new entry on the invok‐
1037 ing user's existing entry.
1038 Unsupported values will be ignored.
1040 argv_out
1042 The NULL-terminated argument vector to pass to the execve(2)
1043 system call when executing the command. The plugin is re‐
1044 sponsible for allocating and populating the vector.
1045 user_env_out
1047 The NULL-terminated environment vector to use when executing
1048 the command. The plugin is responsible for allocating and
1049 populating the vector.
1050 errstr
1052 If the check_policy() function returns a value other than 1,
1053 the plugin may store a message describing the failure or er‐
1054 ror in errstr. The sudo front-end will then pass this value
1055 to any registered audit plugins. The string stored in errstr
1056 must remain valid until the plugin's close() function is
1057 called.
1058 The errstr parameter is only available starting with API ver‐
1060 sion 1.15. A plugin must check the API version specified by
1061 the sudo front-end before using errstr. Failure to do so may
1062 result in a crash.
1063 list
1065 int (*list)(int argc, char * const argv[], int verbose,
1066 const char *user, const char **errstr);
1067 List available privileges for the invoking user. Returns 1 on suc‐
1069 cess, 0 on failure, and -1 on error. On error, the plugin may op‐
1070 tionally call the conversation() or sudo_plugin_printf() function
1071 with SUDO_CONF_ERROR_MSG to present additional error information to
1072 the user.
1073 Privileges should be output via the conversation() or
1075 sudo_plugin_printf() function using SUDO_CONV_INFO_MSG.
1076 The function arguments are as follows:
1078 argc The number of elements in argv, not counting the final NULL
1080 pointer.
1081 argv If non-NULL, an argument vector describing a command the user
1083 wishes to check against the policy in the same form as what
1084 would be passed to the execve(2) system call. If the command
1085 is permitted by the policy, the fully-qualified path to the
1086 command should be displayed along with any command line argu‐
1087 ments.
1088 verbose
1090 Flag indicating whether to list in verbose mode or not.
1091 user The name of a different user to list privileges for if the
1093 policy allows it. If NULL, the plugin should list the privi‐
1094 leges of the invoking user.
1095 errstr
1097 If the list() function returns a value other than 1, the
1098 plugin may store a message describing the failure or error in
1099 errstr. The sudo front-end will then pass this value to any
1100 registered audit plugins. The string stored in errstr must
1101 remain valid until the plugin's close() function is called.
1102 The errstr parameter is only available starting with API ver‐
1104 sion 1.15. A plugin must check the API version specified by
1105 the sudo front-end before using errstr. Failure to do so may
1106 result in a crash.
1107 validate
1109 int (*validate)(const char **errstr);
1110 The validate() function is called when sudo is run with the -v op‐
1112 tion. For policy plugins such as sudoers that cache authentication
1113 credentials, this function will validate and cache the credentials.
1114 The validate() function should be NULL if the plugin does not sup‐
1116 port credential caching.
1117 Returns 1 on success, 0 on failure, and -1 on error. On error, the
1119 plugin may optionally call the conversation() or
1120 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1121 additional error information to the user.
1122 The function arguments are as follows:
1124 errstr
1126 If the validate() function returns a value other than 1, the
1127 plugin may store a message describing the failure or error in
1128 errstr. The sudo front-end will then pass this value to any
1129 registered audit plugins. The string stored in errstr must
1130 remain valid until the plugin's close() function is called.
1131 The errstr parameter is only available starting with API ver‐
1133 sion 1.15. A plugin must check the API version specified by
1134 the sudo front-end before using errstr. Failure to do so may
1135 result in a crash.
1136 invalidate
1138 void (*invalidate)(int rmcred);
1139 The invalidate() function is called when sudo is run with the -k or
1141 -K option. For policy plugins such as sudoers that cache authenti‐
1142 cation credentials, this function will invalidate the credentials.
1143 If the rmcred flag is non-zero, the plugin may remove the creden‐
1144 tials instead of simply invalidating them.
1145 The invalidate() function should be NULL if the plugin does not
1147 support credential caching.
1148 init_session
1150 int (*init_session)(struct passwd *pwd, char **user_env[],
1151 const char **errstr);
1152 The init_session() function is called before sudo sets up the exe‐
1154 cution environment for the command. It is run in the parent sudo
1155 process before any user-ID or group-ID changes. This can be used
1156 to perform session setup that is not supported by command_info,
1157 such as opening the PAM session. The close() function can be used
1158 to tear down the session that was opened by init_session().
1159 Returns 1 on success, 0 on failure, and -1 on error. On error, the
1161 plugin may optionally call the conversation() or
1162 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1163 additional error information to the user.
1164 The function arguments are as follows:
1166 pwd If the user-ID the command will run as was found in the pass‐
1168 word database, pwd will describe that user, otherwise it will
1169 be NULL.
1170 user_env_out
1172 The NULL-terminated environment vector to use when executing
1173 the command. This is the same string passed back to the
1174 front-end via the Policy Plugin's user_env_out parameter. If
1175 the init_session() function needs to modify the user environ‐
1176 ment, it should update the pointer stored in user_env_out.
1177 The expected use case is to merge the contents of the PAM en‐
1178 vironment (if any) with the contents of user_env_out. The
1179 user_env_out parameter is only available starting with API
1180 version 1.2. A plugin must check the API version specified
1181 by the sudo front-end before using user_env_out. Failure to
1182 do so may result in a crash.
1183 errstr
1185 If the init_session() function returns a value other than 1,
1186 the plugin may store a message describing the failure or er‐
1187 ror in errstr. The sudo front-end will then pass this value
1188 to any registered audit plugins. The string stored in errstr
1189 must remain valid until the plugin's close() function is
1190 called.
1191 The errstr parameter is only available starting with API ver‐
1193 sion 1.15. A plugin must check the API version specified by
1194 the sudo front-end before using errstr. Failure to do so may
1195 result in a crash.
1196 register_hooks
1198 void (*register_hooks)(int version,
1199 int (*register_hook)(struct sudo_hook *hook));
1200 The register_hooks() function is called by the sudo front-end to
1202 register any hooks the plugin needs. If the plugin does not sup‐
1203 port hooks, register_hooks should be set to the NULL pointer.
1204 The version argument describes the version of the hooks API sup‐
1206 ported by the sudo front-end.
1207 The register_hook() function should be used to register any sup‐
1209 ported hooks the plugin needs. It returns 0 on success, 1 if the
1210 hook type is not supported, and -1 if the major version in struct
1211 sudo_hook does not match the front-end's major hook API version.
1212 See the Hook function API section below for more information about
1214 hooks.
1215 The register_hooks() function is only available starting with API
1217 version 1.2. If the sudo front-end doesn't support API version 1.2
1218 or higher, register_hooks() will not be called.
1219 deregister_hooks
1221 void (*deregister_hooks)(int version,
1222 int (*deregister_hook)(struct sudo_hook *hook));
1223 The deregister_hooks() function is called by the sudo front-end to
1225 deregister any hooks the plugin has registered. If the plugin does
1226 not support hooks, deregister_hooks should be set to the NULL
1227 pointer.
1228 The version argument describes the version of the hooks API sup‐
1230 ported by the sudo front-end.
1231 The deregister_hook() function should be used to deregister any
1233 hooks that were put in place by the register_hook() function. If
1234 the plugin tries to deregister a hook that the front-end does not
1235 support, deregister_hook() will return an error.
1236 See the Hook function API section below for more information about
1238 hooks.
1239 The deregister_hooks() function is only available starting with API
1241 version 1.2. If the sudo front-end doesn't support API version 1.2
1242 or higher, deregister_hooks() will not be called.
1243 event_alloc
1245 struct sudo_plugin_event * (*event_alloc)(void);
1246 The event_alloc() function is used to allocate a struct
1248 sudo_plugin_event which provides access to the main sudo event
1249 loop. Unlike the other fields, the event_alloc pointer is filled
1250 in by the sudo front-end, not by the plugin.
1251 See the Event API section below for more information about events.
1253 The event_alloc() function is only available starting with API ver‐
1255 sion 1.15. If the sudo front-end doesn't support API version 1.15
1256 or higher, event_alloc will not be set.
1257 Policy Plugin Version Macros
1259 /* Plugin API version major/minor. */
1261 #define SUDO_API_VERSION_MAJOR 1
1262 #define SUDO_API_VERSION_MINOR 13
1263 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1264 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
1265 SUDO_API_VERSION_MINOR)
1266 /* Getters and setters for API version */
1268 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1269 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1270 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
1271 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1272 } while(0)
1273 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
1274 *(vp) = (*(vp) & 0xffff0000) | (n); \
1275 } while(0)
1276 I/O plugin API
1278 struct io_plugin {
1279 #define SUDO_IO_PLUGIN 2
1280 unsigned int type; /* always SUDO_IO_PLUGIN */
1281 unsigned int version; /* always SUDO_API_VERSION */
1282 int (*open)(unsigned int version, sudo_conv_t conversation,
1283 sudo_printf_t sudo_plugin_printf, char * const settings[],
1284 char * const user_info[], char * const command_info[],
1285 int argc, char * const argv[], char * const user_env[],
1286 char * const plugin_options[], const char **errstr);
1287 void (*close)(int exit_status, int error); /* wait status or error */
1288 int (*show_version)(int verbose);
1289 int (*log_ttyin)(const char *buf, unsigned int len,
1290 const char **errstr);
1291 int (*log_ttyout)(const char *buf, unsigned int len,
1292 const char **errstr);
1293 int (*log_stdin)(const char *buf, unsigned int len,
1294 const char **errstr);
1295 int (*log_stdout)(const char *buf, unsigned int len,
1296 const char **errstr);
1297 int (*log_stderr)(const char *buf, unsigned int len,
1298 const char **errstr);
1299 void (*register_hooks)(int version,
1300 int (*register_hook)(struct sudo_hook *hook));
1301 void (*deregister_hooks)(int version,
1302 int (*deregister_hook)(struct sudo_hook *hook));
1303 int (*change_winsize)(unsigned int lines, unsigned int cols,
1304 const char **errstr);
1305 int (*log_suspend)(int signo, const char **errstr);
1306 struct sudo_plugin_event * (*event_alloc)(void);
1307 };
1308 When an I/O plugin is loaded, sudo runs the command in a pseudo-terminal.
1310 This makes it possible to log the input and output from the user's ses‐
1311 sion. If any of the standard input, standard output, or standard error
1312 do not correspond to a tty, sudo will open a pipe to capture the I/O for
1313 logging before passing it on.
1314 The log_ttyin() function receives the raw user input from the terminal
1316 device (this will include input even when echo is disabled, such as when
1317 a password is read). The log_ttyout() function receives output from the
1318 pseudo-terminal that is suitable for replaying the user's session at a
1319 later time. The log_stdin(), log_stdout(), and log_stderr() functions
1320 are only called if the standard input, standard output, or standard error
1321 respectively correspond to something other than a tty.
1322 Any of the logging functions may be set to the NULL pointer if no logging
1324 is to be performed. If the open function returns 0, no I/O will be sent
1325 to the plugin.
1326 If a logging function returns an error (-1), the running command will be
1328 terminated and all of the plugin's logging functions will be disabled.
1329 Other I/O logging plugins will still receive any remaining input or out‐
1330 put that has not yet been processed.
1331 If an input logging function rejects the data by returning 0, the command
1333 will be terminated and the data will not be passed to the command, though
1334 it will still be sent to any other I/O logging plugins. If an output
1335 logging function rejects the data by returning 0, the command will be
1336 terminated and the data will not be written to the terminal, though it
1337 will still be sent to any other I/O logging plugins.
1338 A struct audit_plugin has the following fields:
1340 type The type field should always be set to SUDO_IO_PLUGIN.
1342 version
1344 The version field should be set to SUDO_API_VERSION.
1345 This allows sudo to determine the API version the plugin was built
1347 against.
1348 open
1350 int (*open)(unsigned int version, sudo_conv_t conversation,
1351 sudo_printf_t sudo_plugin_printf, char * const settings[],
1352 char * const user_info[], char * const command_info[],
1353 int argc, char * const argv[], char * const user_env[],
1354 char * const plugin_options[]);
1355 The open() function is run before the log_ttyin(), log_ttyout(),
1357 log_stdin(), log_stdout(), log_stderr(), log_suspend(),
1358 change_winsize(), or show_version() functions are called. It is
1359 only called if the version is being requested or if the policy
1360 plugin's check_policy() function has returned successfully. It re‐
1361 turns 1 on success, 0 on failure, -1 if a general error occurred,
1362 or -2 if there was a usage error. In the latter case, sudo will
1363 print a usage message before it exits. If an error occurs, the
1364 plugin may optionally call the conversation() or
1365 sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1366 additional error information to the user.
1367 The function arguments are as follows:
1369 version
1371 The version passed in by sudo allows the plugin to determine
1372 the major and minor version number of the plugin API sup‐
1373 ported by sudo.
1374 conversation
1376 A pointer to the conversation() function that may be used by
1377 the Fa(show_version) function to display version information
1378 (see show_version() below). The conversation() function may
1379 also be used to display additional error message to the user.
1380 The conversation() function returns 0 on success and -1 on
1381 failure.
1382 sudo_plugin_printf
1384 A pointer to a printf()-style function that may be used by
1385 the show_version() function to display version information
1386 (see show_version below). The sudo_plugin_printf() function
1387 may also be used to display additional error message to the
1388 user. The sudo_plugin_printf() function returns number of
1389 characters printed on success and -1 on failure.
1390 settings
1392 A vector of user-supplied sudo settings in the form of
1393 “name=value” strings. The vector is terminated by a NULL
1394 pointer. These settings correspond to options the user spec‐
1395 ified when running sudo. As such, they will only be present
1396 when the corresponding option has been specified on the com‐
1397 mand line.
1398 When parsing settings, the plugin should split on the first
1400 equal sign (‘=’) since the name field will never include one
1401 itself but the value might.
1402 See the Policy plugin API section for a list of all possible
1404 settings.
1405 user_info
1407 A vector of information about the user running the command in
1408 the form of “name=value” strings. The vector is terminated
1409 by a NULL pointer.
1410 When parsing user_info, the plugin should split on the first
1412 equal sign (‘=’) since the name field will never include one
1413 itself but the value might.
1414 See the Policy plugin API section for a list of all possible
1416 strings.
1417 command_info
1419 A vector of information describing the command being run in
1420 the form of “name=value” strings. The vector is terminated
1421 by a NULL pointer.
1422 When parsing command_info, the plugin should split on the
1424 first equal sign (‘=’) since the name field will never in‐
1425 clude one itself but the value might.
1426 See the Policy plugin API section for a list of all possible
1428 strings.
1429 argc The number of elements in argv, not counting the final NULL
1431 pointer. It can be zero, such as when sudo is called with
1432 the -V option.
1433 argv If non-NULL, an argument vector describing a command the user
1435 wishes to run in the same form as what would be passed to the
1436 execve(2) system call.
1437 user_env
1439 The user's environment in the form of a NULL-terminated vec‐
1440 tor of “name=value” strings.
1441 When parsing user_env, the plugin should split on the first
1443 equal sign (‘=’) since the name field will never include one
1444 itself but the value might.
1445 plugin_options
1447 Any (non-comment) strings immediately after the plugin path
1448 are treated as arguments to the plugin. These arguments are
1449 split on a white space boundary and are passed to the plugin
1450 in the form of a NULL-terminated array of strings. If no ar‐
1451 guments were specified, plugin_options will be the NULL
1452 pointer.
1453 The plugin_options parameter is only available starting with
1455 API version 1.2. A plugin must check the API version speci‐
1456 fied by the sudo front-end before using plugin_options.
1457 Failure to do so may result in a crash.
1458 errstr
1460 If the open() function returns a value other than 1, the
1461 plugin may store a message describing the failure or error in
1462 errstr. The sudo front-end will then pass this value to any
1463 registered audit plugins. The string stored in errstr must
1464 remain valid until the plugin's close() function is called.
1465 The errstr parameter is only available starting with API ver‐
1467 sion 1.15. A plugin must check the API version specified by
1468 the sudo front-end before using errstr. Failure to do so may
1469 result in a crash.
1470 close
1472 void (*close)(int exit_status, int error);
1473 The close() function is called when sudo is finished, shortly be‐
1475 fore it exits.
1476 The function arguments are as follows:
1478 exit_status
1480 The command's exit status, as returned by the wait(2) system
1481 call, or zero if no command was run. The value of
1482 exit_status is undefined if error is non-zero.
1483 error
1485 If the command could not be executed, this is set to the
1486 value of errno set by the execve(2) system call. If the com‐
1487 mand was successfully executed, the value of error is zero.
1488 show_version
1490 int (*show_version)(int verbose);
1491 The show_version() function is called by sudo when the user speci‐
1493 fies the -V option. The plugin may display its version information
1494 to the user via the conversation() or sudo_plugin_printf() function
1495 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1496 information, the verbose flag will be non-zero.
1497 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1499 or -2 if there was a usage error, although the return value is cur‐
1500 rently ignored.
1501 log_ttyin
1503 int (*log_ttyin)(const char *buf, unsigned int len,
1504 const char **errstr);
1505 The log_ttyin() function is called whenever data can be read from
1507 the user but before it is passed to the running command. This al‐
1508 lows the plugin to reject data if it chooses to (for instance if
1509 the input contains banned content). Returns 1 if the data should
1510 be passed to the command, 0 if the data is rejected (which will
1511 terminate the running command), or -1 if an error occurred.
1512 The function arguments are as follows:
1514 buf The buffer containing user input.
1516 len The length of buf in bytes.
1518 errstr
1520 If the log_ttyin() function returns a value other than 1, the
1521 plugin may store a message describing the failure or error in
1522 errstr. The sudo front-end will then pass this value to any
1523 registered audit plugins. The string stored in errstr must
1524 remain valid until the plugin's close() function is called.
1525 The errstr parameter is only available starting with API ver‐
1527 sion 1.15. A plugin must check the API version specified by
1528 the sudo front-end before using errstr. Failure to do so may
1529 result in a crash.
1530 log_ttyout
1532 int (*log_ttyout)(const char *buf, unsigned int len,
1533 const char **errstr);
1534 The log_ttyout() function is called whenever data can be read from
1536 the command but before it is written to the user's terminal. This
1537 allows the plugin to reject data if it chooses to (for instance if
1538 the output contains banned content). Returns 1 if the data should
1539 be passed to the user, 0 if the data is rejected (which will termi‐
1540 nate the running command), or -1 if an error occurred.
1541 The function arguments are as follows:
1543 buf The buffer containing command output.
1545 len The length of buf in bytes.
1547 errstr
1549 If the log_ttyout() function returns a value other than 1,
1550 the plugin may store a message describing the failure or er‐
1551 ror in errstr. The sudo front-end will then pass this value
1552 to any registered audit plugins. The string stored in errstr
1553 must remain valid until the plugin's close() function is
1554 called.
1555 The errstr parameter is only available starting with API ver‐
1557 sion 1.15. A plugin must check the API version specified by
1558 the sudo front-end before using errstr. Failure to do so may
1559 result in a crash.
1560 log_stdin
1562 int (*log_stdin)(const char *buf, unsigned int len,
1563 const char **errstr);
1564 The log_stdin() function is only used if the standard input does
1566 not correspond to a tty device. It is called whenever data can be
1567 read from the standard input but before it is passed to the running
1568 command. This allows the plugin to reject data if it chooses to
1569 (for instance if the input contains banned content). Returns 1 if
1570 the data should be passed to the command, 0 if the data is rejected
1571 (which will terminate the running command), or -1 if an error oc‐
1572 curred.
1573 The function arguments are as follows:
1575 buf The buffer containing user input.
1577 len The length of buf in bytes.
1579 errstr
1581 If the log_stdin() function returns a value other than 1, the
1582 plugin may store a message describing the failure or error in
1583 errstr. The sudo front-end will then pass this value to any
1584 registered audit plugins. The string stored in errstr must
1585 remain valid until the plugin's close() function is called.
1586 The errstr parameter is only available starting with API ver‐
1588 sion 1.15. A plugin must check the API version specified by
1589 the sudo front-end before using errstr. Failure to do so may
1590 result in a crash.
1591 log_stdout
1593 int (*log_stdout)(const char *buf, unsigned int len,
1594 const char **errstr);
1595 The log_stdout() function is only used if the standard output does
1597 not correspond to a tty device. It is called whenever data can be
1598 read from the command but before it is written to the standard out‐
1599 put. This allows the plugin to reject data if it chooses to (for
1600 instance if the output contains banned content). Returns 1 if the
1601 data should be passed to the user, 0 if the data is rejected (which
1602 will terminate the running command), or -1 if an error occurred.
1603 The function arguments are as follows:
1605 buf The buffer containing command output.
1607 len The length of buf in bytes.
1609 errstr
1611 If the log_stdout() function returns a value other than 1,
1612 the plugin may store a message describing the failure or er‐
1613 ror in errstr. The sudo front-end will then pass this value
1614 to any registered audit plugins. The string stored in errstr
1615 must remain valid until the plugin's close() function is
1616 called.
1617 The errstr parameter is only available starting with API ver‐
1619 sion 1.15. A plugin must check the API version specified by
1620 the sudo front-end before using errstr. Failure to do so may
1621 result in a crash.
1622 log_stderr
1624 int (*log_stderr)(const char *buf, unsigned int len,
1625 const char **errstr);
1626 The log_stderr() function is only used if the standard error does
1628 not correspond to a tty device. It is called whenever data can be
1629 read from the command but before it is written to the standard er‐
1630 ror. This allows the plugin to reject data if it chooses to (for
1631 instance if the output contains banned content). Returns 1 if the
1632 data should be passed to the user, 0 if the data is rejected (which
1633 will terminate the running command), or -1 if an error occurred.
1634 The function arguments are as follows:
1636 buf The buffer containing command output.
1638 len The length of buf in bytes.
1640 errstr
1642 If the log_stderr() function returns a value other than 1,
1643 the plugin may store a message describing the failure or er‐
1644 ror in errstr. The sudo front-end will then pass this value
1645 to any registered audit plugins. The string stored in errstr
1646 must remain valid until the plugin's close() function is
1647 called.
1648 The errstr parameter is only available starting with API ver‐
1650 sion 1.15. A plugin must check the API version specified by
1651 the sudo front-end before using errstr. Failure to do so may
1652 result in a crash.
1653 register_hooks
1655 See the Policy plugin API section for a description of
1656 register_hooks().
1657 deregister_hooks
1659 See the Policy plugin API section for a description of
1660 deregister_hooks().
1661 change_winsize
1663 int (*change_winsize)(unsigned int lines, unsigned int cols,
1664 const char **errstr);
1665 The change_winsize() function is called whenever the window size of
1667 the terminal changes from the initial values specified in the
1668 user_info list. Returns -1 if an error occurred, in which case no
1669 further calls to change_winsize() will be made,
1670 The function arguments are as follows:
1672 lines
1674 The number of lines (rows) in the re-sized terminal.
1675 cols The number of columns in the re-sized terminal.
1677 errstr
1679 If the change_winsize() function returns a value other than
1680 1, the plugin may store a message describing the failure or
1681 error in errstr. The sudo front-end will then pass this
1682 value to any registered audit plugins. The string stored in
1683 errstr must remain valid until the plugin's close() function
1684 is called.
1685 The errstr parameter is only available starting with API ver‐
1687 sion 1.15. A plugin must check the API version specified by
1688 the sudo front-end before using errstr. Failure to do so may
1689 result in a crash.
1690 log_suspend
1692 int (*log_suspend)(int signo, const char **errstr);
1693 The log_suspend() function is called whenever a command is sus‐
1695 pended or resumed. Logging this information makes it possible to
1696 skip the period of time when the command was suspended during play‐
1697 back of a session. Returns -1 if an error occurred, in which case
1698 no further calls to log_suspend() will be made,
1699 The function arguments are as follows:
1701 signo
1703 The signal that caused the command to be suspended, or
1704 SIGCONT if the command was resumed.
1705 errstr
1707 If the log_suspend() function returns a value other than 1,
1708 the plugin may store a message describing the failure or er‐
1709 ror in errstr. The sudo front-end will then pass this value
1710 to any registered audit plugins. The string stored in errstr
1711 must remain valid until the plugin's close() function is
1712 called.
1713 The errstr parameter is only available starting with API ver‐
1715 sion 1.15. A plugin must check the API version specified by
1716 the sudo front-end before using errstr. Failure to do so may
1717 result in a crash.
1718 event_alloc
1720 struct sudo_plugin_event * (*event_alloc)(void);
1721 The event_alloc() function is used to allocate a struct
1723 sudo_plugin_event which provides access to the main sudo
1724 event loop. Unlike the other fields, the event_alloc()
1725 pointer is filled in by the sudo front-end, not by the
1726 plugin.
1727 See the Event API section below for more information about
1729 events.
1730 The event_alloc() function is only available starting with
1732 API version 1.15. If the sudo front-end doesn't support API
1733 version 1.15 or higher, event_alloc() will not be set.
1734 I/O Plugin Version Macros
1736 Same as for the Policy plugin API.
1738 Audit plugin API
1740 /* Audit plugin close function status types. */
1741 #define SUDO_PLUGIN_NO_STATUS 0
1742 #define SUDO_PLUGIN_WAIT_STATUS 1
1743 #define SUDO_PLUGIN_EXEC_ERROR 2
1744 #define SUDO_PLUGIN_SUDO_ERROR 3
1745 #define SUDO_AUDIT_PLUGIN 3
1747 struct audit_plugin {
1748 unsigned int type; /* always SUDO_AUDIT_PLUGIN */
1749 unsigned int version; /* always SUDO_API_VERSION */
1750 int (*open)(unsigned int version, sudo_conv_t conversation,
1751 sudo_printf_t sudo_plugin_printf, char * const settings[],
1752 char * const user_info[], int submit_optind,
1753 char * const submit_argv[], char * const submit_envp[],
1754 char * const plugin_options[], const char **errstr);
1755 void (*close)(int status_type, int status);
1756 int (*accept)(const char *plugin_name,
1757 unsigned int plugin_type, char * const command_info[],
1758 char * const run_argv[], char * const run_envp[],
1759 const char **errstr);
1760 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1761 const char *audit_msg, char * const command_info[],
1762 const char **errstr);
1763 int (*error)(const char *plugin_name, unsigned int plugin_type,
1764 const char *audit_msg, char * const command_info[],
1765 const char **errstr);
1766 int (*show_version)(int verbose);
1767 void (*register_hooks)(int version,
1768 int (*register_hook)(struct sudo_hook *hook));
1769 void (*deregister_hooks)(int version,
1770 int (*deregister_hook)(struct sudo_hook *hook));
1771 struct sudo_plugin_event * (*event_alloc)(void);
1772 }
1773 An audit plugin can be used to log successful and unsuccessful attempts
1775 to run sudo independent of the policy or any I/O plugins. Multiple audit
1776 plugins may be specified in sudo.conf(5).
1777 A struct audit_plugin has the following fields:
1779 type The type field should always be set to SUDO_AUDIT_PLUGIN.
1781 version
1783 The version field should be set to SUDO_API_VERSION.
1784 This allows sudo to determine the API version the plugin was built
1786 against.
1787 open
1789 int (*open)(unsigned int version, sudo_conv_t conversation,
1790 sudo_printf_t sudo_plugin_printf, char * const settings[],
1791 char * const user_info[], int submit_optind,
1792 char * const submit_argv[], char * const submit_envp[],
1793 char * const plugin_options[], const char **errstr);
1794 The audit open() function is run before any other sudo plugin API
1796 functions. This makes it possible to audit failures in the other
1797 plugins. It returns 1 on success, 0 on failure, -1 if a general
1798 error occurred, or -2 if there was a usage error. In the latter
1799 case, sudo will print a usage message before it exits. If an error
1800 occurs, the plugin may optionally call the conversation() or
1801 plugin_printf() function with SUDO_CONF_ERROR_MSG to present addi‐
1802 tional error information to the user.
1803 The function arguments are as follows:
1805 version
1807 The version passed in by sudo allows the plugin to determine
1808 the major and minor version number of the plugin API sup‐
1809 ported by sudo.
1810 conversation
1812 A pointer to the conversation() function that may be used by
1813 the show_version() function to display version information
1814 (see show_version() below). The conversation() function may
1815 also be used to display additional error message to the user.
1816 The conversation() function returns 0 on success, and -1 on
1817 failure.
1818 plugin_printf
1820 A pointer to a printf()-style function that may be used by
1821 the show_version() function to display version information
1822 (see show_version below). The plugin_printf() function may
1823 also be used to display additional error message to the user.
1824 The plugin_printf() function returns number of characters
1825 printed on success and -1 on failure.
1826 settings
1828 A vector of user-supplied sudo settings in the form of
1829 “name=value” strings. The vector is terminated by a NULL
1830 pointer. These settings correspond to options the user spec‐
1831 ified when running sudo. As such, they will only be present
1832 when the corresponding option has been specified on the com‐
1833 mand line.
1834 When parsing settings, the plugin should split on the first
1836 equal sign (‘=’) since the name field will never include one
1837 itself but the value might.
1838 See the Policy plugin API section for a list of all possible
1840 settings.
1841 user_info
1843 A vector of information about the user running the command in
1844 the form of “name=value” strings. The vector is terminated
1845 by a NULL pointer.
1846 When parsing user_info, the plugin should split on the first
1848 equal sign (‘=’) since the name field will never include one
1849 itself but the value might.
1850 See the Policy plugin API section for a list of all possible
1852 strings.
1853 submit_optind
1855 The index into submit_argv that corresponds to the first en‐
1856 try that is not a command line option. If submit_argv only
1857 consists of options, which may be the case with the -l or -v
1858 options, submit_argv[submit_optind] will evaluate to the NULL
1859 pointer.
1860 submit_argv
1862 The argument vector sudo was invoked with, including all com‐
1863 mand line options. The submit_optind argument can be used to
1864 determine the end of the command line options.
1865 submit_envp
1867 The invoking user's environment in the form of a
1868 NULL-terminated vector of “name=value” strings.
1869 When parsing submit_envp, the plugin should split on the
1871 first equal sign (‘=’) since the name field will never in‐
1872 clude one itself but the value might.
1873 plugin_options
1875 Any (non-comment) strings immediately after the plugin path
1876 are treated as arguments to the plugin. These arguments are
1877 split on a white space boundary and are passed to the plugin
1878 in the form of a NULL-terminated array of strings. If no ar‐
1879 guments were specified, plugin_options will be the NULL
1880 pointer.
1881 errstr
1883 If the open() function returns a value other than 1, the
1884 plugin may store a message describing the failure or error in
1885 errstr. The sudo front-end will then pass this value to any
1886 registered audit plugins. The string stored in errstr must
1887 remain valid until the plugin's close() function is called.
1888 close
1890 void (*close)(int status_type, int status);
1891 The close() function is called when sudo is finished, shortly be‐
1893 fore it exits.
1894 The function arguments are as follows:
1896 status_type
1898 The type of status being passed. One of
1899 SUDO_PLUGIN_NO_STATUS, SUDO_PLUGIN_WAIT_STATUS,
1900 SUDO_PLUGIN_EXEC_ERROR or SUDO_PLUGIN_SUDO_ERROR.
1901 status
1903 Depending on the value of status_type, this value is either
1904 ignored, the command's exit status as returned by the wait(2)
1905 system call, the value of errno set by the execve(2) system
1906 call, or the value of errno resulting from an error in the
1907 sudo front-end.
1908 accept
1910 int (*accept)(const char *plugin_name, unsigned int plugin_type,
1911 char * const command_info[], char * const run_argv[],
1912 char * const run_envp[], const char **errstr);
1913 The accept() function is called when a command or action is ac‐
1915 cepted by a policy or approval plugin. The function arguments are
1916 as follows:
1917 plugin_name
1919 The name of the plugin that accepted the command or “sudo”
1920 for the sudo front-end.
1921 plugin_type
1923 The type of plugin that accepted the command, currently ei‐
1924 ther SUDO_POLICY_PLUGIN, SUDO_POLICY_APPROVAL, or
1925 SUDO_FRONT_END. The accept() function is called multiple
1926 times--once for each policy or approval plugin that succeeds
1927 and once for the sudo front-end. When called on behalf of
1928 the sudo front-end, command_info may include information from
1929 an I/O logging plugin as well.
1930 Typically, an audit plugin is interested in either the accept
1932 status from the sudo front-end or from the various policy and
1933 approval plugins, but not both. It is possible for the pol‐
1934 icy plugin to accept a command that is later rejected by an
1935 approval plugin, in which case the audit plugin's accept()
1936 and reject() functions will both be called.
1937 command_info
1939 An optional vector of information describing the command be‐
1940 ing run in the form of “name=value” strings. The vector is
1941 terminated by a NULL pointer.
1942 When parsing command_info, the plugin should split on the
1944 first equal sign (‘=’) since the name field will never in‐
1945 clude one itself but the value might.
1946 See the Policy plugin API section for a list of all possible
1948 strings.
1949 run_argv
1951 A NULL-terminated argument vector describing a command that
1952 will be run in the same form as what would be passed to the
1953 execve(2) system call.
1954 run_envp
1956 The environment the command will be run with in the form of a
1957 NULL-terminated vector of “name=value” strings.
1958 When parsing run_envp, the plugin should split on the first
1960 equal sign (‘=’) since the name field will never include one
1961 itself but the value might.
1962 errstr
1964 If the accept() function returns a value other than 1, the
1965 plugin may store a message describing the failure or error in
1966 errstr. The sudo front-end will then pass this value to any
1967 registered audit plugins. The string stored in errstr must
1968 remain valid until the plugin's close() function is called.
1969 reject
1971 int (*reject)(const char *plugin_name, unsigned int plugin_type,
1972 const char *audit_msg, char * const command_info[],
1973 const char **errstr);
1974 The reject() function is called when a command or action is re‐
1976 jected by a plugin. The function arguments are as follows:
1977 plugin_name
1979 The name of the plugin that rejected the command.
1980 plugin_type
1982 The type of plugin that rejected the command, currently ei‐
1983 ther SUDO_POLICY_PLUGIN, SUDO_APPROVAL_PLUGIN, or
1984 SUDO_IO_PLUGIN.
1985 Unlike the accept() function, the reject() function is not
1987 called on behalf of the sudo front-end.
1988 audit_msg
1990 An optional string describing the reason the command was re‐
1991 jected by the plugin. If the plugin did not provide a rea‐
1992 son, audit_msg will be the NULL pointer.
1993 command_info
1995 An optional vector of information describing the command be‐
1996 ing run in the form of “name=value” strings. The vector is
1997 terminated by a NULL pointer.
1998 When parsing command_info, the plugin should split on the
2000 first equal sign (‘=’) since the name field will never in‐
2001 clude one itself but the value might.
2002 See the Policy plugin API section for a list of all possible
2004 strings.
2005 errstr
2007 If the reject() function returns a value other than 1, the
2008 plugin may store a message describing the failure or error in
2009 errstr. The sudo front-end will then pass this value to any
2010 registered audit plugins. The string stored in errstr must
2011 remain valid until the plugin's close() function is called.
2012 error
2014 int (*error)(const char *plugin_name, unsigned int plugin_type,
2015 const char *audit_msg, char * const command_info[],
2016 const char **errstr);
2017 The error() function is called when a plugin or the sudo front-end
2019 returns an error. The function arguments are as follows:
2020 plugin_name
2022 The name of the plugin that generated the error or “sudo” for
2023 the sudo front-end.
2024 plugin_type
2026 The type of plugin that generated the error, or
2027 SUDO_FRONT_END for the sudo front-end.
2028 audit_msg
2030 An optional string describing the plugin error. If the
2031 plugin did not provide a description, audit_msg will be the
2032 NULL pointer.
2033 command_info
2035 An optional vector of information describing the command be‐
2036 ing run in the form of “name=value” strings. The vector is
2037 terminated by a NULL pointer.
2038 When parsing command_info, the plugin should split on the
2040 first equal sign (‘=’) since the name field will never in‐
2041 clude one itself but the value might.
2042 See the Policy plugin API section for a list of all possible
2044 strings.
2045 errstr
2047 If the error() function returns a value other than 1, the
2048 plugin may store a message describing the failure or error in
2049 errstr. The sudo front-end will then pass this value to any
2050 registered audit plugins. The string stored in errstr must
2051 remain valid until the plugin's close() function is called.
2052 show_version
2054 int (*show_version)(int verbose);
2055 The show_version() function is called by sudo when the user speci‐
2057 fies the -V option. The plugin may display its version information
2058 to the user via the conversation() or plugin_printf() function us‐
2059 ing SUDO_CONV_INFO_MSG. If the user requests detailed version in‐
2060 formation, the verbose flag will be set.
2061 Returns 1 on success, 0 on failure, -1 if a general error occurred,
2063 or -2 if there was a usage error, although the return value is cur‐
2064 rently ignored.
2065 register_hooks
2067 See the Policy plugin API section for a description of
2068 register_hooks().
2069 deregister_hooks
2071 See the Policy plugin API section for a description of
2072 deregister_hooks().
2073 event_alloc
2075 struct sudo_plugin_event * (*event_alloc)(void);
2076 The event_alloc() function is used to allocate a struct
2078 sudo_plugin_event which provides access to the main sudo event
2079 loop. Unlike the other fields, the event_alloc pointer is filled
2080 in by the sudo front-end, not by the plugin.
2081 See the Event API section below for more information about events.
2083 The event_alloc() function is only available starting with API ver‐
2085 sion 1.17. If the sudo front-end doesn't support API version 1.17
2086 or higher, event_alloc() will not be set.
2087 Approval plugin API
2089 struct approval_plugin {
2090 #define SUDO_APPROVAL_PLUGIN 4
2091 unsigned int type; /* always SUDO_APPROVAL_PLUGIN */
2092 unsigned int version; /* always SUDO_API_VERSION */
2093 int (*open)(unsigned int version, sudo_conv_t conversation,
2094 sudo_printf_t sudo_plugin_printf, char * const settings[],
2095 char * const user_info[], int submit_optind,
2096 char * const submit_argv[], char * const submit_envp[],
2097 char * const plugin_options[], const char **errstr);
2098 void (*close)(void);
2099 int (*check)(char * const command_info[], char * const run_argv[],
2100 char * const run_envp[], const char **errstr);
2101 int (*show_version)(int verbose);
2102 };
2103 An approval plugin can be used to apply extra constraints after a command
2105 has been accepted by the policy plugin. Unlike the other plugin types,
2106 it does not remain open until the command completes. The plugin is
2107 opened before a call to check() or show_version() and closed shortly
2108 thereafter (audit plugin functions must be called before the plugin is
2109 closed). Multiple approval plugins may be specified in sudo.conf(5).
2110 A struct approval_plugin has the following fields:
2112 type The type field should always be set to SUDO_APPROVAL_PLUGIN.
2114 version
2116 The version field should be set to SUDO_API_VERSION.
2117 This allows sudo to determine the API version the plugin was built
2119 against.
2120 open
2122 int (*open)(unsigned int version, sudo_conv_t conversation,
2123 sudo_printf_t sudo_plugin_printf, char * const settings[],
2124 char * const user_info[], int submit_optind,
2125 char * const submit_argv[], char * const submit_envp[],
2126 char * const plugin_options[], const char **errstr);
2127 The approval open() function is run immediately before a call to
2129 the plugin's check() or show_version() functions. It is only
2130 called if the version is being requested or if the policy plugin's
2131 check_policy() function has returned successfully. It returns 1 on
2132 success, 0 on failure, -1 if a general error occurred, or -2 if
2133 there was a usage error. In the latter case, sudo will print a us‐
2134 age message before it exits. If an error occurs, the plugin may
2135 optionally call the conversation() or plugin_printf() function with
2136 SUDO_CONF_ERROR_MSG to present additional error information to the
2137 user.
2138 The function arguments are as follows:
2140 version
2142 The version passed in by sudo allows the plugin to determine
2143 the major and minor version number of the plugin API sup‐
2144 ported by sudo.
2145 conversation
2147 A pointer to the conversation() function that can be used by
2148 the plugin to interact with the user (see Conversation API
2149 for details). Returns 0 on success and -1 on failure.
2150 plugin_printf
2152 A pointer to a printf()-style function that may be used to
2153 display informational or error messages (see Conversation API
2154 for details). Returns the number of characters printed on
2155 success and -1 on failure.
2156 settings
2158 A vector of user-supplied sudo settings in the form of
2159 “name=value” strings. The vector is terminated by a NULL
2160 pointer. These settings correspond to options the user spec‐
2161 ified when running sudo. As such, they will only be present
2162 when the corresponding option has been specified on the com‐
2163 mand line.
2164 When parsing settings, the plugin should split on the first
2166 equal sign (‘=’) since the name field will never include one
2167 itself but the value might.
2168 See the Policy plugin API section for a list of all possible
2170 settings.
2171 user_info
2173 A vector of information about the user running the command in
2174 the form of “name=value” strings. The vector is terminated
2175 by a NULL pointer.
2176 When parsing user_info, the plugin should split on the first
2178 equal sign (‘=’) since the name field will never include one
2179 itself but the value might.
2180 See the Policy plugin API section for a list of all possible
2182 strings.
2183 submit_optind
2185 The index into submit_argv that corresponds to the first en‐
2186 try that is not a command line option. If submit_argv only
2187 consists of options, which may be the case with the -l or -v
2188 options, submit_argv[submit_optind] will evaluate to the NULL
2189 pointer.
2190 submit_argv
2192 The argument vector sudo was invoked with, including all com‐
2193 mand line options. The submit_optind argument can be used to
2194 determine the end of the command line options.
2195 submit_envp
2197 The invoking user's environment in the form of a
2198 NULL-terminated vector of “name=value” strings.
2199 When parsing submit_envp, the plugin should split on the
2201 first equal sign (‘=’) since the name field will never in‐
2202 clude one itself but the value might.
2203 plugin_options
2205 Any (non-comment) strings immediately after the plugin path
2206 are treated as arguments to the plugin. These arguments are
2207 split on a white space boundary and are passed to the plugin
2208 in the form of a NULL-terminated array of strings. If no ar‐
2209 guments were specified, plugin_options will be the NULL
2210 pointer.
2211 errstr
2213 If the open() function returns a value other than 1, the
2214 plugin may store a message describing the failure or error in
2215 errstr. The sudo front-end will then pass this value to any
2216 registered audit plugins. The string stored in errstr must
2217 remain valid until the plugin's close() function is called.
2218 close
2220 void (*close)(void);
2221 The close() function is called after the approval plugin's check()
2223 or show_version() functions have been called. It takes no argu‐
2224 ments. The close() function is typically used to perform plugin-
2225 specific cleanup, such as the freeing of memory objects allocated
2226 by the plugin. If the plugin does not need to perform any cleanup,
2227 close() may be set to the NULL pointer.
2228 check
2230 int (*check)(char * const command_info[], char * const run_argv[],
2231 char * const run_envp[], const char **errstr);
2232 The approval check() function is run after the policy plugin
2234 check_policy() function and before any I/O logging plugins. If
2235 multiple approval plugins are loaded, they must all succeed for the
2236 command to be allowed. It returns 1 on success, 0 on failure, -1
2237 if a general error occurred, or -2 if there was a usage error. In
2238 the latter case, sudo will print a usage message before it exits.
2239 If an error occurs, the plugin may optionally call the
2240 conversation() or plugin_printf() function with SUDO_CONF_ERROR_MSG
2241 to present additional error information to the user.
2242 The function arguments are as follows:
2244 command_info
2246 A vector of information describing the command being run in
2247 the form of “name=value” strings. The vector is terminated
2248 by a NULL pointer.
2249 When parsing command_info, the plugin should split on the
2251 first equal sign (‘=’) since the name field will never in‐
2252 clude one itself but the value might.
2253 See the Policy plugin API section for a list of all possible
2255 strings.
2256 run_argv
2258 A NULL-terminated argument vector describing a command that
2259 will be run in the same form as what would be passed to the
2260 execve(2) system call.
2261 run_envp
2263 The environment the command will be run with in the form of a
2264 NULL-terminated vector of “name=value” strings.
2265 When parsing run_envp, the plugin should split on the first
2267 equal sign (‘=’) since the name field will never include one
2268 itself but the value might.
2269 errstr
2271 If the open() function returns a value other than 1, the
2272 plugin may store a message describing the failure or error in
2273 errstr. The sudo front-end will then pass this value to any
2274 registered audit plugins. The string stored in errstr must
2275 remain valid until the plugin's close() function is called.
2276 show_version
2278 int (*show_version)(int verbose);
2279 The show_version() function is called by sudo when the user speci‐
2281 fies the -V option. The plugin may display its version information
2282 to the user via the conversation() or plugin_printf() function us‐
2283 ing SUDO_CONV_INFO_MSG. If the user requests detailed version in‐
2284 formation, the verbose flag will be set.
2285 Returns 1 on success, 0 on failure, -1 if a general error occurred,
2287 or -2 if there was a usage error, although the return value is cur‐
2288 rently ignored.
2289 Signal handlers
2291 The sudo front-end installs default signal handlers to trap common sig‐
2292 nals while the plugin functions are run. The following signals are
2293 trapped by default before the command is executed:
2294 • SIGALRM
2296 • SIGHUP
2297 • SIGINT
2298 • SIGPIPE
2299 • SIGQUIT
2300 • SIGTERM
2301 • SIGTSTP
2302 • SIGUSR1
2303 • SIGUSR2
2304 If a fatal signal is received before the command is executed, sudo will
2306 call the plugin's close() function with an exit status of 128 plus the
2307 value of the signal that was received. This allows for consistent log‐
2308 ging of commands killed by a signal for plugins that log such information
2309 in their close() function. An exception to this is SIGPIPE, which is ig‐
2310 nored until the command is executed.
2311 A plugin may temporarily install its own signal handlers but must restore
2313 the original handler before the plugin function returns.
2314 Hook function API
2316 Beginning with plugin API version 1.2, it is possible to install hooks
2317 for certain functions called by the sudo front-end.
2318 Currently, the only supported hooks relate to the handling of environment
2320 variables. Hooks can be used to intercept attempts to get, set, or re‐
2321 move environment variables so that these changes can be reflected in the
2322 version of the environment that is used to execute a command. A future
2323 version of the API will support hooking internal sudo front-end functions
2324 as well.
2325 Hook structure
2327 Hooks in sudo are described by the following structure:
2329 typedef int (*sudo_hook_fn_t)();
2331 struct sudo_hook {
2333 unsigned int hook_version;
2334 unsigned int hook_type;
2335 sudo_hook_fn_t hook_fn;
2336 void *closure;
2337 };
2338 A struct sudo_hook has the following fields:
2340 hook_version
2342 The hook_version field should be set to SUDO_HOOK_VERSION.
2343 hook_type
2345 The hook_type field may be one of the following supported hook
2346 types:
2347 SUDO_HOOK_SETENV
2349 The C library setenv(3) function. Any registered hooks will
2350 run before the C library implementation. The hook_fn field
2351 should be a function that matches the following typedef:
2352 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
2354 const char *value, int overwrite, void *closure);
2355 If the registered hook does not match the typedef the results
2357 are unspecified.
2358 SUDO_HOOK_UNSETENV
2360 The C library unsetenv(3) function. Any registered hooks
2361 will run before the C library implementation. The hook_fn
2362 field should be a function that matches the following type‐
2363 def:
2364 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2366 void *closure);
2367 SUDO_HOOK_GETENV
2369 The C library getenv(3) function. Any registered hooks will
2370 run before the C library implementation. The hook_fn field
2371 should be a function that matches the following typedef:
2372 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2374 char **value, void *closure);
2375 If the registered hook does not match the typedef the results
2377 are unspecified.
2378 SUDO_HOOK_PUTENV
2380 The C library putenv(3) function. Any registered hooks will
2381 run before the C library implementation. The hook_fn field
2382 should be a function that matches the following typedef:
2383 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2385 void *closure);
2386 If the registered hook does not match the typedef the results
2388 are unspecified.
2389 hook_fn
2391 sudo_hook_fn_t hook_fn;
2392 The hook_fn field should be set to the plugin's hook implementa‐
2394 tion. The actual function arguments will vary depending on the
2395 hook_type (see hook_type above). In all cases, the closure field
2396 of struct sudo_hook is passed as the last function parameter. This
2397 can be used to pass arbitrary data to the plugin's hook implementa‐
2398 tion.
2399 The function return value may be one of the following:
2401 SUDO_HOOK_RET_ERROR
2403 The hook function encountered an error.
2404 SUDO_HOOK_RET_NEXT
2406 The hook completed without error, go on to the next hook (in‐
2407 cluding the system implementation if applicable). For exam‐
2408 ple, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if the
2409 specified variable was not found in the private copy of the
2410 environment.
2411 SUDO_HOOK_RET_STOP
2413 The hook completed without error, stop processing hooks for
2414 this invocation. This can be used to replace the system im‐
2415 plementation. For example, a setenv hook that operates on a
2416 private copy of the environment but leaves environ unchanged.
2417 Care must be taken when hooking C library functions, it is very easy to
2419 create an infinite loop. For example, a getenv(3) hook that calls the
2420 snprintf(3) function may create a loop if the snprintf(3) implementation
2421 calls getenv(3) to check the locale. To prevent this, you may wish to
2422 use a static variable in the hook function to guard against nested calls.
2423 For example:
2424 static int in_progress = 0; /* avoid recursion */
2426 if (in_progress)
2427 return SUDO_HOOK_RET_NEXT;
2428 in_progress = 1;
2429 ...
2430 in_progress = 0;
2431 return SUDO_HOOK_RET_STOP;
2432 Hook API Version Macros
2434 /* Hook API version major/minor */
2436 #define SUDO_HOOK_VERSION_MAJOR 1
2437 #define SUDO_HOOK_VERSION_MINOR 0
2438 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
2439 SUDO_HOOK_VERSION_MINOR)
2440 For getters and setters see the Policy plugin API.
2442 Event API
2444 When sudo runs a command, it uses an event loop to service signals and
2445 I/O. Events may be triggered based on time, a file or socket descriptor
2446 becoming ready, or due to receipt of a signal. Starting with API version
2447 1.15, it is possible for a plugin to participate in this event loop by
2448 calling the event_alloc() function.
2449 Event structure
2451 Events are described by the following structure:
2453 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure);
2455 struct sudo_plugin_event {
2457 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2458 sudo_plugin_ev_callback_t callback, void *closure);
2459 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2460 int (*del)(struct sudo_plugin_event *pev);
2461 int (*pending)(struct sudo_plugin_event *pev, int events,
2462 struct timespec *ts);
2463 int (*fd)(struct sudo_plugin_event *pev);
2464 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2465 void (*loopbreak)(struct sudo_plugin_event *pev);
2466 void (*free)(struct sudo_plugin_event *pev);
2467 };
2468 A struct sudo_plugin_event contains the following function pointers:
2470 set
2472 int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2473 sudo_plugin_ev_callback_t callback, void *closure);
2474 The set() function takes the following arguments:
2476 struct sudo_plugin_event *pev
2478 A pointer to the struct sudo_plugin_event itself.
2479 fd The file or socket descriptor for I/O-based events or the
2481 signal number for signal events. For time-based events, fd
2482 must be -1.
2483 events
2485 The following values determine what will trigger the event
2486 callback:
2487 SUDO_PLUGIN_EV_TIMEOUT
2489 callback is run after the specified timeout expires
2490 SUDO_PLUGIN_EV_READ
2492 callback is run when the file descriptor is readable
2493 SUDO_PLUGIN_EV_WRITE
2495 callback is run when the file descriptor is writable
2496 SUDO_PLUGIN_EV_PERSIST
2498 event is persistent and remains enabled until explic‐
2499 itly deleted
2500 SUDO_PLUGIN_EV_SIGNAL
2502 callback is run when the specified signal is received
2503 The SUDO_PLUGIN_EV_PERSIST flag may be ORed with any of the
2505 event types. It is also possible to OR SUDO_PLUGIN_EV_READ
2506 and SUDO_PLUGIN_EV_WRITE together to run the callback when a
2507 descriptor is ready to be either read from or written to.
2508 All other event values are mutually exclusive.
2509 sudo_plugin_ev_callback_t callback
2511 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what,
2512 void *closure);
2513 The function to call when an event is triggered. The
2515 callback() function is run with the following arguments:
2516 fd The file or socket descriptor for I/O-based events or
2518 the signal number for signal events.
2519 what The event type that triggered that callback. For
2521 events that have multiple event types (for example
2522 SUDO_PLUGIN_EV_READ and SUDO_PLUGIN_EV_WRITE) or have
2523 an associated timeout, what can be used to determine
2524 why the callback was run.
2525 closure
2527 The generic pointer that was specified in the set()
2528 function.
2529 closure
2531 A generic pointer that will be passed to the callback func‐
2532 tion.
2533 The set() function returns 1 on success, and -1 if a error oc‐
2535 curred.
2536 add
2538 int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2539 The add() function adds the event pev to sudo's event loop. The
2541 event must have previously been initialized via the set() function.
2542 If the timeout argument is not NULL, it should specify a (relative)
2543 timeout after which the event will be triggered if the main event
2544 criteria has not been met. This is often used to implement an I/O
2545 timeout where the event will fire if a descriptor is not ready
2546 within a certain time period. If the event is already present in
2547 the event loop, its timeout will be adjusted to match the new
2548 value, if any.
2549 The add() function returns 1 on success, and -1 if a error oc‐
2551 curred.
2552 del
2554 int (*del)(struct sudo_plugin_event *pev);
2555 The del() function deletes the event pev from sudo's event loop.
2557 Deleted events can be added back via the add() function.
2558 The del() function returns 1 on success, and -1 if a error oc‐
2560 curred.
2561 pending
2563 int (*pending)(struct sudo_plugin_event *pev, int events,
2564 struct timespec *ts);
2565 The pending() function can be used to determine whether one or more
2567 events is pending. The events argument specifies which events to
2568 check for. See the set() function for a list of valid event types.
2569 If SUDO_PLUGIN_EV_TIMEOUT is specified in events, the event has an
2570 associated timeout and the ts pointer is non-NULL, it will be
2571 filled in with the remaining time.
2572 fd
2574 int (*fd)(struct sudo_plugin_event *pev);
2575 The fd() function returns the descriptor or signal number associ‐
2577 ated with the event pev.
2578 setbase
2580 void (*setbase)(struct sudo_plugin_event *pev, void *base);
2581 The setbase() function sets the underlying event base for pev to
2583 the specified value. This can be used to move an event created via
2584 event_alloc() to a new event loop allocated by sudo's event subsys‐
2585 tem. If base is NULL, pev's event base is reset to the default
2586 value, which corresponds to sudo's main event loop. Using this
2587 function requires linking the plugin with the sudo_util library.
2588 It is unlikely to be used outside of the sudoers plugin.
2589 loopbreak
2591 void (*loopbreak)(struct sudo_plugin_event *pev);
2592 The loopbreak() function causes sudo's event loop to exit immedi‐
2594 ately and the running command to be terminated.
2595 free
2597 void (*free)(struct sudo_plugin_event *pev);
2598 The free() function deletes the event pev from the event loop and
2600 frees the memory associated with it.
2601 Remote command execution
2603 The sudo front-end does not support running remote commands. However,
2604 starting with sudo 1.8.8, the -h option may be used to specify a remote
2605 host that is passed to the policy plugin. A plugin may also accept a
2606 runas_user in the form of “user@hostname” which will work with older ver‐
2607 sions of sudo. It is anticipated that remote commands will be supported
2608 by executing a “helper” program. The policy plugin should setup the exe‐
2609 cution environment such that the sudo front-end will run the helper
2610 which, in turn, will connect to the remote host and run the command.
2611 For example, the policy plugin could utilize ssh to perform remote com‐
2613 mand execution. The helper program would be responsible for running ssh
2614 with the proper options to use a private key or certificate that the re‐
2615 mote host will accept and run a program on the remote host that would
2616 setup the execution environment accordingly.
2617 Remote sudoedit functionality must be handled by the policy plugin, not
2619 sudo itself as the front-end has no knowledge that a remote command is
2620 being executed. This may be addressed in a future revision of the plugin
2621 API.
2622 Conversation API
2624 If the plugin needs to interact with the user, it may do so via the
2625 conversation() function. A plugin should not attempt to read directly
2626 from the standard input or the user's terminal (neither of which are
2627 guaranteed to exist). The caller must include a trailing newline in msg
2628 if one is to be printed.
2629 A printf()-style function is also available that can be used to display
2631 informational or error messages to the user, which is usually more conve‐
2632 nient for simple messages where no use input is required.
2633 Conversation function structures
2635 The conversation function takes as arguments pointers to the following
2637 structures:
2638 struct sudo_conv_message {
2640 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2641 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2642 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2643 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2644 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2645 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2646 #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */
2647 int msg_type;
2648 int timeout;
2649 const char *msg;
2650 };
2651 #define SUDO_CONV_REPL_MAX 1023
2653 struct sudo_conv_reply {
2655 char *reply;
2656 };
2657 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
2659 struct sudo_conv_callback {
2660 unsigned int version;
2661 void *closure;
2662 sudo_conv_callback_fn_t on_suspend;
2663 sudo_conv_callback_fn_t on_resume;
2664 };
2665 Pointers to the conversation() and printf()-style functions are passed in
2667 to the plugin's open() function when the plugin is initialized. The fol‐
2668 lowing type definitions can be used in the declaration of the open()
2669 function:
2670 typedef int (*sudo_conv_t)(int num_msgs,
2672 const struct sudo_conv_message msgs[],
2673 struct sudo_conv_reply replies[], struct sudo_conv_callback *callback);
2674 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2676 To use the conversation() function, the plugin must pass an array of
2678 struct sudo_conv_message and struct sudo_conv_reply. There must be a
2679 struct sudo_conv_message and struct sudo_conv_reply for each message in
2680 the conversation, that is, both arrays must have the same number of ele‐
2681 ments. Each struct sudo_conv_reply must have its reply member initial‐
2682 ized to NULL. The struct sudo_conv_callback pointer, if not NULL, should
2683 contain function pointers to be called when the sudo process is suspended
2684 and/or resumed during conversation input. The on_suspend and on_resume
2685 functions are called with the signal that caused sudo to be suspended and
2686 the closure pointer from the struct sudo_conv_callback. These functions
2687 should return 0 on success and -1 on error. On error, the conversation
2688 will end and the conversation function will return a value of -1. The
2689 intended use is to allow the plugin to release resources, such as locks,
2690 that should not be held indefinitely while suspended and then reacquire
2691 them when the process is resumed. The functions are not actually invoked
2692 from within a signal handler.
2693 The msg_type must be set to one of the following values:
2695 SUDO_CONV_PROMPT_ECHO_OFF
2697 Prompt the user for input with echo disabled; this is generally
2698 used for passwords. The reply will be stored in the replies array,
2699 and it will never be NULL.
2700 SUDO_CONV_PROMPT_ECHO_ON
2702 Prompt the user for input with echo enabled. The reply will be
2703 stored in the replies array, and it will never be NULL.
2704 SUDO_CONV_ERROR_MSG
2706 Display an error message. The message is written to the standard
2707 error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
2708 is written to the user's terminal if possible.
2709 SUDO_CONV_INFO_MSG
2711 Display a message. The message is written to the standard output
2712 unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
2713 written to the user's terminal if possible.
2714 SUDO_CONV_PROMPT_MASK
2716 Prompt the user for input but echo an asterisk character for each
2717 character read. The reply will be stored in the replies array, and
2718 it will never be NULL. This can be used to provide visual feedback
2719 to the user while reading sensitive information that should not be
2720 displayed.
2721 In addition to the above values, the following flag bits may also be set:
2723 SUDO_CONV_PROMPT_ECHO_OK
2725 Allow input to be read when echo cannot be disabled when the mes‐
2726 sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
2727 By default, sudo will refuse to read input if the echo cannot be
2728 disabled for those message types.
2729 SUDO_CONV_PREFER_TTY
2731 When displaying a message via SUDO_CONV_ERROR_MSG or
2732 SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
2733 nal. If the terminal is unavailable, the standard error or stan‐
2734 dard output will be used, depending upon whether
2735 SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used. The user's
2736 terminal is always used when possible for input, this flag is only
2737 used for output.
2738 The timeout in seconds until the prompt will wait for no more input. A
2740 zero value implies an infinite timeout.
2741 The plugin is responsible for freeing the reply buffer located in each
2743 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
2744 the maximum length of the reply buffer (not including the trailing NUL
2745 character). In practical terms, this is the longest password sudo will
2746 support.
2747 The printf()-style function uses the same underlying mechanism as the
2749 conversation() function but only supports SUDO_CONV_INFO_MSG and
2750 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
2751 nient than using the conversation() function if no user reply is needed
2752 and supports standard printf() escape sequences.
2753 See the sample plugin for an example of the conversation() function us‐
2755 age.
2756 Plugin invocation order
2758 As of sudo 1.9.0, the plugin open() and close() functions are called in
2759 the following order:
2760 1. audit open
2762 2. policy open
2764 3. approval open
2766 4. approval close
2768 5. I/O log open
2770 6. command runs
2772 7. command exits
2774 8. I/O log close
2776 9. policy close
2778 10. audit close
2780 11. sudo exits
2782 Prior to sudo 1.9.0, the I/O log close() function was called after the
2784 policy close() function.
2785 Sudoers group plugin API
2787 The sudoers plugin supports its own plugin interface to allow non-Unix
2788 group lookups. This can be used to query a group source other than the
2789 standard Unix group database. Two sample group plugins are bundled with
2790 sudo, group_file, and system_group, are detailed in sudoers(5). Third
2791 party group plugins include a QAS AD plugin available from Quest Soft‐
2792 ware.
2793 A group plugin must declare and populate a struct sudoers_group_plugin in
2795 the global scope. This structure contains pointers to the functions that
2796 implement plugin initialization, cleanup, and group lookup.
2797 struct sudoers_group_plugin {
2799 unsigned int version;
2800 int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2801 char *const argv[]);
2802 void (*cleanup)(void);
2803 int (*query)(const char *user, const char *group,
2804 const struct passwd *pwd);
2805 };
2806 A struct sudoers_group_plugin has the following fields:
2808 version
2810 The version field should be set to GROUP_API_VERSION.
2811 This allows sudoers to determine the API version the group plugin
2813 was built against.
2814 init
2816 int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2817 char *const argv[]);
2818 The init() function is called after sudoers has been parsed but be‐
2820 fore any policy checks. It returns 1 on success, 0 on failure (or
2821 if the plugin is not configured), and -1 if a error occurred. If
2822 an error occurs, the plugin may call the plugin_printf() function
2823 with SUDO_CONF_ERROR_MSG to present additional error information to
2824 the user.
2825 The function arguments are as follows:
2827 version
2829 The version passed in by sudoers allows the plugin to deter‐
2830 mine the major and minor version number of the group plugin
2831 API supported by sudoers.
2832 plugin_printf
2834 A pointer to a printf()-style function that may be used to
2835 display informational or error message to the user. Returns
2836 the number of characters printed on success and -1 on fail‐
2837 ure.
2838 argv A NULL-terminated array of arguments generated from the
2840 group_plugin option in sudoers. If no arguments were given,
2841 argv will be NULL.
2842 cleanup
2844 void (*cleanup)();
2845 The cleanup() function is called when sudoers has finished its
2847 group checks. The plugin should free any memory it has allocated
2848 and close open file handles.
2849 query
2851 int (*query)(const char *user, const char *group,
2852 const struct passwd *pwd);
2853 The query() function is used to ask the group plugin whether user
2855 is a member of group.
2856 The function arguments are as follows:
2858 user The name of the user being looked up in the external group
2860 database.
2861 group
2863 The name of the group being queried.
2864 pwd The password database entry for user, if any. If user is not
2866 present in the password database, pwd will be NULL.
2867 Group API Version Macros
2869 /* Sudoers group plugin version major/minor */
2871 #define GROUP_API_VERSION_MAJOR 1
2872 #define GROUP_API_VERSION_MINOR 0
2873 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
2874 GROUP_API_VERSION_MINOR)
2875 For getters and setters see the Policy plugin API.
2876
2878 The following revisions have been made to the Sudo Plugin API.
2879 Version 1.0
2881 Initial API version.
2882 Version 1.1 (sudo 1.8.0)
2884 The I/O logging plugin's open() function was modified to take the
2885 command_info list as an argument.
2886 Version 1.2 (sudo 1.8.5)
2888 The Policy and I/O logging plugins' open() functions are now passed
2889 a list of plugin parameters if any are specified in sudo.conf(5).
2890 A simple hooks API has been introduced to allow plugins to hook in
2892 to the system's environment handling functions.
2893 The init_session() Policy plugin function is now passed a pointer
2895 to the user environment which can be updated as needed. This can
2896 be used to merge in environment variables stored in the PAM handle
2897 before a command is run.
2898 Version 1.3 (sudo 1.8.7)
2900 Support for the exec_background entry has been added to the
2901 command_info list.
2902 The max_groups and plugin_dir entries were added to the settings
2904 list.
2905 The version() and close() functions are now optional. Previously,
2907 a missing version() or close() function would result in a crash.
2908 If no policy plugin close() function is defined, a default close()
2909 function will be provided by the sudo front-end that displays a
2910 warning if the command could not be executed.
2911 The sudo front-end now installs default signal handlers to trap
2913 common signals while the plugin functions are run.
2914 Version 1.4 (sudo 1.8.8)
2916 The remote_host entry was added to the settings list.
2917 Version 1.5 (sudo 1.8.9)
2919 The preserve_fds entry was added to the command_info list.
2920 Version 1.6 (sudo 1.8.11)
2922 The behavior when an I/O logging plugin returns an error (-1) has
2923 changed. Previously, the sudo front-end took no action when the
2924 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
2925 log_stderr() function returned an error.
2926 The behavior when an I/O logging plugin returns 0 has changed.
2928 Previously, output from the command would be displayed to the ter‐
2929 minal even if an output logging function returned 0.
2930 Version 1.7 (sudo 1.8.12)
2932 The plugin_path entry was added to the settings list.
2933 The debug_flags entry now starts with a debug file path name and
2935 may occur multiple times if there are multiple plugin-specific De‐
2936 bug lines in the sudo.conf(5) file.
2937 Version 1.8 (sudo 1.8.15)
2939 The sudoedit_checkdir and sudoedit_follow entries were added to the
2940 command_info list. The default value of sudoedit_checkdir was
2941 changed to true in sudo 1.8.16.
2942 The sudo conversation() function now takes a pointer to a struct
2944 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
2945 tion has been updated to match. The plugin must specify that it
2946 supports plugin API version 1.8 or higher to receive a conversation
2947 function pointer that supports this argument.
2948 Version 1.9 (sudo 1.8.16)
2950 The execfd entry was added to the command_info list.
2951 Version 1.10 (sudo 1.8.19)
2953 The umask entry was added to the user_info list. The iolog_group,
2954 iolog_mode, and iolog_user entries were added to the command_info
2955 list.
2956 Version 1.11 (sudo 1.8.20)
2958 The timeout entry was added to the settings list.
2959 Version 1.12 (sudo 1.8.21)
2961 The change_winsize() function was added to struct io_plugin.
2962 Version 1.13 (sudo 1.8.26)
2964 The log_suspend() function was added to struct io_plugin.
2965 Version 1.14 (sudo 1.8.29)
2967 The umask_override entry was added to the command_info list.
2968 Version 1.15 (sudo 1.9.0)
2970 The cwd_optional entry was added to the command_info list.
2971 The event_alloc() function was added to struct policy_plugin and
2973 struct io_plugin.
2974 The errstr argument was added to the policy and I/O plugin func‐
2976 tions which the plugin function can use to return an error string.
2977 This string may be used by the audit plugin to report failure or
2978 error conditions set by the other plugins.
2979 The close() function is now is called regardless of whether or not
2981 a command was actually executed. This makes it possible for plug‐
2982 ins to perform cleanup even when a command was not run.
2983 SUDO_CONV_REPL_MAX has increased from 255 to 1023 bytes.
2985 Support for audit and approval plugins was added.
2987 Version 1.16 (sudo 1.9.3)
2989 Initial resource limit values were added to the user_info list.
2990 The cmnd_chroot and cmnd_cwd entries were added to the settings
2992 list.
2993 Version 1.17 (sudo 1.9.4)
2995 The event_alloc() function was added to struct audit_plugin and
2996 struct approval_plugin.
2997 Version 1.18 (sudo 1.9.9)
2999 The policy may now set resource limit values in the command_info
3000 list. The intercept and log_subcmds entries were added to the
3001 command_info list.
3002 Version 1.19 (sudo 1.9.11)
3004 The intercept_ptrace and intercept_setid entries were added to the
3005 settings list. The apparmor_profile and use_ptrace entries were
3006 added to the command_info list.
3007 Version 1.20 (sudo 1.9.12)
3009 The update_ticket entry was added to the settings list. The
3010 intercept_verify entry was added to the command_info list.
3011 Version 1.21 (sudo 1.9.13)
3013 The sudoedit_nfiles entry was added to the command_info list.
3014
3016 sudo.conf(5), sudoers(5), sudo(8)
3017
3019 Many people have worked on sudo over the years; this version consists of
3020 code written primarily by:
3021 Todd C. Miller
3023 See the CONTRIBUTORS.md file in the sudo distribution
3025 (https://www.sudo.ws/about/contributors/) for an exhaustive list of peo‐
3026 ple who have contributed to sudo.
3027
3029 If you believe you have found a bug in sudo, you can submit a bug report
3030 at https://bugzilla.sudo.ws/
3031
3033 Limited free support is available via the sudo-users mailing list, see
3034 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
3035 the archives.
3036
3038 sudo is provided “AS IS” and any express or implied warranties, includ‐
3039 ing, but not limited to, the implied warranties of merchantability and
3040 fitness for a particular purpose are disclaimed. See the LICENSE.md file
3041 distributed with sudo or https://www.sudo.ws/about/license/ for complete
3042 details.
3043Sudo 1.9.13p2 January 18, 2023 Sudo 1.9.13p2