1 Copyright (c) 2009-2011 Todd C. Miller <Todd.Miller@courtesan.com>
3 Permission to use, copy, modify, and distribute this software for any
4 purpose with or without fee is hereby granted, provided that the above
5 copyright notice and this permission notice appear in all copies.
7 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
8 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
9 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
10 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
11 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
12 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
13 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
14 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
20 sudo_plugin - Sudo Plugin API
24 Starting with version 1.8, B<sudo> supports a plugin API
25 for policy and session logging. By default, the I<sudoers> policy
26 plugin and an associated I/O logging plugin are used. Via the plugin
27 API, B<sudo> can be configured to use alternate policy and/or I/O
28 logging plugins provided by third parties. The plugins to be used
29 are specified via the F<@sysconfdir@/sudo.conf> file.
31 The API is versioned with a major and minor number. The minor
32 version number is incremented when additions are made. The major
33 number is incremented when incompatible changes are made. A plugin
34 should be check the version passed to it and make sure that the
35 major version matches.
37 The plugin API is defined by the C<sudo_plugin.h> header file.
39 =head2 The sudo.conf File
41 The F<@sysconfdir@/sudo.conf> file contains plugin configuration directives.
42 Currently, the only supported keyword is the C<Plugin> directive,
43 which causes a plugin plugin to be loaded.
45 A C<Plugin> line consists of the C<Plugin> keyword, followed by the
46 I<symbol_name> and the I<path> to the shared object containing the
47 plugin. The I<symbol_name> is the name of the C<struct policy_plugin>
48 or C<struct io_plugin> in the plugin shared object. The I<path>
49 may be fully qualified or relative. If not fully qualified it is
50 relative to the F<@prefix@/libexec> directory. Any additional
51 parameters after the I<path> are ignored. Lines that don't begin
52 with C<Plugin> or C<Path> are silently ignored.
54 The same shared object may contain multiple plugins, each with a
55 different symbol name. The shared object file must be owned by uid
56 0 and only writable by its owner. Because of ambiguities that arise
57 from composite policies, only a single policy plugin may be specified.
58 This limitation does not apply to I/O plugins.
61 # Default @sysconfdir@/sudo.conf file
64 # Plugin plugin_name plugin_path
65 # Path askpass /path/to/askpass
67 # The plugin_path is relative to @prefix@/libexec unless
69 # The plugin_name corresponds to a global symbol in the plugin
70 # that contains the plugin interface structure.
72 Plugin sudoers_policy sudoers.so
73 Plugin sudoers_io sudoers.so
75 =head2 Policy Plugin API
77 A policy plugin must declare and populate a C<policy_plugin> struct
78 in the global scope. This structure contains pointers to the functions
79 that implement the B<sudo> policy checks. The name of the symbol should
80 be specified in F<@sysconfdir@/sudo.conf> along with a path to the plugin
81 so that B<sudo> can load it.
83 struct policy_plugin {
84 #define SUDO_POLICY_PLUGIN 1
85 unsigned int type; /* always SUDO_POLICY_PLUGIN */
86 unsigned int version; /* always SUDO_API_VERSION */
87 int (*open)(unsigned int version, sudo_conv_t conversation,
88 sudo_printf_t plugin_printf, char * const settings[],
89 char * const user_info[], char * const user_env[]);
90 void (*close)(int exit_status, int error);
91 int (*show_version)(int verbose);
92 int (*check_policy)(int argc, char * const argv[],
93 char *env_add[], char **command_info[],
94 char **argv_out[], char **user_env_out[]);
95 int (*list)(int argc, char * const argv[], int verbose,
96 const char *list_user);
97 int (*validate)(void);
98 void (*invalidate)(int remove);
99 int (*init_session)(struct passwd *pwd);
102 The policy_plugin struct has the following fields:
108 The C<type> field should always be set to SUDO_POLICY_PLUGIN.
112 The C<version> field should be set to SUDO_API_VERSION.
114 This allows B<sudo> to determine the API version the plugin was
119 int (*open)(unsigned int version, sudo_conv_t conversation,
120 sudo_printf_t plugin_printf, char * const settings[],
121 char * const user_info[], char * const user_env[]);
123 Returns 1 on success, 0 on failure, -1 if a general error occurred,
124 or -2 if there was a usage error. In the latter case, B<sudo> will
125 print a usage message before it exits. If an error occurs, the
126 plugin may optionally call the conversation or plugin_printf function
127 with C<SUDO_CONF_ERROR_MSG> to present additional error information
130 The function arguments are as follows:
136 The version passed in by B<sudo> allows the plugin to determine the
137 major and minor version number of the plugin API supported by
142 A pointer to the conversation function that can be used by the
143 plugin to interact with the user (see below).
144 Returns 0 on success and -1 on failure.
148 A pointer to a printf-style function that may be used to display
149 informational or error messages (see below).
150 Returns the number of characters printed on success and -1 on failure.
154 A vector of user-supplied B<sudo> settings in the form of "name=value"
155 strings. The vector is terminated by a C<NULL> pointer. These
156 settings correspond to flags the user specified when running B<sudo>.
157 As such, they will only be present when the corresponding flag has
158 been specified on the command line.
160 When parsing I<settings>, the plugin should split on the B<first>
161 equal sign ('=') since the I<name> field will never include one
162 itself but the I<value> might.
166 =item debug_level=number
168 A numeric debug level, from 1-9, if specified via the C<-D> flag.
170 =item runas_user=string
172 The user name or uid to to run the command as, if specified via the
175 =item runas_group=string
177 The group name or gid to to run the command as, if specified via
182 The prompt to use when requesting a password, if specified via
187 Set to true if the user specified the C<-H> flag. If true, set the
188 C<HOME> environment variable to the target user's home directory.
190 =item preserve_environment=bool
192 Set to true if the user specified the C<-E> flag, indicating that
193 the user wishes to preserve the environment.
197 Set to true if the user specified the C<-s> flag, indicating that
198 the user wishes to run a shell.
200 =item login_shell=bool
202 Set to true if the user specified the C<-i> flag, indicating that
203 the user wishes to run a login shell.
205 =item implied_shell=bool
207 If the user does not specify a program on the command line, B<sudo>
208 will pass the plugin the path to the user's shell and set
209 I<implied_shell> to true. This allows B<sudo> with no arguments
210 to be used similarly to L<su(1)>. If the plugin does not to support
211 this usage, it may return a value of -2 from the C<check_policy>
212 function, which will cause B<sudo> to print a usage message and
215 =item preserve_groups=bool
217 Set to true if the user specified the C<-P> flag, indicating that
218 the user wishes to preserve the group vector instead of setting it
219 based on the runas user.
221 =item ignore_ticket=bool
223 Set to true if the user specified the C<-k> flag along with a
224 command, indicating that the user wishes to ignore any cached
225 authentication credentials.
227 =item noninteractive=bool
229 Set to true if the user specified the C<-n> flag, indicating that
230 B<sudo> should operate in non-interactive mode. The plugin may
231 reject a command run in non-interactive mode if user interaction
234 =item login_class=string
236 BSD login class to use when setting resource limits and nice value,
237 if specified by the C<-c> flag.
239 =item selinux_role=string
241 SELinux role to use when executing the command, if specified by
244 =item selinux_type=string
246 SELinux type to use when executing the command, if specified by
249 =item bsdauth_type=string
251 Authentication type, if specified by the C<-a> flag, to use on
252 systems where BSD authentication is supported.
254 =item network_addrs=list
256 A space-separated list of IP network addresses and netmasks in the
257 form "addr/netmask", e.g. "192.168.1.2/255.255.255.0". The address
258 and netmask pairs may be either IPv4 or IPv6, depending on what the
259 operating system supports. If the address contains a colon (':'),
260 it is an IPv6 address, else it is IPv4.
262 =item progname=string
264 The command name that sudo was run as, typically "sudo" or "sudoedit".
268 Set to true when the C<-e> flag is is specified or if invoked as
269 B<sudoedit>. The plugin shall substitute an editor into I<argv>
270 in the I<check_policy> function or return C<-2> with a usage error
271 if the plugin does not support I<sudoedit>. For more information,
272 see the I<check_policy> section.
274 =item closefrom=number
276 If specified, the user has requested via the C<-C> flag that B<sudo>
277 close all files descriptors with a value of I<number> or higher.
278 The plugin may optionally pass this, or another value, back in the
279 I<command_info> list.
283 Additional settings may be added in the future so the plugin should
284 silently ignore settings that it does not recognize.
288 A vector of information about the user running the command in the form of
289 "name=value" strings. The vector is terminated by a C<NULL> pointer.
291 When parsing I<user_info>, the plugin should split on the B<first>
292 equal sign ('=') since the I<name> field will never include one
293 itself but the I<value> might.
299 The name of the user invoking B<sudo>.
303 The real user ID of the user invoking B<sudo>.
307 The real group ID of the user invoking B<sudo>.
311 The user's supplementary group list formatted as a string of
312 comma-separated group IDs.
316 The user's current working directory.
320 The path to the user's terminal device. If the user has no terminal
321 device associated with the session, the value will be empty, as in
326 The local machine's hostname as returned by the C<gethostname()>
331 The number of lines the user's terminal supports. If there is
332 no terminal device available, a default value of 24 is used.
336 The number of columns the user's terminal supports. If there is
337 no terminal device available, a default value of 80 is used.
343 The user's environment in the form of a C<NULL>-terminated vector of
344 "name=value" strings.
346 When parsing I<user_env>, the plugin should split on the B<first>
347 equal sign ('=') since the I<name> field will never include one
348 itself but the I<value> might.
354 void (*close)(int exit_status, int error);
356 The C<close> function is called when the command being run by B<sudo>
359 The function arguments are as follows:
365 The command's exit status, as returned by the wait(2) system call.
366 The value of C<exit_status> is undefined if C<error> is non-zero.
370 If the command could not be executed, this is set to the value of
371 C<errno> set by the execve(2) system call. The plugin is responsible
372 for displaying error information via the conversation or plugin_printf
373 function. If the command was successfully executed, the value of
380 int (*show_version)(int verbose);
382 The C<show_version> function is called by B<sudo> when the user specifies
383 the C<-V> option. The plugin may display its version information
384 to the user via the conversation or plugin_printf function using
385 C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
386 information, the verbose flag will be set.
390 int (*check_policy)(int argc, char * const argv[]
391 char *env_add[], char **command_info[],
392 char **argv_out[], char **user_env_out[]);
394 The I<check_policy> function is called by B<sudo> to determine
395 whether the user is allowed to run the specified commands.
397 If the I<sudoedit> option was enabled in the I<settings> array
398 passed to the I<open> function, the user has requested I<sudoedit>
399 mode. I<sudoedit> is a mechanism for editing one or more files
400 where an editor is run with the user's credentials instead of with
401 elevated privileges. B<sudo> achieves this by creating user-writable
402 temporary copies of the files to be edited and then overwriting the
403 originals with the temporary copies after editing is complete. If
404 the plugin supports B<sudoedit>, it should choose the editor to be
405 used, potentially from a variable in the user's environment, such
406 as C<EDITOR>, and include it in I<argv_out> (note that environment
407 variables may include command line flags). The files to be edited
408 should be copied from I<argv> into I<argv_out>, separated from the
409 editor and its arguments by a C<"--"> element. The C<"--"> will
410 be removed by B<sudo> before the editor is executed. The plugin
411 should also set I<sudoedit=true> in the I<command_info> list.
413 The I<check_policy> function returns 1 if the command is allowed,
414 0 if not allowed, -1 for a general error, or -2 for a usage error
415 or if B<sudoedit> was specified but is unsupported by the plugin.
416 In the latter case, B<sudo> will print a usage message before it
417 exits. If an error occurs, the plugin may optionally call the
418 conversation or plugin_printf function with C<SUDO_CONF_ERROR_MSG>
419 to present additional error information to the user.
421 The function arguments are as follows:
427 The number of elements in I<argv>, not counting the final C<NULL>
432 The argument vector describing the command the user wishes to run,
433 in the same form as what would be passed to the execve() system
434 call. The vector is terminated by a C<NULL> pointer.
438 Additional environment variables specified by the user on the command
439 line in the form of a C<NULL>-terminated vector of "name=value"
440 strings. The plugin may reject the command if one or more variables
441 are not allowed to be set, or it may silently ignore such variables.
443 When parsing I<env_add>, the plugin should split on the B<first>
444 equal sign ('=') since the I<name> field will never include one
445 itself but the I<value> might.
449 Information about the command being run in the form of "name=value"
450 strings. These values are used by B<sudo> to set the execution
451 environment when running a command. The plugin is responsible for
452 creating and populating the vector, which must be terminated with
453 a C<NULL> pointer. The following values are recognized by B<sudo>:
459 Fully qualified path to the command to be executed.
463 User ID to run the command as.
467 Effective user ID to run the command as.
468 If not specified, the value of I<runas_uid> is used.
472 Group ID to run the command as.
476 Effective group ID to run the command as.
477 If not specified, the value of I<runas_gid> is used.
479 =item runas_groups=list
481 The supplementary group vector to use for the command in the form
482 of a comma-separated list of group IDs. If I<preserve_groups>
483 is set, this option is ignored.
485 =item login_class=string
487 BSD login class to use when setting resource limits and nice value
488 (optional). This option is only set on systems that support login
491 =item preserve_groups=bool
493 If set, B<sudo> will preserve the user's group vector instead of
494 initializing the group vector based on C<runas_user>.
498 The current working directory to change to when executing the command.
502 If set, prevent the command from executing other programs.
506 The root directory to use when running the command.
510 Nice value (priority) to use when executing the command. The nice
511 value, if specified, overrides the priority associated with the
512 I<login_class> on BSD systems.
516 The file creation mask to use when executing the command.
518 =item selinux_role=string
520 SELinux role to use when executing the command.
522 =item selinux_type=string
524 SELinux type to use when executing the command.
528 Command timeout. If non-zero then when the timeout expires the
529 command will be killed.
533 Set to true when in I<sudoedit> mode. The plugin may enable
534 I<sudoedit> mode even if B<sudo> was not invoked as B<sudoedit>.
535 This allows the plugin to perform command substitution and transparently
536 enable I<sudoedit> when the user attempts to run an editor.
538 =item closefrom=number
540 If specified, B<sudo> will close all files descriptors with a value
541 of I<number> or higher.
543 =item iolog_compress=bool
545 Set to true if the I/O logging plugins, if any, should compress the
546 log data. This is a hint to the I/O logging plugin which may choose
549 =item iolog_path=string
551 Fully qualified path to the file or directory in which I/O log is
552 to be stored. This is a hint to the I/O logging plugin which may
553 choose to ignore it. If no I/O logging plugin is loaded, this
554 setting has no effect.
556 =item iolog_stdin=bool
558 Set to true if the I/O logging plugins, if any, should log the
559 standard input if it is not connected to a terminal device. This
560 is a hint to the I/O logging plugin which may choose to ignore it.
562 =item iolog_stdout=bool
564 Set to true if the I/O logging plugins, if any, should log the
565 standard output if it is not connected to a terminal device. This
566 is a hint to the I/O logging plugin which may choose to ignore it.
568 =item iolog_stderr=bool
570 Set to true if the I/O logging plugins, if any, should log the
571 standard error if it is not connected to a terminal device. This
572 is a hint to the I/O logging plugin which may choose to ignore it.
574 =item iolog_ttyin=bool
576 Set to true if the I/O logging plugins, if any, should log all
577 terminal input. This only includes input typed by the user and not
578 from a pipe or redirected from a file. This is a hint to the I/O
579 logging plugin which may choose to ignore it.
581 =item iolog_ttyout=bool
583 Set to true if the I/O logging plugins, if any, should log all
584 terminal output. This only includes output to the screen, not
585 output to a pipe or file. This is a hint to the I/O logging plugin
586 which may choose to ignore it.
590 Allocate a pseudo-tty to run the command in, regardless of whether
591 or not I/O logging is in use. By default, B<sudo> will only run
592 the command in a pty when an I/O log plugin is loaded.
596 Create a utmp (or utmpx) entry when a pseudo-tty is allocated. By
597 default, the new entry will be a copy of the user's existing utmp
598 entry (if any), with the tty, time, type and pid fields updated.
600 =item utmp_user=string
602 User name to use when constructing a new utmp (or utmpx) entry when
603 I<set_utmp> is enabled. This option can be used to set the user
604 field in the utmp entry to the user the command runs as rather than
605 the invoking user. If not set, B<sudo> will base the new entry on
606 the invoking user's existing entry.
610 Unsupported values will be ignored.
614 The C<NULL>-terminated argument vector to pass to the execve()
615 system call when executing the command. The plugin is responsible
616 for allocating and populating the vector.
620 The C<NULL>-terminated environment vector to use when executing the
621 command. The plugin is responsible for allocating and populating
628 int (*list)(int verbose, const char *list_user,
629 int argc, char * const argv[]);
631 List available privileges for the invoking user. Returns 1 on
632 success, 0 on failure and -1 on error. On error, the plugin may
633 optionally call the conversation or plugin_printf function with
634 C<SUDO_CONF_ERROR_MSG> to present additional error information to
637 Privileges should be output via the conversation or plugin_printf
638 function using C<SUDO_CONV_INFO_MSG>.
644 Flag indicating whether to list in verbose mode or not.
648 The name of a different user to list privileges for if the policy
649 allows it. If C<NULL>, the plugin should list the privileges of
654 The number of elements in I<argv>, not counting the final C<NULL>
659 If non-C<NULL>, an argument vector describing a command the user
660 wishes to check against the policy in the same form as what would
661 be passed to the execve() system call. If the command is permitted
662 by the policy, the fully-qualified path to the command should be
663 displayed along with any command line arguments.
669 int (*validate)(void);
671 The C<validate> function is called when B<sudo> is run with the
672 C<-v> flag. For policy plugins such as I<sudoers> that cache
673 authentication credentials, this function will validate and cache
676 The C<validate> function should be C<NULL> if the plugin does not
677 support credential caching.
679 Returns 1 on success, 0 on failure and -1 on error.
680 On error, the plugin may optionally call the conversation or plugin_printf
681 function with C<SUDO_CONF_ERROR_MSG> to present additional
682 error information to the user.
686 void (*invalidate)(int remove);
688 The C<invalidate> function is called when B<sudo> is called with
689 the C<-k> or C<-K> flag. For policy plugins such as I<sudoers> that
690 cache authentication credentials, this function will invalidate the
691 credentials. If the I<remove> flag is set, the plugin may remove
692 the credentials instead of simply invalidating them.
694 The C<invalidate> function should be C<NULL> if the plugin does not
695 support credential caching.
699 int (*init_session)(struct passwd *pwd);
701 The C<init_session> function is called when B<sudo> sets up the
702 execution environment for the command, immediately before the
703 contents of the I<command_info> list are applied (before the uid
704 changes). This can be used to do session setup that is not supported
705 by I<command_info>, such as opening the PAM session.
707 The I<pwd> argument points to a passwd struct for the user the
708 command will be run as if the uid the command will run as was found
709 in the password database, otherwise it will be NULL.
711 Returns 1 on success, 0 on failure and -1 on error.
712 On error, the plugin may optionally call the conversation or plugin_printf
713 function with C<SUDO_CONF_ERROR_MSG> to present additional
714 error information to the user.
718 =head3 Version macros
720 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
721 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
722 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
723 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
725 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
726 *(vp) = (*(vp) & 0xffff0000) | (n); \
729 #define SUDO_API_VERSION_MAJOR 1
730 #define SUDO_API_VERSION_MINOR 0
731 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
732 SUDO_API_VERSION_MINOR)
734 =head2 I/O Plugin API
737 #define SUDO_IO_PLUGIN 2
738 unsigned int type; /* always SUDO_IO_PLUGIN */
739 unsigned int version; /* always SUDO_API_VERSION */
740 int (*open)(unsigned int version, sudo_conv_t conversation
741 sudo_printf_t plugin_printf, char * const settings[],
742 char * const user_info[], int argc, char * const argv[],
743 char * const user_env[]);
744 void (*close)(int exit_status, int error); /* wait status or error */
745 int (*show_version)(int verbose);
746 int (*log_ttyin)(const char *buf, unsigned int len);
747 int (*log_ttyout)(const char *buf, unsigned int len);
748 int (*log_stdin)(const char *buf, unsigned int len);
749 int (*log_stdout)(const char *buf, unsigned int len);
750 int (*log_stderr)(const char *buf, unsigned int len);
753 When an I/O plugin is loaded, B<sudo> runs the command in a pseudo-tty.
754 This makes it possible to log the input and output from the user's
755 session. If any of the standard input, standard output or standard
756 error do not correspond to a tty, B<sudo> will open a pipe to capture
757 the I/O for logging before passing it on.
759 The log_ttyin function receives the raw user input from the terminal
760 device (note that this will include input even when echo is disabled,
761 such as when a password is read). The log_ttyout function receives
762 output from the pseudo-tty that is suitable for replaying the user's
763 session at a later time. The log_stdin, log_stdout and log_stderr
764 functions are only called if the standard input, standard output
765 or standard error respectively correspond to something other than
768 Any of the logging functions may be set to the NULL
769 pointer if no logging is to be performed. If the open function
770 returns C<0>, no I/O will be sent to the plugin.
772 The io_plugin struct has the following fields:
778 The C<type> field should always be set to SUDO_IO_PLUGIN
782 The C<version> field should be set to SUDO_API_VERSION.
784 This allows B<sudo> to determine the API version the plugin was
789 int (*open)(unsigned int version, sudo_conv_t conversation
790 sudo_printf_t plugin_printf, char * const settings[],
791 char * const user_info[], int argc, char * const argv[],
792 char * const user_env[]);
794 The I<open> function is run before the I<log_input>, I<log_output>
795 or I<show_version> functions are called. It is only called if the
796 version is being requested or the I<check_policy> function has
797 returned successfully. It returns 1 on success, 0 on failure, -1
798 if a general error occurred, or -2 if there was a usage error. In
799 the latter case, B<sudo> will print a usage message before it exits.
800 If an error occurs, the plugin may optionally call the conversation
801 or plugin_printf function with C<SUDO_CONF_ERROR_MSG> to present
802 additional error information to the user.
804 The function arguments are as follows:
810 The version passed in by B<sudo> allows the plugin to determine the
811 major and minor version number of the plugin API supported by
816 A pointer to the conversation function that may be used by the
817 I<show_version> function to display version information (see
818 show_version below). The conversation function may also be used
819 to display additional error message to the user.
820 The conversation function returns 0 on success and -1 on failure.
824 A pointer to a printf-style function that may be used by the
825 I<show_version> function to display version information (see
826 show_version below). The plugin_printf function may also be used
827 to display additional error message to the user.
828 The plugin_printf function returns number of characters printed on
829 success and -1 on failure.
833 A vector of user-supplied B<sudo> settings in the form of "name=value"
834 strings. The vector is terminated by a C<NULL> pointer. These
835 settings correspond to flags the user specified when running B<sudo>.
836 As such, they will only be present when the corresponding flag has
837 been specified on the command line.
839 When parsing I<settings>, the plugin should split on the B<first>
840 equal sign ('=') since the I<name> field will never include one
841 itself but the I<value> might.
843 See the L<Policy Plugin API> section for a list of all possible settings.
847 A vector of information about the user running the command in the form of
848 "name=value" strings. The vector is terminated by a C<NULL> pointer.
850 When parsing I<user_info>, the plugin should split on the B<first>
851 equal sign ('=') since the I<name> field will never include one
852 itself but the I<value> might.
854 See the L<Policy Plugin API> section for a list of all possible strings.
858 The number of elements in I<argv>, not counting the final C<NULL>
863 If non-C<NULL>, an argument vector describing a command the user
864 wishes to run in the same form as what would be passed to the
865 execve() system call.
869 The user's environment in the form of a C<NULL>-terminated vector of
870 "name=value" strings.
872 When parsing I<user_env>, the plugin should split on the B<first>
873 equal sign ('=') since the I<name> field will never include one
874 itself but the I<value> might.
880 void (*close)(int exit_status, int error);
882 The C<close> function is called when the command being run by B<sudo>
885 The function arguments are as follows:
891 The command's exit status, as returned by the wait(2) system call.
892 The value of C<exit_status> is undefined if C<error> is non-zero.
896 If the command could not be executed, this is set to the value of
897 C<errno> set by the execve(2) system call. If the command was
898 successfully executed, the value of C<error> is 0.
904 int (*show_version)(int verbose);
906 The C<show_version> function is called by B<sudo> when the user specifies
907 the C<-V> option. The plugin may display its version information
908 to the user via the conversation or plugin_printf function using
909 C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
910 information, the verbose flag will be set.
914 int (*log_ttyin)(const char *buf, unsigned int len);
916 The I<log_ttyin> function is called whenever data can be read from
917 the user but before it is passed to the running command. This
918 allows the plugin to reject data if it chooses to (for instance
919 if the input contains banned content). Returns C<1> if the data
920 should be passed to the command, C<0> if the data is rejected
921 (which will terminate the command) or C<-1> if an error occurred.
923 The function arguments are as follows:
929 The buffer containing user input.
933 The length of I<buf> in bytes.
939 int (*log_ttyout)(const char *buf, unsigned int len);
941 The I<log_ttyout> function is called whenever data can be read from
942 the command but before it is written to the user's terminal. This
943 allows the plugin to reject data if it chooses to (for instance
944 if the output contains banned content). Returns C<1> if the data
945 should be passed to the user, C<0> if the data is rejected
946 (which will terminate the command) or C<-1> if an error occurred.
948 The function arguments are as follows:
954 The buffer containing command output.
958 The length of I<buf> in bytes.
964 int (*log_stdin)(const char *buf, unsigned int len);
966 The I<log_stdin> function is only used if the standard input does
967 not correspond to a tty device. It is called whenever data can be
968 read from the standard input but before it is passed to the running
969 command. This allows the plugin to reject data if it chooses to
970 (for instance if the input contains banned content). Returns C<1>
971 if the data should be passed to the command, C<0> if the data is
972 rejected (which will terminate the command) or C<-1> if an error
975 The function arguments are as follows:
981 The buffer containing user input.
985 The length of I<buf> in bytes.
991 int (*log_stdout)(const char *buf, unsigned int len);
993 The I<log_stdout> function is only used if the standard output does
994 not correspond to a tty device. It is called whenever data can be
995 read from the command but before it is written to the standard
996 output. This allows the plugin to reject data if it chooses to
997 (for instance if the output contains banned content). Returns C<1>
998 if the data should be passed to the user, C<0> if the data is
999 rejected (which will terminate the command) or C<-1> if an error
1002 The function arguments are as follows:
1008 The buffer containing command output.
1012 The length of I<buf> in bytes.
1018 int (*log_stderr)(const char *buf, unsigned int len);
1020 The I<log_stderr> function is only used if the standard error does
1021 not correspond to a tty device. It is called whenever data can be
1022 read from the command but before it is written to the standard
1023 error. This allows the plugin to reject data if it chooses to
1024 (for instance if the output contains banned content). Returns C<1>
1025 if the data should be passed to the user, C<0> if the data is
1026 rejected (which will terminate the command) or C<-1> if an error
1029 The function arguments are as follows:
1035 The buffer containing command output.
1039 The length of I<buf> in bytes.
1045 =head3 Version macros
1047 Same as for the L<Policy Plugin API>.
1049 =head2 Conversation API
1051 If the plugin needs to interact with the user, it may do so via the
1052 conversation function. A plugin should not attempt to read directly
1053 from the standard input or the user's tty (neither of which are
1054 guaranteed to exist). The caller must include a trailing newline
1055 in C<msg> if one is to be printed.
1057 A printf-style function is also available that can be used to display
1058 informational or error messages to the user, which is usually more
1059 convenient for simple messages where no use input is required.
1061 struct sudo_conv_message {
1062 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1063 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1064 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1065 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1066 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1067 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1073 struct sudo_conv_reply {
1077 typedef int (*sudo_conv_t)(int num_msgs,
1078 const struct sudo_conv_message msgs[],
1079 struct sudo_conv_reply replies[]);
1081 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1083 Pointers to the conversation and printf-style functions are passed
1084 in to the plugin's C<open> function when the plugin is initialized.
1086 To use the conversation function, the plugin must pass an array of
1087 C<sudo_conv_message> and C<sudo_conv_reply> structures. There must
1088 be a C<struct sudo_conv_message> and C<struct sudo_conv_reply> for
1089 each message in the conversation. The plugin is responsible for
1090 freeing the reply buffer filled in to the C<struct sudo_conv_reply>,
1093 The printf-style function uses the same underlying mechanism as the
1094 conversation function but only supports C<SUDO_CONV_INFO_MSG> and
1095 C<SUDO_CONV_ERROR_MSG> for the I<msg_type> parameter. It can be
1096 more convenient than using the conversation function if no user
1097 reply is needed and supports standard printf() escape sequences.
1099 See the sample plugin for an example of the conversation function usage.
1101 =head2 Sudoers Group Plugin API
1103 The I<sudoers> module supports a plugin interface to allow non-Unix
1104 group lookups. This can be used to query a group source other than
1105 the standard Unix group database. A sample group plugin is bundled
1106 with B<sudo> that implements file-based lookups. Third party group
1107 plugins include a QAS AD plugin available from Quest Software.
1109 A group plugin must declare and populate a C<sudoers_group_plugin>
1110 struct in the global scope. This structure contains pointers to
1111 the functions that implement plugin initialization, cleanup and
1114 struct sudoers_group_plugin {
1115 unsigned int version;
1116 int (*init)(int version, sudo_printf_t sudo_printf,
1117 char *const argv[]);
1118 void (*cleanup)(void);
1119 int (*query)(const char *user, const char *group,
1120 const struct passwd *pwd);
1123 The C<sudoers_group_plugin> struct has the following fields:
1129 The C<version> field should be set to GROUP_API_VERSION.
1131 This allows I<sudoers> to determine the API version the group plugin
1136 int (*init)(int version, sudo_printf_t plugin_printf,
1137 char *const argv[]);
1139 The I<init> function is called after I<sudoers> has been parsed but
1140 before any policy checks. It returns 1 on success, 0 on failure
1141 (or if the plugin is not configured), and -1 if a error occurred.
1142 If an error occurs, the plugin may call the plugin_printf function
1143 with C<SUDO_CONF_ERROR_MSG> to present additional error information
1146 The function arguments are as follows:
1152 The version passed in by I<sudoers> allows the plugin to determine the
1153 major and minor version number of the group plugin API supported by
1158 A pointer to a printf-style function that may be used to display
1159 informational or error message to the user.
1160 Returns the number of characters printed on success and -1 on failure.
1164 A NULL-terminated array of arguments generated from the I<group_plugin>
1165 option in I<sudoers>. If no arguments were given, I<argv> will be
1174 The I<cleanup> function is called when I<sudoers> has finished its
1175 group checks. The plugin should free any memory it has allocated
1176 and close open file handles.
1180 int (*query)(const char *user, const char *group,
1181 const struct passwd *pwd);
1183 The I<query> function is used to ask the group plugin whether I<user>
1184 is a member of I<group>.
1186 The function arguments are as follows:
1192 The name of the user being looked up in the external group database.
1196 The name of the group being queried.
1200 The password database entry for I<user>, if any. If I<user> is not
1201 present in the password database, I<pwd> will be C<NULL>.
1207 =head3 Version Macros
1209 /* Sudoers group plugin version major/minor */
1210 #define GROUP_API_VERSION_MAJOR 1
1211 #define GROUP_API_VERSION_MINOR 0
1212 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1213 GROUP_API_VERSION_MINOR)
1215 /* Getters and setters for group version */
1216 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1217 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1218 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1219 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1221 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1222 *(vp) = (*(vp) & 0xffff0000) | (n); \
1227 L<sudoers(5)>, L<sudo(8)>
1231 If you feel you have found a bug in B<sudo>, please submit a bug report
1232 at http://www.sudo.ws/sudo/bugs/
1236 Limited free support is available via the sudo-workers mailing list,
1237 see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1238 search the archives.
1242 B<sudo> is provided ``AS IS'' and any express or implied warranties,
1243 including, but not limited to, the implied warranties of merchantability
1244 and fitness for a particular purpose are disclaimed. See the LICENSE
1245 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
1246 for complete details.