1SUDO_PLUGIN(5) BSD File Formats Manual SUDO_PLUGIN(5)
2
4 sudo_plugin — Sudo Plugin API
5
7 Starting with version 1.8, sudo supports a plugin API for policy and ses‐
8 sion logging. Plugins may be compiled as dynamic shared objects (the
9 default on systems that support them) or compiled statically into the
10 sudo binary itself. By default, the sudoers policy plugin and an associ‐
11 ated I/O logging plugin are used. Via the plugin API, sudo can be con‐
12 figured to use alternate policy and/or I/O logging plugins provided by
13 third parties. The plugins to be used are specified in the sudo.conf(5)
14 file.
15 The API is versioned with a major and minor number. The minor version
17 number is incremented when additions are made. The major number is
18 incremented when incompatible changes are made. A plugin should be check
19 the version passed to it and make sure that the major version matches.
20 The plugin API is defined by the sudo_plugin.h header file.
22 Policy plugin API
24 A policy plugin must declare and populate a policy_plugin struct in the
25 global scope. This structure contains pointers to the functions that
26 implement the sudo policy checks. The name of the symbol should be spec‐
27 ified in sudo.conf(5) along with a path to the plugin so that sudo can
28 load it.
29 struct policy_plugin {
31 #define SUDO_POLICY_PLUGIN 1
32 unsigned int type; /* always SUDO_POLICY_PLUGIN */
33 unsigned int version; /* always SUDO_API_VERSION */
34 int (*open)(unsigned int version, sudo_conv_t conversation,
35 sudo_printf_t plugin_printf, char * const settings[],
36 char * const user_info[], char * const user_env[],
37 char * const plugin_options[]);
38 void (*close)(int exit_status, int error);
39 int (*show_version)(int verbose);
40 int (*check_policy)(int argc, char * const argv[],
41 char *env_add[], char **command_info[],
42 char **argv_out[], char **user_env_out[]);
43 int (*list)(int argc, char * const argv[], int verbose,
44 const char *list_user);
45 int (*validate)(void);
46 void (*invalidate)(int remove);
47 int (*init_session)(struct passwd *pwd, char **user_env[]);
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 };
53 The policy_plugin struct has the following fields:
55 type The type field should always be set to SUDO_POLICY_PLUGIN.
57 version
59 The version field should be set to SUDO_API_VERSION.
60 This allows sudo to determine the API version the plugin was built
62 against.
63 open
65 int (*open)(unsigned int version, sudo_conv_t conversation,
66 sudo_printf_t plugin_printf, char * const settings[],
67 char * const user_info[], char * const user_env[],
68 char * const plugin_options[]);
69 Returns 1 on success, 0 on failure, -1 if a general error occurred,
71 or -2 if there was a usage error. In the latter case, sudo will
72 print a usage message before it exits. If an error occurs, the
73 plugin may optionally call the conversation() or plugin_printf()
74 function with SUDO_CONF_ERROR_MSG to present additional error
75 information to the user.
76 The function arguments are as follows:
78 version
80 The version passed in by sudo allows the plugin to determine
81 the major and minor version number of the plugin API sup‐
82 ported by sudo.
83 conversation
85 A pointer to the conversation() function that can be used by
86 the plugin to interact with the user (see below). Returns 0
87 on success and -1 on failure.
88 plugin_printf
90 A pointer to a printf()-style function that may be used to
91 display informational or error messages (see below). Returns
92 the number of characters printed on success and -1 on fail‐
93 ure.
94 settings
96 A vector of user-supplied sudo settings in the form of
97 “name=value” strings. The vector is terminated by a NULL
98 pointer. These settings correspond to options the user spec‐
99 ified when running sudo. As such, they will only be present
100 when the corresponding option has been specified on the com‐
101 mand line.
102 When parsing settings, the plugin should split on the first
104 equal sign (‘=’) since the name field will never include one
105 itself but the value might.
106 bsdauth_type=string
108 Authentication type, if specified by the -a option, to
109 use on systems where BSD authentication is supported.
110 closefrom=number
112 If specified, the user has requested via the -C option
113 that sudo close all files descriptors with a value of
114 number or higher. The plugin may optionally pass this,
115 or another value, back in the command_info list.
116 debug_flags=string
118 A debug file path name followed by a space and a comma-
119 separated list of debug flags that correspond to the
120 plugin's Debug entry in sudo.conf(5), if there is one.
121 The flags are passed to the plugin exactly as they
122 appear in sudo.conf(5). The syntax used by sudo and
123 the sudoers plugin is subsystem@priority but a plugin
124 is free to use a different format so long as it does
125 not include a comma (‘,’). Prior to sudo 1.8.12, there
126 was no way to specify plugin-specific debug_flags so
127 the value was always the same as that used by the sudo
128 front end and did not include a path name, only the
129 flags themselves. As of version 1.7 of the plugin
130 interface, sudo will only pass debug_flags if
131 sudo.conf(5) contains a plugin-specific Debug entry.
132 debug_level=number
134 This setting has been deprecated in favor of
135 debug_flags.
136 ignore_ticket=bool
138 Set to true if the user specified the -k option along
139 with a command, indicating that the user wishes to
140 ignore any cached authentication credentials.
141 implied_shell to true. This allows sudo with no argu‐
142 ments to be used similarly to su(1). If the plugin
143 does not to support this usage, it may return a value
144 of -2 from the check_policy() function, which will
145 cause sudo to print a usage message and exit.
146 implied_shell=bool
148 If the user does not specify a program on the command
149 line, sudo will pass the plugin the path to the user's
150 shell and set
151 login_class=string
153 BSD login class to use when setting resource limits and
154 nice value, if specified by the -c option.
155 login_shell=bool
157 Set to true if the user specified the -i option, indi‐
158 cating that the user wishes to run a login shell.
159 max_groups=int
161 The maximum number of groups a user may belong to.
162 This will only be present if there is a corresponding
163 setting in sudo.conf(5).
164 network_addrs=list
166 A space-separated list of IP network addresses and net‐
167 masks in the form “addr/netmask”, e.g.,
168 “192.168.1.2/255.255.255.0”. The address and netmask
169 pairs may be either IPv4 or IPv6, depending on what the
170 operating system supports. If the address contains a
171 colon (‘:’), it is an IPv6 address, else it is IPv4.
172 noninteractive=bool
174 Set to true if the user specified the -n option, indi‐
175 cating that sudo should operate in non-interactive
176 mode. The plugin may reject a command run in non-
177 interactive mode if user interaction is required.
178 plugin_dir=string
180 The default plugin directory used by the sudo front
181 end. This is the default directory set at compile time
182 and may not correspond to the directory the running
183 plugin was loaded from. It may be used by a plugin to
184 locate support files.
185 plugin_path=string
187 The path name of plugin loaded by the sudo front end.
188 The path name will be a fully-qualified unless the
189 plugin was statically compiled into sudo.
190 preserve_environment=bool
192 Set to true if the user specified the -E option, indi‐
193 cating that the user wishes to preserve the environ‐
194 ment.
195 preserve_groups=bool
197 Set to true if the user specified the -P option, indi‐
198 cating that the user wishes to preserve the group vec‐
199 tor instead of setting it based on the runas user.
200 progname=string
202 The command name that sudo was run as, typically “sudo”
203 or “sudoedit”.
204 prompt=string
206 The prompt to use when requesting a password, if speci‐
207 fied via the -p option.
208 remote_host=string
210 The name of the remote host to run the command on, if
211 specified via the -h option. Support for running the
212 command on a remote host is meant to be implemented via
213 a helper program that is executed in place of the user-
214 specified command. The sudo front end is only capable
215 of executing commands on the local host. Only avail‐
216 able starting with API version 1.4.
217 run_shell=bool
219 Set to true if the user specified the -s option, indi‐
220 cating that the user wishes to run a shell.
221 runas_group=string
223 The group name or gid to run the command as, if speci‐
224 fied via the -g option.
225 runas_user=string
227 The user name or uid to run the command as, if speci‐
228 fied via the -u option.
229 selinux_role=string
231 SELinux role to use when executing the command, if
232 specified by the -r option.
233 selinux_type=string
235 SELinux type to use when executing the command, if
236 specified by the -t option.
237 set_home=bool
239 Set to true if the user specified the -H option. If
240 true, set the HOME environment variable to the target
241 user's home directory.
242 sudoedit=bool
244 Set to true when the -e option is specified or if
245 invoked as sudoedit. The plugin shall substitute an
246 editor into argv in the check_policy() function or
247 return -2 with a usage error if the plugin does not
248 support sudoedit. For more information, see the
249 check_policy section.
250 timeout=string
252 User-specified command timeout. Not all plugins sup‐
253 port command timeouts and the ability for the user to
254 set a timeout may be restricted by policy. The format
255 of the timeout string is plugin-specific.
256 Additional settings may be added in the future so the plugin
258 should silently ignore settings that it does not recognize.
259 user_info
261 A vector of information about the user running the command in
262 the form of “name=value” strings. The vector is terminated
263 by a NULL pointer.
264 When parsing user_info, the plugin should split on the first
266 equal sign (‘=’) since the name field will never include one
267 itself but the value might.
268 cols=int
270 The number of columns the user's terminal supports. If
271 there is no terminal device available, a default value
272 of 80 is used.
273 cwd=string
275 The user's current working directory.
276 egid=gid_t
278 The effective group-ID of the user invoking sudo.
279 euid=uid_t
281 The effective user-ID of the user invoking sudo.
282 gid=gid_t
284 The real group-ID of the user invoking sudo.
285 groups=list
287 The user's supplementary group list formatted as a
288 string of comma-separated group-IDs.
289 host=string
291 The local machine's hostname as returned by the
292 gethostname(2) system call.
293 lines=int
295 The number of lines the user's terminal supports. If
296 there is no terminal device available, a default value
297 of 24 is used.
298 pgid=int
300 The ID of the process group that the running sudo
301 process is a member of. Only available starting with
302 API version 1.2.
303 pid=int
305 The process ID of the running sudo process. Only
306 available starting with API version 1.2.
307 plugin_options
309 Any (non-comment) strings immediately after the plugin
310 path are passed as arguments to the plugin. These
311 arguments are split on a white space boundary and are
312 passed to the plugin in the form of a NULL-terminated
313 array of strings. If no arguments were specified,
314 plugin_options will be the NULL pointer.
315 NOTE: the plugin_options parameter is only available
317 starting with API version 1.2. A plugin must check the
318 API version specified by the sudo front end before
319 using plugin_options. Failure to do so may result in a
320 crash.
321 ppid=int
323 The parent process ID of the running sudo process.
324 Only available starting with API version 1.2.
325 sid=int
327 The session ID of the running sudo process or 0 if sudo
328 is not part of a POSIX job control session. Only
329 available starting with API version 1.2.
330 tcpgid=int
332 The ID of the foreground process group associated with
333 the terminal device associated with the sudo process or
334 -1 if there is no terminal present. Only available
335 starting with API version 1.2.
336 tty=string
338 The path to the user's terminal device. If the user
339 has no terminal device associated with the session, the
340 value will be empty, as in “tty=”.
341 uid=uid_t
343 The real user-ID of the user invoking sudo.
344 umask=octal
346 The invoking user's file creation mask. Only available
347 starting with API version 1.10.
348 user=string
350 The name of the user invoking sudo.
351 user_env
353 The user's environment in the form of a NULL-terminated
354 vector of “name=value” strings.
355 When parsing user_env, the plugin should split on the first
357 equal sign (‘=’) since the name field will never include one
358 itself but the value might.
359 close
361 void (*close)(int exit_status, int error);
362 The close() function is called when the command being run by sudo
364 finishes.
365 The function arguments are as follows:
367 exit_status
369 The command's exit status, as returned by the wait(2) system
370 call. The value of exit_status is undefined if error is non-
371 zero.
372 error
374 If the command could not be executed, this is set to the
375 value of errno set by the execve(2) system call. The plugin
376 is responsible for displaying error information via the
377 conversation() or plugin_printf() function. If the command
378 was successfully executed, the value of error is 0.
379 If no close() function is defined, no I/O logging plugins are
381 loaded, and neither the timeout not use_pty options are set in the
382 command_info list, the sudo front end may execute the command
383 directly instead of running it as a child process.
384 show_version
386 int (*show_version)(int verbose);
387 The show_version() function is called by sudo when the user speci‐
389 fies the -V option. The plugin may display its version information
390 to the user via the conversation() or plugin_printf() function
391 using SUDO_CONV_INFO_MSG. If the user requests detailed version
392 information, the verbose flag will be set.
393 Returns 1 on success, 0 on failure, -1 if a general error occurred,
395 or -2 if there was a usage error, although the return value is cur‐
396 rently ignored.
397 check_policy
399 int (*check_policy)(int argc, char * const argv[],
400 char *env_add[], char **command_info[],
401 char **argv_out[], char **user_env_out[]);
402 The check_policy() function is called by sudo to determine whether
404 the user is allowed to run the specified commands.
405 If the sudoedit option was enabled in the settings array passed to
407 the open() function, the user has requested sudoedit mode.
408 sudoedit is a mechanism for editing one or more files where an edi‐
409 tor is run with the user's credentials instead of with elevated
410 privileges. sudo achieves this by creating user-writable temporary
411 copies of the files to be edited and then overwriting the originals
412 with the temporary copies after editing is complete. If the plugin
413 supports sudoedit, it should choose the editor to be used, poten‐
414 tially from a variable in the user's environment, such as EDITOR,
415 and include it in argv_out (note that environment variables may
416 include command line options). The files to be edited should be
417 copied from argv into argv_out, separated from the editor and its
418 arguments by a “--” element. The “--” will be removed by sudo
419 before the editor is executed. The plugin should also set
420 sudoedit=true in the command_info list.
421 The check_policy() function returns 1 if the command is allowed, 0
423 if not allowed, -1 for a general error, or -2 for a usage error or
424 if sudoedit was specified but is unsupported by the plugin. In the
425 latter case, sudo will print a usage message before it exits. If
426 an error occurs, the plugin may optionally call the conversation()
427 or plugin_printf() function with SUDO_CONF_ERROR_MSG to present
428 additional error information to the user.
429 The function arguments are as follows:
431 argc The number of elements in argv, not counting the final NULL
433 pointer.
434 argv The argument vector describing the command the user wishes to
436 run, in the same form as what would be passed to the
437 execve(2) system call. The vector is terminated by a NULL
438 pointer.
439 env_add
441 Additional environment variables specified by the user on the
442 command line in the form of a NULL-terminated vector of
443 “name=value” strings. The plugin may reject the command if
444 one or more variables are not allowed to be set, or it may
445 silently ignore such variables.
446 When parsing env_add, the plugin should split on the first
448 equal sign (‘=’) since the name field will never include one
449 itself but the value might.
450 command_info
452 Information about the command being run in the form of
453 “name=value” strings. These values are used by sudo to set
454 the execution environment when running a command. The plugin
455 is responsible for creating and populating the vector, which
456 must be terminated with a NULL pointer. The following values
457 are recognized by sudo:
458 chroot=string
460 The root directory to use when running the command.
461 closefrom=number
463 If specified, sudo will close all files descriptors
464 with a value of number or higher.
465 command=string
467 Fully qualified path to the command to be executed.
468 cwd=string
470 The current working directory to change to when execut‐
471 ing the command.
472 exec_background=bool
474 By default, sudo runs a command as the foreground
475 process as long as sudo itself is running in the fore‐
476 ground. When exec_background is enabled and the com‐
477 mand is being run in a pseudo-terminal (due to I/O log‐
478 ging or the use_pty setting), the command will be run
479 as a background process. Attempts to read from the
480 controlling terminal (or to change terminal settings)
481 will result in the command being suspended with the
482 SIGTTIN signal (or SIGTTOU in the case of terminal set‐
483 tings). If this happens when sudo is a foreground
484 process, the command will be granted the controlling
485 terminal and resumed in the foreground with no user
486 intervention required. The advantage of initially run‐
487 ning the command in the background is that sudo need
488 not read from the terminal unless the command explic‐
489 itly requests it. Otherwise, any terminal input must
490 be passed to the command, whether it has required it or
491 not (the kernel buffers terminals so it is not possible
492 to tell whether the command really wants the input).
493 This is different from historic sudo behavior or when
494 the command is not being run in a pseudo-terminal.
495 For this to work seamlessly, the operating system must
497 support the automatic restarting of system calls.
498 Unfortunately, not all operating systems do this by
499 default, and even those that do may have bugs. For
500 example, macOS fails to restart the tcgetattr() and
501 tcsetattr() system calls (this is a bug in macOS).
502 Furthermore, because this behavior depends on the com‐
503 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
504 grams that catch these signals and suspend themselves
505 with a different signal (usually SIGTOP) will not be
506 automatically foregrounded. Some versions of the linux
507 su(1) command behave this way. Because of this, a
508 plugin should not set exec_background unless it is
509 explicitly enabled by the administrator and there
510 should be a way to enabled or disable it on a per-com‐
511 mand basis.
512 This setting has no effect unless I/O logging is
514 enabled or use_pty is enabled.
515 execfd=number
517 If specified, sudo will use the fexecve(2) system call
518 to execute the command instead of execve(2). The spec‐
519 ified number must refer to an open file descriptor.
520 iolog_compress=bool
522 Set to true if the I/O logging plugins, if any, should
523 compress the log data. This is a hint to the I/O log‐
524 ging plugin which may choose to ignore it.
525 iolog_group=string
527 The group that will own newly created I/O log files and
528 directories. This is a hint to the I/O logging plugin
529 which may choose to ignore it.
530 iolog_mode=octal
532 The file permission mode to use when creating I/O log
533 files and directories. This is a hint to the I/O log‐
534 ging plugin which may choose to ignore it.
535 iolog_user=string
537 The user that will own newly created I/O log files and
538 directories. This is a hint to the I/O logging plugin
539 which may choose to ignore it.
540 iolog_path=string
542 Fully qualified path to the file or directory in which
543 I/O log is to be stored. This is a hint to the I/O
544 logging plugin which may choose to ignore it. If no
545 I/O logging plugin is loaded, this setting has no
546 effect.
547 iolog_stdin=bool
549 Set to true if the I/O logging plugins, if any, should
550 log the standard input if it is not connected to a ter‐
551 minal device. This is a hint to the I/O logging plugin
552 which may choose to ignore it.
553 iolog_stdout=bool
555 Set to true if the I/O logging plugins, if any, should
556 log the standard output if it is not connected to a
557 terminal device. This is a hint to the I/O logging
558 plugin which may choose to ignore it.
559 iolog_stderr=bool
561 Set to true if the I/O logging plugins, if any, should
562 log the standard error if it is not connected to a ter‐
563 minal device. This is a hint to the I/O logging plugin
564 which may choose to ignore it.
565 iolog_ttyin=bool
567 Set to true if the I/O logging plugins, if any, should
568 log all terminal input. This only includes input typed
569 by the user and not from a pipe or redirected from a
570 file. This is a hint to the I/O logging plugin which
571 may choose to ignore it.
572 iolog_ttyout=bool
574 Set to true if the I/O logging plugins, if any, should
575 log all terminal output. This only includes output to
576 the screen, not output to a pipe or file. This is a
577 hint to the I/O logging plugin which may choose to
578 ignore it.
579 login_class=string
581 BSD login class to use when setting resource limits and
582 nice value (optional). This option is only set on sys‐
583 tems that support login classes.
584 nice=int
586 Nice value (priority) to use when executing the com‐
587 mand. The nice value, if specified, overrides the pri‐
588 ority associated with the login_class on BSD systems.
589 noexec=bool
591 If set, prevent the command from executing other pro‐
592 grams.
593 preserve_fds=list
595 A comma-separated list of file descriptors that should
596 be preserved, regardless of the value of the closefrom
597 setting. Only available starting with API version 1.5.
598 preserve_groups=bool
600 If set, sudo will preserve the user's group vector
601 instead of initializing the group vector based on
602 runas_user.
603 runas_egid=gid
605 Effective group-ID to run the command as. If not spec‐
606 ified, the value of runas_gid is used.
607 runas_euid=uid
609 Effective user-ID to run the command as. If not speci‐
610 fied, the value of runas_uid is used.
611 runas_gid=gid
613 Group-ID to run the command as.
614 runas_groups=list
616 The supplementary group vector to use for the command
617 in the form of a comma-separated list of group-IDs. If
618 preserve_groups is set, this option is ignored.
619 runas_uid=uid
621 User-ID to run the command as.
622 selinux_role=string
624 SELinux role to use when executing the command.
625 selinux_type=string
627 SELinux type to use when executing the command.
628 set_utmp=bool
630 Create a utmp (or utmpx) entry when a pseudo-terminal
631 is allocated. By default, the new entry will be a copy
632 of the user's existing utmp entry (if any), with the
633 tty, time, type and pid fields updated.
634 sudoedit=bool
636 Set to true when in sudoedit mode. The plugin may
637 enable sudoedit mode even if sudo was not invoked as
638 sudoedit. This allows the plugin to perform command
639 substitution and transparently enable sudoedit when the
640 user attempts to run an editor.
641 sudoedit_checkdir=bool
643 Set to false to disable directory writability checks in
644 sudoedit. By default, sudoedit 1.8.16 and higher will
645 check all directory components of the path to be edited
646 for writability by the invoking user. Symbolic links
647 will not be followed in writable directories and
648 sudoedit will refuse to edit a file located in a
649 writable directory. These restrictions are not
650 enforced when sudoedit is run by root. The
651 sudoedit_follow option can be set to false to disable
652 this check. Only available starting with API version
653 1.8.
654 sudoedit_follow=bool
656 Set to true to allow sudoedit to edit files that are
657 symbolic links. By default, sudoedit 1.8.15 and higher
658 will refuse to open a symbolic link. The
659 sudoedit_follow option can be used to restore the older
660 behavior and allow sudoedit to open symbolic links.
661 Only available starting with API version 1.8.
662 timeout=int
664 Command timeout. If non-zero then when the timeout
665 expires the command will be killed.
666 umask=octal
668 The file creation mask to use when executing the com‐
669 mand. This value may be overridden by PAM or
670 login.conf on some systems unless the umask_override
671 option is also set.
672 umask_override=bool
674 Force the value specified by the umask option to over‐
675 ride any umask set by PAM or login.conf.
676 use_pty=bool
678 Allocate a pseudo-terminal to run the command in,
679 regardless of whether or not I/O logging is in use. By
680 default, sudo will only run the command in a pseudo-
681 terminal when an I/O log plugin is loaded.
682 utmp_user=string
684 User name to use when constructing a new utmp (or
685 utmpx) entry when set_utmp is enabled. This option can
686 be used to set the user field in the utmp entry to the
687 user the command runs as rather than the invoking user.
688 If not set, sudo will base the new entry on the invok‐
689 ing user's existing entry.
690 Unsupported values will be ignored.
692 argv_out
694 The NULL-terminated argument vector to pass to the execve(2)
695 system call when executing the command. The plugin is
696 responsible for allocating and populating the vector.
697 user_env_out
699 The NULL-terminated environment vector to use when executing
700 the command. The plugin is responsible for allocating and
701 populating the vector.
702 list
704 int (*list)(int argc, char * const argv[],
705 int verbose, const char *list_user);
706 List available privileges for the invoking user. Returns 1 on suc‐
708 cess, 0 on failure and -1 on error. On error, the plugin may
709 optionally call the conversation() or plugin_printf() function with
710 SUDO_CONF_ERROR_MSG to present additional error information to the
711 user.
712 Privileges should be output via the conversation() or
714 plugin_printf() function using SUDO_CONV_INFO_MSG,
715 verbose
717 Flag indicating whether to list in verbose mode or not.
718 list_user
720 The name of a different user to list privileges for if the
721 policy allows it. If NULL, the plugin should list the privi‐
722 leges of the invoking user.
723 argc The number of elements in argv, not counting the final NULL
725 pointer.
726 argv If non-NULL, an argument vector describing a command the user
728 wishes to check against the policy in the same form as what
729 would be passed to the execve(2) system call. If the command
730 is permitted by the policy, the fully-qualified path to the
731 command should be displayed along with any command line argu‐
732 ments.
733 validate
735 int (*validate)(void);
736 The validate() function is called when sudo is run with the -v
738 option. For policy plugins such as sudoers that cache authentica‐
739 tion credentials, this function will validate and cache the creden‐
740 tials.
741 The validate() function should be NULL if the plugin does not sup‐
743 port credential caching.
744 Returns 1 on success, 0 on failure and -1 on error. On error, the
746 plugin may optionally call the conversation() or plugin_printf()
747 function with SUDO_CONF_ERROR_MSG to present additional error
748 information to the user.
749 invalidate
751 void (*invalidate)(int remove);
752 The invalidate() function is called when sudo is called with the -k
754 or -K option. For policy plugins such as sudoers that cache
755 authentication credentials, this function will invalidate the cre‐
756 dentials. If the remove flag is set, the plugin may remove the
757 credentials instead of simply invalidating them.
758 The invalidate() function should be NULL if the plugin does not
760 support credential caching.
761 init_session
763 int (*init_session)(struct passwd *pwd, char **user_envp[);
764 The init_session() function is called before sudo sets up the exe‐
766 cution environment for the command. It is run in the parent sudo
767 process and before any uid or gid changes. This can be used to
768 perform session setup that is not supported by command_info, such
769 as opening the PAM session. The close() function can be used to
770 tear down the session that was opened by init_session.
771 The pwd argument points to a passwd struct for the user the command
773 will be run as if the uid the command will run as was found in the
774 password database, otherwise it will be NULL.
775 The user_env argument points to the environment the command will
777 run in, in the form of a NULL-terminated vector of “name=value”
778 strings. This is the same string passed back to the front end via
779 the Policy Plugin's user_env_out parameter. If the init_session()
780 function needs to modify the user environment, it should update the
781 pointer stored in user_env. The expected use case is to merge the
782 contents of the PAM environment (if any) with the contents of
783 user_env. NOTE: the user_env parameter is only available starting
784 with API version 1.2. A plugin must check the API version speci‐
785 fied by the sudo front end before using user_env. Failure to do so
786 may result in a crash.
787 Returns 1 on success, 0 on failure and -1 on error. On error, the
789 plugin may optionally call the conversation() or plugin_printf()
790 function with SUDO_CONF_ERROR_MSG to present additional error
791 information to the user.
792 register_hooks
794 void (*register_hooks)(int version,
795 int (*register_hook)(struct sudo_hook *hook));
796 The register_hooks() function is called by the sudo front end to
798 register any hooks the plugin needs. If the plugin does not sup‐
799 port hooks, register_hooks should be set to the NULL pointer.
800 The version argument describes the version of the hooks API sup‐
802 ported by the sudo front end.
803 The register_hook() function should be used to register any sup‐
805 ported hooks the plugin needs. It returns 0 on success, 1 if the
806 hook type is not supported and -1 if the major version in struct
807 hook does not match the front end's major hook API version.
808 See the Hook function API section below for more information about
810 hooks.
811 NOTE: the register_hooks() function is only available starting with
813 API version 1.2. If the sudo front end doesn't support API version
814 1.2 or higher, register_hooks will not be called.
815 deregister_hooks
817 void (*deregister_hooks)(int version,
818 int (*deregister_hook)(struct sudo_hook *hook));
819 The deregister_hooks() function is called by the sudo front end to
821 deregister any hooks the plugin has registered. If the plugin does
822 not support hooks, deregister_hooks should be set to the NULL
823 pointer.
824 The version argument describes the version of the hooks API sup‐
826 ported by the sudo front end.
827 The deregister_hook() function should be used to deregister any
829 hooks that were put in place by the register_hook() function. If
830 the plugin tries to deregister a hook that the front end does not
831 support, deregister_hook will return an error.
832 See the Hook function API section below for more information about
834 hooks.
835 NOTE: the deregister_hooks() function is only available starting
837 with API version 1.2. If the sudo front end doesn't support API
838 version 1.2 or higher, deregister_hooks will not be called.
839 Policy Plugin Version Macros
841 /* Plugin API version major/minor. */
843 #define SUDO_API_VERSION_MAJOR 1
844 #define SUDO_API_VERSION_MINOR 13
845 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
846 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
847 SUDO_API_VERSION_MINOR)
848 /* Getters and setters for API version */
850 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
851 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
852 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
853 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
854 } while(0)
855 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
856 *(vp) = (*(vp) & 0xffff0000) | (n); \
857 } while(0)
858 I/O plugin API
860 struct io_plugin {
861 #define SUDO_IO_PLUGIN 2
862 unsigned int type; /* always SUDO_IO_PLUGIN */
863 unsigned int version; /* always SUDO_API_VERSION */
864 int (*open)(unsigned int version, sudo_conv_t conversation,
865 sudo_printf_t plugin_printf, char * const settings[],
866 char * const user_info[], char * const command_info[],
867 int argc, char * const argv[], char * const user_env[],
868 char * const plugin_options[]);
869 void (*close)(int exit_status, int error); /* wait status or error */
870 int (*show_version)(int verbose);
871 int (*log_ttyin)(const char *buf, unsigned int len);
872 int (*log_ttyout)(const char *buf, unsigned int len);
873 int (*log_stdin)(const char *buf, unsigned int len);
874 int (*log_stdout)(const char *buf, unsigned int len);
875 int (*log_stderr)(const char *buf, unsigned int len);
876 void (*register_hooks)(int version,
877 int (*register_hook)(struct sudo_hook *hook));
878 void (*deregister_hooks)(int version,
879 int (*deregister_hook)(struct sudo_hook *hook));
880 int (*change_winsize)(unsigned int lines, unsigned int cols);
881 int (*log_suspend)(int signo);
882 };
883 When an I/O plugin is loaded, sudo runs the command in a pseudo-terminal.
885 This makes it possible to log the input and output from the user's ses‐
886 sion. If any of the standard input, standard output or standard error do
887 not correspond to a tty, sudo will open a pipe to capture the I/O for
888 logging before passing it on.
889 The log_ttyin function receives the raw user input from the terminal
891 device (note that this will include input even when echo is disabled,
892 such as when a password is read). The log_ttyout function receives out‐
893 put from the pseudo-terminal that is suitable for replaying the user's
894 session at a later time. The log_stdin(), log_stdout() and log_stderr()
895 functions are only called if the standard input, standard output or stan‐
896 dard error respectively correspond to something other than a tty.
897 Any of the logging functions may be set to the NULL pointer if no logging
899 is to be performed. If the open function returns 0, no I/O will be sent
900 to the plugin.
901 If a logging function returns an error (-1), the running command will be
903 terminated and all of the plugin's logging functions will be disabled.
904 Other I/O logging plugins will still receive any remaining input or out‐
905 put that has not yet been processed.
906 If an input logging function rejects the data by returning 0, the command
908 will be terminated and the data will not be passed to the command, though
909 it will still be sent to any other I/O logging plugins. If an output
910 logging function rejects the data by returning 0, the command will be
911 terminated and the data will not be written to the terminal, though it
912 will still be sent to any other I/O logging plugins.
913 The io_plugin struct has the following fields:
915 type The type field should always be set to SUDO_IO_PLUGIN.
917 version
919 The version field should be set to SUDO_API_VERSION.
920 This allows sudo to determine the API version the plugin was built
922 against.
923 open
925 int (*open)(unsigned int version, sudo_conv_t conversation,
926 sudo_printf_t plugin_printf, char * const settings[],
927 char * const user_info[], char * const command_info[],
928 int argc, char * const argv[], char * const user_env[],
929 char * const plugin_options[]);
930 The open() function is run before the log_ttyin(), log_ttyout(),
932 log_stdin(), log_stdout(), log_stderr(), log_suspend(),
933 change_winsize(), or show_version() functions are called. It is
934 only called if the version is being requested or if the policy
935 plugin's check_policy() function has returned successfully. It
936 returns 1 on success, 0 on failure, -1 if a general error occurred,
937 or -2 if there was a usage error. In the latter case, sudo will
938 print a usage message before it exits. If an error occurs, the
939 plugin may optionally call the conversation() or plugin_printf()
940 function with SUDO_CONF_ERROR_MSG to present additional error
941 information to the user.
942 The function arguments are as follows:
944 version
946 The version passed in by sudo allows the plugin to determine
947 the major and minor version number of the plugin API sup‐
948 ported by sudo.
949 conversation
951 A pointer to the conversation() function that may be used by
952 the show_version() function to display version information
953 (see show_version() below). The conversation() function may
954 also be used to display additional error message to the user.
955 The conversation() function returns 0 on success and -1 on
956 failure.
957 plugin_printf
959 A pointer to a printf()-style function that may be used by
960 the show_version() function to display version information
961 (see show_version below). The plugin_printf() function may
962 also be used to display additional error message to the user.
963 The plugin_printf() function returns number of characters
964 printed on success and -1 on failure.
965 settings
967 A vector of user-supplied sudo settings in the form of
968 “name=value” strings. The vector is terminated by a NULL
969 pointer. These settings correspond to options the user spec‐
970 ified when running sudo. As such, they will only be present
971 when the corresponding option has been specified on the com‐
972 mand line.
973 When parsing settings, the plugin should split on the first
975 equal sign (‘=’) since the name field will never include one
976 itself but the value might.
977 See the Policy plugin API section for a list of all possible
979 settings.
980 user_info
982 A vector of information about the user running the command in
983 the form of “name=value” strings. The vector is terminated
984 by a NULL pointer.
985 When parsing user_info, the plugin should split on the first
987 equal sign (‘=’) since the name field will never include one
988 itself but the value might.
989 See the Policy plugin API section for a list of all possible
991 strings.
992 argc The number of elements in argv, not counting the final NULL
994 pointer. It can be zero, when sudo is called with -V.
995 argv If non-NULL, an argument vector describing a command the user
997 wishes to run in the same form as what would be passed to the
998 execve(2) system call.
999 user_env
1001 The user's environment in the form of a NULL-terminated vec‐
1002 tor of “name=value” strings.
1003 When parsing user_env, the plugin should split on the first
1005 equal sign (‘=’) since the name field will never include one
1006 itself but the value might.
1007 plugin_options
1009 Any (non-comment) strings immediately after the plugin path
1010 are treated as arguments to the plugin. These arguments are
1011 split on a white space boundary and are passed to the plugin
1012 in the form of a NULL-terminated array of strings. If no
1013 arguments were specified, plugin_options will be the NULL
1014 pointer.
1015 NOTE: the plugin_options parameter is only available starting
1017 with API version 1.2. A plugin must check the API version
1018 specified by the sudo front end before using plugin_options.
1019 Failure to do so may result in a crash.
1020 close
1022 void (*close)(int exit_status, int error);
1023 The close() function is called when the command being run by sudo
1025 finishes.
1026 The function arguments are as follows:
1028 exit_status
1030 The command's exit status, as returned by the wait(2) system
1031 call. The value of exit_status is undefined if error is non-
1032 zero.
1033 error
1035 If the command could not be executed, this is set to the
1036 value of errno set by the execve(2) system call. If the com‐
1037 mand was successfully executed, the value of error is 0.
1038 show_version
1040 int (*show_version)(int verbose);
1041 The show_version() function is called by sudo when the user speci‐
1043 fies the -V option. The plugin may display its version information
1044 to the user via the conversation() or plugin_printf() function
1045 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1046 information, the verbose flag will be set.
1047 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1049 or -2 if there was a usage error, although the return value is cur‐
1050 rently ignored.
1051 log_ttyin
1053 int (*log_ttyin)(const char *buf, unsigned int len);
1054 The log_ttyin() function is called whenever data can be read from
1056 the user but before it is passed to the running command. This
1057 allows the plugin to reject data if it chooses to (for instance if
1058 the input contains banned content). Returns 1 if the data should
1059 be passed to the command, 0 if the data is rejected (which will
1060 terminate the running command) or -1 if an error occurred.
1061 The function arguments are as follows:
1063 buf The buffer containing user input.
1065 len The length of buf in bytes.
1067 log_ttyout
1069 int (*log_ttyout)(const char *buf, unsigned int len);
1070 The log_ttyout() function is called whenever data can be read from
1072 the command but before it is written to the user's terminal. This
1073 allows the plugin to reject data if it chooses to (for instance if
1074 the output contains banned content). Returns 1 if the data should
1075 be passed to the user, 0 if the data is rejected (which will termi‐
1076 nate the running command) or -1 if an error occurred.
1077 The function arguments are as follows:
1079 buf The buffer containing command output.
1081 len The length of buf in bytes.
1083 log_stdin
1085 int (*log_stdin)(const char *buf, unsigned int len);
1086 The log_stdin() function is only used if the standard input does
1088 not correspond to a tty device. It is called whenever data can be
1089 read from the standard input but before it is passed to the running
1090 command. This allows the plugin to reject data if it chooses to
1091 (for instance if the input contains banned content). Returns 1 if
1092 the data should be passed to the command, 0 if the data is rejected
1093 (which will terminate the running command) or -1 if an error
1094 occurred.
1095 The function arguments are as follows:
1097 buf The buffer containing user input.
1099 len The length of buf in bytes.
1101 log_stdout
1103 int (*log_stdout)(const char *buf, unsigned int len);
1104 The log_stdout() function is only used if the standard output does
1106 not correspond to a tty device. It is called whenever data can be
1107 read from the command but before it is written to the standard out‐
1108 put. This allows the plugin to reject data if it chooses to (for
1109 instance if the output contains banned content). Returns 1 if the
1110 data should be passed to the user, 0 if the data is rejected (which
1111 will terminate the running command) or -1 if an error occurred.
1112 The function arguments are as follows:
1114 buf The buffer containing command output.
1116 len The length of buf in bytes.
1118 log_stderr
1120 int (*log_stderr)(const char *buf, unsigned int len);
1121 The log_stderr() function is only used if the standard error does
1123 not correspond to a tty device. It is called whenever data can be
1124 read from the command but before it is written to the standard
1125 error. This allows the plugin to reject data if it chooses to (for
1126 instance if the output contains banned content). Returns 1 if the
1127 data should be passed to the user, 0 if the data is rejected (which
1128 will terminate the running command) or -1 if an error occurred.
1129 The function arguments are as follows:
1131 buf The buffer containing command output.
1133 len The length of buf in bytes.
1135 register_hooks
1137 See the Policy plugin API section for a description of
1138 register_hooks.
1139 deregister_hooks
1141 See the Policy plugin API section for a description of
1142 deregister_hooks.
1143 change_winsize
1145 int (*change_winsize)(unsigned int lines, unsigned int cols);
1146 The change_winsize() function is called whenever the window size of
1148 the terminal changes from the initial values specified in the
1149 user_info list. Returns -1 if an error occurred, in which case no
1150 further calls to change_winsize() will be made,
1151 log_suspend
1153 int (*log_suspend)(int signo);
1154 The log_suspend() function is called whenever a command is sus‐
1156 pended or resumed. The signo argument is either the signal that
1157 caused the command to be suspended or SIGCONT if the command was
1158 resumed. Logging this information makes it possible to skip the
1159 period of time when the command was suspended during playback of a
1160 session. Returns -1 if an error occurred, in which case no further
1161 calls to log_suspend() will be made,
1162 I/O Plugin Version Macros
1164 Same as for the Policy plugin API.
1166 Signal handlers
1168 The sudo front end installs default signal handlers to trap common sig‐
1169 nals while the plugin functions are run. The following signals are
1170 trapped by default before the command is executed:
1171 · SIGALRM
1173 · SIGHUP
1174 · SIGINT
1175 · SIGPIPE
1176 · SIGQUIT
1177 · SIGTERM
1178 · SIGTSTP
1179 · SIGUSR1
1180 · SIGUSR2
1181 If a fatal signal is received before the command is executed, sudo will
1183 call the plugin's close() function with an exit status of 128 plus the
1184 value of the signal that was received. This allows for consistent log‐
1185 ging of commands killed by a signal for plugins that log such information
1186 in their close() function. An exception to this is SIGPIPE, which is
1187 ignored until the command is executed.
1188 A plugin may temporarily install its own signal handlers but must restore
1190 the original handler before the plugin function returns.
1191 Hook function API
1193 Beginning with plugin API version 1.2, it is possible to install hooks
1194 for certain functions called by the sudo front end.
1195 Currently, the only supported hooks relate to the handling of environment
1197 variables. Hooks can be used to intercept attempts to get, set, or
1198 remove environment variables so that these changes can be reflected in
1199 the version of the environment that is used to execute a command. A
1200 future version of the API will support hooking internal sudo front end
1201 functions as well.
1202 Hook structure
1204 Hooks in sudo are described by the following structure:
1206 typedef int (*sudo_hook_fn_t)();
1208 struct sudo_hook {
1210 unsigned int hook_version;
1211 unsigned int hook_type;
1212 sudo_hook_fn_t hook_fn;
1213 void *closure;
1214 };
1215 The sudo_hook structure has the following fields:
1217 hook_version
1219 The hook_version field should be set to SUDO_HOOK_VERSION.
1220 hook_type
1222 The hook_type field may be one of the following supported hook
1223 types:
1224 SUDO_HOOK_SETENV
1226 The C library setenv(3) function. Any registered hooks will
1227 run before the C library implementation. The hook_fn field
1228 should be a function that matches the following typedef:
1229 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1231 const char *value, int overwrite, void *closure);
1232 If the registered hook does not match the typedef the results
1234 are unspecified.
1235 SUDO_HOOK_UNSETENV
1237 The C library unsetenv(3) function. Any registered hooks
1238 will run before the C library implementation. The hook_fn
1239 field should be a function that matches the following type‐
1240 def:
1241 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1243 void *closure);
1244 SUDO_HOOK_GETENV
1246 The C library getenv(3) function. Any registered hooks will
1247 run before the C library implementation. The hook_fn field
1248 should be a function that matches the following typedef:
1249 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1251 char **value, void *closure);
1252 If the registered hook does not match the typedef the results
1254 are unspecified.
1255 SUDO_HOOK_PUTENV
1257 The C library putenv(3) function. Any registered hooks will
1258 run before the C library implementation. The hook_fn field
1259 should be a function that matches the following typedef:
1260 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1262 void *closure);
1263 If the registered hook does not match the typedef the results
1265 are unspecified.
1266 hook_fn
1268 sudo_hook_fn_t hook_fn;
1269 The hook_fn field should be set to the plugin's hook implementa‐
1271 tion. The actual function arguments will vary depending on the
1272 hook_type (see hook_type above). In all cases, the closure field
1273 of struct sudo_hook is passed as the last function parameter. This
1274 can be used to pass arbitrary data to the plugin's hook implementa‐
1275 tion.
1276 The function return value may be one of the following:
1278 SUDO_HOOK_RET_ERROR
1280 The hook function encountered an error.
1281 SUDO_HOOK_RET_NEXT
1283 The hook completed without error, go on to the next hook
1284 (including the native implementation if applicable). For
1285 example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1286 the specified variable was not found in the private copy of
1287 the environment.
1288 SUDO_HOOK_RET_STOP
1290 The hook completed without error, stop processing hooks for
1291 this invocation. This can be used to replace the native
1292 implementation. For example, a setenv hook that operates on
1293 a private copy of the environment but leaves environ
1294 unchanged.
1295 Note that it is very easy to create an infinite loop when hooking C
1297 library functions. For example, a getenv(3) hook that calls the
1298 snprintf(3) function may create a loop if the snprintf(3) implementation
1299 calls getenv(3) to check the locale. To prevent this, you may wish to
1300 use a static variable in the hook function to guard against nested calls.
1301 For example:
1302 static int in_progress = 0; /* avoid recursion */
1304 if (in_progress)
1305 return SUDO_HOOK_RET_NEXT;
1306 in_progress = 1;
1307 ...
1308 in_progress = 0;
1309 return SUDO_HOOK_RET_STOP;
1310 Hook API Version Macros
1312 /* Hook API version major/minor */
1314 #define SUDO_HOOK_VERSION_MAJOR 1
1315 #define SUDO_HOOK_VERSION_MINOR 0
1316 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1317 SUDO_HOOK_VERSION_MINOR)
1318 For getters and setters see the Policy plugin API.
1320 Remote command execution
1322 The sudo front end does not have native support for running remote com‐
1323 mands. However, starting with sudo 1.8.8, the -h option may be used to
1324 specify a remote host that is passed to the policy plugin. A plugin may
1325 also accept a runas_user in the form of “user@hostname” which will work
1326 with older versions of sudo. It is anticipated that remote commands will
1327 be supported by executing a “helper” program. The policy plugin should
1328 setup the execution environment such that the sudo front end will run the
1329 helper which, in turn, will connect to the remote host and run the com‐
1330 mand.
1331 For example, the policy plugin could utilize ssh to perform remote com‐
1333 mand execution. The helper program would be responsible for running ssh
1334 with the proper options to use a private key or certificate that the
1335 remote host will accept and run a program on the remote host that would
1336 setup the execution environment accordingly.
1337 Note that remote sudoedit functionality must be handled by the policy
1339 plugin, not sudo itself as the front end has no knowledge that a remote
1340 command is being executed. This may be addressed in a future revision of
1341 the plugin API.
1342 Conversation API
1344 If the plugin needs to interact with the user, it may do so via the
1345 conversation() function. A plugin should not attempt to read directly
1346 from the standard input or the user's tty (neither of which are guaran‐
1347 teed to exist). The caller must include a trailing newline in msg if one
1348 is to be printed.
1349 A printf()-style function is also available that can be used to display
1351 informational or error messages to the user, which is usually more conve‐
1352 nient for simple messages where no use input is required.
1353 Conversation function structures
1355 The conversation function takes as arguments pointers to the following
1357 structures:
1358 struct sudo_conv_message {
1360 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1361 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1362 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1363 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1364 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1365 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1366 #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */
1367 int msg_type;
1368 int timeout;
1369 const char *msg;
1370 };
1371 #define SUDO_CONV_REPL_MAX 255
1373 struct sudo_conv_reply {
1375 char *reply;
1376 };
1377 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
1379 struct sudo_conv_callback {
1380 unsigned int version;
1381 void *closure;
1382 sudo_conv_callback_fn_t on_suspend;
1383 sudo_conv_callback_fn_t on_resume;
1384 };
1385 Pointers to the conversation() and printf()-style functions are passed in
1387 to the plugin's open() function when the plugin is initialized. The fol‐
1388 lowing type definitions can be used in the declaration of the open()
1389 function:
1390 typedef int (*sudo_conv_t)(int num_msgs,
1392 const struct sudo_conv_message msgs[],
1393 struct sudo_conv_reply replies[],
1394 struct sudo_conv_callback *callback);
1395 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1397 To use the conversation() function, the plugin must pass an array of
1399 sudo_conv_message and sudo_conv_reply structures. There must be a struct
1400 sudo_conv_message and struct sudo_conv_reply for each message in the con‐
1401 versation, that is, both arrays must have the same number of elements.
1402 Each struct sudo_conv_reply must have its reply member initialized to
1403 NULL. The struct sudo_conv_callback pointer, if not NULL, should contain
1404 function pointers to be called when the sudo process is suspended and/or
1405 resumed during conversation input. The on_suspend and on_resume func‐
1406 tions are called with the signal that caused sudo to be suspended and the
1407 closure pointer from the struct sudo_conv_callback. These functions
1408 should return 0 on success and -1 on error. On error, the conversation
1409 will end and the conversation function will return a value of -1. The
1410 intended use is to allow the plugin to release resources, such as locks,
1411 that should not be held indefinitely while suspended and then reacquire
1412 them when the process is resumed. Note that the functions are not actu‐
1413 ally invoked from within a signal handler.
1414 The msg_type must be set to one of the following values:
1416 SUDO_CONV_PROMPT_ECHO_OFF
1418 Prompt the user for input with echo disabled; this is generally
1419 used for passwords. The reply will be stored in the replies array,
1420 and it will never be NULL.
1421 SUDO_CONV_PROMPT_ECHO_ON
1423 Prompt the user for input with echo enabled. The reply will be
1424 stored in the replies array, and it will never be NULL.
1425 SUDO_CONV_ERROR_MSG
1427 Display an error message. The message is written to the standard
1428 error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
1429 is written to the user's terminal if possible.
1430 SUDO_CONV_INFO_MSG
1432 Display a message. The message is written to the standard output
1433 unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
1434 written to the user's terminal if possible.
1435 SUDO_CONV_PROMPT_MASK
1437 Prompt the user for input but echo an asterisk character for each
1438 character read. The reply will be stored in the replies array, and
1439 it will never be NULL. This can be used to provide visual feedback
1440 to the user while reading sensitive information that should not be
1441 displayed.
1442 In addition to the above values, the following flag bits may also be set:
1444 SUDO_CONV_PROMPT_ECHO_OK
1446 Allow input to be read when echo cannot be disabled when the mes‐
1447 sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
1448 By default, sudo will refuse to read input if the echo cannot be
1449 disabled for those message types.
1450 SUDO_CONV_PREFER_TTY
1452 When displaying a message via SUDO_CONV_ERROR_MSG or
1453 SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
1454 nal. If the terminal is unavailable, the standard error or stan‐
1455 dard output will be used, depending upon whether The user's termi‐
1456 nal is always used when possible for input, this flag is only used
1457 for output. SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used.
1458 The timeout in seconds until the prompt will wait for no more input. A
1460 zero value implies an infinite timeout.
1461 The plugin is responsible for freeing the reply buffer located in each
1463 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
1464 the maximum length of the reply buffer (not including the trailing NUL
1465 character). In practical terms, this is the longest password sudo will
1466 support. It is also useful as a maximum value for the memset_s() func‐
1467 tion when clearing passwords filled in by the conversation function.
1468 The printf()-style function uses the same underlying mechanism as the
1470 conversation() function but only supports SUDO_CONV_INFO_MSG and
1471 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
1472 nient than using the conversation() function if no user reply is needed
1473 and supports standard printf() escape sequences.
1474 See the sample plugin for an example of the conversation() function
1476 usage.
1477 Sudoers group plugin API
1479 The sudoers plugin supports its own plugin interface to allow non-Unix
1480 group lookups. This can be used to query a group source other than the
1481 standard Unix group database. Two sample group plugins are bundled with
1482 sudo, group_file and system_group, are detailed in sudoers(5). Third
1483 party group plugins include a QAS AD plugin available from Quest Soft‐
1484 ware.
1485 A group plugin must declare and populate a sudoers_group_plugin struct in
1487 the global scope. This structure contains pointers to the functions that
1488 implement plugin initialization, cleanup and group lookup.
1489 struct sudoers_group_plugin {
1491 unsigned int version;
1492 int (*init)(int version, sudo_printf_t sudo_printf,
1493 char *const argv[]);
1494 void (*cleanup)(void);
1495 int (*query)(const char *user, const char *group,
1496 const struct passwd *pwd);
1497 };
1498 The sudoers_group_plugin struct has the following fields:
1500 version
1502 The version field should be set to GROUP_API_VERSION.
1503 This allows sudoers to determine the API version the group plugin
1505 was built against.
1506 init
1508 int (*init)(int version, sudo_printf_t plugin_printf,
1509 char *const argv[]);
1510 The init() function is called after sudoers has been parsed but
1512 before any policy checks. It returns 1 on success, 0 on failure
1513 (or if the plugin is not configured), and -1 if a error occurred.
1514 If an error occurs, the plugin may call the plugin_printf() func‐
1515 tion with SUDO_CONF_ERROR_MSG to present additional error informa‐
1516 tion to the user.
1517 The function arguments are as follows:
1519 version
1521 The version passed in by sudoers allows the plugin to deter‐
1522 mine the major and minor version number of the group plugin
1523 API supported by sudoers.
1524 plugin_printf
1526 A pointer to a printf()-style function that may be used to
1527 display informational or error message to the user. Returns
1528 the number of characters printed on success and -1 on fail‐
1529 ure.
1530 argv A NULL-terminated array of arguments generated from the
1532 group_plugin option in sudoers. If no arguments were given,
1533 argv will be NULL.
1534 cleanup
1536 void (*cleanup)();
1537 The cleanup() function is called when sudoers has finished its
1539 group checks. The plugin should free any memory it has allocated
1540 and close open file handles.
1541 query
1543 int (*query)(const char *user, const char *group,
1544 const struct passwd *pwd);
1545 The query() function is used to ask the group plugin whether user
1547 is a member of group.
1548 The function arguments are as follows:
1550 user The name of the user being looked up in the external group
1552 database.
1553 group
1555 The name of the group being queried.
1556 pwd The password database entry for user, if any. If user is not
1558 present in the password database, pwd will be NULL.
1559 Group API Version Macros
1561 /* Sudoers group plugin version major/minor */
1563 #define GROUP_API_VERSION_MAJOR 1
1564 #define GROUP_API_VERSION_MINOR 0
1565 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1566 GROUP_API_VERSION_MINOR)
1567 For getters and setters see the Policy plugin API.
1568
1570 The following revisions have been made to the Sudo Plugin API.
1571 Version 1.0
1573 Initial API version.
1574 Version 1.1 (sudo 1.8.0)
1576 The I/O logging plugin's open() function was modified to take the
1577 command_info list as an argument.
1578 Version 1.2 (sudo 1.8.5)
1580 The Policy and I/O logging plugins' open() functions are now passed
1581 a list of plugin parameters if any are specified in sudo.conf(5).
1582 A simple hooks API has been introduced to allow plugins to hook in
1584 to the system's environment handling functions.
1585 The init_session Policy plugin function is now passed a pointer to
1587 the user environment which can be updated as needed. This can be
1588 used to merge in environment variables stored in the PAM handle
1589 before a command is run.
1590 Version 1.3 (sudo 1.8.7)
1592 Support for the exec_background entry has been added to the
1593 command_info list.
1594 The max_groups and plugin_dir entries were added to the settings
1596 list.
1597 The version() and close() functions are now optional. Previously,
1599 a missing version() or close() function would result in a crash.
1600 If no policy plugin close() function is defined, a default close()
1601 function will be provided by the sudo front end that displays a
1602 warning if the command could not be executed.
1603 The sudo front end now installs default signal handlers to trap
1605 common signals while the plugin functions are run.
1606 Version 1.4 (sudo 1.8.8)
1608 The remote_host entry was added to the settings list.
1609 Version 1.5 (sudo 1.8.9)
1611 The preserve_fds entry was added to the command_info list.
1612 Version 1.6 (sudo 1.8.11)
1614 The behavior when an I/O logging plugin returns an error (-1) has
1615 changed. Previously, the sudo front end took no action when the
1616 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
1617 log_stderr() function returned an error.
1618 The behavior when an I/O logging plugin returns 0 has changed.
1620 Previously, output from the command would be displayed to the ter‐
1621 minal even if an output logging function returned 0.
1622 Version 1.7 (sudo 1.8.12)
1624 The plugin_path entry was added to the settings list.
1625 The debug_flags entry now starts with a debug file path name and
1627 may occur multiple times if there are multiple plugin-specific
1628 Debug lines in the sudo.conf(5) file.
1629 Version 1.8 (sudo 1.8.15)
1631 The sudoedit_checkdir and sudoedit_follow entries were added to the
1632 command_info list. The default value of sudoedit_checkdir was
1633 changed to true in sudo 1.8.16.
1634 The sudo conversation function now takes a pointer to a struct
1636 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
1637 tion has been updated to match. The plugin must specify that it
1638 supports plugin API version 1.8 or higher to receive a conversation
1639 function pointer that supports this argument.
1640 Version 1.9 (sudo 1.8.16)
1642 The execfd entry was added to the command_info list.
1643 Version 1.10 (sudo 1.8.19)
1645 The umask entry was added to the user_info list. The iolog_group,
1646 iolog_mode, and iolog_user entries were added to the command_info
1647 list.
1648 Version 1.11 (sudo 1.8.20)
1650 The timeout entry was added to the settings list.
1651 Version 1.12 (sudo 1.8.21)
1653 The change_winsize field was added to the io_plugin struct.
1654 Version 1.13 (sudo 1.8.26)
1656 The log_suspend field was added to the io_plugin struct.
1657 Version 1.14 (sudo 1.8.29)
1659 The umask_override entry was added to the command_info list.
1660
1662 sudo.conf(5), sudoers(5), sudo(8)
1663
1665 Many people have worked on sudo over the years; this version consists of
1666 code written primarily by:
1667 Todd C. Miller
1669 See the CONTRIBUTORS file in the sudo distribution
1671 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
1672 who have contributed to sudo.
1673
1675 If you feel you have found a bug in sudo, please submit a bug report at
1676 https://bugzilla.sudo.ws/
1677
1679 Limited free support is available via the sudo-users mailing list, see
1680 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
1681 the archives.
1682
1684 sudo is provided “AS IS” and any express or implied warranties, includ‐
1685 ing, but not limited to, the implied warranties of merchantability and
1686 fitness for a particular purpose are disclaimed. See the LICENSE file
1687 distributed with sudo or https://www.sudo.ws/license.html for complete
1688 details.
1689Sudo 1.8.29 October 20, 2019 Sudo 1.8.29