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 flags the user speci‐
99 fied when running sudo. As such, they will only be present
100 when the corresponding flag has been specified on the command
101 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 flag, to
109 use on systems where BSD authentication is supported.
110 closefrom=number
112 If specified, the user has requested via the -C flag
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 flag 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 flag.
155 login_shell=bool
157 Set to true if the user specified the -i flag, indicat‐
158 ing 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 flag, indicat‐
175 ing that sudo should operate in non-interactive mode.
176 The plugin may reject a command run in non-interactive
177 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 flag, indicat‐
193 ing that the user wishes to preserve the environment.
194 preserve_groups=bool
196 Set to true if the user specified the -P flag, indicat‐
197 ing that the user wishes to preserve the group vector
198 instead of setting it based on the runas user.
199 progname=string
201 The command name that sudo was run as, typically “sudo”
202 or “sudoedit”.
203 prompt=string
205 The prompt to use when requesting a password, if speci‐
206 fied via the -p flag.
207 remote_host=string
209 The name of the remote host to run the command on, if
210 specified via the -h option. Support for running the
211 command on a remote host is meant to be implemented via
212 a helper program that is executed in place of the user-
213 specified command. The sudo front end is only capable
214 of executing commands on the local host. Only avail‐
215 able starting with API version 1.4.
216 run_shell=bool
218 Set to true if the user specified the -s flag, indicat‐
219 ing that the user wishes to run a shell.
220 runas_group=string
222 The group name or gid to run the command as, if speci‐
223 fied via the -g flag.
224 runas_user=string
226 The user name or uid to run the command as, if speci‐
227 fied via the -u flag.
228 selinux_role=string
230 SELinux role to use when executing the command, if
231 specified by the -r flag.
232 selinux_type=string
234 SELinux type to use when executing the command, if
235 specified by the -t flag.
236 set_home=bool
238 Set to true if the user specified the -H flag. If
239 true, set the HOME environment variable to the target
240 user's home directory.
241 sudoedit=bool
243 Set to true when the -e flag is specified or if invoked
244 as sudoedit. The plugin shall substitute an editor
245 into argv in the check_policy() function or return -2
246 with a usage error if the plugin does not support
247 sudoedit. For more information, see the check_policy
248 section.
249 timeout=string
251 User-specified command timeout. Not all plugins sup‐
252 port command timeouts and the ability for the user to
253 set a timeout may be restricted by policy. The format
254 of the timeout string is plugin-specific.
255 Additional settings may be added in the future so the plugin
257 should silently ignore settings that it does not recognize.
258 user_info
260 A vector of information about the user running the command in
261 the form of “name=value” strings. The vector is terminated
262 by a NULL pointer.
263 When parsing user_info, the plugin should split on the first
265 equal sign (‘=’) since the name field will never include one
266 itself but the value might.
267 cols=int
269 The number of columns the user's terminal supports. If
270 there is no terminal device available, a default value
271 of 80 is used.
272 cwd=string
274 The user's current working directory.
275 egid=gid_t
277 The effective group ID of the user invoking sudo.
278 euid=uid_t
280 The effective user ID of the user invoking sudo.
281 gid=gid_t
283 The real group ID of the user invoking sudo.
284 groups=list
286 The user's supplementary group list formatted as a
287 string of comma-separated group IDs.
288 host=string
290 The local machine's hostname as returned by the
291 gethostname(2) system call.
292 lines=int
294 The number of lines the user's terminal supports. If
295 there is no terminal device available, a default value
296 of 24 is used.
297 pgid=int
299 The ID of the process group that the running sudo
300 process is a member of. Only available starting with
301 API version 1.2.
302 pid=int
304 The process ID of the running sudo process. Only
305 available starting with API version 1.2.
306 plugin_options
308 Any (non-comment) strings immediately after the plugin
309 path are passed as arguments to the plugin. These
310 arguments are split on a white space boundary and are
311 passed to the plugin in the form of a NULL-terminated
312 array of strings. If no arguments were specified,
313 plugin_options will be the NULL pointer.
314 NOTE: the plugin_options parameter is only available
316 starting with API version 1.2. A plugin must check the
317 API version specified by the sudo front end before
318 using plugin_options. Failure to do so may result in a
319 crash.
320 ppid=int
322 The parent process ID of the running sudo process.
323 Only available starting with API version 1.2.
324 sid=int
326 The session ID of the running sudo process or 0 if sudo
327 is not part of a POSIX job control session. Only
328 available starting with API version 1.2.
329 tcpgid=int
331 The ID of the foreground process group associated with
332 the terminal device associated with the sudo process or
333 -1 if there is no terminal present. Only available
334 starting with API version 1.2.
335 tty=string
337 The path to the user's terminal device. If the user
338 has no terminal device associated with the session, the
339 value will be empty, as in “tty=”.
340 uid=uid_t
342 The real user ID of the user invoking sudo.
343 umask=octal
345 The invoking user's file creation mask. Only available
346 starting with API version 1.10.
347 user=string
349 The name of the user invoking sudo.
350 user_env
352 The user's environment in the form of a NULL-terminated
353 vector of “name=value” strings.
354 When parsing user_env, the plugin should split on the first
356 equal sign (‘=’) since the name field will never include one
357 itself but the value might.
358 close
360 void (*close)(int exit_status, int error);
361 The close() function is called when the command being run by sudo
363 finishes.
364 The function arguments are as follows:
366 exit_status
368 The command's exit status, as returned by the wait(2) system
369 call. The value of exit_status is undefined if error is non-
370 zero.
371 error
373 If the command could not be executed, this is set to the
374 value of errno set by the execve(2) system call. The plugin
375 is responsible for displaying error information via the
376 conversation() or plugin_printf() function. If the command
377 was successfully executed, the value of error is 0.
378 If no close() function is defined, no I/O logging plugins are
380 loaded, and neither the timeout not use_pty options are set in the
381 command_info list, the sudo front end may execute the command
382 directly instead of running it as a child process.
383 show_version
385 int (*show_version)(int verbose);
386 The show_version() function is called by sudo when the user speci‐
388 fies the -V option. The plugin may display its version information
389 to the user via the conversation() or plugin_printf() function
390 using SUDO_CONV_INFO_MSG. If the user requests detailed version
391 information, the verbose flag will be set.
392 Returns 1 on success, 0 on failure, -1 if a general error occurred,
394 or -2 if there was a usage error, although the return value is cur‐
395 rently ignored.
396 check_policy
398 int (*check_policy)(int argc, char * const argv[],
399 char *env_add[], char **command_info[],
400 char **argv_out[], char **user_env_out[]);
401 The check_policy() function is called by sudo to determine whether
403 the user is allowed to run the specified commands.
404 If the sudoedit option was enabled in the settings array passed to
406 the open() function, the user has requested sudoedit mode.
407 sudoedit is a mechanism for editing one or more files where an edi‐
408 tor is run with the user's credentials instead of with elevated
409 privileges. sudo achieves this by creating user-writable temporary
410 copies of the files to be edited and then overwriting the originals
411 with the temporary copies after editing is complete. If the plugin
412 supports sudoedit, it should choose the editor to be used, poten‐
413 tially from a variable in the user's environment, such as EDITOR,
414 and include it in argv_out (note that environment variables may
415 include command line flags). The files to be edited should be
416 copied from argv into argv_out, separated from the editor and its
417 arguments by a “--” element. The “--” will be removed by sudo
418 before the editor is executed. The plugin should also set
419 sudoedit=true in the command_info list.
420 The check_policy() function returns 1 if the command is allowed, 0
422 if not allowed, -1 for a general error, or -2 for a usage error or
423 if sudoedit was specified but is unsupported by the plugin. In the
424 latter case, sudo will print a usage message before it exits. If
425 an error occurs, the plugin may optionally call the conversation()
426 or plugin_printf() function with SUDO_CONF_ERROR_MSG to present
427 additional error information to the user.
428 The function arguments are as follows:
430 argc The number of elements in argv, not counting the final NULL
432 pointer.
433 argv The argument vector describing the command the user wishes to
435 run, in the same form as what would be passed to the
436 execve(2) system call. The vector is terminated by a NULL
437 pointer.
438 env_add
440 Additional environment variables specified by the user on the
441 command line in the form of a NULL-terminated vector of
442 “name=value” strings. The plugin may reject the command if
443 one or more variables are not allowed to be set, or it may
444 silently ignore such variables.
445 When parsing env_add, the plugin should split on the first
447 equal sign (‘=’) since the name field will never include one
448 itself but the value might.
449 command_info
451 Information about the command being run in the form of
452 “name=value” strings. These values are used by sudo to set
453 the execution environment when running a command. The plugin
454 is responsible for creating and populating the vector, which
455 must be terminated with a NULL pointer. The following values
456 are recognized by sudo:
457 chroot=string
459 The root directory to use when running the command.
460 closefrom=number
462 If specified, sudo will close all files descriptors
463 with a value of number or higher.
464 command=string
466 Fully qualified path to the command to be executed.
467 cwd=string
469 The current working directory to change to when execut‐
470 ing the command.
471 exec_background=bool
473 By default, sudo runs a command as the foreground
474 process as long as sudo itself is running in the fore‐
475 ground. When exec_background is enabled and the com‐
476 mand is being run in a pty (due to I/O logging or the
477 use_pty setting), the command will be run as a back‐
478 ground process. Attempts to read from the controlling
479 terminal (or to change terminal settings) will result
480 in the command being suspended with the SIGTTIN signal
481 (or SIGTTOU in the case of terminal settings). If this
482 happens when sudo is a foreground process, the command
483 will be granted the controlling terminal and resumed in
484 the foreground with no user intervention required. The
485 advantage of initially running the command in the back‐
486 ground is that sudo need not read from the terminal
487 unless the command explicitly requests it. Otherwise,
488 any terminal input must be passed to the command,
489 whether it has required it or not (the kernel buffers
490 terminals so it is not possible to tell whether the
491 command really wants the input). This is different
492 from historic sudo behavior or when the command is not
493 being run in a pty.
494 For this to work seamlessly, the operating system must
496 support the automatic restarting of system calls.
497 Unfortunately, not all operating systems do this by
498 default, and even those that do may have bugs. For
499 example, macOS fails to restart the tcgetattr() and
500 tcsetattr() system calls (this is a bug in macOS).
501 Furthermore, because this behavior depends on the com‐
502 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
503 grams that catch these signals and suspend themselves
504 with a different signal (usually SIGTOP) will not be
505 automatically foregrounded. Some versions of the linux
506 su(1) command behave this way. Because of this, a
507 plugin should not set exec_background unless it is
508 explicitly enabled by the administrator and there
509 should be a way to enabled or disable it on a per-com‐
510 mand basis.
511 This setting has no effect unless I/O logging is
513 enabled or use_pty is enabled.
514 execfd=number
516 If specified, sudo will use the fexecve(2) system call
517 to execute the command instead of execve(2). The spec‐
518 ified number must refer to an open file descriptor.
519 iolog_compress=bool
521 Set to true if the I/O logging plugins, if any, should
522 compress the log data. This is a hint to the I/O log‐
523 ging plugin which may choose to ignore it.
524 iolog_group=string
526 The group that will own newly created I/O log files and
527 directories. This is a hint to the I/O logging plugin
528 which may choose to ignore it.
529 iolog_mode=octal
531 The file permission mode to use when creating I/O log
532 files and directories. This is a hint to the I/O log‐
533 ging plugin which may choose to ignore it.
534 iolog_user=string
536 The user that will own newly created I/O log files and
537 directories. This is a hint to the I/O logging plugin
538 which may choose to ignore it.
539 iolog_path=string
541 Fully qualified path to the file or directory in which
542 I/O log is to be stored. This is a hint to the I/O
543 logging plugin which may choose to ignore it. If no
544 I/O logging plugin is loaded, this setting has no
545 effect.
546 iolog_stdin=bool
548 Set to true if the I/O logging plugins, if any, should
549 log the standard input if it is not connected to a ter‐
550 minal device. This is a hint to the I/O logging plugin
551 which may choose to ignore it.
552 iolog_stdout=bool
554 Set to true if the I/O logging plugins, if any, should
555 log the standard output if it is not connected to a
556 terminal device. This is a hint to the I/O logging
557 plugin which may choose to ignore it.
558 iolog_stderr=bool
560 Set to true if the I/O logging plugins, if any, should
561 log the standard error if it is not connected to a ter‐
562 minal device. This is a hint to the I/O logging plugin
563 which may choose to ignore it.
564 iolog_ttyin=bool
566 Set to true if the I/O logging plugins, if any, should
567 log all terminal input. This only includes input typed
568 by the user and not from a pipe or redirected from a
569 file. This is a hint to the I/O logging plugin which
570 may choose to ignore it.
571 iolog_ttyout=bool
573 Set to true if the I/O logging plugins, if any, should
574 log all terminal output. This only includes output to
575 the screen, not output to a pipe or file. This is a
576 hint to the I/O logging plugin which may choose to
577 ignore it.
578 login_class=string
580 BSD login class to use when setting resource limits and
581 nice value (optional). This option is only set on sys‐
582 tems that support login classes.
583 nice=int
585 Nice value (priority) to use when executing the com‐
586 mand. The nice value, if specified, overrides the pri‐
587 ority associated with the login_class on BSD systems.
588 noexec=bool
590 If set, prevent the command from executing other pro‐
591 grams.
592 preserve_fds=list
594 A comma-separated list of file descriptors that should
595 be preserved, regardless of the value of the closefrom
596 setting. Only available starting with API version 1.5.
597 preserve_groups=bool
599 If set, sudo will preserve the user's group vector
600 instead of initializing the group vector based on
601 runas_user.
602 runas_egid=gid
604 Effective group ID to run the command as. If not spec‐
605 ified, the value of runas_gid is used.
606 runas_euid=uid
608 Effective user ID to run the command as. If not speci‐
609 fied, the value of runas_uid is used.
610 runas_gid=gid
612 Group ID to run the command as.
613 runas_groups=list
615 The supplementary group vector to use for the command
616 in the form of a comma-separated list of group IDs. If
617 preserve_groups is set, this option is ignored.
618 runas_uid=uid
620 User ID to run the command as.
621 selinux_role=string
623 SELinux role to use when executing the command.
624 selinux_type=string
626 SELinux type to use when executing the command.
627 set_utmp=bool
629 Create a utmp (or utmpx) entry when a pseudo-tty is
630 allocated. By default, the new entry will be a copy of
631 the user's existing utmp entry (if any), with the tty,
632 time, type and pid fields updated.
633 sudoedit=bool
635 Set to true when in sudoedit mode. The plugin may
636 enable sudoedit mode even if sudo was not invoked as
637 sudoedit. This allows the plugin to perform command
638 substitution and transparently enable sudoedit when the
639 user attempts to run an editor.
640 sudoedit_checkdir=bool
642 Set to false to disable directory writability checks in
643 sudoedit. By default, sudoedit 1.8.16 and higher will
644 check all directory components of the path to be edited
645 for writability by the invoking user. Symbolic links
646 will not be followed in writable directories and
647 sudoedit will refuse to edit a file located in a
648 writable directory. These restrictions are not
649 enforced when sudoedit is run by root. The
650 sudoedit_follow option can be set to false to disable
651 this check. Only available starting with API version
652 1.8.
653 sudoedit_follow=bool
655 Set to true to allow sudoedit to edit files that are
656 symbolic links. By default, sudoedit 1.8.15 and higher
657 will refuse to open a symbolic link. The
658 sudoedit_follow option can be used to restore the older
659 behavior and allow sudoedit to open symbolic links.
660 Only available starting with API version 1.8.
661 timeout=int
663 Command timeout. If non-zero then when the timeout
664 expires the command will be killed.
665 umask=octal
667 The file creation mask to use when executing the com‐
668 mand.
669 use_pty=bool
671 Allocate a pseudo-tty to run the command in, regardless
672 of whether or not I/O logging is in use. By default,
673 sudo will only run the command in a pty when an I/O log
674 plugin is loaded.
675 utmp_user=string
677 User name to use when constructing a new utmp (or
678 utmpx) entry when set_utmp is enabled. This option can
679 be used to set the user field in the utmp entry to the
680 user the command runs as rather than the invoking user.
681 If not set, sudo will base the new entry on the invok‐
682 ing user's existing entry.
683 Unsupported values will be ignored.
685 argv_out
687 The NULL-terminated argument vector to pass to the execve(2)
688 system call when executing the command. The plugin is
689 responsible for allocating and populating the vector.
690 user_env_out
692 The NULL-terminated environment vector to use when executing
693 the command. The plugin is responsible for allocating and
694 populating the vector.
695 list
697 int (*list)(int argc, char * const argv[],
698 int verbose, const char *list_user);
699 List available privileges for the invoking user. Returns 1 on suc‐
701 cess, 0 on failure and -1 on error. On error, the plugin may
702 optionally call the conversation() or plugin_printf() function with
703 SUDO_CONF_ERROR_MSG to present additional error information to the
704 user.
705 Privileges should be output via the conversation() or
707 plugin_printf() function using SUDO_CONV_INFO_MSG,
708 verbose
710 Flag indicating whether to list in verbose mode or not.
711 list_user
713 The name of a different user to list privileges for if the
714 policy allows it. If NULL, the plugin should list the privi‐
715 leges of the invoking user.
716 argc The number of elements in argv, not counting the final NULL
718 pointer.
719 argv If non-NULL, an argument vector describing a command the user
721 wishes to check against the policy in the same form as what
722 would be passed to the execve(2) system call. If the command
723 is permitted by the policy, the fully-qualified path to the
724 command should be displayed along with any command line argu‐
725 ments.
726 validate
728 int (*validate)(void);
729 The validate() function is called when sudo is run with the -v
731 flag. For policy plugins such as sudoers that cache authentication
732 credentials, this function will validate and cache the credentials.
733 The validate() function should be NULL if the plugin does not sup‐
735 port credential caching.
736 Returns 1 on success, 0 on failure and -1 on error. On error, the
738 plugin may optionally call the conversation() or plugin_printf()
739 function with SUDO_CONF_ERROR_MSG to present additional error
740 information to the user.
741 invalidate
743 void (*invalidate)(int remove);
744 The invalidate() function is called when sudo is called with the -k
746 or -K flag. For policy plugins such as sudoers that cache authen‐
747 tication credentials, this function will invalidate the creden‐
748 tials. If the remove flag is set, the plugin may remove the cre‐
749 dentials instead of simply invalidating them.
750 The invalidate() function should be NULL if the plugin does not
752 support credential caching.
753 init_session
755 int (*init_session)(struct passwd *pwd, char **user_envp[);
756 The init_session() function is called before sudo sets up the exe‐
758 cution environment for the command. It is run in the parent sudo
759 process and before any uid or gid changes. This can be used to
760 perform session setup that is not supported by command_info, such
761 as opening the PAM session. The close() function can be used to
762 tear down the session that was opened by init_session.
763 The pwd argument points to a passwd struct for the user the command
765 will be run as if the uid the command will run as was found in the
766 password database, otherwise it will be NULL.
767 The user_env argument points to the environment the command will
769 run in, in the form of a NULL-terminated vector of “name=value”
770 strings. This is the same string passed back to the front end via
771 the Policy Plugin's user_env_out parameter. If the init_session()
772 function needs to modify the user environment, it should update the
773 pointer stored in user_env. The expected use case is to merge the
774 contents of the PAM environment (if any) with the contents of
775 user_env. NOTE: the user_env parameter is only available starting
776 with API version 1.2. A plugin must check the API version speci‐
777 fied by the sudo front end before using user_env. Failure to do so
778 may result in a crash.
779 Returns 1 on success, 0 on failure and -1 on error. On error, the
781 plugin may optionally call the conversation() or plugin_printf()
782 function with SUDO_CONF_ERROR_MSG to present additional error
783 information to the user.
784 register_hooks
786 void (*register_hooks)(int version,
787 int (*register_hook)(struct sudo_hook *hook));
788 The register_hooks() function is called by the sudo front end to
790 register any hooks the plugin needs. If the plugin does not sup‐
791 port hooks, register_hooks should be set to the NULL pointer.
792 The version argument describes the version of the hooks API sup‐
794 ported by the sudo front end.
795 The register_hook() function should be used to register any sup‐
797 ported hooks the plugin needs. It returns 0 on success, 1 if the
798 hook type is not supported and -1 if the major version in struct
799 hook does not match the front end's major hook API version.
800 See the Hook function API section below for more information about
802 hooks.
803 NOTE: the register_hooks() function is only available starting with
805 API version 1.2. If the sudo front end doesn't support API version
806 1.2 or higher, register_hooks will not be called.
807 deregister_hooks
809 void (*deregister_hooks)(int version,
810 int (*deregister_hook)(struct sudo_hook *hook));
811 The deregister_hooks() function is called by the sudo front end to
813 deregister any hooks the plugin has registered. If the plugin does
814 not support hooks, deregister_hooks should be set to the NULL
815 pointer.
816 The version argument describes the version of the hooks API sup‐
818 ported by the sudo front end.
819 The deregister_hook() function should be used to deregister any
821 hooks that were put in place by the register_hook() function. If
822 the plugin tries to deregister a hook that the front end does not
823 support, deregister_hook will return an error.
824 See the Hook function API section below for more information about
826 hooks.
827 NOTE: the deregister_hooks() function is only available starting
829 with API version 1.2. If the sudo front end doesn't support API
830 version 1.2 or higher, deregister_hooks will not be called.
831 Policy Plugin Version Macros
833 /* Plugin API version major/minor. */
835 #define SUDO_API_VERSION_MAJOR 1
836 #define SUDO_API_VERSION_MINOR 13
837 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
838 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
839 SUDO_API_VERSION_MINOR)
840 /* Getters and setters for API version */
842 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
843 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
844 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
845 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
846 } while(0)
847 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
848 *(vp) = (*(vp) & 0xffff0000) | (n); \
849 } while(0)
850 I/O plugin API
852 struct io_plugin {
853 #define SUDO_IO_PLUGIN 2
854 unsigned int type; /* always SUDO_IO_PLUGIN */
855 unsigned int version; /* always SUDO_API_VERSION */
856 int (*open)(unsigned int version, sudo_conv_t conversation,
857 sudo_printf_t plugin_printf, char * const settings[],
858 char * const user_info[], char * const command_info[],
859 int argc, char * const argv[], char * const user_env[],
860 char * const plugin_options[]);
861 void (*close)(int exit_status, int error); /* wait status or error */
862 int (*show_version)(int verbose);
863 int (*log_ttyin)(const char *buf, unsigned int len);
864 int (*log_ttyout)(const char *buf, unsigned int len);
865 int (*log_stdin)(const char *buf, unsigned int len);
866 int (*log_stdout)(const char *buf, unsigned int len);
867 int (*log_stderr)(const char *buf, unsigned int len);
868 void (*register_hooks)(int version,
869 int (*register_hook)(struct sudo_hook *hook));
870 void (*deregister_hooks)(int version,
871 int (*deregister_hook)(struct sudo_hook *hook));
872 int (*change_winsize)(unsigned int lines, unsigned int cols);
873 int (*log_suspend)(int signo);
874 };
875 When an I/O plugin is loaded, sudo runs the command in a pseudo-tty.
877 This makes it possible to log the input and output from the user's ses‐
878 sion. If any of the standard input, standard output or standard error do
879 not correspond to a tty, sudo will open a pipe to capture the I/O for
880 logging before passing it on.
881 The log_ttyin function receives the raw user input from the terminal
883 device (note that this will include input even when echo is disabled,
884 such as when a password is read). The log_ttyout function receives out‐
885 put from the pseudo-tty that is suitable for replaying the user's session
886 at a later time. The log_stdin(), log_stdout() and log_stderr() func‐
887 tions are only called if the standard input, standard output or standard
888 error respectively correspond to something other than a tty.
889 Any of the logging functions may be set to the NULL pointer if no logging
891 is to be performed. If the open function returns 0, no I/O will be sent
892 to the plugin.
893 If a logging function returns an error (-1), the running command will be
895 terminated and all of the plugin's logging functions will be disabled.
896 Other I/O logging plugins will still receive any remaining input or out‐
897 put that has not yet been processed.
898 If an input logging function rejects the data by returning 0, the command
900 will be terminated and the data will not be passed to the command, though
901 it will still be sent to any other I/O logging plugins. If an output
902 logging function rejects the data by returning 0, the command will be
903 terminated and the data will not be written to the terminal, though it
904 will still be sent to any other I/O logging plugins.
905 The io_plugin struct has the following fields:
907 type The type field should always be set to SUDO_IO_PLUGIN.
909 version
911 The version field should be set to SUDO_API_VERSION.
912 This allows sudo to determine the API version the plugin was built
914 against.
915 open
917 int (*open)(unsigned int version, sudo_conv_t conversation,
918 sudo_printf_t plugin_printf, char * const settings[],
919 char * const user_info[], char * const command_info[],
920 int argc, char * const argv[], char * const user_env[],
921 char * const plugin_options[]);
922 The open() function is run before the log_ttyin(), log_ttyout(),
924 log_stdin(), log_stdout(), log_stderr(), log_suspend(),
925 change_winsize(), or show_version() functions are called. It is
926 only called if the version is being requested or if the policy
927 plugin's check_policy() function has returned successfully. It
928 returns 1 on success, 0 on failure, -1 if a general error occurred,
929 or -2 if there was a usage error. In the latter case, sudo will
930 print a usage message before it exits. If an error occurs, the
931 plugin may optionally call the conversation() or plugin_printf()
932 function with SUDO_CONF_ERROR_MSG to present additional error
933 information to the user.
934 The function arguments are as follows:
936 version
938 The version passed in by sudo allows the plugin to determine
939 the major and minor version number of the plugin API sup‐
940 ported by sudo.
941 conversation
943 A pointer to the conversation() function that may be used by
944 the show_version() function to display version information
945 (see show_version() below). The conversation() function may
946 also be used to display additional error message to the user.
947 The conversation() function returns 0 on success and -1 on
948 failure.
949 plugin_printf
951 A pointer to a printf()-style function that may be used by
952 the show_version() function to display version information
953 (see show_version below). The plugin_printf() function may
954 also be used to display additional error message to the user.
955 The plugin_printf() function returns number of characters
956 printed on success and -1 on failure.
957 settings
959 A vector of user-supplied sudo settings in the form of
960 “name=value” strings. The vector is terminated by a NULL
961 pointer. These settings correspond to flags the user speci‐
962 fied when running sudo. As such, they will only be present
963 when the corresponding flag has been specified on the command
964 line.
965 When parsing settings, the plugin should split on the first
967 equal sign (‘=’) since the name field will never include one
968 itself but the value might.
969 See the Policy plugin API section for a list of all possible
971 settings.
972 user_info
974 A vector of information about the user running the command in
975 the form of “name=value” strings. The vector is terminated
976 by a NULL pointer.
977 When parsing user_info, the plugin should split on the first
979 equal sign (‘=’) since the name field will never include one
980 itself but the value might.
981 See the Policy plugin API section for a list of all possible
983 strings.
984 argc The number of elements in argv, not counting the final NULL
986 pointer. It can be zero, when sudo is called with -V.
987 argv If non-NULL, an argument vector describing a command the user
989 wishes to run in the same form as what would be passed to the
990 execve(2) system call.
991 user_env
993 The user's environment in the form of a NULL-terminated vec‐
994 tor of “name=value” strings.
995 When parsing user_env, the plugin should split on the first
997 equal sign (‘=’) since the name field will never include one
998 itself but the value might.
999 plugin_options
1001 Any (non-comment) strings immediately after the plugin path
1002 are treated as arguments to the plugin. These arguments are
1003 split on a white space boundary and are passed to the plugin
1004 in the form of a NULL-terminated array of strings. If no
1005 arguments were specified, plugin_options will be the NULL
1006 pointer.
1007 NOTE: the plugin_options parameter is only available starting
1009 with API version 1.2. A plugin must check the API version
1010 specified by the sudo front end before using plugin_options.
1011 Failure to do so may result in a crash.
1012 close
1014 void (*close)(int exit_status, int error);
1015 The close() function is called when the command being run by sudo
1017 finishes.
1018 The function arguments are as follows:
1020 exit_status
1022 The command's exit status, as returned by the wait(2) system
1023 call. The value of exit_status is undefined if error is non-
1024 zero.
1025 error
1027 If the command could not be executed, this is set to the
1028 value of errno set by the execve(2) system call. If the com‐
1029 mand was successfully executed, the value of error is 0.
1030 show_version
1032 int (*show_version)(int verbose);
1033 The show_version() function is called by sudo when the user speci‐
1035 fies the -V option. The plugin may display its version information
1036 to the user via the conversation() or plugin_printf() function
1037 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1038 information, the verbose flag will be set.
1039 Returns 1 on success, 0 on failure, -1 if a general error occurred,
1041 or -2 if there was a usage error, although the return value is cur‐
1042 rently ignored.
1043 log_ttyin
1045 int (*log_ttyin)(const char *buf, unsigned int len);
1046 The log_ttyin() function is called whenever data can be read from
1048 the user but before it is passed to the running command. This
1049 allows the plugin to reject data if it chooses to (for instance if
1050 the input contains banned content). Returns 1 if the data should
1051 be passed to the command, 0 if the data is rejected (which will
1052 terminate the running command) or -1 if an error occurred.
1053 The function arguments are as follows:
1055 buf The buffer containing user input.
1057 len The length of buf in bytes.
1059 log_ttyout
1061 int (*log_ttyout)(const char *buf, unsigned int len);
1062 The log_ttyout() function is called whenever data can be read from
1064 the command but before it is written to the user's terminal. This
1065 allows the plugin to reject data if it chooses to (for instance if
1066 the output contains banned content). Returns 1 if the data should
1067 be passed to the user, 0 if the data is rejected (which will termi‐
1068 nate the running command) or -1 if an error occurred.
1069 The function arguments are as follows:
1071 buf The buffer containing command output.
1073 len The length of buf in bytes.
1075 log_stdin
1077 int (*log_stdin)(const char *buf, unsigned int len);
1078 The log_stdin() function is only used if the standard input does
1080 not correspond to a tty device. It is called whenever data can be
1081 read from the standard input but before it is passed to the running
1082 command. This allows the plugin to reject data if it chooses to
1083 (for instance if the input contains banned content). Returns 1 if
1084 the data should be passed to the command, 0 if the data is rejected
1085 (which will terminate the running command) or -1 if an error
1086 occurred.
1087 The function arguments are as follows:
1089 buf The buffer containing user input.
1091 len The length of buf in bytes.
1093 log_stdout
1095 int (*log_stdout)(const char *buf, unsigned int len);
1096 The log_stdout() function is only used if the standard output does
1098 not correspond to a tty device. It is called whenever data can be
1099 read from the command but before it is written to the standard out‐
1100 put. This allows the plugin to reject data if it chooses to (for
1101 instance if the output contains banned content). Returns 1 if the
1102 data should be passed to the user, 0 if the data is rejected (which
1103 will terminate the running command) or -1 if an error occurred.
1104 The function arguments are as follows:
1106 buf The buffer containing command output.
1108 len The length of buf in bytes.
1110 log_stderr
1112 int (*log_stderr)(const char *buf, unsigned int len);
1113 The log_stderr() function is only used if the standard error does
1115 not correspond to a tty device. It is called whenever data can be
1116 read from the command but before it is written to the standard
1117 error. This allows the plugin to reject data if it chooses to (for
1118 instance if the output contains banned content). Returns 1 if the
1119 data should be passed to the user, 0 if the data is rejected (which
1120 will terminate the running command) or -1 if an error occurred.
1121 The function arguments are as follows:
1123 buf The buffer containing command output.
1125 len The length of buf in bytes.
1127 register_hooks
1129 See the Policy plugin API section for a description of
1130 register_hooks.
1131 deregister_hooks
1133 See the Policy plugin API section for a description of
1134 deregister_hooks.
1135 change_winsize
1137 int (*change_winsize)(unsigned int lines, unsigned int cols);
1138 The change_winsize() function is called whenever the window size of
1140 the terminal changes from the initial values specified in the
1141 user_info list. Returns -1 if an error occurred, in which case no
1142 further calls to change_winsize() will be made,
1143 log_suspend
1145 int (*log_suspend)(int signo);
1146 The log_suspend() function is called whenever a command is sus‐
1148 pended or resumed. The signo argument is either the signal that
1149 caused the command to be suspended or SIGCONT if the command was
1150 resumed. Logging this information makes it possible to skip the
1151 period of time when the command was suspended during playback of a
1152 session. Returns -1 if an error occurred, in which case no further
1153 calls to log_suspend() will be made,
1154 I/O Plugin Version Macros
1156 Same as for the Policy plugin API.
1158 Signal handlers
1160 The sudo front end installs default signal handlers to trap common sig‐
1161 nals while the plugin functions are run. The following signals are
1162 trapped by default before the command is executed:
1163 · SIGALRM
1165 · SIGHUP
1166 · SIGINT
1167 · SIGPIPE
1168 · SIGQUIT
1169 · SIGTERM
1170 · SIGTSTP
1171 · SIGUSR1
1172 · SIGUSR2
1173 If a fatal signal is received before the command is executed, sudo will
1175 call the plugin's close() function with an exit status of 128 plus the
1176 value of the signal that was received. This allows for consistent log‐
1177 ging of commands killed by a signal for plugins that log such information
1178 in their close() function. An exception to this is SIGPIPE, which is
1179 ignored until the command is executed.
1180 A plugin may temporarily install its own signal handlers but must restore
1182 the original handler before the plugin function returns.
1183 Hook function API
1185 Beginning with plugin API version 1.2, it is possible to install hooks
1186 for certain functions called by the sudo front end.
1187 Currently, the only supported hooks relate to the handling of environment
1189 variables. Hooks can be used to intercept attempts to get, set, or
1190 remove environment variables so that these changes can be reflected in
1191 the version of the environment that is used to execute a command. A
1192 future version of the API will support hooking internal sudo front end
1193 functions as well.
1194 Hook structure
1196 Hooks in sudo are described by the following structure:
1198 typedef int (*sudo_hook_fn_t)();
1200 struct sudo_hook {
1202 unsigned int hook_version;
1203 unsigned int hook_type;
1204 sudo_hook_fn_t hook_fn;
1205 void *closure;
1206 };
1207 The sudo_hook structure has the following fields:
1209 hook_version
1211 The hook_version field should be set to SUDO_HOOK_VERSION.
1212 hook_type
1214 The hook_type field may be one of the following supported hook
1215 types:
1216 SUDO_HOOK_SETENV
1218 The C library setenv(3) function. Any registered hooks will
1219 run before the C library implementation. The hook_fn field
1220 should be a function that matches the following typedef:
1221 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1223 const char *value, int overwrite, void *closure);
1224 If the registered hook does not match the typedef the results
1226 are unspecified.
1227 SUDO_HOOK_UNSETENV
1229 The C library unsetenv(3) function. Any registered hooks
1230 will run before the C library implementation. The hook_fn
1231 field should be a function that matches the following type‐
1232 def:
1233 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1235 void *closure);
1236 SUDO_HOOK_GETENV
1238 The C library getenv(3) function. Any registered hooks will
1239 run before the C library implementation. The hook_fn field
1240 should be a function that matches the following typedef:
1241 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1243 char **value, void *closure);
1244 If the registered hook does not match the typedef the results
1246 are unspecified.
1247 SUDO_HOOK_PUTENV
1249 The C library putenv(3) function. Any registered hooks will
1250 run before the C library implementation. The hook_fn field
1251 should be a function that matches the following typedef:
1252 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1254 void *closure);
1255 If the registered hook does not match the typedef the results
1257 are unspecified.
1258 hook_fn
1260 sudo_hook_fn_t hook_fn;
1261 The hook_fn field should be set to the plugin's hook implementa‐
1263 tion. The actual function arguments will vary depending on the
1264 hook_type (see hook_type above). In all cases, the closure field
1265 of struct sudo_hook is passed as the last function parameter. This
1266 can be used to pass arbitrary data to the plugin's hook implementa‐
1267 tion.
1268 The function return value may be one of the following:
1270 SUDO_HOOK_RET_ERROR
1272 The hook function encountered an error.
1273 SUDO_HOOK_RET_NEXT
1275 The hook completed without error, go on to the next hook
1276 (including the native implementation if applicable). For
1277 example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1278 the specified variable was not found in the private copy of
1279 the environment.
1280 SUDO_HOOK_RET_STOP
1282 The hook completed without error, stop processing hooks for
1283 this invocation. This can be used to replace the native
1284 implementation. For example, a setenv hook that operates on
1285 a private copy of the environment but leaves environ
1286 unchanged.
1287 Note that it is very easy to create an infinite loop when hooking C
1289 library functions. For example, a getenv(3) hook that calls the
1290 snprintf(3) function may create a loop if the snprintf(3) implementation
1291 calls getenv(3) to check the locale. To prevent this, you may wish to
1292 use a static variable in the hook function to guard against nested calls.
1293 For example:
1294 static int in_progress = 0; /* avoid recursion */
1296 if (in_progress)
1297 return SUDO_HOOK_RET_NEXT;
1298 in_progress = 1;
1299 ...
1300 in_progress = 0;
1301 return SUDO_HOOK_RET_STOP;
1302 Hook API Version Macros
1304 /* Hook API version major/minor */
1306 #define SUDO_HOOK_VERSION_MAJOR 1
1307 #define SUDO_HOOK_VERSION_MINOR 0
1308 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1309 SUDO_HOOK_VERSION_MINOR)
1310 For getters and setters see the Policy plugin API.
1312 Remote command execution
1314 The sudo front end does not have native support for running remote com‐
1315 mands. However, starting with sudo 1.8.8, the -h option may be used to
1316 specify a remote host that is passed to the policy plugin. A plugin may
1317 also accept a runas_user in the form of “user@hostname” which will work
1318 with older versions of sudo. It is anticipated that remote commands will
1319 be supported by executing a “helper” program. The policy plugin should
1320 setup the execution environment such that the sudo front end will run the
1321 helper which, in turn, will connect to the remote host and run the com‐
1322 mand.
1323 For example, the policy plugin could utilize ssh to perform remote com‐
1325 mand execution. The helper program would be responsible for running ssh
1326 with the proper options to use a private key or certificate that the
1327 remote host will accept and run a program on the remote host that would
1328 setup the execution environment accordingly.
1329 Note that remote sudoedit functionality must be handled by the policy
1331 plugin, not sudo itself as the front end has no knowledge that a remote
1332 command is being executed. This may be addressed in a future revision of
1333 the plugin API.
1334 Conversation API
1336 If the plugin needs to interact with the user, it may do so via the
1337 conversation() function. A plugin should not attempt to read directly
1338 from the standard input or the user's tty (neither of which are guaran‐
1339 teed to exist). The caller must include a trailing newline in msg if one
1340 is to be printed.
1341 A printf()-style function is also available that can be used to display
1343 informational or error messages to the user, which is usually more conve‐
1344 nient for simple messages where no use input is required.
1345 Conversation function structures
1347 The conversation function takes as arguments pointers to the following
1349 structures:
1350 struct sudo_conv_message {
1352 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1353 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1354 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1355 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1356 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1357 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1358 #define SUDO_CONV_PREFER_TTY 0x2000 /* flag: use tty if possible */
1359 int msg_type;
1360 int timeout;
1361 const char *msg;
1362 };
1363 #define SUDO_CONV_REPL_MAX 255
1365 struct sudo_conv_reply {
1367 char *reply;
1368 };
1369 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
1371 struct sudo_conv_callback {
1372 unsigned int version;
1373 void *closure;
1374 sudo_conv_callback_fn_t on_suspend;
1375 sudo_conv_callback_fn_t on_resume;
1376 };
1377 Pointers to the conversation() and printf()-style functions are passed in
1379 to the plugin's open() function when the plugin is initialized. The fol‐
1380 lowing type definitions can be used in the declaration of the open()
1381 function:
1382 typedef int (*sudo_conv_t)(int num_msgs,
1384 const struct sudo_conv_message msgs[],
1385 struct sudo_conv_reply replies[],
1386 struct sudo_conv_callback *callback);
1387 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1389 To use the conversation() function, the plugin must pass an array of
1391 sudo_conv_message and sudo_conv_reply structures. There must be a struct
1392 sudo_conv_message and struct sudo_conv_reply for each message in the con‐
1393 versation, that is, both arrays must have the same number of elements.
1394 Each struct sudo_conv_reply must have its reply member initialized to
1395 NULL. The struct sudo_conv_callback pointer, if not NULL, should contain
1396 function pointers to be called when the sudo process is suspended and/or
1397 resumed during conversation input. The on_suspend and on_resume func‐
1398 tions are called with the signal that caused sudo to be suspended and the
1399 closure pointer from the struct sudo_conv_callback. These functions
1400 should return 0 on success and -1 on error. On error, the conversation
1401 will end and the conversation function will return a value of -1. The
1402 intended use is to allow the plugin to release resources, such as locks,
1403 that should not be held indefinitely while suspended and then reacquire
1404 them when the process is resumed. Note that the functions are not actu‐
1405 ally invoked from within a signal handler.
1406 The msg_type must be set to one of the following values:
1408 SUDO_CONV_PROMPT_ECHO_OFF
1410 Prompt the user for input with echo disabled; this is generally
1411 used for passwords. The reply will be stored in the replies array,
1412 and it will never be NULL.
1413 SUDO_CONV_PROMPT_ECHO_ON
1415 Prompt the user for input with echo enabled. The reply will be
1416 stored in the replies array, and it will never be NULL.
1417 SUDO_CONV_ERROR_MSG
1419 Display an error message. The message is written to the standard
1420 error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
1421 is written to the user's terminal if possible.
1422 SUDO_CONV_INFO_MSG
1424 Display a message. The message is written to the standard output
1425 unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
1426 written to the user's terminal if possible.
1427 SUDO_CONV_PROMPT_MASK
1429 Prompt the user for input but echo an asterisk character for each
1430 character read. The reply will be stored in the replies array, and
1431 it will never be NULL. This can be used to provide visual feedback
1432 to the user while reading sensitive information that should not be
1433 displayed.
1434 In addition to the above values, the following flag bits may also be set:
1436 SUDO_CONV_PROMPT_ECHO_OK
1438 Allow input to be read when echo cannot be disabled when the mes‐
1439 sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
1440 By default, sudo will refuse to read input if the echo cannot be
1441 disabled for those message types.
1442 SUDO_CONV_PREFER_TTY
1444 When displaying a message via SUDO_CONV_ERROR_MSG or
1445 SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
1446 nal. If the terminal is unavailable, the standard error or stan‐
1447 dard output will be used, depending upon whether The user's termi‐
1448 nal is always used when possible for input, this flag is only used
1449 for output. SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used.
1450 The timeout in seconds until the prompt will wait for no more input. A
1452 zero value implies an infinite timeout.
1453 The plugin is responsible for freeing the reply buffer located in each
1455 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
1456 the maximum length of the reply buffer (not including the trailing NUL
1457 character). In practical terms, this is the longest password sudo will
1458 support. It is also useful as a maximum value for the memset_s() func‐
1459 tion when clearing passwords filled in by the conversation function.
1460 The printf()-style function uses the same underlying mechanism as the
1462 conversation() function but only supports SUDO_CONV_INFO_MSG and
1463 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
1464 nient than using the conversation() function if no user reply is needed
1465 and supports standard printf() escape sequences.
1466 See the sample plugin for an example of the conversation() function
1468 usage.
1469 Sudoers group plugin API
1471 The sudoers plugin supports its own plugin interface to allow non-Unix
1472 group lookups. This can be used to query a group source other than the
1473 standard Unix group database. Two sample group plugins are bundled with
1474 sudo, group_file and system_group, are detailed in sudoers(5). Third
1475 party group plugins include a QAS AD plugin available from Quest Soft‐
1476 ware.
1477 A group plugin must declare and populate a sudoers_group_plugin struct in
1479 the global scope. This structure contains pointers to the functions that
1480 implement plugin initialization, cleanup and group lookup.
1481 struct sudoers_group_plugin {
1483 unsigned int version;
1484 int (*init)(int version, sudo_printf_t sudo_printf,
1485 char *const argv[]);
1486 void (*cleanup)(void);
1487 int (*query)(const char *user, const char *group,
1488 const struct passwd *pwd);
1489 };
1490 The sudoers_group_plugin struct has the following fields:
1492 version
1494 The version field should be set to GROUP_API_VERSION.
1495 This allows sudoers to determine the API version the group plugin
1497 was built against.
1498 init
1500 int (*init)(int version, sudo_printf_t plugin_printf,
1501 char *const argv[]);
1502 The init() function is called after sudoers has been parsed but
1504 before any policy checks. It returns 1 on success, 0 on failure
1505 (or if the plugin is not configured), and -1 if a error occurred.
1506 If an error occurs, the plugin may call the plugin_printf() func‐
1507 tion with SUDO_CONF_ERROR_MSG to present additional error informa‐
1508 tion to the user.
1509 The function arguments are as follows:
1511 version
1513 The version passed in by sudoers allows the plugin to deter‐
1514 mine the major and minor version number of the group plugin
1515 API supported by sudoers.
1516 plugin_printf
1518 A pointer to a printf()-style function that may be used to
1519 display informational or error message to the user. Returns
1520 the number of characters printed on success and -1 on fail‐
1521 ure.
1522 argv A NULL-terminated array of arguments generated from the
1524 group_plugin option in sudoers. If no arguments were given,
1525 argv will be NULL.
1526 cleanup
1528 void (*cleanup)();
1529 The cleanup() function is called when sudoers has finished its
1531 group checks. The plugin should free any memory it has allocated
1532 and close open file handles.
1533 query
1535 int (*query)(const char *user, const char *group,
1536 const struct passwd *pwd);
1537 The query() function is used to ask the group plugin whether user
1539 is a member of group.
1540 The function arguments are as follows:
1542 user The name of the user being looked up in the external group
1544 database.
1545 group
1547 The name of the group being queried.
1548 pwd The password database entry for user, if any. If user is not
1550 present in the password database, pwd will be NULL.
1551 Group API Version Macros
1553 /* Sudoers group plugin version major/minor */
1555 #define GROUP_API_VERSION_MAJOR 1
1556 #define GROUP_API_VERSION_MINOR 0
1557 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1558 GROUP_API_VERSION_MINOR)
1559 For getters and setters see the Policy plugin API.
1560
1562 The following revisions have been made to the Sudo Plugin API.
1563 Version 1.0
1565 Initial API version.
1566 Version 1.1 (sudo 1.8.0)
1568 The I/O logging plugin's open() function was modified to take the
1569 command_info list as an argument.
1570 Version 1.2 (sudo 1.8.5)
1572 The Policy and I/O logging plugins' open() functions are now passed
1573 a list of plugin parameters if any are specified in sudo.conf(5).
1574 A simple hooks API has been introduced to allow plugins to hook in
1576 to the system's environment handling functions.
1577 The init_session Policy plugin function is now passed a pointer to
1579 the user environment which can be updated as needed. This can be
1580 used to merge in environment variables stored in the PAM handle
1581 before a command is run.
1582 Version 1.3 (sudo 1.8.7)
1584 Support for the exec_background entry has been added to the
1585 command_info list.
1586 The max_groups and plugin_dir entries were added to the settings
1588 list.
1589 The version() and close() functions are now optional. Previously,
1591 a missing version() or close() function would result in a crash.
1592 If no policy plugin close() function is defined, a default close()
1593 function will be provided by the sudo front end that displays a
1594 warning if the command could not be executed.
1595 The sudo front end now installs default signal handlers to trap
1597 common signals while the plugin functions are run.
1598 Version 1.4 (sudo 1.8.8)
1600 The remote_host entry was added to the settings list.
1601 Version 1.5 (sudo 1.8.9)
1603 The preserve_fds entry was added to the command_info list.
1604 Version 1.6 (sudo 1.8.11)
1606 The behavior when an I/O logging plugin returns an error (-1) has
1607 changed. Previously, the sudo front end took no action when the
1608 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
1609 log_stderr() function returned an error.
1610 The behavior when an I/O logging plugin returns 0 has changed.
1612 Previously, output from the command would be displayed to the ter‐
1613 minal even if an output logging function returned 0.
1614 Version 1.7 (sudo 1.8.12)
1616 The plugin_path entry was added to the settings list.
1617 The debug_flags entry now starts with a debug file path name and
1619 may occur multiple times if there are multiple plugin-specific
1620 Debug lines in the sudo.conf(5) file.
1621 Version 1.8 (sudo 1.8.15)
1623 The sudoedit_checkdir and sudoedit_follow entries were added to the
1624 command_info list. The default value of sudoedit_checkdir was
1625 changed to true in sudo 1.8.16.
1626 The sudo conversation function now takes a pointer to a struct
1628 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
1629 tion has been updated to match. The plugin must specify that it
1630 supports plugin API version 1.8 or higher to receive a conversation
1631 function pointer that supports this argument.
1632 Version 1.9 (sudo 1.8.16)
1634 The execfd entry was added to the command_info list.
1635 Version 1.10 (sudo 1.8.19)
1637 The umask entry was added to the user_info list. The iolog_group,
1638 iolog_mode, and iolog_user entries were added to the command_info
1639 list.
1640 Version 1.11 (sudo 1.8.20)
1642 The timeout entry was added to the settings list.
1643 Version 1.12 (sudo 1.8.21)
1645 The change_winsize field was added to the io_plugin struct.
1646 Version 1.13 (sudo 1.8.26)
1648 The log_suspend field was added to the io_plugin struct.
1649
1651 sudo.conf(5), sudoers(5), sudo(8)
1652
1654 Many people have worked on sudo over the years; this version consists of
1655 code written primarily by:
1656 Todd C. Miller
1658 See the CONTRIBUTORS file in the sudo distribution
1660 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
1661 who have contributed to sudo.
1662
1664 If you feel you have found a bug in sudo, please submit a bug report at
1665 https://bugzilla.sudo.ws/
1666
1668 Limited free support is available via the sudo-users mailing list, see
1669 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
1670 the archives.
1671
1673 sudo is provided “AS IS” and any express or implied warranties, includ‐
1674 ing, but not limited to, the implied warranties of merchantability and
1675 fitness for a particular purpose are disclaimed. See the LICENSE file
1676 distributed with sudo or https://www.sudo.ws/license.html for complete
1677 details.
1678Sudo 1.8.27 October 24, 2018 Sudo 1.8.27