1 .\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
2 .\" IT IS GENERATED AUTOMATICALLY FROM sudo_plugin.mdoc.in
4 .\" Copyright (c) 2009-2012 Todd C. Miller <Todd.Miller@courtesan.com>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
19 .TH "SUDO_PLUGIN" "5" "July 16, 2012" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
26 Starting with version 1.8,
29 for policy and session logging.
32 policy plugin and an associated I/O logging plugin are used.
35 can be configured to use alternate policy and/or I/O logging plugins
36 provided by third parties.
37 The plugins to be used are specified via the
38 \fI@sysconfdir@/sudo.conf\fR
41 The API is versioned with a major and minor number.
42 The minor version number is incremented when additions are made.
43 The major number is incremented when incompatible changes are made.
44 A plugin should be check the version passed to it and make sure that the
45 major version matches.
47 The plugin API is defined by the
50 .SS "The sudo.conf file"
52 \fI@sysconfdir@/sudo.conf\fR
53 file contains plugin configuration directives.
54 The primary keyword is the
56 directive, which causes a plugin to be loaded.
62 keyword, followed by the
66 to the shared object containing the plugin.
70 \fRstruct policy_plugin\fR
72 \fRstruct io_plugin\fR
73 in the plugin shared object.
76 may be fully qualified or relative.
77 If not fully qualified it is relative to the
78 \fI@prefix@/libexec\fR
80 Any additional parameters after the
82 are passed as options to the plugin's
85 Lines that don't begin with
93 The same shared object may contain multiple plugins, each with a
94 different symbol name.
95 The shared object file must be owned by uid 0 and only writable by its owner.
96 Because of ambiguities that arise from composite policies, only a single
97 policy plugin may be specified.
98 This limitation does not apply to I/O plugins.
103 # Default @sysconfdir@/sudo.conf file
106 # Plugin plugin_name plugin_path plugin_options ...
107 # Path askpass /path/to/askpass
108 # Path noexec /path/to/sudo_noexec.so
109 # Debug sudo /var/log/sudo_debug all@warn
110 # Set disable_coredump true
112 # The plugin_path is relative to @prefix@/libexec unless
114 # The plugin_name corresponds to a global symbol in the plugin
115 # that contains the plugin interface structure.
116 # The plugin_options are optional.
118 Plugin sudoers_policy sudoers.so
119 Plugin sudoers_io sudoers.so
122 .SS "Policy plugin API"
123 A policy plugin must declare and populate a
125 struct in the global scope.
126 This structure contains pointers to the functions that implement the
129 The name of the symbol should be specified in
130 \fI@sysconfdir@/sudo.conf\fR
131 along with a path to the plugin so that
137 struct policy_plugin {
138 #define SUDO_POLICY_PLUGIN 1
139 unsigned int type; /* always SUDO_POLICY_PLUGIN */
140 unsigned int version; /* always SUDO_API_VERSION */
141 int (*open)(unsigned int version, sudo_conv_t conversation,
142 sudo_printf_t plugin_printf, char * const settings[],
143 char * const user_info[], char * const user_env[],
144 char * const plugin_options[]);
145 void (*close)(int exit_status, int error);
146 int (*show_version)(int verbose);
147 int (*check_policy)(int argc, char * const argv[],
148 char *env_add[], char **command_info[],
149 char **argv_out[], char **user_env_out[]);
150 int (*list)(int argc, char * const argv[], int verbose,
151 const char *list_user);
152 int (*validate)(void);
153 void (*invalidate)(int remove);
154 int (*init_session)(struct passwd *pwd, char **user_env[]);
155 void (*register_hooks)(int version,
156 int (*register_hook)(struct sudo_hook *hook));
157 void (*deregister_hooks)(int version,
158 int (*deregister_hook)(struct sudo_hook *hook));
163 The policy_plugin struct has the following fields:
168 field should always be set to SUDO_POLICY_PLUGIN.
173 field should be set to
174 \fRSUDO_API_VERSION\fR.
178 to determine the API version the plugin was
185 int (*open)(unsigned int version, sudo_conv_t conversation,
186 sudo_printf_t plugin_printf, char * const settings[],
187 char * const user_info[], char * const user_env[],
188 char * const plugin_options[]);
192 Returns 1 on success, 0 on failure, \-1 if a general error occurred,
193 or \-2 if there was a usage error.
196 will print a usage message before it exits.
197 If an error occurs, the plugin may optionally call the
200 \fBplugin_printf\fR()
202 \fRSUDO_CONF_ERROR_MSG\fR
203 to present additional error information to the user.
205 The function arguments are as follows:
208 The version passed in by
210 allows the plugin to determine the
211 major and minor version number of the plugin API supported by
217 function that can be used by the plugin to interact with the user (see below).
218 Returns 0 on success and \-1 on failure.
223 function that may be used to display informational or error messages
225 Returns the number of characters printed on success and \-1 on failure.
228 A vector of user-supplied
230 settings in the form of
233 The vector is terminated by a
236 These settings correspond to flags the user specified when running
238 As such, they will only be present when the corresponding flag has
239 been specified on the command line.
243 the plugin should split on the
249 field will never include one
256 A comma-separated list of debug flags that correspond to
260 \fI@sysconfdir@/sudo.conf\fR,
262 The flags are passed to the plugin as they appear in
263 \fI@sysconfdir@/sudo.conf\fR.
269 \fIsubsystem\fR@\fIpriority\fR
270 but the plugin is free to use a different
271 format so long as it does not include a comma
274 For reference, the priorities supported by the
289 The following subsystems are defined:
318 includes every subsystem.
320 There is not currently a way to specify a set of debug flags specific
321 to the plugin--the flags are shared by
326 This setting has been deprecated in favor of
330 The user name or uid to to run the command as, if specified via the
335 The group name or gid to to run the command as, if specified via
341 The prompt to use when requesting a password, if specified via
347 Set to true if the user specified the
352 environment variable to the target user's home directory.
354 preserve_environment=bool
355 Set to true if the user specified the
357 flag, indicating that
358 the user wishes to preserve the environment.
361 Set to true if the user specified the
363 flag, indicating that
364 the user wishes to run a shell.
367 Set to true if the user specified the
369 flag, indicating that
370 the user wishes to run a login shell.
373 If the user does not specify a program on the command line,
375 will pass the plugin the path to the user's shell and set
381 to be used similarly to
383 If the plugin does not to support this usage, it may return a value of \-2
386 function, which will cause
388 to print a usage message and
392 Set to true if the user specified the
394 flag, indicating that
395 the user wishes to preserve the group vector instead of setting it
396 based on the runas user.
399 Set to true if the user specified the
402 command, indicating that the user wishes to ignore any cached
403 authentication credentials.
406 Set to true if the user specified the
408 flag, indicating that
410 should operate in non-interactive mode.
411 The plugin may reject a command run in non-interactive mode if user
412 interaction is required.
415 BSD login class to use when setting resource limits and nice value,
421 SELinux role to use when executing the command, if specified by
427 SELinux type to use when executing the command, if specified by
433 Authentication type, if specified by the
436 systems where BSD authentication is supported.
439 A space-separated list of IP network addresses and netmasks in the
443 ``192.168.1.2/255.255.255.0''.
444 The address and netmask pairs may be either IPv4 or IPv6, depending on
445 what the operating system supports.
446 If the address contains a colon
448 it is an IPv6 address, else it is IPv4.
451 The command name that sudo was run as, typically
459 flag is is specified or if invoked as
461 The plugin shall substitute an editor into
465 function or return \-2 with a usage error
466 if the plugin does not support
468 For more information, see the
473 If specified, the user has requested via the
477 close all files descriptors with a value of
480 The plugin may optionally pass this, or another value, back in the
484 Additional settings may be added in the future so the plugin should
485 silently ignore settings that it does not recognize.
491 A vector of information about the user running the command in the form of
494 The vector is terminated by a
500 the plugin should split on the
506 field will never include one
514 The process ID of the running
517 Only available starting with API version 1.2
520 The parent process ID of the running
523 Only available starting with API version 1.2
526 The session ID of the running
531 not part of a POSIX job control session.
532 Only available starting with API version 1.2
535 The ID of the process group that the running
539 Only available starting with API version 1.2
542 The ID of the forground process group associated with the terminal
543 device associcated with the
545 process or \-1 if there is no
547 Only available starting with API version 1.2
550 The name of the user invoking
554 The effective user ID of the user invoking
558 The real user ID of the user invoking
562 The effective group ID of the user invoking
566 The real group ID of the user invoking
570 The user's supplementary group list formatted as a string of
571 comma-separated group IDs.
574 The user's current working directory.
577 The path to the user's terminal device.
578 If the user has no terminal device associated with the session,
579 the value will be empty, as in
583 The local machine's hostname as returned by the
588 The number of lines the user's terminal supports.
590 no terminal device available, a default value of 24 is used.
593 The number of columns the user's terminal supports.
594 If there is no terminal device available, a default value of 80 is used.
600 The user's environment in the form of a
601 \fRNULL\fR-terminated vector of
607 the plugin should split on the
613 field will never include one
620 Any (non-comment) strings immediately after the plugin path are
621 treated as arguments to the plugin.
622 These arguments are split on a white space boundary and are passed to
623 the plugin in the form of a
624 \fRNULL\fR-terminated
635 parameter is only available starting with
639 check the API version specified
642 front end before using
643 \fIplugin_options\fR.
644 Failure to do so may result in a crash.
654 void (*close)(int exit_status, int error);
660 function is called when the command being run by
664 The function arguments are as follows:
668 The command's exit status, as returned by the
679 If the command could not be executed, this is set to the value of
684 The plugin is responsible for displaying error information via the
687 \fBplugin_printf\fR()
689 If the command was successfully executed, the value of
700 int (*show_version)(int verbose);
706 function is called by
708 when the user specifies
712 The plugin may display its version information to the user via the
715 \fBplugin_printf\fR()
717 \fRSUDO_CONV_INFO_MSG\fR.
718 If the user requests detailed version information, the verbose flag will be set.
728 int (*check_policy)(int argc, char * const argv[]
729 char *env_add[], char **command_info[],
730 char **argv_out[], char **user_env_out[]);
736 function is called by
739 whether the user is allowed to run the specified commands.
743 option was enabled in the
748 function, the user has requested
752 is a mechanism for editing one or more files
753 where an editor is run with the user's credentials instead of with
756 achieves this by creating user-writable
757 temporary copies of the files to be edited and then overwriting the
758 originals with the temporary copies after editing is complete.
759 If the plugin supports
761 it should choose the editor to be used, potentially from a variable
762 in the user's environment, such as
766 (note that environment
767 variables may include command line flags).
768 The files to be edited should be copied from
773 editor and its arguments by a
781 before the editor is executed.
782 The plugin should also set
790 function returns 1 if the command is allowed,
791 0 if not allowed, \-1 for a general error, or \-2 for a usage error
794 was specified but is unsupported by the plugin.
797 will print a usage message before it
799 If an error occurs, the plugin may optionally call the
802 \fBplugin_printf\fR()
804 \fRSUDO_CONF_ERROR_MSG\fR
805 to present additional error information to the user.
807 The function arguments are as follows:
811 The number of elements in
813 not counting the final
818 The argument vector describing the command the user wishes to run,
819 in the same form as what would be passed to the
822 The vector is terminated by a
827 Additional environment variables specified by the user on the command
828 line in the form of a
829 \fRNULL\fR-terminated
833 The plugin may reject the command if one or more variables
834 are not allowed to be set, or it may silently ignore such variables.
838 the plugin should split on the
844 field will never include one
850 Information about the command being run in the form of
853 These values are used by
856 environment when running a command.
857 The plugin is responsible for creating and populating the vector,
858 which must be terminated with a
861 The following values are recognized by
866 Fully qualified path to the command to be executed.
869 User ID to run the command as.
872 Effective user ID to run the command as.
873 If not specified, the value of
878 Group ID to run the command as.
881 Effective group ID to run the command as.
882 If not specified, the value of
887 The supplementary group vector to use for the command in the form
888 of a comma-separated list of group IDs.
890 \fIpreserve_groups\fR
891 is set, this option is ignored.
894 BSD login class to use when setting resource limits and nice value
896 This option is only set on systems that support login classes.
901 will preserve the user's group vector instead of
902 initializing the group vector based on
906 The current working directory to change to when executing the command.
909 If set, prevent the command from executing other programs.
912 The root directory to use when running the command.
915 Nice value (priority) to use when executing the command.
916 The nice value, if specified, overrides the priority associated with the
921 The file creation mask to use when executing the command.
924 SELinux role to use when executing the command.
927 SELinux type to use when executing the command.
931 If non-zero then when the timeout expires the command will be killed.
937 The plugin may enable
943 This allows the plugin to perform command substitution and transparently
946 when the user attempts to run an editor.
951 will close all files descriptors with a value
957 Set to true if the I/O logging plugins, if any, should compress the
959 This is a hint to the I/O logging plugin which may choose to ignore it.
962 Fully qualified path to the file or directory in which I/O log is
964 This is a hint to the I/O logging plugin which may choose to ignore it.
965 If no I/O logging plugin is loaded, this setting has no effect.
968 Set to true if the I/O logging plugins, if any, should log the
969 standard input if it is not connected to a terminal device.
970 This is a hint to the I/O logging plugin which may choose to ignore it.
973 Set to true if the I/O logging plugins, if any, should log the
974 standard output if it is not connected to a terminal device.
975 This is a hint to the I/O logging plugin which may choose to ignore it.
978 Set to true if the I/O logging plugins, if any, should log the
979 standard error if it is not connected to a terminal device.
980 This is a hint to the I/O logging plugin which may choose to ignore it.
983 Set to true if the I/O logging plugins, if any, should log all
985 This only includes input typed by the user and not from a pipe or
986 redirected from a file.
987 This is a hint to the I/O logging plugin which may choose to ignore it.
990 Set to true if the I/O logging plugins, if any, should log all
992 This only includes output to the screen, not output to a pipe or file.
993 This is a hint to the I/O logging plugin which may choose to ignore it.
996 Allocate a pseudo-tty to run the command in, regardless of whether
997 or not I/O logging is in use.
1001 the command in a pty when an I/O log plugin is loaded.
1004 Create a utmp (or utmpx) entry when a pseudo-tty is allocated.
1005 By default, the new entry will be a copy of the user's existing utmp
1006 entry (if any), with the tty, time, type and pid fields updated.
1009 User name to use when constructing a new utmp (or utmpx) entry when
1012 This option can be used to set the user field in the utmp entry to
1013 the user the command runs as rather than the invoking user.
1016 will base the new entry on
1017 the invoking user's existing entry.
1019 Unsupported values will be ignored.
1026 \fRNULL\fR-terminated
1027 argument vector to pass to the
1029 system call when executing the command.
1030 The plugin is responsible for allocating and populating the vector.
1035 \fRNULL\fR-terminated
1036 environment vector to use when executing the command.
1037 The plugin is responsible for allocating and populating the vector.
1046 int (*list)(int verbose, const char *list_user,
1047 int argc, char * const argv[]);
1051 List available privileges for the invoking user.
1052 Returns 1 on success, 0 on failure and \-1 on error.
1053 On error, the plugin may optionally call the
1054 \fBconversation\fR()
1056 \fBplugin_printf\fR()
1058 \fRSUDO_CONF_ERROR_MSG\fR
1059 to present additional error information to
1062 Privileges should be output via the
1063 \fBconversation\fR()
1065 \fBplugin_printf\fR()
1067 \fRSUDO_CONV_INFO_MSG\fR,
1071 Flag indicating whether to list in verbose mode or not.
1074 The name of a different user to list privileges for if the policy
1078 the plugin should list the privileges of the invoking user.
1081 The number of elements in
1083 not counting the final
1090 an argument vector describing a command the user
1091 wishes to check against the policy in the same form as what would
1095 If the command is permitted by the policy, the fully-qualified path
1096 to the command should be displayed along with any command line arguments.
1105 int (*validate)(void);
1111 function is called when
1116 For policy plugins such as
1119 authentication credentials, this function will validate and cache
1126 if the plugin does not support credential caching.
1128 Returns 1 on success, 0 on failure and \-1 on error.
1129 On error, the plugin may optionally call the
1130 \fBconversation\fR()
1132 \fBplugin_printf\fR()
1134 \fRSUDO_CONF_ERROR_MSG\fR
1135 to present additional
1136 error information to the user.
1146 void (*invalidate)(int remove);
1152 function is called when
1160 For policy plugins such as
1163 cache authentication credentials, this function will invalidate the
1167 flag is set, the plugin may remove
1168 the credentials instead of simply invalidating them.
1174 if the plugin does not support credential caching.
1184 int (*init_session)(struct passwd *pwd, char **user_envp[);
1189 \fBinit_session\fR()
1190 function is called before
1193 execution environment for the command.
1194 It is run in the parent
1196 process and before any uid or gid changes.
1197 This can be used to perform session setup that is not supported by
1199 such as opening the PAM session.
1203 used to tear down the session that was opened by
1208 argument points to a passwd struct for the user the
1209 command will be run as if the uid the command will run as was found
1210 in the password database, otherwise it will be
1215 argument points to the environment the command will
1216 run in, in the form of a
1217 \fRNULL\fR-terminated
1221 This is the same string passed back to the front end via
1226 \fBinit_session\fR()
1227 function needs to modify the user environment, it should update the
1230 The expected use case is to merge the contents of the PAM environment
1231 (if any) with the contents of
1235 parameter is only available
1236 starting with API version 1.2.
1240 version specified by the
1242 front end before using
1244 Failure to do so may result in a crash.
1246 Returns 1 on success, 0 on failure and \-1 on error.
1247 On error, the plugin may optionally call the
1248 \fBconversation\fR()
1250 \fBplugin_printf\fR()
1252 \fRSUDO_CONF_ERROR_MSG\fR
1253 to present additional
1254 error information to the user.
1264 void (*register_hooks)(int version,
1265 int (*register_hook)(struct sudo_hook *hook));
1270 \fBregister_hooks\fR()
1271 function is called by the sudo front end to
1272 register any hooks the plugin needs.
1273 If the plugin does not support hooks,
1274 \fRregister_hooks\fR
1275 should be set to the
1281 argument describes the version of the hooks API
1287 \fBregister_hook\fR()
1288 function should be used to register any supported
1289 hooks the plugin needs.
1290 It returns 0 on success, 1 if the hook type is not supported and \-1
1291 if the major version in
1293 does not match the front end's major hook API version.
1296 \fIHook function API\fR
1297 section below for more information
1301 \fBregister_hooks\fR()
1302 function is only available starting
1303 with API version 1.2.
1306 front end doesn't support API
1307 version 1.2 or higher,
1308 \fRregister_hooks\fR
1319 void (*deregister_hooks)(int version,
1320 int (*deregister_hook)(struct sudo_hook *hook));
1325 \fBderegister_hooks\fR()
1326 function is called by the sudo front end
1327 to deregister any hooks the plugin has registered.
1328 If the plugin does not support hooks,
1329 \fRderegister_hooks\fR
1330 should be set to the
1336 argument describes the version of the hooks API
1342 \fBderegister_hook\fR()
1343 function should be used to deregister any
1344 hooks that were put in place by the
1345 \fBregister_hook\fR()
1347 If the plugin tries to deregister a hook that the front end does not support,
1348 \fRderegister_hook\fR
1349 will return an error.
1352 \fIHook function API\fR
1353 section below for more information
1357 \fBderegister_hooks\fR()
1358 function is only available starting
1359 with API version 1.2.
1362 front end doesn't support API
1363 version 1.2 or higher,
1364 \fRderegister_hooks\fR
1369 \fIPolicy Plugin Version Macros\fR
1373 /* Plugin API version major/minor. */
1374 #define SUDO_API_VERSION_MAJOR 1
1375 #define SUDO_API_VERSION_MINOR 2
1376 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1377 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e
1378 SUDO_API_VERSION_MINOR)
1380 /* Getters and setters for API version */
1381 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1382 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1383 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
1384 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1386 #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
1387 *(vp) = (*(vp) & 0xffff0000) | (n); \e
1391 .SS "I/O plugin API"
1395 #define SUDO_IO_PLUGIN 2
1396 unsigned int type; /* always SUDO_IO_PLUGIN */
1397 unsigned int version; /* always SUDO_API_VERSION */
1398 int (*open)(unsigned int version, sudo_conv_t conversation
1399 sudo_printf_t plugin_printf, char * const settings[],
1400 char * const user_info[], int argc, char * const argv[],
1401 char * const user_env[], char * const plugin_options[]);
1402 void (*close)(int exit_status, int error); /* wait status or error */
1403 int (*show_version)(int verbose);
1404 int (*log_ttyin)(const char *buf, unsigned int len);
1405 int (*log_ttyout)(const char *buf, unsigned int len);
1406 int (*log_stdin)(const char *buf, unsigned int len);
1407 int (*log_stdout)(const char *buf, unsigned int len);
1408 int (*log_stderr)(const char *buf, unsigned int len);
1409 void (*register_hooks)(int version,
1410 int (*register_hook)(struct sudo_hook *hook));
1411 void (*deregister_hooks)(int version,
1412 int (*deregister_hook)(struct sudo_hook *hook));
1417 When an I/O plugin is loaded,
1419 runs the command in a pseudo-tty.
1420 This makes it possible to log the input and output from the user's
1422 If any of the standard input, standard output or standard error do not
1423 correspond to a tty,
1425 will open a pipe to capture
1426 the I/O for logging before passing it on.
1428 The log_ttyin function receives the raw user input from the terminal
1429 device (note that this will include input even when echo is disabled,
1430 such as when a password is read).
1431 The log_ttyout function receives output from the pseudo-tty that is
1432 suitable for replaying the user's session at a later time.
1438 functions are only called if the standard input, standard output
1439 or standard error respectively correspond to something other than
1442 Any of the logging functions may be set to the
1444 pointer if no logging is to be performed.
1445 If the open function returns 0, no I/O will be sent to the plugin.
1447 The io_plugin struct has the following fields:
1452 field should always be set to
1453 \fRSUDO_IO_PLUGIN\fR.
1458 field should be set to
1459 \fRSUDO_API_VERSION\fR.
1463 to determine the API version the plugin was
1470 int (*open)(unsigned int version, sudo_conv_t conversation
1471 sudo_printf_t plugin_printf, char * const settings[],
1472 char * const user_info[], int argc, char * const argv[],
1473 char * const user_env[], char * const plugin_options[]);
1479 function is run before the
1483 \fBshow_version\fR()
1484 functions are called.
1485 It is only called if the version is being requested or the
1486 \fBcheck_policy\fR()
1488 returned successfully.
1489 It returns 1 on success, 0 on failure, \-1 if a general error occurred,
1490 or \-2 if there was a usage error.
1493 will print a usage message before it exits.
1494 If an error occurs, the plugin may optionally call the
1495 \fBconversation\fR()
1497 \fBplugin_printf\fR()
1499 \fRSUDO_CONF_ERROR_MSG\fR
1501 additional error information to the user.
1503 The function arguments are as follows:
1506 The version passed in by
1508 allows the plugin to determine the
1509 major and minor version number of the plugin API supported by
1514 \fBconversation\fR()
1515 function that may be used by the
1516 \fBshow_version\fR()
1517 function to display version information (see
1518 \fBshow_version\fR()
1521 \fBconversation\fR()
1522 function may also be used to display additional error message to the user.
1524 \fBconversation\fR()
1525 function returns 0 on success and \-1 on failure.
1529 \fBprintf\fR()-style
1530 function that may be used by the
1531 \fBshow_version\fR()
1532 function to display version information (see
1533 show_version below).
1535 \fBplugin_printf\fR()
1536 function may also be used to display additional error message to the user.
1538 \fBplugin_printf\fR()
1539 function returns number of characters printed on success and \-1 on failure.
1542 A vector of user-supplied
1544 settings in the form of
1547 The vector is terminated by a
1550 These settings correspond to flags the user specified when running
1552 As such, they will only be present when the corresponding flag has
1553 been specified on the command line.
1557 the plugin should split on the
1563 field will never include one
1569 \fIPolicy plugin API\fR
1570 section for a list of all possible settings.
1573 A vector of information about the user running the command in the form of
1576 The vector is terminated by a
1582 the plugin should split on the
1588 field will never include one
1594 \fIPolicy plugin API\fR
1595 section for a list of all possible strings.
1598 The number of elements in
1600 not counting the final
1607 an argument vector describing a command the user
1608 wishes to run in the same form as what would be passed to the
1613 The user's environment in the form of a
1614 \fRNULL\fR-terminated
1621 the plugin should split on the
1627 field will never include one
1633 Any (non-comment) strings immediately after the plugin path are
1634 treated as arguments to the plugin.
1635 These arguments are split on a white space boundary and are passed to
1636 the plugin in the form of a
1637 \fRNULL\fR-terminated
1639 If no arguments were specified,
1640 \fIplugin_options\fR
1646 \fIplugin_options\fR
1647 parameter is only available starting with
1651 check the API version specified
1654 front end before using
1655 \fIplugin_options\fR.
1656 Failure to do so may result in a crash.
1666 void (*close)(int exit_status, int error);
1672 function is called when the command being run by
1676 The function arguments are as follows:
1680 The command's exit status, as returned by the
1691 If the command could not be executed, this is set to the value of
1696 If the command was successfully executed, the value of
1707 int (*show_version)(int verbose);
1712 \fBshow_version\fR()
1713 function is called by
1715 when the user specifies
1719 The plugin may display its version information to the user via the
1720 \fBconversation\fR()
1722 \fBplugin_printf\fR()
1724 \fRSUDO_CONV_INFO_MSG\fR.
1725 If the user requests detailed version information, the verbose flag will be set.
1735 int (*log_ttyin)(const char *buf, unsigned int len);
1741 function is called whenever data can be read from
1742 the user but before it is passed to the running command.
1743 This allows the plugin to reject data if it chooses to (for instance
1744 if the input contains banned content).
1745 Returns 1 if the data should be passed to the command, 0 if the data
1746 is rejected (which will terminate the command) or \-1 if an error occurred.
1748 The function arguments are as follows:
1752 The buffer containing user input.
1766 int (*log_ttyout)(const char *buf, unsigned int len);
1772 function is called whenever data can be read from
1773 the command but before it is written to the user's terminal.
1774 This allows the plugin to reject data if it chooses to (for instance
1775 if the output contains banned content).
1776 Returns 1 if the data should be passed to the user, 0 if the data is rejected
1777 (which will terminate the command) or \-1 if an error occurred.
1779 The function arguments are as follows:
1783 The buffer containing command output.
1797 int (*log_stdin)(const char *buf, unsigned int len);
1803 function is only used if the standard input does
1804 not correspond to a tty device.
1805 It is called whenever data can be read from the standard input but
1806 before it is passed to the running command.
1807 This allows the plugin to reject data if it chooses to
1808 (for instance if the input contains banned content).
1809 Returns 1 if the data should be passed to the command, 0 if the data is
1810 rejected (which will terminate the command) or \-1 if an error occurred.
1812 The function arguments are as follows:
1816 The buffer containing user input.
1830 int (*log_stdout)(const char *buf, unsigned int len);
1836 function is only used if the standard output does not correspond
1838 It is called whenever data can be read from the command but before
1839 it is written to the standard output.
1840 This allows the plugin to reject data if it chooses to
1841 (for instance if the output contains banned content).
1842 Returns 1 if the data should be passed to the user, 0 if the data is
1843 rejected (which will terminate the command) or \-1 if an error occurred.
1845 The function arguments are as follows:
1849 The buffer containing command output.
1863 int (*log_stderr)(const char *buf, unsigned int len);
1869 function is only used if the standard error does
1870 not correspond to a tty device.
1871 It is called whenever data can be read from the command but before it
1872 is written to the standard error.
1873 This allows the plugin to reject data if it chooses to
1874 (for instance if the output contains banned content).
1875 Returns 1 if the data should be passed to the user, 0 if the data is
1876 rejected (which will terminate the command) or \-1 if an error occurred.
1878 The function arguments are as follows:
1882 The buffer containing command output.
1894 \fIPolicy plugin API\fR
1895 section for a description of
1896 \fRregister_hooks\fR.
1901 \fIPolicy plugin API\fR
1902 section for a description of
1903 \fRderegister_hooks.\fR
1905 \fII/O Plugin Version Macros\fR
1908 \fIPolicy plugin API\fR.
1909 .SS "Hook function API"
1910 Beginning with plugin API version 1.2, it is possible to install
1911 hooks for certain functions called by the
1915 Currently, the only supported hooks relate to the handling of
1916 environment variables.
1917 Hooks can be used to intercept attempts to get, set, or remove
1918 environment variables so that these changes can be reflected in
1919 the version of the environment that is used to execute a command.
1920 A future version of the API will support hooking internal
1922 front end functions as well.
1924 \fIHook structure\fR
1928 are described by the following structure:
1932 typedef int (*sudo_hook_fn_t)();
1937 sudo_hook_fn_t hook_fn;
1945 structure has the following fields:
1950 field should be set to
1951 \fRSUDO_HOOK_VERSION\fR.
1956 field may be one of the following supported hook types:
1959 \fRSUDO_HOOK_SETENV\fR
1963 Any registered hooks will run before the C library implementation.
1967 be a function that matches the following typedef:
1972 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1973 const char *value, int overwrite, void *closure);
1977 If the registered hook does not match the typedef the results are
1983 \fRSUDO_HOOK_UNSETENV\fR
1987 Any registered hooks will run before the C library implementation.
1991 be a function that matches the following typedef:
1996 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2005 \fRSUDO_HOOK_GETENV\fR
2009 Any registered hooks will run before the C library implementation.
2013 be a function that matches the following typedef:
2018 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2019 char **value, void *closure);
2023 If the registered hook does not match the typedef the results are
2030 \fRSUDO_HOOK_PUTENV\fR
2034 Any registered hooks will run before the C library implementation.
2038 be a function that matches the following typedef:
2043 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2048 If the registered hook does not match the typedef the results are
2057 sudo_hook_fn_t hook_fn;
2061 field should be set to the plugin's hook implementation.
2062 The actual function arguments will vary depending on the
2070 \fRstruct sudo_hook\fR
2071 is passed as the last function parameter.
2072 This can be used to pass arbitrary data to the plugin's hook implementation.
2074 The function return value may be one of the following:
2078 \fRSUDO_HOOK_RET_ERROR\fR
2079 The hook function encountered an error.
2081 \fRSUDO_HOOK_RET_NEXT\fR
2082 The hook completed without error, go on to the next hook (including
2083 the native implementation if applicable).
2087 \fRSUDO_HOOK_RET_NEXT\fR
2088 if the specified variable was not found in the private copy of the environment.
2090 \fRSUDO_HOOK_RET_STOP\fR
2091 The hook completed without error, stop processing hooks for this invocation.
2092 This can be used to replace the native implementation.
2095 hook that operates on a private copy of
2096 the environment but leaves
2101 Note that it is very easy to create an infinite loop when hooking
2102 C library functions.
2107 function may create a loop if the
2109 implementation calls
2111 to check the locale.
2112 To prevent this, you may wish to use a static variable in the hook
2113 function to guard against nested calls.
2118 static int in_progress = 0; /* avoid recursion */
2120 return SUDO_HOOK_RET_NEXT;
2124 return SUDO_HOOK_RET_STOP;
2128 \fIHook API Version Macros\fR
2132 /* Hook API version major/minor */
2133 #define SUDO_HOOK_VERSION_MAJOR 1
2134 #define SUDO_HOOK_VERSION_MINOR 0
2135 #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
2136 #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e
2137 SUDO_HOOK_VERSION_MINOR)
2139 /* Getters and setters for hook API version */
2140 #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
2141 #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
2142 #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e
2143 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2145 #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e
2146 *(vp) = (*(vp) & 0xffff0000) | (n); \e
2150 .SS "Conversation API"
2151 If the plugin needs to interact with the user, it may do so via the
2152 \fBconversation\fR()
2154 A plugin should not attempt to read directly from the standard input
2155 or the user's tty (neither of which are guaranteed to exist).
2156 The caller must include a trailing newline in
2158 if one is to be printed.
2161 \fBprintf\fR()-style
2162 function is also available that can be used to display informational
2163 or error messages to the user, which is usually more convenient for
2164 simple messages where no use input is required.
2168 struct sudo_conv_message {
2169 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2170 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2171 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2172 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2173 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2174 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
2175 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2181 struct sudo_conv_reply {
2185 typedef int (*sudo_conv_t)(int num_msgs,
2186 const struct sudo_conv_message msgs[],
2187 struct sudo_conv_reply replies[]);
2189 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2194 \fBconversation\fR()
2196 \fBprintf\fR()-style
2197 functions are passed
2200 function when the plugin is initialized.
2203 \fBconversation\fR()
2204 function, the plugin must pass an array of
2205 \fRsudo_conv_message\fR
2207 \fRsudo_conv_reply\fR
2210 \fRstruct sudo_conv_message\fR
2212 \fRstruct sudo_conv_reply\fR
2214 each message in the conversation.
2215 The plugin is responsible for freeing the reply buffer filled in to the
2216 \fRstruct sudo_conv_reply\fR,
2220 \fBprintf\fR()-style
2221 function uses the same underlying mechanism as the
2222 \fBconversation\fR()
2223 function but only supports
2224 \fRSUDO_CONV_INFO_MSG\fR,
2225 \fRSUDO_CONV_ERROR_MSG\fR
2227 \fRSUDO_CONV_DEBUG_MSG\fR
2231 It can be more convenient than using the
2232 \fBconversation\fR()
2233 function if no user reply is needed and supports standard
2238 \fRSUDO_CONV_INFO_MSG\fR
2240 Dv SUDO_CONV_ERROR_MSG ,
2243 \fRSUDO_CONV_DEBUG_MSG\fR
2247 Instead, they are logged to the file specified in the
2249 statement (if any) in the
2250 \fI@sysconfdir@/sudo.conf\fR
2253 This allows a plugin to log debugging information and is intended
2254 to be used in conjunction with the
2258 See the sample plugin for an example of the
2259 \fBconversation\fR()
2261 .SS "Sudoers group plugin API"
2264 module supports a plugin interface to allow non-Unix
2266 This can be used to query a group source other than the standard Unix
2268 A sample group plugin is bundled with
2270 that implements file-based lookups.
2271 Third party group plugins include a QAS AD plugin available from Quest Software.
2273 A group plugin must declare and populate a
2274 \fRsudoers_group_plugin\fR
2275 struct in the global scope.
2276 This structure contains pointers to the functions that implement plugin
2277 initialization, cleanup and group lookup.
2281 struct sudoers_group_plugin {
2282 unsigned int version;
2283 int (*init)(int version, sudo_printf_t sudo_printf,
2284 char *const argv[]);
2285 void (*cleanup)(void);
2286 int (*query)(const char *user, const char *group,
2287 const struct passwd *pwd);
2293 \fRsudoers_group_plugin\fR
2294 struct has the following fields:
2299 field should be set to GROUP_API_VERSION.
2303 to determine the API version the group plugin
2310 int (*init)(int version, sudo_printf_t plugin_printf,
2311 char *const argv[]);
2317 function is called after
2320 before any policy checks.
2321 It returns 1 on success, 0 on failure (or if the plugin is not configured),
2322 and \-1 if a error occurred.
2323 If an error occurs, the plugin may call the
2324 \fBplugin_printf\fR()
2326 \fRSUDO_CONF_ERROR_MSG\fR
2327 to present additional error information
2330 The function arguments are as follows:
2333 The version passed in by
2335 allows the plugin to determine the
2336 major and minor version number of the group plugin API supported by
2341 \fBprintf\fR()-style
2342 function that may be used to display informational or error message to the user.
2343 Returns the number of characters printed on success and \-1 on failure.
2347 \fRNULL\fR-terminated
2348 array of arguments generated from the
2352 If no arguments were given,
2370 function is called when
2374 The plugin should free any memory it has allocated and close open file handles.
2385 int (*query)(const char *user, const char *group,
2386 const struct passwd *pwd);
2392 function is used to ask the group plugin whether
2397 The function arguments are as follows:
2401 The name of the user being looked up in the external group database.
2405 The name of the group being queried.
2408 The password database entry for
2414 present in the password database,
2420 \fIGroup API Version Macros\fR
2424 /* Sudoers group plugin version major/minor */
2425 #define GROUP_API_VERSION_MAJOR 1
2426 #define GROUP_API_VERSION_MINOR 0
2427 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
2428 GROUP_API_VERSION_MINOR)
2430 /* Getters and setters for group version */
2431 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
2432 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
2433 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
2434 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2436 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
2437 *(vp) = (*(vp) & 0xffff0000) | (n); \e
2441 .SH "PLUGIN API CHANGELOG"
2442 The following revisions have been made to the Sudo Plugin API.
2445 Initial API version.
2448 The I/O logging plugin's
2450 function was modified to take the
2452 list as an argument.
2455 The Policy and I/O logging plugins'
2457 functions are now passed
2458 a list of plugin options if any are specified in
2459 \fI@sysconfdir@/sudo.conf\fR.
2461 A simple hooks API has been introduced to allow plugins to hook in to the
2462 system's environment handling functions.
2466 Policy plugin function is now passed a pointer
2467 to the user environment which can be updated as needed.
2468 This can be used to merge in environment variables stored in the PAM
2469 handle before a command is run.
2471 sudoers(@mansectform@),
2474 If you feel you have found a bug in
2476 please submit a bug report at http://www.sudo.ws/sudo/bugs/
2478 Limited free support is available via the sudo-users mailing list,
2479 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
2480 search the archives.
2485 and any express or implied warranties, including, but not limited
2486 to, the implied warranties of merchantability and fitness for a
2487 particular purpose are disclaimed.
2488 See the LICENSE file distributed with
2490 or http://www.sudo.ws/sudo/license.html for complete details.