2 .\" Copyright (c) 2009-2013 Todd C. Miller <Todd.Miller@courtesan.com>
4 .\" Permission to use, copy, modify, and distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
18 .Dt SUDO_PLUGIN @mansectform@
19 .Os Sudo @PACKAGE_VERSION@
24 Starting with version 1.8,
27 for policy and session logging.
30 policy plugin and an associated I/O logging plugin are used.
33 can be configured to use alternate policy and/or I/O logging plugins
34 provided by third parties.
35 The plugins to be used are specified in the
36 .Xr sudo.conf @mansectform@
39 The API is versioned with a major and minor number.
40 The minor version number is incremented when additions are made.
41 The major number is incremented when incompatible changes are made.
42 A plugin should be check the version passed to it and make sure that the
43 major version matches.
45 The plugin API is defined by the
49 A policy plugin must declare and populate a
51 struct in the global scope.
52 This structure contains pointers to the functions that implement the
55 The name of the symbol should be specified in
56 .Xr sudo.conf @mansectform@
57 along with a path to the plugin so that
61 struct policy_plugin {
62 #define SUDO_POLICY_PLUGIN 1
63 unsigned int type; /* always SUDO_POLICY_PLUGIN */
64 unsigned int version; /* always SUDO_API_VERSION */
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 void (*close)(int exit_status, int error);
70 int (*show_version)(int verbose);
71 int (*check_policy)(int argc, char * const argv[],
72 char *env_add[], char **command_info[],
73 char **argv_out[], char **user_env_out[]);
74 int (*list)(int argc, char * const argv[], int verbose,
75 const char *list_user);
76 int (*validate)(void);
77 void (*invalidate)(int remove);
78 int (*init_session)(struct passwd *pwd, char **user_env[]);
79 void (*register_hooks)(int version,
80 int (*register_hook)(struct sudo_hook *hook));
81 void (*deregister_hooks)(int version,
82 int (*deregister_hook)(struct sudo_hook *hook));
86 The policy_plugin struct has the following fields:
91 field should always be set to SUDO_POLICY_PLUGIN.
95 field should be set to
96 .Dv SUDO_API_VERSION .
100 to determine the API version the plugin was
103 .Bd -literal -compact
104 int (*open)(unsigned int version, sudo_conv_t conversation,
105 sudo_printf_t plugin_printf, char * const settings[],
106 char * const user_info[], char * const user_env[],
107 char * const plugin_options[]);
110 Returns 1 on success, 0 on failure, \-1 if a general error occurred,
111 or \-2 if there was a usage error.
114 will print a usage message before it exits.
115 If an error occurs, the plugin may optionally call the
120 .Dv SUDO_CONF_ERROR_MSG
121 to present additional error information to the user.
123 The function arguments are as follows:
126 The version passed in by
128 allows the plugin to determine the
129 major and minor version number of the plugin API supported by
134 function that can be used by the plugin to interact with the user (see below).
135 Returns 0 on success and \-1 on failure.
138 .Fn printf Ns No -style
139 function that may be used to display informational or error messages
141 Returns the number of characters printed on success and \-1 on failure.
143 A vector of user-supplied
145 settings in the form of
148 The vector is terminated by a
151 These settings correspond to flags the user specified when running
153 As such, they will only be present when the corresponding flag has
154 been specified on the command line.
158 the plugin should split on the
164 field will never include one
169 .It bsdauth_type=string
170 Authentication type, if specified by the
173 systems where BSD authentication is supported.
175 If specified, the user has requested via the
179 close all files descriptors with a value of
182 The plugin may optionally pass this, or another value, back in the
185 .It debug_flags=string
186 A comma-separated list of debug flags that correspond to
190 .Xr sudo.conf @mansectform@ ,
192 The flags are passed to the plugin as they appear in
193 .Xr sudo.conf @mansectform@ .
199 .Em subsystem Ns No @ Ns Em priority
200 but the plugin is free to use a different
201 format so long as it does not include a comma
203 There is not currently a way to specify a set of debug flags specific
204 to the plugin--the flags are shared by
207 .It debug_level=number
208 This setting has been deprecated in favor of
210 .It ignore_ticket=bool
211 Set to true if the user specified the
214 command, indicating that the user wishes to ignore any cached
215 authentication credentials.
221 to be used similarly to
223 If the plugin does not to support this usage, it may return a value of \-2
226 function, which will cause
228 to print a usage message and
230 .It implied_shell=bool
231 If the user does not specify a program on the command line,
233 will pass the plugin the path to the user's shell and set
234 .It login_class=string
235 BSD login class to use when setting resource limits and nice value,
240 Set to true if the user specified the
242 flag, indicating that
243 the user wishes to run a login shell.
245 The maximum number of groups a user may belong to.
246 This will only be present if there is a corresponding setting in
247 .Xr sudo.conf @mansectform@ .
248 .It network_addrs=list
249 A space-separated list of IP network addresses and netmasks in the
253 .Dq 192.168.1.2/255.255.255.0 .
254 The address and netmask pairs may be either IPv4 or IPv6, depending on
255 what the operating system supports.
256 If the address contains a colon
258 it is an IPv6 address, else it is IPv4.
259 .It noninteractive=bool
260 Set to true if the user specified the
262 flag, indicating that
264 should operate in non-interactive mode.
265 The plugin may reject a command run in non-interactive mode if user
266 interaction is required.
267 .It plugin_dir=string
268 The default plugin directory used by the
271 This is the default directory set at compile time and may not
272 correspond to the directory the running plugin was loaded from.
273 It may be used by a plugin to locate support files.
274 .It preserve_environment=bool
275 Set to true if the user specified the
277 flag, indicating that
278 the user wishes to preserve the environment.
279 .It preserve_groups=bool
280 Set to true if the user specified the
282 flag, indicating that
283 the user wishes to preserve the group vector instead of setting it
284 based on the runas user.
286 The command name that sudo was run as, typically
291 The prompt to use when requesting a password, if specified via
296 Set to true if the user specified the
298 flag, indicating that
299 the user wishes to run a shell.
300 .It runas_group=string
301 The group name or gid to to run the command as, if specified via
305 .It runas_user=string
306 The user name or uid to to run the command as, if specified via the
309 .It selinux_role=string
310 SELinux role to use when executing the command, if specified by
314 .It selinux_type=string
315 SELinux type to use when executing the command, if specified by
320 Set to true if the user specified the
325 environment variable to the target user's home directory.
329 flag is is specified or if invoked as
331 The plugin shall substitute an editor into
335 function or return \-2 with a usage error
336 if the plugin does not support
338 For more information, see the
343 Additional settings may be added in the future so the plugin should
344 silently ignore settings that it does not recognize.
346 A vector of information about the user running the command in the form of
349 The vector is terminated by a
355 the plugin should split on the
361 field will never include one
367 The number of columns the user's terminal supports.
368 If there is no terminal device available, a default value of 80 is used.
370 The user's current working directory.
372 The effective group ID of the user invoking
375 The effective user ID of the user invoking
378 The real group ID of the user invoking
381 The user's supplementary group list formatted as a string of
382 comma-separated group IDs.
384 The local machine's hostname as returned by the
388 The number of lines the user's terminal supports.
390 no terminal device available, a default value of 24 is used.
392 The ID of the process group that the running
394 process is a member of.
395 Only available starting with API version 1.2
397 The process ID of the running
400 Only available starting with API version 1.2
402 Any (non-comment) strings immediately after the plugin path are
403 passed as arguments to the plugin.
404 These arguments are split on a white space boundary and are passed to
405 the plugin in the form of a
406 .Dv NULL Ns No -terminated
417 parameter is only available starting with
421 check the API version specified
424 front end before using
426 Failure to do so may result in a crash.
428 The parent process ID of the running
431 Only available starting with API version 1.2
433 The session ID of the running
437 is not part of a POSIX job control session.
438 Only available starting with API version 1.2
440 The ID of the foreground process group associated with the terminal
441 device associated with the
443 process or \-1 if there is no
445 Only available starting with API version 1.2
447 The path to the user's terminal device.
448 If the user has no terminal device associated with the session,
449 the value will be empty, as in
452 The real user ID of the user invoking
455 The name of the user invoking
459 The user's environment in the form of a
460 .Dv NULL Ns No -terminated vector of
466 the plugin should split on the
472 field will never include one
478 .Bd -literal -compact
479 void (*close)(int exit_status, int error);
484 function is called when the command being run by
488 The function arguments are as follows:
491 The command's exit status, as returned by the
500 If the command could not be executed, this is set to the value of
505 The plugin is responsible for displaying error information via the
510 If the command was successfully executed, the value of
517 function is defined, no I/O logging plugins are loaded,
522 options are set in the
526 front end may execute the command directly instead of running
527 it as a child process.
529 .Bd -literal -compact
530 int (*show_version)(int verbose);
535 function is called by
537 when the user specifies
541 The plugin may display its version information to the user via the
546 .Dv SUDO_CONV_INFO_MSG .
547 If the user requests detailed version information, the verbose flag will be set.
549 .Bd -literal -compact
550 int (*check_policy)(int argc, char * const argv[]
551 char *env_add[], char **command_info[],
552 char **argv_out[], char **user_env_out[]);
557 function is called by
560 whether the user is allowed to run the specified commands.
564 option was enabled in the
569 function, the user has requested
573 is a mechanism for editing one or more files
574 where an editor is run with the user's credentials instead of with
577 achieves this by creating user-writable
578 temporary copies of the files to be edited and then overwriting the
579 originals with the temporary copies after editing is complete.
580 If the plugin supports
582 it should choose the editor to be used, potentially from a variable
583 in the user's environment, such as
587 (note that environment
588 variables may include command line flags).
589 The files to be edited should be copied from
594 editor and its arguments by a
602 before the editor is executed.
603 The plugin should also set
611 function returns 1 if the command is allowed,
612 0 if not allowed, \-1 for a general error, or \-2 for a usage error
615 was specified but is unsupported by the plugin.
618 will print a usage message before it
620 If an error occurs, the plugin may optionally call the
625 .Dv SUDO_CONF_ERROR_MSG
626 to present additional error information to the user.
628 The function arguments are as follows:
631 The number of elements in
633 not counting the final
637 The argument vector describing the command the user wishes to run,
638 in the same form as what would be passed to the
641 The vector is terminated by a
645 Additional environment variables specified by the user on the command
646 line in the form of a
647 .Dv NULL Ns No -terminated
651 The plugin may reject the command if one or more variables
652 are not allowed to be set, or it may silently ignore such variables.
656 the plugin should split on the
662 field will never include one
667 Information about the command being run in the form of
670 These values are used by
673 environment when running a command.
674 The plugin is responsible for creating and populating the vector,
675 which must be terminated with a
678 The following values are recognized by
682 The root directory to use when running the command.
686 will close all files descriptors with a value
691 Fully qualified path to the command to be executed.
693 The current working directory to change to when executing the command.
694 .It exec_background=bool
697 runs a command as the foreground process as long as
699 itself is running in the foreground.
702 is enabled and the command is being run in a pty (due to I/O logging
705 setting), the command will be run as a background process.
706 Attempts to read from the controlling terminal (or to change terminal
707 settings) will result in the command being suspended with the
711 in the case of terminal settings).
714 is a foreground process, the command will be granted the controlling terminal
715 and resumed in the foreground with no user intervention required.
716 The advantage of initially running the command in the background is that
718 need not read from the terminal unless the command explicitly requests it.
719 Otherwise, any terminal input must be passed to the command, whether it
720 has required it or not (the kernel buffers terminals so it is not possible
721 to tell whether the command really wants the input).
722 This is different from historic
724 behavior or when the command is not being run in a pty.
726 For this to work seamlessly, the operating system must support the
727 automatic restarting of system calls.
728 Unfortunately, not all operating systems do this by default,
729 and even those that do may have bugs.
730 For example, Mac OS X fails to restart the
734 system calls (this is a bug in Mac OS X).
735 Furthermore, because this behavior depends on the command stopping with the
739 signals, programs that catch these signals and suspend themselves
740 with a different signal (usually
742 will not be automatically foregrounded.
743 Some versions of the linux
745 command behave this way.
746 Because of this, a plugin should not set
748 unless it is explicitly enabled by the administrator and there should
749 be a way to enabled or disable it on a per-command basis.
751 This setting has no effect unless I/O logging is enabled or
754 .It iolog_compress=bool
755 Set to true if the I/O logging plugins, if any, should compress the
757 This is a hint to the I/O logging plugin which may choose to ignore it.
758 .It iolog_path=string
759 Fully qualified path to the file or directory in which I/O log is
761 This is a hint to the I/O logging plugin which may choose to ignore it.
762 If no I/O logging plugin is loaded, this setting has no effect.
764 Set to true if the I/O logging plugins, if any, should log the
765 standard input if it is not connected to a terminal device.
766 This is a hint to the I/O logging plugin which may choose to ignore it.
767 .It iolog_stdout=bool
768 Set to true if the I/O logging plugins, if any, should log the
769 standard output if it is not connected to a terminal device.
770 This is a hint to the I/O logging plugin which may choose to ignore it.
771 .It iolog_stderr=bool
772 Set to true if the I/O logging plugins, if any, should log the
773 standard error if it is not connected to a terminal device.
774 This is a hint to the I/O logging plugin which may choose to ignore it.
776 Set to true if the I/O logging plugins, if any, should log all
778 This only includes input typed by the user and not from a pipe or
779 redirected from a file.
780 This is a hint to the I/O logging plugin which may choose to ignore it.
781 .It iolog_ttyout=bool
782 Set to true if the I/O logging plugins, if any, should log all
784 This only includes output to the screen, not output to a pipe or file.
785 This is a hint to the I/O logging plugin which may choose to ignore it.
786 .It login_class=string
787 BSD login class to use when setting resource limits and nice value
789 This option is only set on systems that support login classes.
791 Nice value (priority) to use when executing the command.
792 The nice value, if specified, overrides the priority associated with the
796 If set, prevent the command from executing other programs.
797 .It preserve_groups=bool
800 will preserve the user's group vector instead of
801 initializing the group vector based on
804 Effective group ID to run the command as.
805 If not specified, the value of
809 Effective user ID to run the command as.
810 If not specified, the value of
814 Group ID to run the command as.
815 .It runas_groups=list
816 The supplementary group vector to use for the command in the form
817 of a comma-separated list of group IDs.
820 is set, this option is ignored.
822 User ID to run the command as.
823 .It selinux_role=string
824 SELinux role to use when executing the command.
825 .It selinux_type=string
826 SELinux type to use when executing the command.
828 Create a utmp (or utmpx) entry when a pseudo-tty is allocated.
829 By default, the new entry will be a copy of the user's existing utmp
830 entry (if any), with the tty, time, type and pid fields updated.
835 The plugin may enable
841 This allows the plugin to perform command substitution and transparently
844 when the user attempts to run an editor.
847 If non-zero then when the timeout expires the command will be killed.
849 The file creation mask to use when executing the command.
851 Allocate a pseudo-tty to run the command in, regardless of whether
852 or not I/O logging is in use.
856 the command in a pty when an I/O log plugin is loaded.
858 User name to use when constructing a new utmp (or utmpx) entry when
861 This option can be used to set the user field in the utmp entry to
862 the user the command runs as rather than the invoking user.
865 will base the new entry on
866 the invoking user's existing entry.
869 Unsupported values will be ignored.
872 .Dv NULL Ns No -terminated
873 argument vector to pass to the
875 system call when executing the command.
876 The plugin is responsible for allocating and populating the vector.
879 .Dv NULL Ns No -terminated
880 environment vector to use when executing the command.
881 The plugin is responsible for allocating and populating the vector.
884 .Bd -literal -compact
885 int (*list)(int verbose, const char *list_user,
886 int argc, char * const argv[]);
889 List available privileges for the invoking user.
890 Returns 1 on success, 0 on failure and \-1 on error.
891 On error, the plugin may optionally call the
896 .Dv SUDO_CONF_ERROR_MSG
897 to present additional error information to
900 Privileges should be output via the
905 .Dv SUDO_CONV_INFO_MSG ,
908 Flag indicating whether to list in verbose mode or not.
910 The name of a different user to list privileges for if the policy
914 the plugin should list the privileges of the invoking user.
916 The number of elements in
918 not counting the final
923 .No non- Ns Dv NULL ,
924 an argument vector describing a command the user
925 wishes to check against the policy in the same form as what would
929 If the command is permitted by the policy, the fully-qualified path
930 to the command should be displayed along with any command line arguments.
933 .Bd -literal -compact
934 int (*validate)(void);
939 function is called when
944 For policy plugins such as
947 authentication credentials, this function will validate and cache
954 if the plugin does not support credential caching.
956 Returns 1 on success, 0 on failure and \-1 on error.
957 On error, the plugin may optionally call the
962 .Dv SUDO_CONF_ERROR_MSG
963 to present additional
964 error information to the user.
966 .Bd -literal -compact
967 void (*invalidate)(int remove);
972 function is called when
980 For policy plugins such as
983 cache authentication credentials, this function will invalidate the
987 flag is set, the plugin may remove
988 the credentials instead of simply invalidating them.
994 if the plugin does not support credential caching.
996 .Bd -literal -compact
997 int (*init_session)(struct passwd *pwd, char **user_envp[);
1002 function is called before
1005 execution environment for the command.
1006 It is run in the parent
1008 process and before any uid or gid changes.
1009 This can be used to perform session setup that is not supported by
1011 such as opening the PAM session.
1015 used to tear down the session that was opened by
1020 argument points to a passwd struct for the user the
1021 command will be run as if the uid the command will run as was found
1022 in the password database, otherwise it will be
1027 argument points to the environment the command will
1028 run in, in the form of a
1029 .Dv NULL Ns No -terminated
1033 This is the same string passed back to the front end via
1039 function needs to modify the user environment, it should update the
1042 The expected use case is to merge the contents of the PAM environment
1043 (if any) with the contents of
1047 parameter is only available
1048 starting with API version 1.2.
1052 version specified by the
1054 front end before using
1056 Failure to do so may result in a crash.
1058 Returns 1 on success, 0 on failure and \-1 on error.
1059 On error, the plugin may optionally call the
1064 .Dv SUDO_CONF_ERROR_MSG
1065 to present additional
1066 error information to the user.
1068 .Bd -literal -compact
1069 void (*register_hooks)(int version,
1070 int (*register_hook)(struct sudo_hook *hook));
1075 function is called by the sudo front end to
1076 register any hooks the plugin needs.
1077 If the plugin does not support hooks,
1079 should be set to the
1085 argument describes the version of the hooks API
1092 function should be used to register any supported
1093 hooks the plugin needs.
1094 It returns 0 on success, 1 if the hook type is not supported and \-1
1095 if the major version in
1097 does not match the front end's major hook API version.
1100 .Sx Hook function API
1101 section below for more information
1106 function is only available starting
1107 with API version 1.2.
1110 front end doesn't support API
1111 version 1.2 or higher,
1114 .It deregister_hooks
1115 .Bd -literal -compact
1116 void (*deregister_hooks)(int version,
1117 int (*deregister_hook)(struct sudo_hook *hook));
1121 .Fn deregister_hooks
1122 function is called by the sudo front end
1123 to deregister any hooks the plugin has registered.
1124 If the plugin does not support hooks,
1125 .Li deregister_hooks
1126 should be set to the
1132 argument describes the version of the hooks API
1139 function should be used to deregister any
1140 hooks that were put in place by the
1143 If the plugin tries to deregister a hook that the front end does not support,
1145 will return an error.
1148 .Sx Hook function API
1149 section below for more information
1153 .Fn deregister_hooks
1154 function is only available starting
1155 with API version 1.2.
1158 front end doesn't support API
1159 version 1.2 or higher,
1160 .Li deregister_hooks
1164 .Em Policy Plugin Version Macros
1166 /* Plugin API version major/minor. */
1167 #define SUDO_API_VERSION_MAJOR 1
1168 #define SUDO_API_VERSION_MINOR 2
1169 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1170 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e
1171 SUDO_API_VERSION_MINOR)
1173 /* Getters and setters for API version */
1174 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1175 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1176 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
1177 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1179 #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
1180 *(vp) = (*(vp) & 0xffff0000) | (n); \e
1186 #define SUDO_IO_PLUGIN 2
1187 unsigned int type; /* always SUDO_IO_PLUGIN */
1188 unsigned int version; /* always SUDO_API_VERSION */
1189 int (*open)(unsigned int version, sudo_conv_t conversation,
1190 sudo_printf_t plugin_printf, char * const settings[],
1191 char * const user_info[], char * const command_info[],
1192 int argc, char * const argv[], char * const user_env[],
1193 char * const plugin_options[]);
1194 void (*close)(int exit_status, int error); /* wait status or error */
1195 int (*show_version)(int verbose);
1196 int (*log_ttyin)(const char *buf, unsigned int len);
1197 int (*log_ttyout)(const char *buf, unsigned int len);
1198 int (*log_stdin)(const char *buf, unsigned int len);
1199 int (*log_stdout)(const char *buf, unsigned int len);
1200 int (*log_stderr)(const char *buf, unsigned int len);
1201 void (*register_hooks)(int version,
1202 int (*register_hook)(struct sudo_hook *hook));
1203 void (*deregister_hooks)(int version,
1204 int (*deregister_hook)(struct sudo_hook *hook));
1208 When an I/O plugin is loaded,
1210 runs the command in a pseudo-tty.
1211 This makes it possible to log the input and output from the user's
1213 If any of the standard input, standard output or standard error do not
1214 correspond to a tty,
1216 will open a pipe to capture
1217 the I/O for logging before passing it on.
1219 The log_ttyin function receives the raw user input from the terminal
1220 device (note that this will include input even when echo is disabled,
1221 such as when a password is read).
1222 The log_ttyout function receives output from the pseudo-tty that is
1223 suitable for replaying the user's session at a later time.
1229 functions are only called if the standard input, standard output
1230 or standard error respectively correspond to something other than
1233 Any of the logging functions may be set to the
1235 pointer if no logging is to be performed.
1236 If the open function returns 0, no I/O will be sent to the plugin.
1238 The io_plugin struct has the following fields:
1243 field should always be set to
1244 .Dv SUDO_IO_PLUGIN .
1248 field should be set to
1249 .Dv SUDO_API_VERSION .
1253 to determine the API version the plugin was
1256 .Bd -literal -compact
1257 int (*open)(unsigned int version, sudo_conv_t conversation,
1258 sudo_printf_t plugin_printf, char * const settings[],
1259 char * const user_info[], int argc, char * const argv[],
1260 char * const user_env[], char * const plugin_options[]);
1265 function is run before the
1270 functions are called.
1271 It is only called if the version is being requested or the
1274 returned successfully.
1275 It returns 1 on success, 0 on failure, \-1 if a general error occurred,
1276 or \-2 if there was a usage error.
1279 will print a usage message before it exits.
1280 If an error occurs, the plugin may optionally call the
1285 .Dv SUDO_CONF_ERROR_MSG
1287 additional error information to the user.
1289 The function arguments are as follows:
1292 The version passed in by
1294 allows the plugin to determine the
1295 major and minor version number of the plugin API supported by
1300 function that may be used by the
1302 function to display version information (see
1307 function may also be used to display additional error message to the user.
1310 function returns 0 on success and \-1 on failure.
1313 .Fn printf Ns No -style
1314 function that may be used by the
1316 function to display version information (see
1317 show_version below).
1320 function may also be used to display additional error message to the user.
1323 function returns number of characters printed on success and \-1 on failure.
1325 A vector of user-supplied
1327 settings in the form of
1330 The vector is terminated by a
1333 These settings correspond to flags the user specified when running
1335 As such, they will only be present when the corresponding flag has
1336 been specified on the command line.
1340 the plugin should split on the
1346 field will never include one
1352 .Sx Policy plugin API
1353 section for a list of all possible settings.
1355 A vector of information about the user running the command in the form of
1358 The vector is terminated by a
1364 the plugin should split on the
1370 field will never include one
1376 .Sx Policy plugin API
1377 section for a list of all possible strings.
1379 The number of elements in
1381 not counting the final
1386 .No non- Ns Dv NULL ,
1387 an argument vector describing a command the user
1388 wishes to run in the same form as what would be passed to the
1392 The user's environment in the form of a
1393 .Dv NULL Ns No -terminated
1400 the plugin should split on the
1406 field will never include one
1411 Any (non-comment) strings immediately after the plugin path are
1412 treated as arguments to the plugin.
1413 These arguments are split on a white space boundary and are passed to
1414 the plugin in the form of a
1415 .Dv NULL Ns No -terminated
1417 If no arguments were specified,
1425 parameter is only available starting with
1429 check the API version specified
1432 front end before using
1433 .Em plugin_options .
1434 Failure to do so may result in a crash.
1437 .Bd -literal -compact
1438 void (*close)(int exit_status, int error);
1443 function is called when the command being run by
1447 The function arguments are as follows:
1450 The command's exit status, as returned by the
1459 If the command could not be executed, this is set to the value of
1464 If the command was successfully executed, the value of
1469 .Bd -literal -compact
1470 int (*show_version)(int verbose);
1475 function is called by
1477 when the user specifies
1481 The plugin may display its version information to the user via the
1486 .Dv SUDO_CONV_INFO_MSG .
1487 If the user requests detailed version information, the verbose flag will be set.
1489 .Bd -literal -compact
1490 int (*log_ttyin)(const char *buf, unsigned int len);
1495 function is called whenever data can be read from
1496 the user but before it is passed to the running command.
1497 This allows the plugin to reject data if it chooses to (for instance
1498 if the input contains banned content).
1499 Returns 1 if the data should be passed to the command, 0 if the data
1500 is rejected (which will terminate the command) or \-1 if an error occurred.
1502 The function arguments are as follows:
1505 The buffer containing user input.
1512 .Bd -literal -compact
1513 int (*log_ttyout)(const char *buf, unsigned int len);
1518 function is called whenever data can be read from
1519 the command but before it is written to the user's terminal.
1520 This allows the plugin to reject data if it chooses to (for instance
1521 if the output contains banned content).
1522 Returns 1 if the data should be passed to the user, 0 if the data is rejected
1523 (which will terminate the command) or \-1 if an error occurred.
1525 The function arguments are as follows:
1528 The buffer containing command output.
1535 .Bd -literal -compact
1536 int (*log_stdin)(const char *buf, unsigned int len);
1541 function is only used if the standard input does
1542 not correspond to a tty device.
1543 It is called whenever data can be read from the standard input but
1544 before it is passed to the running command.
1545 This allows the plugin to reject data if it chooses to
1546 (for instance if the input contains banned content).
1547 Returns 1 if the data should be passed to the command, 0 if the data is
1548 rejected (which will terminate the command) or \-1 if an error occurred.
1550 The function arguments are as follows:
1553 The buffer containing user input.
1560 .Bd -literal -compact
1561 int (*log_stdout)(const char *buf, unsigned int len);
1566 function is only used if the standard output does not correspond
1568 It is called whenever data can be read from the command but before
1569 it is written to the standard output.
1570 This allows the plugin to reject data if it chooses to
1571 (for instance if the output contains banned content).
1572 Returns 1 if the data should be passed to the user, 0 if the data is
1573 rejected (which will terminate the command) or \-1 if an error occurred.
1575 The function arguments are as follows:
1578 The buffer containing command output.
1585 .Bd -literal -compact
1586 int (*log_stderr)(const char *buf, unsigned int len);
1591 function is only used if the standard error does
1592 not correspond to a tty device.
1593 It is called whenever data can be read from the command but before it
1594 is written to the standard error.
1595 This allows the plugin to reject data if it chooses to
1596 (for instance if the output contains banned content).
1597 Returns 1 if the data should be passed to the user, 0 if the data is
1598 rejected (which will terminate the command) or \-1 if an error occurred.
1600 The function arguments are as follows:
1603 The buffer containing command output.
1611 .Sx Policy plugin API
1612 section for a description of
1613 .Li register_hooks .
1614 .It deregister_hooks
1616 .Sx Policy plugin API
1617 section for a description of
1618 .Li deregister_hooks.
1621 .Em I/O Plugin Version Macros
1624 .Sx Policy plugin API .
1628 front end installs default signal handlers to trap common signals
1629 while the plugin functions are run.
1630 The following signals are trapped by default before the command is
1633 .Bl -bullet -compact
1652 If a fatal signal is received before the command is executed,
1654 will call the plugin's
1656 function with an exit status of 128 plus the value of the signal
1658 This allows for consistent logging of commands killed by a signal
1659 for plugins that log such information in their
1663 A plugin may temporarily install its own signal handlers but must
1664 restore the original handler before the plugin function returns.
1665 .Ss Hook function API
1666 Beginning with plugin API version 1.2, it is possible to install
1667 hooks for certain functions called by the
1671 Currently, the only supported hooks relate to the handling of
1672 environment variables.
1673 Hooks can be used to intercept attempts to get, set, or remove
1674 environment variables so that these changes can be reflected in
1675 the version of the environment that is used to execute a command.
1676 A future version of the API will support hooking internal
1678 front end functions as well.
1684 are described by the following structure:
1686 typedef int (*sudo_hook_fn_t)();
1691 sudo_hook_fn_t hook_fn;
1698 structure has the following fields:
1703 field should be set to
1704 .Dv SUDO_HOOK_VERSION .
1708 field may be one of the following supported hook types:
1710 .It Dv SUDO_HOOK_SETENV
1714 Any registered hooks will run before the C library implementation.
1718 be a function that matches the following typedef:
1720 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1721 const char *value, int overwrite, void *closure);
1724 If the registered hook does not match the typedef the results are
1726 .It Dv SUDO_HOOK_UNSETENV
1730 Any registered hooks will run before the C library implementation.
1734 be a function that matches the following typedef:
1736 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1739 .It Dv SUDO_HOOK_GETENV
1743 Any registered hooks will run before the C library implementation.
1747 be a function that matches the following typedef:
1749 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1750 char **value, void *closure);
1753 If the registered hook does not match the typedef the results are
1755 .It Dv SUDO_HOOK_PUTENV
1759 Any registered hooks will run before the C library implementation.
1763 be a function that matches the following typedef:
1765 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1769 If the registered hook does not match the typedef the results are
1773 sudo_hook_fn_t hook_fn;
1777 field should be set to the plugin's hook implementation.
1778 The actual function arguments will vary depending on the
1786 .Li struct sudo_hook
1787 is passed as the last function parameter.
1788 This can be used to pass arbitrary data to the plugin's hook implementation.
1790 The function return value may be one of the following:
1792 .It Dv SUDO_HOOK_RET_ERROR
1793 The hook function encountered an error.
1794 .It Dv SUDO_HOOK_RET_NEXT
1795 The hook completed without error, go on to the next hook (including
1796 the native implementation if applicable).
1800 .Dv SUDO_HOOK_RET_NEXT
1801 if the specified variable was not found in the private copy of the environment.
1802 .It Dv SUDO_HOOK_RET_STOP
1803 The hook completed without error, stop processing hooks for this invocation.
1804 This can be used to replace the native implementation.
1807 hook that operates on a private copy of
1808 the environment but leaves
1814 Note that it is very easy to create an infinite loop when hooking
1815 C library functions.
1820 function may create a loop if the
1822 implementation calls
1824 to check the locale.
1825 To prevent this, you may wish to use a static variable in the hook
1826 function to guard against nested calls.
1829 static int in_progress = 0; /* avoid recursion */
1831 return SUDO_HOOK_RET_NEXT;
1835 return SUDO_HOOK_RET_STOP;
1838 .Em Hook API Version Macros
1840 /* Hook API version major/minor */
1841 #define SUDO_HOOK_VERSION_MAJOR 1
1842 #define SUDO_HOOK_VERSION_MINOR 0
1843 #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1844 #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e
1845 SUDO_HOOK_VERSION_MINOR)
1847 /* Getters and setters for hook API version */
1848 #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1849 #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1850 #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e
1851 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1853 #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e
1854 *(vp) = (*(vp) & 0xffff0000) | (n); \e
1857 .Ss Conversation API
1858 If the plugin needs to interact with the user, it may do so via the
1861 A plugin should not attempt to read directly from the standard input
1862 or the user's tty (neither of which are guaranteed to exist).
1863 The caller must include a trailing newline in
1865 if one is to be printed.
1868 .Fn printf Ns No -style
1869 function is also available that can be used to display informational
1870 or error messages to the user, which is usually more convenient for
1871 simple messages where no use input is required.
1873 struct sudo_conv_message {
1874 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1875 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1876 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1877 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1878 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1879 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1880 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1886 struct sudo_conv_reply {
1890 typedef int (*sudo_conv_t)(int num_msgs,
1891 const struct sudo_conv_message msgs[],
1892 struct sudo_conv_reply replies[]);
1894 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1900 .Fn printf Ns No -style
1901 functions are passed
1904 function when the plugin is initialized.
1908 function, the plugin must pass an array of
1909 .Li sudo_conv_message
1914 .Li struct sudo_conv_message
1916 .Li struct sudo_conv_reply
1918 each message in the conversation.
1919 The plugin is responsible for freeing the reply buffer filled in to the
1920 .Li struct sudo_conv_reply ,
1924 .Fn printf Ns No -style
1925 function uses the same underlying mechanism as the
1927 function but only supports
1928 .Dv SUDO_CONV_INFO_MSG ,
1929 .Dv SUDO_CONV_ERROR_MSG
1931 .Dv SUDO_CONV_DEBUG_MSG
1935 It can be more convenient than using the
1937 function if no user reply is needed and supports standard
1942 .Dv SUDO_CONV_INFO_MSG
1944 Dv SUDO_CONV_ERROR_MSG ,
1947 .Dv SUDO_CONV_DEBUG_MSG
1951 Instead, they are logged to the file specified in the
1953 statement (if any) in the
1954 .Xr sudo.conf @mansectform@ .
1956 This allows a plugin to log debugging information and is intended
1957 to be used in conjunction with the
1961 See the sample plugin for an example of the
1964 .Ss Sudoers group plugin API
1967 plugin supports its own plugin interface to allow non-Unix
1969 This can be used to query a group source other than the standard Unix
1971 Two sample group plugins are bundled with
1977 .Xr sudoers @mansectform@ .
1978 Third party group plugins include a QAS AD plugin available from Quest Software.
1980 A group plugin must declare and populate a
1981 .Li sudoers_group_plugin
1982 struct in the global scope.
1983 This structure contains pointers to the functions that implement plugin
1984 initialization, cleanup and group lookup.
1986 struct sudoers_group_plugin {
1987 unsigned int version;
1988 int (*init)(int version, sudo_printf_t sudo_printf,
1989 char *const argv[]);
1990 void (*cleanup)(void);
1991 int (*query)(const char *user, const char *group,
1992 const struct passwd *pwd);
1997 .Li sudoers_group_plugin
1998 struct has the following fields:
2003 field should be set to GROUP_API_VERSION.
2007 to determine the API version the group plugin
2010 .Bd -literal -compact
2011 int (*init)(int version, sudo_printf_t plugin_printf,
2012 char *const argv[]);
2017 function is called after
2020 before any policy checks.
2021 It returns 1 on success, 0 on failure (or if the plugin is not configured),
2022 and \-1 if a error occurred.
2023 If an error occurs, the plugin may call the
2026 .Dv SUDO_CONF_ERROR_MSG
2027 to present additional error information
2030 The function arguments are as follows:
2033 The version passed in by
2035 allows the plugin to determine the
2036 major and minor version number of the group plugin API supported by
2040 .Fn printf Ns No -style
2041 function that may be used to display informational or error message to the user.
2042 Returns the number of characters printed on success and \-1 on failure.
2045 .Dv NULL Ns No -terminated
2046 array of arguments generated from the
2050 If no arguments were given,
2056 .Bd -literal -compact
2062 function is called when
2066 The plugin should free any memory it has allocated and close open file handles.
2068 .Bd -literal -compact
2069 int (*query)(const char *user, const char *group,
2070 const struct passwd *pwd);
2075 function is used to ask the group plugin whether
2080 The function arguments are as follows:
2083 The name of the user being looked up in the external group database.
2085 The name of the group being queried.
2087 The password database entry for
2093 present in the password database,
2100 .Em Group API Version Macros
2102 /* Sudoers group plugin version major/minor */
2103 #define GROUP_API_VERSION_MAJOR 1
2104 #define GROUP_API_VERSION_MINOR 0
2105 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
2106 GROUP_API_VERSION_MINOR)
2108 /* Getters and setters for group version */
2109 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
2110 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
2111 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
2112 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2114 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
2115 *(vp) = (*(vp) & 0xffff0000) | (n); \e
2118 .Sh PLUGIN API CHANGELOG
2119 The following revisions have been made to the Sudo Plugin API.
2122 Initial API version.
2123 .It Version 1.1 (sudo 1.8.0)
2124 The I/O logging plugin's
2126 function was modified to take the
2128 list as an argument.
2129 .It Version 1.2 (sudo 1.8.5)
2130 The Policy and I/O logging plugins'
2132 functions are now passed
2133 a list of plugin parameters if any are specified in
2134 .Xr sudo.conf @mansectform@ .
2136 A simple hooks API has been introduced to allow plugins to hook in to the
2137 system's environment handling functions.
2141 Policy plugin function is now passed a pointer
2142 to the user environment which can be updated as needed.
2143 This can be used to merge in environment variables stored in the PAM
2144 handle before a command is run.
2145 .It Version 1.3 (sudo 1.8.7)
2148 entry has been added to the
2156 entries were added to the
2164 functions are now optional.
2165 Previously, a missing
2169 function would result in a crash.
2172 function is defined, a default
2174 function will be provided by the
2176 front end that displays a warning if the command could not be
2181 front end now installs default signal handlers to trap common signals
2182 while the plugin functions are run.
2185 .Xr sudo.conf @mansectform@ ,
2186 .Xr sudoers @mansectform@ ,
2187 .Xr sudo @mansectsu@
2189 If you feel you have found a bug in
2191 please submit a bug report at http://www.sudo.ws/sudo/bugs/
2193 Limited free support is available via the sudo-users mailing list,
2194 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
2195 search the archives.
2200 and any express or implied warranties, including, but not limited
2201 to, the implied warranties of merchantability and fitness for a
2202 particular purpose are disclaimed.
2203 See the LICENSE file distributed with
2205 or http://www.sudo.ws/sudo/license.html for complete details.