1 Copyright (c) 2009-2012 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_flags=string
168 A comma-separated list of debug flags that correspond to B<sudo>'s
169 C<Debug> entry in F<@sysconfdir@/sudo.conf>, if there is one. The
170 flags are passed to the plugin as they appear in F<@sysconfdir@/sudo.conf>.
171 The syntax used by B<sudo> and the I<sudoers> plugin is
172 I<subsystem>@I<priority> but the plugin is free to use a different
173 format so long as it does not include a command C<,>.
175 For reference, the priorities supported by the B<sudo> front end and
176 I<sudoers> are: I<crit>, I<err>, I<warn>, I<notice>, I<diag>,
177 I<info>, I<trace> and I<debug>.
179 The following subsystems are defined: I<main>, I<memory>, I<args>,
180 I<exec>, I<pty>, I<utmp>, I<conv>, I<pcomm>, I<util>, I<list>,
181 I<netif>, I<audit>, I<edit>, I<selinux>, I<ldap>, I<match>, I<parser>,
182 I<alias>, I<defaults>, I<auth>, I<env>, I<logging>, I<nss>, I<rbtree>,
183 I<perms>, I<plugin>. The subsystem I<all> includes every subsystem.
185 There is not currently a way to specify a set of debug flags specific
186 to the plugin--the flags are shared by B<sudo> and the plugin.
188 =item debug_level=number
190 This setting has been deprecated in favor of I<debug_flags>.
192 =item runas_user=string
194 The user name or uid to to run the command as, if specified via the
197 =item runas_group=string
199 The group name or gid to to run the command as, if specified via
204 The prompt to use when requesting a password, if specified via
209 Set to true if the user specified the C<-H> flag. If true, set the
210 C<HOME> environment variable to the target user's home directory.
212 =item preserve_environment=bool
214 Set to true if the user specified the C<-E> flag, indicating that
215 the user wishes to preserve the environment.
219 Set to true if the user specified the C<-s> flag, indicating that
220 the user wishes to run a shell.
222 =item login_shell=bool
224 Set to true if the user specified the C<-i> flag, indicating that
225 the user wishes to run a login shell.
227 =item implied_shell=bool
229 If the user does not specify a program on the command line, B<sudo>
230 will pass the plugin the path to the user's shell and set
231 I<implied_shell> to true. This allows B<sudo> with no arguments
232 to be used similarly to L<su(1)>. If the plugin does not to support
233 this usage, it may return a value of -2 from the C<check_policy>
234 function, which will cause B<sudo> to print a usage message and
237 =item preserve_groups=bool
239 Set to true if the user specified the C<-P> flag, indicating that
240 the user wishes to preserve the group vector instead of setting it
241 based on the runas user.
243 =item ignore_ticket=bool
245 Set to true if the user specified the C<-k> flag along with a
246 command, indicating that the user wishes to ignore any cached
247 authentication credentials.
249 =item noninteractive=bool
251 Set to true if the user specified the C<-n> flag, indicating that
252 B<sudo> should operate in non-interactive mode. The plugin may
253 reject a command run in non-interactive mode if user interaction
256 =item login_class=string
258 BSD login class to use when setting resource limits and nice value,
259 if specified by the C<-c> flag.
261 =item selinux_role=string
263 SELinux role to use when executing the command, if specified by
266 =item selinux_type=string
268 SELinux type to use when executing the command, if specified by
271 =item bsdauth_type=string
273 Authentication type, if specified by the C<-a> flag, to use on
274 systems where BSD authentication is supported.
276 =item network_addrs=list
278 A space-separated list of IP network addresses and netmasks in the
279 form "addr/netmask", e.g. "192.168.1.2/255.255.255.0". The address
280 and netmask pairs may be either IPv4 or IPv6, depending on what the
281 operating system supports. If the address contains a colon (':'),
282 it is an IPv6 address, else it is IPv4.
284 =item progname=string
286 The command name that sudo was run as, typically "sudo" or "sudoedit".
290 Set to true when the C<-e> flag is is specified or if invoked as
291 B<sudoedit>. The plugin shall substitute an editor into I<argv>
292 in the I<check_policy> function or return C<-2> with a usage error
293 if the plugin does not support I<sudoedit>. For more information,
294 see the I<check_policy> section.
296 =item closefrom=number
298 If specified, the user has requested via the C<-C> flag that B<sudo>
299 close all files descriptors with a value of I<number> or higher.
300 The plugin may optionally pass this, or another value, back in the
301 I<command_info> list.
305 Additional settings may be added in the future so the plugin should
306 silently ignore settings that it does not recognize.
310 A vector of information about the user running the command in the form of
311 "name=value" strings. The vector is terminated by a C<NULL> pointer.
313 When parsing I<user_info>, the plugin should split on the B<first>
314 equal sign ('=') since the I<name> field will never include one
315 itself but the I<value> might.
321 The name of the user invoking B<sudo>.
325 The real user ID of the user invoking B<sudo>.
329 The real group ID of the user invoking B<sudo>.
333 The user's supplementary group list formatted as a string of
334 comma-separated group IDs.
338 The user's current working directory.
342 The path to the user's terminal device. If the user has no terminal
343 device associated with the session, the value will be empty, as in
348 The local machine's hostname as returned by the C<gethostname()>
353 The number of lines the user's terminal supports. If there is
354 no terminal device available, a default value of 24 is used.
358 The number of columns the user's terminal supports. If there is
359 no terminal device available, a default value of 80 is used.
365 The user's environment in the form of a C<NULL>-terminated vector of
366 "name=value" strings.
368 When parsing I<user_env>, the plugin should split on the B<first>
369 equal sign ('=') since the I<name> field will never include one
370 itself but the I<value> might.
376 void (*close)(int exit_status, int error);
378 The C<close> function is called when the command being run by B<sudo>
381 The function arguments are as follows:
387 The command's exit status, as returned by the wait(2) system call.
388 The value of C<exit_status> is undefined if C<error> is non-zero.
392 If the command could not be executed, this is set to the value of
393 C<errno> set by the execve(2) system call. The plugin is responsible
394 for displaying error information via the conversation or plugin_printf
395 function. If the command was successfully executed, the value of
402 int (*show_version)(int verbose);
404 The C<show_version> function is called by B<sudo> when the user specifies
405 the C<-V> option. The plugin may display its version information
406 to the user via the conversation or plugin_printf function using
407 C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
408 information, the verbose flag will be set.
412 int (*check_policy)(int argc, char * const argv[]
413 char *env_add[], char **command_info[],
414 char **argv_out[], char **user_env_out[]);
416 The I<check_policy> function is called by B<sudo> to determine
417 whether the user is allowed to run the specified commands.
419 If the I<sudoedit> option was enabled in the I<settings> array
420 passed to the I<open> function, the user has requested I<sudoedit>
421 mode. I<sudoedit> is a mechanism for editing one or more files
422 where an editor is run with the user's credentials instead of with
423 elevated privileges. B<sudo> achieves this by creating user-writable
424 temporary copies of the files to be edited and then overwriting the
425 originals with the temporary copies after editing is complete. If
426 the plugin supports B<sudoedit>, it should choose the editor to be
427 used, potentially from a variable in the user's environment, such
428 as C<EDITOR>, and include it in I<argv_out> (note that environment
429 variables may include command line flags). The files to be edited
430 should be copied from I<argv> into I<argv_out>, separated from the
431 editor and its arguments by a C<"--"> element. The C<"--"> will
432 be removed by B<sudo> before the editor is executed. The plugin
433 should also set I<sudoedit=true> in the I<command_info> list.
435 The I<check_policy> function returns 1 if the command is allowed,
436 0 if not allowed, -1 for a general error, or -2 for a usage error
437 or if B<sudoedit> was specified but is unsupported by the plugin.
438 In the latter case, B<sudo> will print a usage message before it
439 exits. If an error occurs, the plugin may optionally call the
440 conversation or plugin_printf function with C<SUDO_CONF_ERROR_MSG>
441 to present additional error information to the user.
443 The function arguments are as follows:
449 The number of elements in I<argv>, not counting the final C<NULL>
454 The argument vector describing the command the user wishes to run,
455 in the same form as what would be passed to the execve() system
456 call. The vector is terminated by a C<NULL> pointer.
460 Additional environment variables specified by the user on the command
461 line in the form of a C<NULL>-terminated vector of "name=value"
462 strings. The plugin may reject the command if one or more variables
463 are not allowed to be set, or it may silently ignore such variables.
465 When parsing I<env_add>, the plugin should split on the B<first>
466 equal sign ('=') since the I<name> field will never include one
467 itself but the I<value> might.
471 Information about the command being run in the form of "name=value"
472 strings. These values are used by B<sudo> to set the execution
473 environment when running a command. The plugin is responsible for
474 creating and populating the vector, which must be terminated with
475 a C<NULL> pointer. The following values are recognized by B<sudo>:
481 Fully qualified path to the command to be executed.
485 User ID to run the command as.
489 Effective user ID to run the command as.
490 If not specified, the value of I<runas_uid> is used.
494 Group ID to run the command as.
498 Effective group ID to run the command as.
499 If not specified, the value of I<runas_gid> is used.
501 =item runas_groups=list
503 The supplementary group vector to use for the command in the form
504 of a comma-separated list of group IDs. If I<preserve_groups>
505 is set, this option is ignored.
507 =item login_class=string
509 BSD login class to use when setting resource limits and nice value
510 (optional). This option is only set on systems that support login
513 =item preserve_groups=bool
515 If set, B<sudo> will preserve the user's group vector instead of
516 initializing the group vector based on C<runas_user>.
520 The current working directory to change to when executing the command.
524 If set, prevent the command from executing other programs.
528 The root directory to use when running the command.
532 Nice value (priority) to use when executing the command. The nice
533 value, if specified, overrides the priority associated with the
534 I<login_class> on BSD systems.
538 The file creation mask to use when executing the command.
540 =item selinux_role=string
542 SELinux role to use when executing the command.
544 =item selinux_type=string
546 SELinux type to use when executing the command.
550 Command timeout. If non-zero then when the timeout expires the
551 command will be killed.
555 Set to true when in I<sudoedit> mode. The plugin may enable
556 I<sudoedit> mode even if B<sudo> was not invoked as B<sudoedit>.
557 This allows the plugin to perform command substitution and transparently
558 enable I<sudoedit> when the user attempts to run an editor.
560 =item closefrom=number
562 If specified, B<sudo> will close all files descriptors with a value
563 of I<number> or higher.
565 =item iolog_compress=bool
567 Set to true if the I/O logging plugins, if any, should compress the
568 log data. This is a hint to the I/O logging plugin which may choose
571 =item iolog_path=string
573 Fully qualified path to the file or directory in which I/O log is
574 to be stored. This is a hint to the I/O logging plugin which may
575 choose to ignore it. If no I/O logging plugin is loaded, this
576 setting has no effect.
578 =item iolog_stdin=bool
580 Set to true if the I/O logging plugins, if any, should log the
581 standard input if it is not connected to a terminal device. This
582 is a hint to the I/O logging plugin which may choose to ignore it.
584 =item iolog_stdout=bool
586 Set to true if the I/O logging plugins, if any, should log the
587 standard output if it is not connected to a terminal device. This
588 is a hint to the I/O logging plugin which may choose to ignore it.
590 =item iolog_stderr=bool
592 Set to true if the I/O logging plugins, if any, should log the
593 standard error if it is not connected to a terminal device. This
594 is a hint to the I/O logging plugin which may choose to ignore it.
596 =item iolog_ttyin=bool
598 Set to true if the I/O logging plugins, if any, should log all
599 terminal input. This only includes input typed by the user and not
600 from a pipe or redirected from a file. This is a hint to the I/O
601 logging plugin which may choose to ignore it.
603 =item iolog_ttyout=bool
605 Set to true if the I/O logging plugins, if any, should log all
606 terminal output. This only includes output to the screen, not
607 output to a pipe or file. This is a hint to the I/O logging plugin
608 which may choose to ignore it.
612 Allocate a pseudo-tty to run the command in, regardless of whether
613 or not I/O logging is in use. By default, B<sudo> will only run
614 the command in a pty when an I/O log plugin is loaded.
618 Create a utmp (or utmpx) entry when a pseudo-tty is allocated. By
619 default, the new entry will be a copy of the user's existing utmp
620 entry (if any), with the tty, time, type and pid fields updated.
622 =item utmp_user=string
624 User name to use when constructing a new utmp (or utmpx) entry when
625 I<set_utmp> is enabled. This option can be used to set the user
626 field in the utmp entry to the user the command runs as rather than
627 the invoking user. If not set, B<sudo> will base the new entry on
628 the invoking user's existing entry.
632 Unsupported values will be ignored.
636 The C<NULL>-terminated argument vector to pass to the execve()
637 system call when executing the command. The plugin is responsible
638 for allocating and populating the vector.
642 The C<NULL>-terminated environment vector to use when executing the
643 command. The plugin is responsible for allocating and populating
650 int (*list)(int verbose, const char *list_user,
651 int argc, char * const argv[]);
653 List available privileges for the invoking user. Returns 1 on
654 success, 0 on failure and -1 on error. On error, the plugin may
655 optionally call the conversation or plugin_printf function with
656 C<SUDO_CONF_ERROR_MSG> to present additional error information to
659 Privileges should be output via the conversation or plugin_printf
660 function using C<SUDO_CONV_INFO_MSG>.
666 Flag indicating whether to list in verbose mode or not.
670 The name of a different user to list privileges for if the policy
671 allows it. If C<NULL>, the plugin should list the privileges of
676 The number of elements in I<argv>, not counting the final C<NULL>
681 If non-C<NULL>, an argument vector describing a command the user
682 wishes to check against the policy in the same form as what would
683 be passed to the execve() system call. If the command is permitted
684 by the policy, the fully-qualified path to the command should be
685 displayed along with any command line arguments.
691 int (*validate)(void);
693 The C<validate> function is called when B<sudo> is run with the
694 C<-v> flag. For policy plugins such as I<sudoers> that cache
695 authentication credentials, this function will validate and cache
698 The C<validate> function should be C<NULL> if the plugin does not
699 support credential caching.
701 Returns 1 on success, 0 on failure and -1 on error.
702 On error, the plugin may optionally call the conversation or plugin_printf
703 function with C<SUDO_CONF_ERROR_MSG> to present additional
704 error information to the user.
708 void (*invalidate)(int remove);
710 The C<invalidate> function is called when B<sudo> is called with
711 the C<-k> or C<-K> flag. For policy plugins such as I<sudoers> that
712 cache authentication credentials, this function will invalidate the
713 credentials. If the I<remove> flag is set, the plugin may remove
714 the credentials instead of simply invalidating them.
716 The C<invalidate> function should be C<NULL> if the plugin does not
717 support credential caching.
721 int (*init_session)(struct passwd *pwd);
723 The C<init_session> function is called when B<sudo> sets up the
724 execution environment for the command, immediately before the
725 contents of the I<command_info> list are applied (before the uid
726 changes). This can be used to do session setup that is not supported
727 by I<command_info>, such as opening the PAM session.
729 The I<pwd> argument points to a passwd struct for the user the
730 command will be run as if the uid the command will run as was found
731 in the password database, otherwise it will be NULL.
733 Returns 1 on success, 0 on failure and -1 on error.
734 On error, the plugin may optionally call the conversation or plugin_printf
735 function with C<SUDO_CONF_ERROR_MSG> to present additional
736 error information to the user.
740 =head3 Version macros
742 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
743 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
744 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
745 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
747 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
748 *(vp) = (*(vp) & 0xffff0000) | (n); \
751 #define SUDO_API_VERSION_MAJOR 1
752 #define SUDO_API_VERSION_MINOR 0
753 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
754 SUDO_API_VERSION_MINOR)
756 =head2 I/O Plugin API
759 #define SUDO_IO_PLUGIN 2
760 unsigned int type; /* always SUDO_IO_PLUGIN */
761 unsigned int version; /* always SUDO_API_VERSION */
762 int (*open)(unsigned int version, sudo_conv_t conversation
763 sudo_printf_t plugin_printf, char * const settings[],
764 char * const user_info[], int argc, char * const argv[],
765 char * const user_env[]);
766 void (*close)(int exit_status, int error); /* wait status or error */
767 int (*show_version)(int verbose);
768 int (*log_ttyin)(const char *buf, unsigned int len);
769 int (*log_ttyout)(const char *buf, unsigned int len);
770 int (*log_stdin)(const char *buf, unsigned int len);
771 int (*log_stdout)(const char *buf, unsigned int len);
772 int (*log_stderr)(const char *buf, unsigned int len);
775 When an I/O plugin is loaded, B<sudo> runs the command in a pseudo-tty.
776 This makes it possible to log the input and output from the user's
777 session. If any of the standard input, standard output or standard
778 error do not correspond to a tty, B<sudo> will open a pipe to capture
779 the I/O for logging before passing it on.
781 The log_ttyin function receives the raw user input from the terminal
782 device (note that this will include input even when echo is disabled,
783 such as when a password is read). The log_ttyout function receives
784 output from the pseudo-tty that is suitable for replaying the user's
785 session at a later time. The log_stdin, log_stdout and log_stderr
786 functions are only called if the standard input, standard output
787 or standard error respectively correspond to something other than
790 Any of the logging functions may be set to the NULL
791 pointer if no logging is to be performed. If the open function
792 returns C<0>, no I/O will be sent to the plugin.
794 The io_plugin struct has the following fields:
800 The C<type> field should always be set to SUDO_IO_PLUGIN
804 The C<version> field should be set to SUDO_API_VERSION.
806 This allows B<sudo> to determine the API version the plugin was
811 int (*open)(unsigned int version, sudo_conv_t conversation
812 sudo_printf_t plugin_printf, char * const settings[],
813 char * const user_info[], int argc, char * const argv[],
814 char * const user_env[]);
816 The I<open> function is run before the I<log_input>, I<log_output>
817 or I<show_version> functions are called. It is only called if the
818 version is being requested or the I<check_policy> function has
819 returned successfully. It returns 1 on success, 0 on failure, -1
820 if a general error occurred, or -2 if there was a usage error. In
821 the latter case, B<sudo> will print a usage message before it exits.
822 If an error occurs, the plugin may optionally call the conversation
823 or plugin_printf function with C<SUDO_CONF_ERROR_MSG> to present
824 additional error information to the user.
826 The function arguments are as follows:
832 The version passed in by B<sudo> allows the plugin to determine the
833 major and minor version number of the plugin API supported by
838 A pointer to the conversation function that may be used by the
839 I<show_version> function to display version information (see
840 show_version below). The conversation function may also be used
841 to display additional error message to the user.
842 The conversation function returns 0 on success and -1 on failure.
846 A pointer to a printf-style function that may be used by the
847 I<show_version> function to display version information (see
848 show_version below). The plugin_printf function may also be used
849 to display additional error message to the user.
850 The plugin_printf function returns number of characters printed on
851 success and -1 on failure.
855 A vector of user-supplied B<sudo> settings in the form of "name=value"
856 strings. The vector is terminated by a C<NULL> pointer. These
857 settings correspond to flags the user specified when running B<sudo>.
858 As such, they will only be present when the corresponding flag has
859 been specified on the command line.
861 When parsing I<settings>, the plugin should split on the B<first>
862 equal sign ('=') since the I<name> field will never include one
863 itself but the I<value> might.
865 See the L<Policy Plugin API> section for a list of all possible settings.
869 A vector of information about the user running the command in the form of
870 "name=value" strings. The vector is terminated by a C<NULL> pointer.
872 When parsing I<user_info>, 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.
876 See the L<Policy Plugin API> section for a list of all possible strings.
880 The number of elements in I<argv>, not counting the final C<NULL>
885 If non-C<NULL>, an argument vector describing a command the user
886 wishes to run in the same form as what would be passed to the
887 execve() system call.
891 The user's environment in the form of a C<NULL>-terminated vector of
892 "name=value" strings.
894 When parsing I<user_env>, the plugin should split on the B<first>
895 equal sign ('=') since the I<name> field will never include one
896 itself but the I<value> might.
902 void (*close)(int exit_status, int error);
904 The C<close> function is called when the command being run by B<sudo>
907 The function arguments are as follows:
913 The command's exit status, as returned by the wait(2) system call.
914 The value of C<exit_status> is undefined if C<error> is non-zero.
918 If the command could not be executed, this is set to the value of
919 C<errno> set by the execve(2) system call. If the command was
920 successfully executed, the value of C<error> is 0.
926 int (*show_version)(int verbose);
928 The C<show_version> function is called by B<sudo> when the user specifies
929 the C<-V> option. The plugin may display its version information
930 to the user via the conversation or plugin_printf function using
931 C<SUDO_CONV_INFO_MSG>. If the user requests detailed version
932 information, the verbose flag will be set.
936 int (*log_ttyin)(const char *buf, unsigned int len);
938 The I<log_ttyin> function is called whenever data can be read from
939 the user but before it is passed to the running command. This
940 allows the plugin to reject data if it chooses to (for instance
941 if the input contains banned content). Returns C<1> if the data
942 should be passed to the command, C<0> if the data is rejected
943 (which will terminate the command) or C<-1> if an error occurred.
945 The function arguments are as follows:
951 The buffer containing user input.
955 The length of I<buf> in bytes.
961 int (*log_ttyout)(const char *buf, unsigned int len);
963 The I<log_ttyout> function is called whenever data can be read from
964 the command but before it is written to the user's terminal. This
965 allows the plugin to reject data if it chooses to (for instance
966 if the output contains banned content). Returns C<1> if the data
967 should be passed to the user, C<0> if the data is rejected
968 (which will terminate the command) or C<-1> if an error occurred.
970 The function arguments are as follows:
976 The buffer containing command output.
980 The length of I<buf> in bytes.
986 int (*log_stdin)(const char *buf, unsigned int len);
988 The I<log_stdin> function is only used if the standard input does
989 not correspond to a tty device. It is called whenever data can be
990 read from the standard input but before it is passed to the running
991 command. This allows the plugin to reject data if it chooses to
992 (for instance if the input contains banned content). Returns C<1>
993 if the data should be passed to the command, C<0> if the data is
994 rejected (which will terminate the command) or C<-1> if an error
997 The function arguments are as follows:
1003 The buffer containing user input.
1007 The length of I<buf> in bytes.
1013 int (*log_stdout)(const char *buf, unsigned int len);
1015 The I<log_stdout> function is only used if the standard output does
1016 not correspond to a tty device. It is called whenever data can be
1017 read from the command but before it is written to the standard
1018 output. This allows the plugin to reject data if it chooses to
1019 (for instance if the output contains banned content). Returns C<1>
1020 if the data should be passed to the user, C<0> if the data is
1021 rejected (which will terminate the command) or C<-1> if an error
1024 The function arguments are as follows:
1030 The buffer containing command output.
1034 The length of I<buf> in bytes.
1040 int (*log_stderr)(const char *buf, unsigned int len);
1042 The I<log_stderr> function is only used if the standard error does
1043 not correspond to a tty device. It is called whenever data can be
1044 read from the command but before it is written to the standard
1045 error. This allows the plugin to reject data if it chooses to
1046 (for instance if the output contains banned content). Returns C<1>
1047 if the data should be passed to the user, C<0> if the data is
1048 rejected (which will terminate the command) or C<-1> if an error
1051 The function arguments are as follows:
1057 The buffer containing command output.
1061 The length of I<buf> in bytes.
1067 =head3 Version macros
1069 Same as for the L<Policy Plugin API>.
1071 =head2 Conversation API
1073 If the plugin needs to interact with the user, it may do so via the
1074 conversation function. A plugin should not attempt to read directly
1075 from the standard input or the user's tty (neither of which are
1076 guaranteed to exist). The caller must include a trailing newline
1077 in C<msg> if one is to be printed.
1079 A printf-style function is also available that can be used to display
1080 informational or error messages to the user, which is usually more
1081 convenient for simple messages where no use input is required.
1083 struct sudo_conv_message {
1084 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1085 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1086 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1087 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1088 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1089 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1090 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1096 struct sudo_conv_reply {
1100 typedef int (*sudo_conv_t)(int num_msgs,
1101 const struct sudo_conv_message msgs[],
1102 struct sudo_conv_reply replies[]);
1104 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1106 Pointers to the conversation and printf-style functions are passed
1107 in to the plugin's C<open> function when the plugin is initialized.
1109 To use the conversation function, the plugin must pass an array of
1110 C<sudo_conv_message> and C<sudo_conv_reply> structures. There must
1111 be a C<struct sudo_conv_message> and C<struct sudo_conv_reply> for
1112 each message in the conversation. The plugin is responsible for
1113 freeing the reply buffer filled in to the C<struct sudo_conv_reply>,
1116 The printf-style function uses the same underlying mechanism as the
1117 conversation function but only supports C<SUDO_CONV_INFO_MSG>,
1118 C<SUDO_CONV_ERROR_MSG> and C<SUDO_CONV_DEBUG_MSG> for the I<msg_type>
1119 parameter. It can be more convenient than using the conversation
1120 function if no user reply is needed and supports standard printf()
1123 Unlike, C<SUDO_CONV_INFO_MSG> and C<SUDO_CONV_ERROR_MSG>, messages
1124 sent with the <SUDO_CONV_DEBUG_MSG> I<msg_type> are not directly
1125 user-visible. Instead, they are logged to the file specified in
1126 the C<Debug> statement (if any) in the F<@sysconfdir@/sudo.conf>
1127 file. This allows a plugin to log debugging information and is
1128 intended to be used in conjunction with the I<debug_flags> setting.
1130 See the sample plugin for an example of the conversation function usage.
1132 =head2 Sudoers Group Plugin API
1134 The I<sudoers> module supports a plugin interface to allow non-Unix
1135 group lookups. This can be used to query a group source other than
1136 the standard Unix group database. A sample group plugin is bundled
1137 with B<sudo> that implements file-based lookups. Third party group
1138 plugins include a QAS AD plugin available from Quest Software.
1140 A group plugin must declare and populate a C<sudoers_group_plugin>
1141 struct in the global scope. This structure contains pointers to
1142 the functions that implement plugin initialization, cleanup and
1145 struct sudoers_group_plugin {
1146 unsigned int version;
1147 int (*init)(int version, sudo_printf_t sudo_printf,
1148 char *const argv[]);
1149 void (*cleanup)(void);
1150 int (*query)(const char *user, const char *group,
1151 const struct passwd *pwd);
1154 The C<sudoers_group_plugin> struct has the following fields:
1160 The C<version> field should be set to GROUP_API_VERSION.
1162 This allows I<sudoers> to determine the API version the group plugin
1167 int (*init)(int version, sudo_printf_t plugin_printf,
1168 char *const argv[]);
1170 The I<init> function is called after I<sudoers> has been parsed but
1171 before any policy checks. It returns 1 on success, 0 on failure
1172 (or if the plugin is not configured), and -1 if a error occurred.
1173 If an error occurs, the plugin may call the plugin_printf function
1174 with C<SUDO_CONF_ERROR_MSG> to present additional error information
1177 The function arguments are as follows:
1183 The version passed in by I<sudoers> allows the plugin to determine the
1184 major and minor version number of the group plugin API supported by
1189 A pointer to a printf-style function that may be used to display
1190 informational or error message to the user.
1191 Returns the number of characters printed on success and -1 on failure.
1195 A NULL-terminated array of arguments generated from the I<group_plugin>
1196 option in I<sudoers>. If no arguments were given, I<argv> will be
1205 The I<cleanup> function is called when I<sudoers> has finished its
1206 group checks. The plugin should free any memory it has allocated
1207 and close open file handles.
1211 int (*query)(const char *user, const char *group,
1212 const struct passwd *pwd);
1214 The I<query> function is used to ask the group plugin whether I<user>
1215 is a member of I<group>.
1217 The function arguments are as follows:
1223 The name of the user being looked up in the external group database.
1227 The name of the group being queried.
1231 The password database entry for I<user>, if any. If I<user> is not
1232 present in the password database, I<pwd> will be C<NULL>.
1238 =head3 Version Macros
1240 /* Sudoers group plugin version major/minor */
1241 #define GROUP_API_VERSION_MAJOR 1
1242 #define GROUP_API_VERSION_MINOR 0
1243 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1244 GROUP_API_VERSION_MINOR)
1246 /* Getters and setters for group version */
1247 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1248 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1249 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1250 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1252 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1253 *(vp) = (*(vp) & 0xffff0000) | (n); \
1258 L<sudoers(5)>, L<sudo(8)>
1262 If you feel you have found a bug in B<sudo>, please submit a bug report
1263 at http://www.sudo.ws/sudo/bugs/
1267 Limited free support is available via the sudo-workers mailing list,
1268 see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1269 search the archives.
1273 B<sudo> is provided ``AS IS'' and any express or implied warranties,
1274 including, but not limited to, the implied warranties of merchantability
1275 and fitness for a particular purpose are disclaimed. See the LICENSE
1276 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
1277 for complete details.