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 is specified or if
244 invoked as sudoedit. The plugin shall substitute an
245 editor into argv in the check_policy() function or
246 return -2 with a usage error if the plugin does not
247 support sudoedit. For more information, see the
248 check_policy 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 check_policy
394 int (*check_policy)(int argc, char * const argv[]
395 char *env_add[], char **command_info[],
396 char **argv_out[], char **user_env_out[]);
397 The check_policy() function is called by sudo to determine whether
399 the user is allowed to run the specified commands.
400 If the sudoedit option was enabled in the settings array passed to
402 the open() function, the user has requested sudoedit mode.
403 sudoedit is a mechanism for editing one or more files where an edi‐
404 tor is run with the user's credentials instead of with elevated
405 privileges. sudo achieves this by creating user-writable temporary
406 copies of the files to be edited and then overwriting the originals
407 with the temporary copies after editing is complete. If the plugin
408 supports sudoedit, it should choose the editor to be used, poten‐
409 tially from a variable in the user's environment, such as EDITOR,
410 and include it in argv_out (note that environment variables may
411 include command line flags). The files to be edited should be
412 copied from argv into argv_out, separated from the editor and its
413 arguments by a “--” element. The “--” will be removed by sudo
414 before the editor is executed. The plugin should also set
415 sudoedit=true in the command_info list.
416 The check_policy() function returns 1 if the command is allowed, 0
418 if not allowed, -1 for a general error, or -2 for a usage error or
419 if sudoedit was specified but is unsupported by the plugin. In the
420 latter case, sudo will print a usage message before it exits. If
421 an error occurs, the plugin may optionally call the conversation()
422 or plugin_printf() function with SUDO_CONF_ERROR_MSG to present
423 additional error information to the user.
424 The function arguments are as follows:
426 argc The number of elements in argv, not counting the final NULL
428 pointer.
429 argv The argument vector describing the command the user wishes to
431 run, in the same form as what would be passed to the
432 execve(2) system call. The vector is terminated by a NULL
433 pointer.
434 env_add
436 Additional environment variables specified by the user on the
437 command line in the form of a NULL-terminated vector of
438 “name=value” strings. The plugin may reject the command if
439 one or more variables are not allowed to be set, or it may
440 silently ignore such variables.
441 When parsing env_add, the plugin should split on the first
443 equal sign (‘=’) since the name field will never include one
444 itself but the value might.
445 command_info
447 Information about the command being run in the form of
448 “name=value” strings. These values are used by sudo to set
449 the execution environment when running a command. The plugin
450 is responsible for creating and populating the vector, which
451 must be terminated with a NULL pointer. The following values
452 are recognized by sudo:
453 chroot=string
455 The root directory to use when running the command.
456 closefrom=number
458 If specified, sudo will close all files descriptors
459 with a value of number or higher.
460 command=string
462 Fully qualified path to the command to be executed.
463 cwd=string
465 The current working directory to change to when execut‐
466 ing the command.
467 exec_background=bool
469 By default, sudo runs a command as the foreground
470 process as long as sudo itself is running in the fore‐
471 ground. When exec_background is enabled and the com‐
472 mand is being run in a pty (due to I/O logging or the
473 use_pty setting), the command will be run as a back‐
474 ground process. Attempts to read from the controlling
475 terminal (or to change terminal settings) will result
476 in the command being suspended with the SIGTTIN signal
477 (or SIGTTOU in the case of terminal settings). If this
478 happens when sudo is a foreground process, the command
479 will be granted the controlling terminal and resumed in
480 the foreground with no user intervention required. The
481 advantage of initially running the command in the back‐
482 ground is that sudo need not read from the terminal
483 unless the command explicitly requests it. Otherwise,
484 any terminal input must be passed to the command,
485 whether it has required it or not (the kernel buffers
486 terminals so it is not possible to tell whether the
487 command really wants the input). This is different
488 from historic sudo behavior or when the command is not
489 being run in a pty.
490 For this to work seamlessly, the operating system must
492 support the automatic restarting of system calls.
493 Unfortunately, not all operating systems do this by
494 default, and even those that do may have bugs. For
495 example, macOS fails to restart the tcgetattr() and
496 tcsetattr() system calls (this is a bug in macOS).
497 Furthermore, because this behavior depends on the com‐
498 mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
499 grams that catch these signals and suspend themselves
500 with a different signal (usually SIGTOP) will not be
501 automatically foregrounded. Some versions of the linux
502 su(1) command behave this way. Because of this, a
503 plugin should not set exec_background unless it is
504 explicitly enabled by the administrator and there
505 should be a way to enabled or disable it on a per-com‐
506 mand basis.
507 This setting has no effect unless I/O logging is
509 enabled or use_pty is enabled.
510 execfd=number
512 If specified, sudo will use the fexecve(2) system call
513 to execute the command instead of execve(2). The spec‐
514 ified number must refer to an open file descriptor.
515 iolog_compress=bool
517 Set to true if the I/O logging plugins, if any, should
518 compress the log data. This is a hint to the I/O log‐
519 ging plugin which may choose to ignore it.
520 iolog_group=string
522 The group that will own newly created I/O log files and
523 directories. This is a hint to the I/O logging plugin
524 which may choose to ignore it.
525 iolog_mode=octal
527 The file permission mode to use when creating I/O log
528 files and directories. This is a hint to the I/O log‐
529 ging plugin which may choose to ignore it.
530 iolog_user=string
532 The user that will own newly created I/O log files and
533 directories. This is a hint to the I/O logging plugin
534 which may choose to ignore it.
535 iolog_path=string
537 Fully qualified path to the file or directory in which
538 I/O log is to be stored. This is a hint to the I/O
539 logging plugin which may choose to ignore it. If no
540 I/O logging plugin is loaded, this setting has no
541 effect.
542 iolog_stdin=bool
544 Set to true if the I/O logging plugins, if any, should
545 log the standard input if it is not connected to a ter‐
546 minal device. This is a hint to the I/O logging plugin
547 which may choose to ignore it.
548 iolog_stdout=bool
550 Set to true if the I/O logging plugins, if any, should
551 log the standard output if it is not connected to a
552 terminal device. This is a hint to the I/O logging
553 plugin which may choose to ignore it.
554 iolog_stderr=bool
556 Set to true if the I/O logging plugins, if any, should
557 log the standard error if it is not connected to a ter‐
558 minal device. This is a hint to the I/O logging plugin
559 which may choose to ignore it.
560 iolog_ttyin=bool
562 Set to true if the I/O logging plugins, if any, should
563 log all terminal input. This only includes input typed
564 by the user and not from a pipe or redirected from a
565 file. This is a hint to the I/O logging plugin which
566 may choose to ignore it.
567 iolog_ttyout=bool
569 Set to true if the I/O logging plugins, if any, should
570 log all terminal output. This only includes output to
571 the screen, not output to a pipe or file. This is a
572 hint to the I/O logging plugin which may choose to
573 ignore it.
574 login_class=string
576 BSD login class to use when setting resource limits and
577 nice value (optional). This option is only set on sys‐
578 tems that support login classes.
579 nice=int
581 Nice value (priority) to use when executing the com‐
582 mand. The nice value, if specified, overrides the pri‐
583 ority associated with the login_class on BSD systems.
584 noexec=bool
586 If set, prevent the command from executing other pro‐
587 grams.
588 preserve_fds=list
590 A comma-separated list of file descriptors that should
591 be preserved, regardless of the value of the closefrom
592 setting. Only available starting with API version 1.5.
593 preserve_groups=bool
595 If set, sudo will preserve the user's group vector
596 instead of initializing the group vector based on
597 runas_user.
598 runas_egid=gid
600 Effective group ID to run the command as. If not spec‐
601 ified, the value of runas_gid is used.
602 runas_euid=uid
604 Effective user ID to run the command as. If not speci‐
605 fied, the value of runas_uid is used.
606 runas_gid=gid
608 Group ID to run the command as.
609 runas_groups=list
611 The supplementary group vector to use for the command
612 in the form of a comma-separated list of group IDs. If
613 preserve_groups is set, this option is ignored.
614 runas_uid=uid
616 User ID to run the command as.
617 selinux_role=string
619 SELinux role to use when executing the command.
620 selinux_type=string
622 SELinux type to use when executing the command.
623 set_utmp=bool
625 Create a utmp (or utmpx) entry when a pseudo-tty is
626 allocated. By default, the new entry will be a copy of
627 the user's existing utmp entry (if any), with the tty,
628 time, type and pid fields updated.
629 sudoedit=bool
631 Set to true when in sudoedit mode. The plugin may
632 enable sudoedit mode even if sudo was not invoked as
633 sudoedit. This allows the plugin to perform command
634 substitution and transparently enable sudoedit when the
635 user attempts to run an editor.
636 sudoedit_checkdir=bool
638 Set to false to disable directory writability checks in
639 sudoedit. By default, sudoedit 1.8.16 and higher will
640 check all directory components of the path to be edited
641 for writability by the invoking user. Symbolic links
642 will not be followed in writable directories and
643 sudoedit will refuse to edit a file located in a
644 writable directory. These restrictions are not
645 enforced when sudoedit is run by root. The
646 sudoedit_follow option can be set to false to disable
647 this check. Only available starting with API version
648 1.8.
649 sudoedit_follow=bool
651 Set to true to allow sudoedit to edit files that are
652 symbolic links. By default, sudoedit 1.8.15 and higher
653 will refuse to open a symbolic link. The
654 sudoedit_follow option can be used to restore the older
655 behavior and allow sudoedit to open symbolic links.
656 Only available starting with API version 1.8.
657 timeout=int
659 Command timeout. If non-zero then when the timeout
660 expires the command will be killed.
661 umask=octal
663 The file creation mask to use when executing the com‐
664 mand.
665 use_pty=bool
667 Allocate a pseudo-tty to run the command in, regardless
668 of whether or not I/O logging is in use. By default,
669 sudo will only run the command in a pty when an I/O log
670 plugin is loaded.
671 utmp_user=string
673 User name to use when constructing a new utmp (or
674 utmpx) entry when set_utmp is enabled. This option can
675 be used to set the user field in the utmp entry to the
676 user the command runs as rather than the invoking user.
677 If not set, sudo will base the new entry on the invok‐
678 ing user's existing entry.
679 Unsupported values will be ignored.
681 argv_out
683 The NULL-terminated argument vector to pass to the execve(2)
684 system call when executing the command. The plugin is
685 responsible for allocating and populating the vector.
686 user_env_out
688 The NULL-terminated environment vector to use when executing
689 the command. The plugin is responsible for allocating and
690 populating the vector.
691 list
693 int (*list)(int verbose, const char *list_user,
694 int argc, char * const argv[]);
695 List available privileges for the invoking user. Returns 1 on suc‐
697 cess, 0 on failure and -1 on error. On error, the plugin may
698 optionally call the conversation() or plugin_printf() function with
699 SUDO_CONF_ERROR_MSG to present additional error information to the
700 user.
701 Privileges should be output via the conversation() or
703 plugin_printf() function using SUDO_CONV_INFO_MSG,
704 verbose
706 Flag indicating whether to list in verbose mode or not.
707 list_user
709 The name of a different user to list privileges for if the
710 policy allows it. If NULL, the plugin should list the privi‐
711 leges of the invoking user.
712 argc The number of elements in argv, not counting the final NULL
714 pointer.
715 argv If non-NULL, an argument vector describing a command the user
717 wishes to check against the policy in the same form as what
718 would be passed to the execve(2) system call. If the command
719 is permitted by the policy, the fully-qualified path to the
720 command should be displayed along with any command line argu‐
721 ments.
722 validate
724 int (*validate)(void);
725 The validate() function is called when sudo is run with the -v
727 flag. For policy plugins such as sudoers that cache authentication
728 credentials, this function will validate and cache the credentials.
729 The validate() function should be NULL if the plugin does not sup‐
731 port credential caching.
732 Returns 1 on success, 0 on failure and -1 on error. On error, the
734 plugin may optionally call the conversation() or plugin_printf()
735 function with SUDO_CONF_ERROR_MSG to present additional error
736 information to the user.
737 invalidate
739 void (*invalidate)(int remove);
740 The invalidate() function is called when sudo is called with the -k
742 or -K flag. For policy plugins such as sudoers that cache authen‐
743 tication credentials, this function will invalidate the creden‐
744 tials. If the remove flag is set, the plugin may remove the cre‐
745 dentials instead of simply invalidating them.
746 The invalidate() function should be NULL if the plugin does not
748 support credential caching.
749 init_session
751 int (*init_session)(struct passwd *pwd, char **user_envp[);
752 The init_session() function is called before sudo sets up the exe‐
754 cution environment for the command. It is run in the parent sudo
755 process and before any uid or gid changes. This can be used to
756 perform session setup that is not supported by command_info, such
757 as opening the PAM session. The close() function can be used to
758 tear down the session that was opened by init_session.
759 The pwd argument points to a passwd struct for the user the command
761 will be run as if the uid the command will run as was found in the
762 password database, otherwise it will be NULL.
763 The user_env argument points to the environment the command will
765 run in, in the form of a NULL-terminated vector of “name=value”
766 strings. This is the same string passed back to the front end via
767 the Policy Plugin's user_env_out parameter. If the init_session()
768 function needs to modify the user environment, it should update the
769 pointer stored in user_env. The expected use case is to merge the
770 contents of the PAM environment (if any) with the contents of
771 user_env. NOTE: the user_env parameter is only available starting
772 with API version 1.2. A plugin must check the API version speci‐
773 fied by the sudo front end before using user_env. Failure to do so
774 may result in a crash.
775 Returns 1 on success, 0 on failure and -1 on error. On error, the
777 plugin may optionally call the conversation() or plugin_printf()
778 function with SUDO_CONF_ERROR_MSG to present additional error
779 information to the user.
780 register_hooks
782 void (*register_hooks)(int version,
783 int (*register_hook)(struct sudo_hook *hook));
784 The register_hooks() function is called by the sudo front end to
786 register any hooks the plugin needs. If the plugin does not sup‐
787 port hooks, register_hooks should be set to the NULL pointer.
788 The version argument describes the version of the hooks API sup‐
790 ported by the sudo front end.
791 The register_hook() function should be used to register any sup‐
793 ported hooks the plugin needs. It returns 0 on success, 1 if the
794 hook type is not supported and -1 if the major version in struct
795 hook does not match the front end's major hook API version.
796 See the Hook function API section below for more information about
798 hooks.
799 NOTE: the register_hooks() function is only available starting with
801 API version 1.2. If the sudo front end doesn't support API version
802 1.2 or higher, register_hooks will not be called.
803 deregister_hooks
805 void (*deregister_hooks)(int version,
806 int (*deregister_hook)(struct sudo_hook *hook));
807 The deregister_hooks() function is called by the sudo front end to
809 deregister any hooks the plugin has registered. If the plugin does
810 not support hooks, deregister_hooks should be set to the NULL
811 pointer.
812 The version argument describes the version of the hooks API sup‐
814 ported by the sudo front end.
815 The deregister_hook() function should be used to deregister any
817 hooks that were put in place by the register_hook() function. If
818 the plugin tries to deregister a hook that the front end does not
819 support, deregister_hook will return an error.
820 See the Hook function API section below for more information about
822 hooks.
823 NOTE: the deregister_hooks() function is only available starting
825 with API version 1.2. If the sudo front end doesn't support API
826 version 1.2 or higher, deregister_hooks will not be called.
827 Policy Plugin Version Macros
829 /* Plugin API version major/minor. */
831 #define SUDO_API_VERSION_MAJOR 1
832 #define SUDO_API_VERSION_MINOR 2
833 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
834 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
835 SUDO_API_VERSION_MINOR)
836 /* Getters and setters for API version */
838 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
839 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
840 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
841 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
842 } while(0)
843 #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
844 *(vp) = (*(vp) & 0xffff0000) | (n); \
845 } while(0)
846 I/O plugin API
848 struct io_plugin {
849 #define SUDO_IO_PLUGIN 2
850 unsigned int type; /* always SUDO_IO_PLUGIN */
851 unsigned int version; /* always SUDO_API_VERSION */
852 int (*open)(unsigned int version, sudo_conv_t conversation,
853 sudo_printf_t plugin_printf, char * const settings[],
854 char * const user_info[], char * const command_info[],
855 int argc, char * const argv[], char * const user_env[],
856 char * const plugin_options[]);
857 void (*close)(int exit_status, int error); /* wait status or error */
858 int (*show_version)(int verbose);
859 int (*log_ttyin)(const char *buf, unsigned int len);
860 int (*log_ttyout)(const char *buf, unsigned int len);
861 int (*log_stdin)(const char *buf, unsigned int len);
862 int (*log_stdout)(const char *buf, unsigned int len);
863 int (*log_stderr)(const char *buf, unsigned int len);
864 void (*register_hooks)(int version,
865 int (*register_hook)(struct sudo_hook *hook));
866 void (*deregister_hooks)(int version,
867 int (*deregister_hook)(struct sudo_hook *hook));
868 int (*change_winsize)(unsigned int lines, unsigned int cols);
869 };
870 When an I/O plugin is loaded, sudo runs the command in a pseudo-tty.
872 This makes it possible to log the input and output from the user's ses‐
873 sion. If any of the standard input, standard output or standard error do
874 not correspond to a tty, sudo will open a pipe to capture the I/O for
875 logging before passing it on.
876 The log_ttyin function receives the raw user input from the terminal
878 device (note that this will include input even when echo is disabled,
879 such as when a password is read). The log_ttyout function receives out‐
880 put from the pseudo-tty that is suitable for replaying the user's session
881 at a later time. The log_stdin(), log_stdout() and log_stderr() func‐
882 tions are only called if the standard input, standard output or standard
883 error respectively correspond to something other than a tty.
884 Any of the logging functions may be set to the NULL pointer if no logging
886 is to be performed. If the open function returns 0, no I/O will be sent
887 to the plugin.
888 If a logging function returns an error (-1), the running command will be
890 terminated and all of the plugin's logging functions will be disabled.
891 Other I/O logging plugins will still receive any remaining input or out‐
892 put that has not yet been processed.
893 If an input logging function rejects the data by returning 0, the command
895 will be terminated and the data will not be passed to the command, though
896 it will still be sent to any other I/O logging plugins. If an output
897 logging function rejects the data by returning 0, the command will be
898 terminated and the data will not be written to the terminal, though it
899 will still be sent to any other I/O logging plugins.
900 The io_plugin struct has the following fields:
902 type The type field should always be set to SUDO_IO_PLUGIN.
904 version
906 The version field should be set to SUDO_API_VERSION.
907 This allows sudo to determine the API version the plugin was built
909 against.
910 open
912 int (*open)(unsigned int version, sudo_conv_t conversation,
913 sudo_printf_t plugin_printf, char * const settings[],
914 char * const user_info[], int argc, char * const argv[],
915 char * const user_env[], char * const plugin_options[]);
916 The open() function is run before the log_ttyin(), log_ttyout(),
918 log_stdin(), log_stdout(), log_stderr(), or show_version() func‐
919 tions are called. It is only called if the version is being
920 requested or if the policy plugin's check_policy() function has
921 returned successfully. It returns 1 on success, 0 on failure, -1
922 if a general error occurred, or -2 if there was a usage error. In
923 the latter case, sudo will print a usage message before it exits.
924 If an error occurs, the plugin may optionally call the
925 conversation() or plugin_printf() function with SUDO_CONF_ERROR_MSG
926 to present additional error information to the user.
927 The function arguments are as follows:
929 version
931 The version passed in by sudo allows the plugin to determine
932 the major and minor version number of the plugin API sup‐
933 ported by sudo.
934 conversation
936 A pointer to the conversation() function that may be used by
937 the show_version() function to display version information
938 (see show_version() below). The conversation() function may
939 also be used to display additional error message to the user.
940 The conversation() function returns 0 on success and -1 on
941 failure.
942 plugin_printf
944 A pointer to a printf()-style function that may be used by
945 the show_version() function to display version information
946 (see show_version below). The plugin_printf() function may
947 also be used to display additional error message to the user.
948 The plugin_printf() function returns number of characters
949 printed on success and -1 on failure.
950 settings
952 A vector of user-supplied sudo settings in the form of
953 “name=value” strings. The vector is terminated by a NULL
954 pointer. These settings correspond to flags the user speci‐
955 fied when running sudo. As such, they will only be present
956 when the corresponding flag has been specified on the command
957 line.
958 When parsing settings, the plugin should split on the first
960 equal sign (‘=’) since the name field will never include one
961 itself but the value might.
962 See the Policy plugin API section for a list of all possible
964 settings.
965 user_info
967 A vector of information about the user running the command in
968 the form of “name=value” strings. The vector is terminated
969 by a NULL pointer.
970 When parsing user_info, the plugin should split on the first
972 equal sign (‘=’) since the name field will never include one
973 itself but the value might.
974 See the Policy plugin API section for a list of all possible
976 strings.
977 argc The number of elements in argv, not counting the final NULL
979 pointer.
980 argv If non-NULL, an argument vector describing a command the user
982 wishes to run in the same form as what would be passed to the
983 execve(2) system call.
984 user_env
986 The user's environment in the form of a NULL-terminated vec‐
987 tor of “name=value” strings.
988 When parsing user_env, the plugin should split on the first
990 equal sign (‘=’) since the name field will never include one
991 itself but the value might.
992 plugin_options
994 Any (non-comment) strings immediately after the plugin path
995 are treated as arguments to the plugin. These arguments are
996 split on a white space boundary and are passed to the plugin
997 in the form of a NULL-terminated array of strings. If no
998 arguments were specified, plugin_options will be the NULL
999 pointer.
1000 NOTE: the plugin_options parameter is only available starting
1002 with API version 1.2. A plugin must check the API version
1003 specified by the sudo front end before using plugin_options.
1004 Failure to do so may result in a crash.
1005 close
1007 void (*close)(int exit_status, int error);
1008 The close() function is called when the command being run by sudo
1010 finishes.
1011 The function arguments are as follows:
1013 exit_status
1015 The command's exit status, as returned by the wait(2) system
1016 call. The value of exit_status is undefined if error is non-
1017 zero.
1018 error
1020 If the command could not be executed, this is set to the
1021 value of errno set by the execve(2) system call. If the com‐
1022 mand was successfully executed, the value of error is 0.
1023 show_version
1025 int (*show_version)(int verbose);
1026 The show_version() function is called by sudo when the user speci‐
1028 fies the -V option. The plugin may display its version information
1029 to the user via the conversation() or plugin_printf() function
1030 using SUDO_CONV_INFO_MSG. If the user requests detailed version
1031 information, the verbose flag will be set.
1032 log_ttyin
1034 int (*log_ttyin)(const char *buf, unsigned int len);
1035 The log_ttyin() function is called whenever data can be read from
1037 the user but before it is passed to the running command. This
1038 allows the plugin to reject data if it chooses to (for instance if
1039 the input contains banned content). Returns 1 if the data should
1040 be passed to the command, 0 if the data is rejected (which will
1041 terminate the running command) or -1 if an error occurred.
1042 The function arguments are as follows:
1044 buf The buffer containing user input.
1046 len The length of buf in bytes.
1048 log_ttyout
1050 int (*log_ttyout)(const char *buf, unsigned int len);
1051 The log_ttyout() function is called whenever data can be read from
1053 the command but before it is written to the user's terminal. This
1054 allows the plugin to reject data if it chooses to (for instance if
1055 the output contains banned content). Returns 1 if the data should
1056 be passed to the user, 0 if the data is rejected (which will termi‐
1057 nate the running command) or -1 if an error occurred.
1058 The function arguments are as follows:
1060 buf The buffer containing command output.
1062 len The length of buf in bytes.
1064 log_stdin
1066 int (*log_stdin)(const char *buf, unsigned int len);
1067 The log_stdin() function is only used if the standard input does
1069 not correspond to a tty device. It is called whenever data can be
1070 read from the standard input but before it is passed to the running
1071 command. This allows the plugin to reject data if it chooses to
1072 (for instance if the input contains banned content). Returns 1 if
1073 the data should be passed to the command, 0 if the data is rejected
1074 (which will terminate the running command) or -1 if an error
1075 occurred.
1076 The function arguments are as follows:
1078 buf The buffer containing user input.
1080 len The length of buf in bytes.
1082 log_stdout
1084 int (*log_stdout)(const char *buf, unsigned int len);
1085 The log_stdout() function is only used if the standard output does
1087 not correspond to a tty device. It is called whenever data can be
1088 read from the command but before it is written to the standard out‐
1089 put. This allows the plugin to reject data if it chooses to (for
1090 instance if the output contains banned content). Returns 1 if the
1091 data should be passed to the user, 0 if the data is rejected (which
1092 will terminate the running command) or -1 if an error occurred.
1093 The function arguments are as follows:
1095 buf The buffer containing command output.
1097 len The length of buf in bytes.
1099 log_stderr
1101 int (*log_stderr)(const char *buf, unsigned int len);
1102 The log_stderr() function is only used if the standard error does
1104 not correspond to a tty device. It is called whenever data can be
1105 read from the command but before it is written to the standard
1106 error. This allows the plugin to reject data if it chooses to (for
1107 instance if the output contains banned content). Returns 1 if the
1108 data should be passed to the user, 0 if the data is rejected (which
1109 will terminate the running command) or -1 if an error occurred.
1110 The function arguments are as follows:
1112 buf The buffer containing command output.
1114 len The length of buf in bytes.
1116 register_hooks
1118 See the Policy plugin API section for a description of
1119 register_hooks.
1120 deregister_hooks
1122 See the Policy plugin API section for a description of
1123 deregister_hooks.
1124 change_winsize
1126 int (*change_winsize)(unsigned int lines, unsigned int cols);
1127 The change_winsize() function is called whenever the window size of
1129 the terminal changes from the initial values specified in the
1130 user_info list. It returns 1 on success, 0 on failure, -1 if an
1131 error occurred (which will terminate the running command).
1132 I/O Plugin Version Macros
1134 Same as for the Policy plugin API.
1136 Signal handlers
1138 The sudo front end installs default signal handlers to trap common sig‐
1139 nals while the plugin functions are run. The following signals are
1140 trapped by default before the command is executed:
1141 · SIGALRM
1143 · SIGHUP
1144 · SIGINT
1145 · SIGPIPE
1146 · SIGQUIT
1147 · SIGTERM
1148 · SIGTSTP
1149 · SIGUSR1
1150 · SIGUSR2
1151 If a fatal signal is received before the command is executed, sudo will
1153 call the plugin's close() function with an exit status of 128 plus the
1154 value of the signal that was received. This allows for consistent log‐
1155 ging of commands killed by a signal for plugins that log such information
1156 in their close() function. An exception to this is SIGPIPE, which is
1157 ignored until the command is executed.
1158 A plugin may temporarily install its own signal handlers but must restore
1160 the original handler before the plugin function returns.
1161 Hook function API
1163 Beginning with plugin API version 1.2, it is possible to install hooks
1164 for certain functions called by the sudo front end.
1165 Currently, the only supported hooks relate to the handling of environment
1167 variables. Hooks can be used to intercept attempts to get, set, or
1168 remove environment variables so that these changes can be reflected in
1169 the version of the environment that is used to execute a command. A
1170 future version of the API will support hooking internal sudo front end
1171 functions as well.
1172 Hook structure
1174 Hooks in sudo are described by the following structure:
1176 typedef int (*sudo_hook_fn_t)();
1178 struct sudo_hook {
1180 unsigned int hook_version;
1181 unsigned int hook_type;
1182 sudo_hook_fn_t hook_fn;
1183 void *closure;
1184 };
1185 The sudo_hook structure has the following fields:
1187 hook_version
1189 The hook_version field should be set to SUDO_HOOK_VERSION.
1190 hook_type
1192 The hook_type field may be one of the following supported hook
1193 types:
1194 SUDO_HOOK_SETENV
1196 The C library setenv(3) function. Any registered hooks will
1197 run before the C library implementation. The hook_fn field
1198 should be a function that matches the following typedef:
1199 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1201 const char *value, int overwrite, void *closure);
1202 If the registered hook does not match the typedef the results
1204 are unspecified.
1205 SUDO_HOOK_UNSETENV
1207 The C library unsetenv(3) function. Any registered hooks
1208 will run before the C library implementation. The hook_fn
1209 field should be a function that matches the following type‐
1210 def:
1211 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1213 void *closure);
1214 SUDO_HOOK_GETENV
1216 The C library getenv(3) function. Any registered hooks will
1217 run before the C library implementation. The hook_fn field
1218 should be a function that matches the following typedef:
1219 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1221 char **value, void *closure);
1222 If the registered hook does not match the typedef the results
1224 are unspecified.
1225 SUDO_HOOK_PUTENV
1227 The C library putenv(3) function. Any registered hooks will
1228 run before the C library implementation. The hook_fn field
1229 should be a function that matches the following typedef:
1230 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1232 void *closure);
1233 If the registered hook does not match the typedef the results
1235 are unspecified.
1236 hook_fn
1238 sudo_hook_fn_t hook_fn;
1239 The hook_fn field should be set to the plugin's hook implementa‐
1241 tion. The actual function arguments will vary depending on the
1242 hook_type (see hook_type above). In all cases, the closure field
1243 of struct sudo_hook is passed as the last function parameter. This
1244 can be used to pass arbitrary data to the plugin's hook implementa‐
1245 tion.
1246 The function return value may be one of the following:
1248 SUDO_HOOK_RET_ERROR
1250 The hook function encountered an error.
1251 SUDO_HOOK_RET_NEXT
1253 The hook completed without error, go on to the next hook
1254 (including the native implementation if applicable). For
1255 example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1256 the specified variable was not found in the private copy of
1257 the environment.
1258 SUDO_HOOK_RET_STOP
1260 The hook completed without error, stop processing hooks for
1261 this invocation. This can be used to replace the native
1262 implementation. For example, a setenv hook that operates on
1263 a private copy of the environment but leaves environ
1264 unchanged.
1265 Note that it is very easy to create an infinite loop when hooking C
1267 library functions. For example, a getenv(3) hook that calls the
1268 snprintf(3) function may create a loop if the snprintf(3) implementation
1269 calls getenv(3) to check the locale. To prevent this, you may wish to
1270 use a static variable in the hook function to guard against nested calls.
1271 For example:
1272 static int in_progress = 0; /* avoid recursion */
1274 if (in_progress)
1275 return SUDO_HOOK_RET_NEXT;
1276 in_progress = 1;
1277 ...
1278 in_progress = 0;
1279 return SUDO_HOOK_RET_STOP;
1280 Hook API Version Macros
1282 /* Hook API version major/minor */
1284 #define SUDO_HOOK_VERSION_MAJOR 1
1285 #define SUDO_HOOK_VERSION_MINOR 0
1286 #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1287 SUDO_HOOK_VERSION_MINOR)
1288 For getters and setters see the Policy plugin API.
1290 Remote command execution
1292 The sudo front end does not have native support for running remote com‐
1293 mands. However, starting with sudo 1.8.8, the -h option may be used to
1294 specify a remote host that is passed to the policy plugin. A plugin may
1295 also accept a runas_user in the form of “user@hostname” which will work
1296 with older versions of sudo. It is anticipated that remote commands will
1297 be supported by executing a “helper” program. The policy plugin should
1298 setup the execution environment such that the sudo front end will run the
1299 helper which, in turn, will connect to the remote host and run the com‐
1300 mand.
1301 For example, the policy plugin could utilize ssh to perform remote com‐
1303 mand execution. The helper program would be responsible for running ssh
1304 with the proper options to use a private key or certificate that the
1305 remote host will accept and run a program on the remote host that would
1306 setup the execution environment accordingly.
1307 Note that remote sudoedit functionality must be handled by the policy
1309 plugin, not sudo itself as the front end has no knowledge that a remote
1310 command is being executed. This may be addressed in a future revision of
1311 the plugin API.
1312 Conversation API
1314 If the plugin needs to interact with the user, it may do so via the
1315 conversation() function. A plugin should not attempt to read directly
1316 from the standard input or the user's tty (neither of which are guaran‐
1317 teed to exist). The caller must include a trailing newline in msg if one
1318 is to be printed.
1319 A printf()-style function is also available that can be used to display
1321 informational or error messages to the user, which is usually more conve‐
1322 nient for simple messages where no use input is required.
1323 Conversation function structures
1325 The conversation function takes as arguments pointers to the following
1327 structures:
1328 struct sudo_conv_message {
1330 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1331 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1332 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1333 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1334 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1335 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1336 int msg_type;
1337 int timeout;
1338 const char *msg;
1339 };
1340 #define SUDO_CONV_REPL_MAX 255
1342 struct sudo_conv_reply {
1344 char *reply;
1345 };
1346 typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
1348 struct sudo_conv_callback {
1349 unsigned int version;
1350 void *closure;
1351 sudo_conv_callback_fn_t on_suspend;
1352 sudo_conv_callback_fn_t on_resume;
1353 };
1354 Pointers to the conversation() and printf()-style functions are passed in
1356 to the plugin's open() function when the plugin is initialized. The fol‐
1357 lowing type definitions can be used in the declaration of the open()
1358 function:
1359 typedef int (*sudo_conv_t)(int num_msgs,
1361 const struct sudo_conv_message msgs[],
1362 struct sudo_conv_reply replies[],
1363 struct sudo_conv_callback *callback);
1364 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1366 To use the conversation() function, the plugin must pass an array of
1368 sudo_conv_message and sudo_conv_reply structures. There must be a struct
1369 sudo_conv_message and struct sudo_conv_reply for each message in the con‐
1370 versation. The struct sudo_conv_callback pointer, if not NULL, should
1371 contain function pointers to be called when the sudo process is suspended
1372 and/or resumed during conversation input. The on_suspend and on_resume
1373 functions are called with the signal that caused sudo to be suspended and
1374 the closure pointer from the struct sudo_conv_callback. These functions
1375 should return 0 on success and -1 on error. On error, the conversation
1376 will end and the conversation function will return a value of -1. The
1377 intended use is to allow the plugin to release resources, such as locks,
1378 that should not be held indefinitely while suspended and then reacquire
1379 them when the process is resumed. Note that the functions are not actu‐
1380 ally invoked from within a signal handler.
1381 The plugin is responsible for freeing the reply buffer located in each
1383 struct sudo_conv_reply, if it is not NULL. SUDO_CONV_REPL_MAX represents
1384 the maximum length of the reply buffer (not including the trailing NUL
1385 character). In practical terms, this is the longest password sudo will
1386 support. It is also useful as a maximum value for the memset_s() func‐
1387 tion when clearing passwords filled in by the conversation function.
1388 The printf()-style function uses the same underlying mechanism as the
1390 conversation() function but only supports SUDO_CONV_INFO_MSG and
1391 SUDO_CONV_ERROR_MSG for the msg_type parameter. It can be more conve‐
1392 nient than using the conversation() function if no user reply is needed
1393 and supports standard printf() escape sequences.
1394 See the sample plugin for an example of the conversation() function
1396 usage.
1397 Sudoers group plugin API
1399 The sudoers plugin supports its own plugin interface to allow non-Unix
1400 group lookups. This can be used to query a group source other than the
1401 standard Unix group database. Two sample group plugins are bundled with
1402 sudo, group_file and system_group, are detailed in sudoers(5). Third
1403 party group plugins include a QAS AD plugin available from Quest Soft‐
1404 ware.
1405 A group plugin must declare and populate a sudoers_group_plugin struct in
1407 the global scope. This structure contains pointers to the functions that
1408 implement plugin initialization, cleanup and group lookup.
1409 struct sudoers_group_plugin {
1411 unsigned int version;
1412 int (*init)(int version, sudo_printf_t sudo_printf,
1413 char *const argv[]);
1414 void (*cleanup)(void);
1415 int (*query)(const char *user, const char *group,
1416 const struct passwd *pwd);
1417 };
1418 The sudoers_group_plugin struct has the following fields:
1420 version
1422 The version field should be set to GROUP_API_VERSION.
1423 This allows sudoers to determine the API version the group plugin
1425 was built against.
1426 init
1428 int (*init)(int version, sudo_printf_t plugin_printf,
1429 char *const argv[]);
1430 The init() function is called after sudoers has been parsed but
1432 before any policy checks. It returns 1 on success, 0 on failure
1433 (or if the plugin is not configured), and -1 if a error occurred.
1434 If an error occurs, the plugin may call the plugin_printf() func‐
1435 tion with SUDO_CONF_ERROR_MSG to present additional error informa‐
1436 tion to the user.
1437 The function arguments are as follows:
1439 version
1441 The version passed in by sudoers allows the plugin to deter‐
1442 mine the major and minor version number of the group plugin
1443 API supported by sudoers.
1444 plugin_printf
1446 A pointer to a printf()-style function that may be used to
1447 display informational or error message to the user. Returns
1448 the number of characters printed on success and -1 on fail‐
1449 ure.
1450 argv A NULL-terminated array of arguments generated from the
1452 group_plugin option in sudoers. If no arguments were given,
1453 argv will be NULL.
1454 cleanup
1456 void (*cleanup)();
1457 The cleanup() function is called when sudoers has finished its
1459 group checks. The plugin should free any memory it has allocated
1460 and close open file handles.
1461 query
1463 int (*query)(const char *user, const char *group,
1464 const struct passwd *pwd);
1465 The query() function is used to ask the group plugin whether user
1467 is a member of group.
1468 The function arguments are as follows:
1470 user The name of the user being looked up in the external group
1472 database.
1473 group
1475 The name of the group being queried.
1476 pwd The password database entry for user, if any. If user is not
1478 present in the password database, pwd will be NULL.
1479 Group API Version Macros
1481 /* Sudoers group plugin version major/minor */
1483 #define GROUP_API_VERSION_MAJOR 1
1484 #define GROUP_API_VERSION_MINOR 0
1485 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1486 GROUP_API_VERSION_MINOR)
1487 For getters and setters see the Policy plugin API.
1488
1490 The following revisions have been made to the Sudo Plugin API.
1491 Version 1.0
1493 Initial API version.
1494 Version 1.1 (sudo 1.8.0)
1496 The I/O logging plugin's open() function was modified to take the
1497 command_info list as an argument.
1498 Version 1.2 (sudo 1.8.5)
1500 The Policy and I/O logging plugins' open() functions are now passed
1501 a list of plugin parameters if any are specified in sudo.conf(5).
1502 A simple hooks API has been introduced to allow plugins to hook in
1504 to the system's environment handling functions.
1505 The init_session Policy plugin function is now passed a pointer to
1507 the user environment which can be updated as needed. This can be
1508 used to merge in environment variables stored in the PAM handle
1509 before a command is run.
1510 Version 1.3 (sudo 1.8.7)
1512 Support for the exec_background entry has been added to the
1513 command_info list.
1514 The max_groups and plugin_dir entries were added to the settings
1516 list.
1517 The version() and close() functions are now optional. Previously,
1519 a missing version() or close() function would result in a crash.
1520 If no policy plugin close() function is defined, a default close()
1521 function will be provided by the sudo front end that displays a
1522 warning if the command could not be executed.
1523 The sudo front end now installs default signal handlers to trap
1525 common signals while the plugin functions are run.
1526 Version 1.4 (sudo 1.8.8)
1528 The remote_host entry was added to the settings list.
1529 Version 1.5 (sudo 1.8.9)
1531 The preserve_fds entry was added to the command_info list.
1532 Version 1.6 (sudo 1.8.11)
1534 The behavior when an I/O logging plugin returns an error (-1) has
1535 changed. Previously, the sudo front end took no action when the
1536 log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
1537 log_stderr() function returned an error.
1538 The behavior when an I/O logging plugin returns 0 has changed.
1540 Previously, output from the command would be displayed to the ter‐
1541 minal even if an output logging function returned 0.
1542 Version 1.7 (sudo 1.8.12)
1544 The plugin_path entry was added to the settings list.
1545 The debug_flags entry now starts with a debug file path name and
1547 may occur multiple times if there are multiple plugin-specific
1548 Debug lines in the sudo.conf(5) file.
1549 Version 1.8 (sudo 1.8.15)
1551 The sudoedit_checkdir and sudoedit_follow entries were added to the
1552 command_info list. The default value of sudoedit_checkdir was
1553 changed to true in sudo 1.8.16.
1554 The sudo conversation function now takes a pointer to a struct
1556 sudo_conv_callback as its fourth argument. The sudo_conv_t defini‐
1557 tion has been updated to match. The plugin must specify that it
1558 supports plugin API version 1.8 or higher to receive a conversation
1559 function pointer that supports this argument.
1560 Version 1.9 (sudo 1.8.16)
1562 The execfd entry was added to the command_info list.
1563 Version 1.10 (sudo 1.8.19)
1565 The umask entry was added to the user_info list. The iolog_group,
1566 iolog_mode, and iolog_user entries were added to the command_info
1567 list.
1568 Version 1.11 (sudo 1.8.20)
1570 The timeout entry was added to the settings list.
1571 Version 1.12 (sudo 1.8.21)
1573 The change_winsize field was added to the io_plugin struct.
1574
1576 sudo.conf(5), sudoers(5), sudo(8)
1577
1579 Many people have worked on sudo over the years; this version consists of
1580 code written primarily by:
1581 Todd C. Miller
1583 See the CONTRIBUTORS file in the sudo distribution
1585 (https://www.sudo.ws/contributors.html) for an exhaustive list of people
1586 who have contributed to sudo.
1587
1589 If you feel you have found a bug in sudo, please submit a bug report at
1590 https://bugzilla.sudo.ws/
1591
1593 Limited free support is available via the sudo-users mailing list, see
1594 https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
1595 the archives.
1596
1598 sudo is provided “AS IS” and any express or implied warranties, includ‐
1599 ing, but not limited to, the implied warranties of merchantability and
1600 fitness for a particular purpose are disclaimed. See the LICENSE file
1601 distributed with sudo or https://www.sudo.ws/license.html for complete
1602 details.
1603Sudo 1.8.23 March 21, 2018 Sudo 1.8.23