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-2013 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" "March 5, 2013" "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 in the
38 sudo.conf(@mansectform@)
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 "Policy plugin API"
51 A policy plugin must declare and populate a
53 struct in the global scope.
54 This structure contains pointers to the functions that implement the
57 The name of the symbol should be specified in
58 sudo.conf(@mansectform@)
59 along with a path to the plugin so that
65 struct policy_plugin {
66 #define SUDO_POLICY_PLUGIN 1
67 unsigned int type; /* always SUDO_POLICY_PLUGIN */
68 unsigned int version; /* always SUDO_API_VERSION */
69 int (*open)(unsigned int version, sudo_conv_t conversation,
70 sudo_printf_t plugin_printf, char * const settings[],
71 char * const user_info[], char * const user_env[],
72 char * const plugin_options[]);
73 void (*close)(int exit_status, int error);
74 int (*show_version)(int verbose);
75 int (*check_policy)(int argc, char * const argv[],
76 char *env_add[], char **command_info[],
77 char **argv_out[], char **user_env_out[]);
78 int (*list)(int argc, char * const argv[], int verbose,
79 const char *list_user);
80 int (*validate)(void);
81 void (*invalidate)(int remove);
82 int (*init_session)(struct passwd *pwd, char **user_env[]);
83 void (*register_hooks)(int version,
84 int (*register_hook)(struct sudo_hook *hook));
85 void (*deregister_hooks)(int version,
86 int (*deregister_hook)(struct sudo_hook *hook));
91 The policy_plugin struct has the following fields:
96 field should always be set to SUDO_POLICY_PLUGIN.
101 field should be set to
102 \fRSUDO_API_VERSION\fR.
106 to determine the API version the plugin was
113 int (*open)(unsigned int version, sudo_conv_t conversation,
114 sudo_printf_t plugin_printf, char * const settings[],
115 char * const user_info[], char * const user_env[],
116 char * const plugin_options[]);
120 Returns 1 on success, 0 on failure, \-1 if a general error occurred,
121 or \-2 if there was a usage error.
124 will print a usage message before it exits.
125 If an error occurs, the plugin may optionally call the
128 \fBplugin_printf\fR()
130 \fRSUDO_CONF_ERROR_MSG\fR
131 to present additional error information to the user.
133 The function arguments are as follows:
136 The version passed in by
138 allows the plugin to determine the
139 major and minor version number of the plugin API supported by
145 function that can be used by the plugin to interact with the user (see below).
146 Returns 0 on success and \-1 on failure.
151 function that may be used to display informational or error messages
153 Returns the number of characters printed on success and \-1 on failure.
156 A vector of user-supplied
158 settings in the form of
161 The vector is terminated by a
164 These settings correspond to flags the user specified when running
166 As such, they will only be present when the corresponding flag has
167 been specified on the command line.
171 the plugin should split on the
177 field will never include one
184 Authentication type, if specified by the
187 systems where BSD authentication is supported.
190 If specified, the user has requested via the
194 close all files descriptors with a value of
197 The plugin may optionally pass this, or another value, back in the
202 A comma-separated list of debug flags that correspond to
206 sudo.conf(@mansectform@),
208 The flags are passed to the plugin as they appear in
209 sudo.conf(@mansectform@).
215 \fIsubsystem\fR@\fIpriority\fR
216 but the plugin is free to use a different
217 format so long as it does not include a comma
219 There is not currently a way to specify a set of debug flags specific
220 to the plugin--the flags are shared by
225 This setting has been deprecated in favor of
229 Set to true if the user specified the
232 command, indicating that the user wishes to ignore any cached
233 authentication credentials.
239 to be used similarly to
241 If the plugin does not to support this usage, it may return a value of \-2
244 function, which will cause
246 to print a usage message and
250 If the user does not specify a program on the command line,
252 will pass the plugin the path to the user's shell and set
255 BSD login class to use when setting resource limits and nice value,
261 Set to true if the user specified the
263 flag, indicating that
264 the user wishes to run a login shell.
267 The maximum number of groups a user may belong to.
268 This will only be present if there is a corresponding setting in
269 sudo.conf(@mansectform@).
272 A space-separated list of IP network addresses and netmasks in the
276 ``192.168.1.2/255.255.255.0''.
277 The address and netmask pairs may be either IPv4 or IPv6, depending on
278 what the operating system supports.
279 If the address contains a colon
281 it is an IPv6 address, else it is IPv4.
284 Set to true if the user specified the
286 flag, indicating that
288 should operate in non-interactive mode.
289 The plugin may reject a command run in non-interactive mode if user
290 interaction is required.
293 The default plugin directory used by the
296 This is the default directory set at compile time and may not
297 correspond to the directory the running plugin was loaded from.
298 It may be used by a plugin to locate support files.
300 preserve_environment=bool
301 Set to true if the user specified the
303 flag, indicating that
304 the user wishes to preserve the environment.
307 Set to true if the user specified the
309 flag, indicating that
310 the user wishes to preserve the group vector instead of setting it
311 based on the runas user.
314 The command name that sudo was run as, typically
320 The prompt to use when requesting a password, if specified via
326 Set to true if the user specified the
328 flag, indicating that
329 the user wishes to run a shell.
332 The group name or gid to to run the command as, if specified via
338 The user name or uid to to run the command as, if specified via the
343 SELinux role to use when executing the command, if specified by
349 SELinux type to use when executing the command, if specified by
355 Set to true if the user specified the
360 environment variable to the target user's home directory.
365 flag is is specified or if invoked as
367 The plugin shall substitute an editor into
371 function or return \-2 with a usage error
372 if the plugin does not support
374 For more information, see the
378 Additional settings may be added in the future so the plugin should
379 silently ignore settings that it does not recognize.
385 A vector of information about the user running the command in the form of
388 The vector is terminated by a
394 the plugin should split on the
400 field will never include one
408 The number of columns the user's terminal supports.
409 If there is no terminal device available, a default value of 80 is used.
412 The user's current working directory.
415 The effective group ID of the user invoking
419 The effective user ID of the user invoking
423 The real group ID of the user invoking
427 The user's supplementary group list formatted as a string of
428 comma-separated group IDs.
431 The local machine's hostname as returned by the
436 The number of lines the user's terminal supports.
438 no terminal device available, a default value of 24 is used.
441 The ID of the process group that the running
443 process is a member of.
444 Only available starting with API version 1.2
447 The process ID of the running
450 Only available starting with API version 1.2
453 Any (non-comment) strings immediately after the plugin path are
454 passed as arguments to the plugin.
455 These arguments are split on a white space boundary and are passed to
456 the plugin in the form of a
457 \fRNULL\fR-terminated
468 parameter is only available starting with
472 check the API version specified
475 front end before using
476 \fIplugin_options\fR.
477 Failure to do so may result in a crash.
480 The parent process ID of the running
483 Only available starting with API version 1.2
486 The session ID of the running
490 is not part of a POSIX job control session.
491 Only available starting with API version 1.2
494 The ID of the foreground process group associated with the terminal
495 device associated with the
497 process or \-1 if there is no
499 Only available starting with API version 1.2
502 The path to the user's terminal device.
503 If the user has no terminal device associated with the session,
504 the value will be empty, as in
508 The real user ID of the user invoking
512 The name of the user invoking
519 The user's environment in the form of a
520 \fRNULL\fR-terminated vector of
526 the plugin should split on the
532 field will never include one
546 void (*close)(int exit_status, int error);
552 function is called when the command being run by
556 The function arguments are as follows:
560 The command's exit status, as returned by the
571 If the command could not be executed, this is set to the value of
576 The plugin is responsible for displaying error information via the
579 \fBplugin_printf\fR()
581 If the command was successfully executed, the value of
587 function is defined, no I/O logging plugins are loaded,
592 options are set in the
596 front end may execute the command directly instead of running
597 it as a child process.
606 int (*show_version)(int verbose);
612 function is called by
614 when the user specifies
618 The plugin may display its version information to the user via the
621 \fBplugin_printf\fR()
623 \fRSUDO_CONV_INFO_MSG\fR.
624 If the user requests detailed version information, the verbose flag will be set.
634 int (*check_policy)(int argc, char * const argv[]
635 char *env_add[], char **command_info[],
636 char **argv_out[], char **user_env_out[]);
642 function is called by
645 whether the user is allowed to run the specified commands.
649 option was enabled in the
654 function, the user has requested
658 is a mechanism for editing one or more files
659 where an editor is run with the user's credentials instead of with
662 achieves this by creating user-writable
663 temporary copies of the files to be edited and then overwriting the
664 originals with the temporary copies after editing is complete.
665 If the plugin supports
667 it should choose the editor to be used, potentially from a variable
668 in the user's environment, such as
672 (note that environment
673 variables may include command line flags).
674 The files to be edited should be copied from
679 editor and its arguments by a
687 before the editor is executed.
688 The plugin should also set
696 function returns 1 if the command is allowed,
697 0 if not allowed, \-1 for a general error, or \-2 for a usage error
700 was specified but is unsupported by the plugin.
703 will print a usage message before it
705 If an error occurs, the plugin may optionally call the
708 \fBplugin_printf\fR()
710 \fRSUDO_CONF_ERROR_MSG\fR
711 to present additional error information to the user.
713 The function arguments are as follows:
717 The number of elements in
719 not counting the final
724 The argument vector describing the command the user wishes to run,
725 in the same form as what would be passed to the
728 The vector is terminated by a
733 Additional environment variables specified by the user on the command
734 line in the form of a
735 \fRNULL\fR-terminated
739 The plugin may reject the command if one or more variables
740 are not allowed to be set, or it may silently ignore such variables.
744 the plugin should split on the
750 field will never include one
756 Information about the command being run in the form of
759 These values are used by
762 environment when running a command.
763 The plugin is responsible for creating and populating the vector,
764 which must be terminated with a
767 The following values are recognized by
772 The root directory to use when running the command.
777 will close all files descriptors with a value
783 Fully qualified path to the command to be executed.
786 The current working directory to change to when executing the command.
791 runs a command as the foreground process as long as
793 itself is running in the foreground.
795 \fIexec_background\fR
796 is enabled and the command is being run in a pty (due to I/O logging
799 setting), the command will be run as a background process.
800 Attempts to read from the controlling terminal (or to change terminal
801 settings) will result in the command being suspended with the
805 in the case of terminal settings).
808 is a foreground process, the command will be granted the controlling terminal
809 and resumed in the foreground with no user intervention required.
810 The advantage of initially running the command in the background is that
812 need not read from the terminal unless the command explicitly requests it.
813 Otherwise, any terminal input must be passed to the command, whether it
814 has required it or not (the kernel buffers terminals so it is not possible
815 to tell whether the command really wants the input).
816 This is different from historic
818 behavior or when the command is not being run in a pty.
820 For this to work seamlessly, the operating system must support the
821 automatic restarting of system calls.
822 Unfortunately, not all operating systems do this by default,
823 and even those that do may have bugs.
824 For example, Mac OS X fails to restart the
828 system calls (this is a bug in Mac OS X).
829 Furthermore, because this behavior depends on the command stopping with the
833 signals, programs that catch these signals and suspend themselves
834 with a different signal (usually
836 will not be automatically foregrounded.
837 Some versions of the linux
839 command behave this way.
840 Because of this, a plugin should not set
841 \fIexec_background\fR
842 unless it is explicitly enabled by the administrator and there should
843 be a way to enabled or disable it on a per-command basis.
845 This setting has no effect unless I/O logging is enabled or
850 Set to true if the I/O logging plugins, if any, should compress the
852 This is a hint to the I/O logging plugin which may choose to ignore it.
855 Fully qualified path to the file or directory in which I/O log is
857 This is a hint to the I/O logging plugin which may choose to ignore it.
858 If no I/O logging plugin is loaded, this setting has no effect.
861 Set to true if the I/O logging plugins, if any, should log the
862 standard input if it is not connected to a terminal device.
863 This is a hint to the I/O logging plugin which may choose to ignore it.
866 Set to true if the I/O logging plugins, if any, should log the
867 standard output if it is not connected to a terminal device.
868 This is a hint to the I/O logging plugin which may choose to ignore it.
871 Set to true if the I/O logging plugins, if any, should log the
872 standard error if it is not connected to a terminal device.
873 This is a hint to the I/O logging plugin which may choose to ignore it.
876 Set to true if the I/O logging plugins, if any, should log all
878 This only includes input typed by the user and not from a pipe or
879 redirected from a file.
880 This is a hint to the I/O logging plugin which may choose to ignore it.
883 Set to true if the I/O logging plugins, if any, should log all
885 This only includes output to the screen, not output to a pipe or file.
886 This is a hint to the I/O logging plugin which may choose to ignore it.
889 BSD login class to use when setting resource limits and nice value
891 This option is only set on systems that support login classes.
894 Nice value (priority) to use when executing the command.
895 The nice value, if specified, overrides the priority associated with the
900 If set, prevent the command from executing other programs.
905 will preserve the user's group vector instead of
906 initializing the group vector based on
910 Effective group ID to run the command as.
911 If not specified, the value of
916 Effective user ID to run the command as.
917 If not specified, the value of
922 Group ID to run the command as.
925 The supplementary group vector to use for the command in the form
926 of a comma-separated list of group IDs.
928 \fIpreserve_groups\fR
929 is set, this option is ignored.
932 User ID to run the command as.
935 SELinux role to use when executing the command.
938 SELinux type to use when executing the command.
941 Create a utmp (or utmpx) entry when a pseudo-tty is allocated.
942 By default, the new entry will be a copy of the user's existing utmp
943 entry (if any), with the tty, time, type and pid fields updated.
949 The plugin may enable
955 This allows the plugin to perform command substitution and transparently
958 when the user attempts to run an editor.
962 If non-zero then when the timeout expires the command will be killed.
965 The file creation mask to use when executing the command.
968 Allocate a pseudo-tty to run the command in, regardless of whether
969 or not I/O logging is in use.
973 the command in a pty when an I/O log plugin is loaded.
976 User name to use when constructing a new utmp (or utmpx) entry when
979 This option can be used to set the user field in the utmp entry to
980 the user the command runs as rather than the invoking user.
983 will base the new entry on
984 the invoking user's existing entry.
986 Unsupported values will be ignored.
993 \fRNULL\fR-terminated
994 argument vector to pass to the
996 system call when executing the command.
997 The plugin is responsible for allocating and populating the vector.
1002 \fRNULL\fR-terminated
1003 environment vector to use when executing the command.
1004 The plugin is responsible for allocating and populating the vector.
1013 int (*list)(int verbose, const char *list_user,
1014 int argc, char * const argv[]);
1018 List available privileges for the invoking user.
1019 Returns 1 on success, 0 on failure and \-1 on error.
1020 On error, the plugin may optionally call the
1021 \fBconversation\fR()
1023 \fBplugin_printf\fR()
1025 \fRSUDO_CONF_ERROR_MSG\fR
1026 to present additional error information to
1029 Privileges should be output via the
1030 \fBconversation\fR()
1032 \fBplugin_printf\fR()
1034 \fRSUDO_CONV_INFO_MSG\fR,
1038 Flag indicating whether to list in verbose mode or not.
1041 The name of a different user to list privileges for if the policy
1045 the plugin should list the privileges of the invoking user.
1048 The number of elements in
1050 not counting the final
1057 an argument vector describing a command the user
1058 wishes to check against the policy in the same form as what would
1062 If the command is permitted by the policy, the fully-qualified path
1063 to the command should be displayed along with any command line arguments.
1072 int (*validate)(void);
1078 function is called when
1083 For policy plugins such as
1086 authentication credentials, this function will validate and cache
1093 if the plugin does not support credential caching.
1095 Returns 1 on success, 0 on failure and \-1 on error.
1096 On error, the plugin may optionally call the
1097 \fBconversation\fR()
1099 \fBplugin_printf\fR()
1101 \fRSUDO_CONF_ERROR_MSG\fR
1102 to present additional
1103 error information to the user.
1113 void (*invalidate)(int remove);
1119 function is called when
1127 For policy plugins such as
1130 cache authentication credentials, this function will invalidate the
1134 flag is set, the plugin may remove
1135 the credentials instead of simply invalidating them.
1141 if the plugin does not support credential caching.
1151 int (*init_session)(struct passwd *pwd, char **user_envp[);
1156 \fBinit_session\fR()
1157 function is called before
1160 execution environment for the command.
1161 It is run in the parent
1163 process and before any uid or gid changes.
1164 This can be used to perform session setup that is not supported by
1166 such as opening the PAM session.
1170 used to tear down the session that was opened by
1175 argument points to a passwd struct for the user the
1176 command will be run as if the uid the command will run as was found
1177 in the password database, otherwise it will be
1182 argument points to the environment the command will
1183 run in, in the form of a
1184 \fRNULL\fR-terminated
1188 This is the same string passed back to the front end via
1193 \fBinit_session\fR()
1194 function needs to modify the user environment, it should update the
1197 The expected use case is to merge the contents of the PAM environment
1198 (if any) with the contents of
1202 parameter is only available
1203 starting with API version 1.2.
1207 version specified by the
1209 front end before using
1211 Failure to do so may result in a crash.
1213 Returns 1 on success, 0 on failure and \-1 on error.
1214 On error, the plugin may optionally call the
1215 \fBconversation\fR()
1217 \fBplugin_printf\fR()
1219 \fRSUDO_CONF_ERROR_MSG\fR
1220 to present additional
1221 error information to the user.
1231 void (*register_hooks)(int version,
1232 int (*register_hook)(struct sudo_hook *hook));
1237 \fBregister_hooks\fR()
1238 function is called by the sudo front end to
1239 register any hooks the plugin needs.
1240 If the plugin does not support hooks,
1241 \fRregister_hooks\fR
1242 should be set to the
1248 argument describes the version of the hooks API
1254 \fBregister_hook\fR()
1255 function should be used to register any supported
1256 hooks the plugin needs.
1257 It returns 0 on success, 1 if the hook type is not supported and \-1
1258 if the major version in
1260 does not match the front end's major hook API version.
1263 \fIHook function API\fR
1264 section below for more information
1268 \fBregister_hooks\fR()
1269 function is only available starting
1270 with API version 1.2.
1273 front end doesn't support API
1274 version 1.2 or higher,
1275 \fRregister_hooks\fR
1286 void (*deregister_hooks)(int version,
1287 int (*deregister_hook)(struct sudo_hook *hook));
1292 \fBderegister_hooks\fR()
1293 function is called by the sudo front end
1294 to deregister any hooks the plugin has registered.
1295 If the plugin does not support hooks,
1296 \fRderegister_hooks\fR
1297 should be set to the
1303 argument describes the version of the hooks API
1309 \fBderegister_hook\fR()
1310 function should be used to deregister any
1311 hooks that were put in place by the
1312 \fBregister_hook\fR()
1314 If the plugin tries to deregister a hook that the front end does not support,
1315 \fRderegister_hook\fR
1316 will return an error.
1319 \fIHook function API\fR
1320 section below for more information
1324 \fBderegister_hooks\fR()
1325 function is only available starting
1326 with API version 1.2.
1329 front end doesn't support API
1330 version 1.2 or higher,
1331 \fRderegister_hooks\fR
1336 \fIPolicy Plugin Version Macros\fR
1340 /* Plugin API version major/minor. */
1341 #define SUDO_API_VERSION_MAJOR 1
1342 #define SUDO_API_VERSION_MINOR 2
1343 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1344 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\e
1345 SUDO_API_VERSION_MINOR)
1347 /* Getters and setters for API version */
1348 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1349 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1350 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \e
1351 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
1353 #define SUDO_VERSION_SET_MINOR(vp, n) do { \e
1354 *(vp) = (*(vp) & 0xffff0000) | (n); \e
1358 .SS "I/O plugin API"
1362 #define SUDO_IO_PLUGIN 2
1363 unsigned int type; /* always SUDO_IO_PLUGIN */
1364 unsigned int version; /* always SUDO_API_VERSION */
1365 int (*open)(unsigned int version, sudo_conv_t conversation,
1366 sudo_printf_t plugin_printf, char * const settings[],
1367 char * const user_info[], char * const command_info[],
1368 int argc, char * const argv[], char * const user_env[],
1369 char * const plugin_options[]);
1370 void (*close)(int exit_status, int error); /* wait status or error */
1371 int (*show_version)(int verbose);
1372 int (*log_ttyin)(const char *buf, unsigned int len);
1373 int (*log_ttyout)(const char *buf, unsigned int len);
1374 int (*log_stdin)(const char *buf, unsigned int len);
1375 int (*log_stdout)(const char *buf, unsigned int len);
1376 int (*log_stderr)(const char *buf, unsigned int len);
1377 void (*register_hooks)(int version,
1378 int (*register_hook)(struct sudo_hook *hook));
1379 void (*deregister_hooks)(int version,
1380 int (*deregister_hook)(struct sudo_hook *hook));
1385 When an I/O plugin is loaded,
1387 runs the command in a pseudo-tty.
1388 This makes it possible to log the input and output from the user's
1390 If any of the standard input, standard output or standard error do not
1391 correspond to a tty,
1393 will open a pipe to capture
1394 the I/O for logging before passing it on.
1396 The log_ttyin function receives the raw user input from the terminal
1397 device (note that this will include input even when echo is disabled,
1398 such as when a password is read).
1399 The log_ttyout function receives output from the pseudo-tty that is
1400 suitable for replaying the user's session at a later time.
1406 functions are only called if the standard input, standard output
1407 or standard error respectively correspond to something other than
1410 Any of the logging functions may be set to the
1412 pointer if no logging is to be performed.
1413 If the open function returns 0, no I/O will be sent to the plugin.
1415 The io_plugin struct has the following fields:
1420 field should always be set to
1421 \fRSUDO_IO_PLUGIN\fR.
1426 field should be set to
1427 \fRSUDO_API_VERSION\fR.
1431 to determine the API version the plugin was
1438 int (*open)(unsigned int version, sudo_conv_t conversation,
1439 sudo_printf_t plugin_printf, char * const settings[],
1440 char * const user_info[], int argc, char * const argv[],
1441 char * const user_env[], char * const plugin_options[]);
1447 function is run before the
1451 \fBshow_version\fR()
1452 functions are called.
1453 It is only called if the version is being requested or the
1454 \fBcheck_policy\fR()
1456 returned successfully.
1457 It returns 1 on success, 0 on failure, \-1 if a general error occurred,
1458 or \-2 if there was a usage error.
1461 will print a usage message before it exits.
1462 If an error occurs, the plugin may optionally call the
1463 \fBconversation\fR()
1465 \fBplugin_printf\fR()
1467 \fRSUDO_CONF_ERROR_MSG\fR
1469 additional error information to the user.
1471 The function arguments are as follows:
1474 The version passed in by
1476 allows the plugin to determine the
1477 major and minor version number of the plugin API supported by
1482 \fBconversation\fR()
1483 function that may be used by the
1484 \fBshow_version\fR()
1485 function to display version information (see
1486 \fBshow_version\fR()
1489 \fBconversation\fR()
1490 function may also be used to display additional error message to the user.
1492 \fBconversation\fR()
1493 function returns 0 on success and \-1 on failure.
1497 \fBprintf\fR()-style
1498 function that may be used by the
1499 \fBshow_version\fR()
1500 function to display version information (see
1501 show_version below).
1503 \fBplugin_printf\fR()
1504 function may also be used to display additional error message to the user.
1506 \fBplugin_printf\fR()
1507 function returns number of characters printed on success and \-1 on failure.
1510 A vector of user-supplied
1512 settings in the form of
1515 The vector is terminated by a
1518 These settings correspond to flags the user specified when running
1520 As such, they will only be present when the corresponding flag has
1521 been specified on the command line.
1525 the plugin should split on the
1531 field will never include one
1537 \fIPolicy plugin API\fR
1538 section for a list of all possible settings.
1541 A vector of information about the user running the command in the form of
1544 The vector is terminated by a
1550 the plugin should split on the
1556 field will never include one
1562 \fIPolicy plugin API\fR
1563 section for a list of all possible strings.
1566 The number of elements in
1568 not counting the final
1575 an argument vector describing a command the user
1576 wishes to run in the same form as what would be passed to the
1581 The user's environment in the form of a
1582 \fRNULL\fR-terminated
1589 the plugin should split on the
1595 field will never include one
1601 Any (non-comment) strings immediately after the plugin path are
1602 treated as arguments to the plugin.
1603 These arguments are split on a white space boundary and are passed to
1604 the plugin in the form of a
1605 \fRNULL\fR-terminated
1607 If no arguments were specified,
1608 \fIplugin_options\fR
1614 \fIplugin_options\fR
1615 parameter is only available starting with
1619 check the API version specified
1622 front end before using
1623 \fIplugin_options\fR.
1624 Failure to do so may result in a crash.
1634 void (*close)(int exit_status, int error);
1640 function is called when the command being run by
1644 The function arguments are as follows:
1648 The command's exit status, as returned by the
1659 If the command could not be executed, this is set to the value of
1664 If the command was successfully executed, the value of
1675 int (*show_version)(int verbose);
1680 \fBshow_version\fR()
1681 function is called by
1683 when the user specifies
1687 The plugin may display its version information to the user via the
1688 \fBconversation\fR()
1690 \fBplugin_printf\fR()
1692 \fRSUDO_CONV_INFO_MSG\fR.
1693 If the user requests detailed version information, the verbose flag will be set.
1703 int (*log_ttyin)(const char *buf, unsigned int len);
1709 function is called whenever data can be read from
1710 the user but before it is passed to the running command.
1711 This allows the plugin to reject data if it chooses to (for instance
1712 if the input contains banned content).
1713 Returns 1 if the data should be passed to the command, 0 if the data
1714 is rejected (which will terminate the command) or \-1 if an error occurred.
1716 The function arguments are as follows:
1720 The buffer containing user input.
1734 int (*log_ttyout)(const char *buf, unsigned int len);
1740 function is called whenever data can be read from
1741 the command but before it is written to the user's terminal.
1742 This allows the plugin to reject data if it chooses to (for instance
1743 if the output contains banned content).
1744 Returns 1 if the data should be passed to the user, 0 if the data is rejected
1745 (which will terminate the command) or \-1 if an error occurred.
1747 The function arguments are as follows:
1751 The buffer containing command output.
1765 int (*log_stdin)(const char *buf, unsigned int len);
1771 function is only used if the standard input does
1772 not correspond to a tty device.
1773 It is called whenever data can be read from the standard input but
1774 before it is passed to the running command.
1775 This allows the plugin to reject data if it chooses to
1776 (for instance if the input contains banned content).
1777 Returns 1 if the data should be passed to the command, 0 if the data is
1778 rejected (which will terminate the command) or \-1 if an error occurred.
1780 The function arguments are as follows:
1784 The buffer containing user input.
1798 int (*log_stdout)(const char *buf, unsigned int len);
1804 function is only used if the standard output does not correspond
1806 It is called whenever data can be read from the command but before
1807 it is written to the standard output.
1808 This allows the plugin to reject data if it chooses to
1809 (for instance if the output contains banned content).
1810 Returns 1 if the data should be passed to the user, 0 if the data is
1811 rejected (which will terminate the command) or \-1 if an error occurred.
1813 The function arguments are as follows:
1817 The buffer containing command output.
1831 int (*log_stderr)(const char *buf, unsigned int len);
1837 function is only used if the standard error does
1838 not correspond to a tty device.
1839 It is called whenever data can be read from the command but before it
1840 is written to the standard error.
1841 This allows the plugin to reject data if it chooses to
1842 (for instance if the output contains banned content).
1843 Returns 1 if the data should be passed to the user, 0 if the data is
1844 rejected (which will terminate the command) or \-1 if an error occurred.
1846 The function arguments are as follows:
1850 The buffer containing command output.
1862 \fIPolicy plugin API\fR
1863 section for a description of
1864 \fRregister_hooks\fR.
1869 \fIPolicy plugin API\fR
1870 section for a description of
1871 \fRderegister_hooks.\fR
1873 \fII/O Plugin Version Macros\fR
1876 \fIPolicy plugin API\fR.
1877 .SS "Signal handlers"
1880 front end installs default signal handlers to trap common signals
1881 while the plugin functions are run.
1882 The following signals are trapped by default before the command is
1911 If a fatal signal is received before the command is executed,
1913 will call the plugin's
1915 function with an exit status of 128 plus the value of the signal
1917 This allows for consistent logging of commands killed by a signal
1918 for plugins that log such information in their
1922 A plugin may temporarily install its own signal handlers but must
1923 restore the original handler before the plugin function returns.
1924 .SS "Hook function API"
1925 Beginning with plugin API version 1.2, it is possible to install
1926 hooks for certain functions called by the
1930 Currently, the only supported hooks relate to the handling of
1931 environment variables.
1932 Hooks can be used to intercept attempts to get, set, or remove
1933 environment variables so that these changes can be reflected in
1934 the version of the environment that is used to execute a command.
1935 A future version of the API will support hooking internal
1937 front end functions as well.
1939 \fIHook structure\fR
1943 are described by the following structure:
1947 typedef int (*sudo_hook_fn_t)();
1952 sudo_hook_fn_t hook_fn;
1960 structure has the following fields:
1965 field should be set to
1966 \fRSUDO_HOOK_VERSION\fR.
1971 field may be one of the following supported hook types:
1974 \fRSUDO_HOOK_SETENV\fR
1978 Any registered hooks will run before the C library implementation.
1982 be a function that matches the following typedef:
1987 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1988 const char *value, int overwrite, void *closure);
1992 If the registered hook does not match the typedef the results are
1998 \fRSUDO_HOOK_UNSETENV\fR
2002 Any registered hooks will run before the C library implementation.
2006 be a function that matches the following typedef:
2011 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2020 \fRSUDO_HOOK_GETENV\fR
2024 Any registered hooks will run before the C library implementation.
2028 be a function that matches the following typedef:
2033 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2034 char **value, void *closure);
2038 If the registered hook does not match the typedef the results are
2045 \fRSUDO_HOOK_PUTENV\fR
2049 Any registered hooks will run before the C library implementation.
2053 be a function that matches the following typedef:
2058 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2063 If the registered hook does not match the typedef the results are
2072 sudo_hook_fn_t hook_fn;
2076 field should be set to the plugin's hook implementation.
2077 The actual function arguments will vary depending on the
2085 \fRstruct sudo_hook\fR
2086 is passed as the last function parameter.
2087 This can be used to pass arbitrary data to the plugin's hook implementation.
2089 The function return value may be one of the following:
2093 \fRSUDO_HOOK_RET_ERROR\fR
2094 The hook function encountered an error.
2096 \fRSUDO_HOOK_RET_NEXT\fR
2097 The hook completed without error, go on to the next hook (including
2098 the native implementation if applicable).
2102 \fRSUDO_HOOK_RET_NEXT\fR
2103 if the specified variable was not found in the private copy of the environment.
2105 \fRSUDO_HOOK_RET_STOP\fR
2106 The hook completed without error, stop processing hooks for this invocation.
2107 This can be used to replace the native implementation.
2110 hook that operates on a private copy of
2111 the environment but leaves
2116 Note that it is very easy to create an infinite loop when hooking
2117 C library functions.
2122 function may create a loop if the
2124 implementation calls
2126 to check the locale.
2127 To prevent this, you may wish to use a static variable in the hook
2128 function to guard against nested calls.
2133 static int in_progress = 0; /* avoid recursion */
2135 return SUDO_HOOK_RET_NEXT;
2139 return SUDO_HOOK_RET_STOP;
2143 \fIHook API Version Macros\fR
2147 /* Hook API version major/minor */
2148 #define SUDO_HOOK_VERSION_MAJOR 1
2149 #define SUDO_HOOK_VERSION_MINOR 0
2150 #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
2151 #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\e
2152 SUDO_HOOK_VERSION_MINOR)
2154 /* Getters and setters for hook API version */
2155 #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
2156 #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
2157 #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \e
2158 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2160 #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \e
2161 *(vp) = (*(vp) & 0xffff0000) | (n); \e
2165 .SS "Conversation API"
2166 If the plugin needs to interact with the user, it may do so via the
2167 \fBconversation\fR()
2169 A plugin should not attempt to read directly from the standard input
2170 or the user's tty (neither of which are guaranteed to exist).
2171 The caller must include a trailing newline in
2173 if one is to be printed.
2176 \fBprintf\fR()-style
2177 function is also available that can be used to display informational
2178 or error messages to the user, which is usually more convenient for
2179 simple messages where no use input is required.
2183 struct sudo_conv_message {
2184 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
2185 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
2186 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
2187 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
2188 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
2189 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
2190 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
2196 struct sudo_conv_reply {
2200 typedef int (*sudo_conv_t)(int num_msgs,
2201 const struct sudo_conv_message msgs[],
2202 struct sudo_conv_reply replies[]);
2204 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2209 \fBconversation\fR()
2211 \fBprintf\fR()-style
2212 functions are passed
2215 function when the plugin is initialized.
2218 \fBconversation\fR()
2219 function, the plugin must pass an array of
2220 \fRsudo_conv_message\fR
2222 \fRsudo_conv_reply\fR
2225 \fRstruct sudo_conv_message\fR
2227 \fRstruct sudo_conv_reply\fR
2229 each message in the conversation.
2230 The plugin is responsible for freeing the reply buffer filled in to the
2231 \fRstruct sudo_conv_reply\fR,
2235 \fBprintf\fR()-style
2236 function uses the same underlying mechanism as the
2237 \fBconversation\fR()
2238 function but only supports
2239 \fRSUDO_CONV_INFO_MSG\fR,
2240 \fRSUDO_CONV_ERROR_MSG\fR
2242 \fRSUDO_CONV_DEBUG_MSG\fR
2246 It can be more convenient than using the
2247 \fBconversation\fR()
2248 function if no user reply is needed and supports standard
2253 \fRSUDO_CONV_INFO_MSG\fR
2255 Dv SUDO_CONV_ERROR_MSG ,
2258 \fRSUDO_CONV_DEBUG_MSG\fR
2262 Instead, they are logged to the file specified in the
2264 statement (if any) in the
2265 sudo.conf(@mansectform@).
2267 This allows a plugin to log debugging information and is intended
2268 to be used in conjunction with the
2272 See the sample plugin for an example of the
2273 \fBconversation\fR()
2275 .SS "Sudoers group plugin API"
2278 plugin supports its own plugin interface to allow non-Unix
2280 This can be used to query a group source other than the standard Unix
2282 Two sample group plugins are bundled with
2288 sudoers(@mansectform@).
2289 Third party group plugins include a QAS AD plugin available from Quest Software.
2291 A group plugin must declare and populate a
2292 \fRsudoers_group_plugin\fR
2293 struct in the global scope.
2294 This structure contains pointers to the functions that implement plugin
2295 initialization, cleanup and group lookup.
2299 struct sudoers_group_plugin {
2300 unsigned int version;
2301 int (*init)(int version, sudo_printf_t sudo_printf,
2302 char *const argv[]);
2303 void (*cleanup)(void);
2304 int (*query)(const char *user, const char *group,
2305 const struct passwd *pwd);
2311 \fRsudoers_group_plugin\fR
2312 struct has the following fields:
2317 field should be set to GROUP_API_VERSION.
2321 to determine the API version the group plugin
2328 int (*init)(int version, sudo_printf_t plugin_printf,
2329 char *const argv[]);
2335 function is called after
2338 before any policy checks.
2339 It returns 1 on success, 0 on failure (or if the plugin is not configured),
2340 and \-1 if a error occurred.
2341 If an error occurs, the plugin may call the
2342 \fBplugin_printf\fR()
2344 \fRSUDO_CONF_ERROR_MSG\fR
2345 to present additional error information
2348 The function arguments are as follows:
2351 The version passed in by
2353 allows the plugin to determine the
2354 major and minor version number of the group plugin API supported by
2359 \fBprintf\fR()-style
2360 function that may be used to display informational or error message to the user.
2361 Returns the number of characters printed on success and \-1 on failure.
2365 \fRNULL\fR-terminated
2366 array of arguments generated from the
2370 If no arguments were given,
2388 function is called when
2392 The plugin should free any memory it has allocated and close open file handles.
2403 int (*query)(const char *user, const char *group,
2404 const struct passwd *pwd);
2410 function is used to ask the group plugin whether
2415 The function arguments are as follows:
2419 The name of the user being looked up in the external group database.
2423 The name of the group being queried.
2426 The password database entry for
2432 present in the password database,
2438 \fIGroup API Version Macros\fR
2442 /* Sudoers group plugin version major/minor */
2443 #define GROUP_API_VERSION_MAJOR 1
2444 #define GROUP_API_VERSION_MINOR 0
2445 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \e
2446 GROUP_API_VERSION_MINOR)
2448 /* Getters and setters for group version */
2449 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
2450 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
2451 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \e
2452 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \e
2454 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \e
2455 *(vp) = (*(vp) & 0xffff0000) | (n); \e
2459 .SH "PLUGIN API CHANGELOG"
2460 The following revisions have been made to the Sudo Plugin API.
2463 Initial API version.
2465 Version 1.1 (sudo 1.8.0)
2466 The I/O logging plugin's
2468 function was modified to take the
2470 list as an argument.
2472 Version 1.2 (sudo 1.8.5)
2473 The Policy and I/O logging plugins'
2475 functions are now passed
2476 a list of plugin parameters if any are specified in
2477 sudo.conf(@mansectform@).
2479 A simple hooks API has been introduced to allow plugins to hook in to the
2480 system's environment handling functions.
2484 Policy plugin function is now passed a pointer
2485 to the user environment which can be updated as needed.
2486 This can be used to merge in environment variables stored in the PAM
2487 handle before a command is run.
2489 Version 1.3 (sudo 1.8.7)
2491 \fIexec_background\fR
2492 entry has been added to the
2500 entries were added to the
2508 functions are now optional.
2509 Previously, a missing
2513 function would result in a crash.
2516 function is defined, a default
2518 function will be provided by the
2520 front end that displays a warning if the command could not be
2525 front end now installs default signal handlers to trap common signals
2526 while the plugin functions are run.
2528 sudo.conf(@mansectform@),
2529 sudoers(@mansectform@),
2532 If you feel you have found a bug in
2534 please submit a bug report at http://www.sudo.ws/sudo/bugs/
2536 Limited free support is available via the sudo-users mailing list,
2537 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
2538 search the archives.
2543 and any express or implied warranties, including, but not limited
2544 to, the implied warranties of merchantability and fitness for a
2545 particular purpose are disclaimed.
2546 See the LICENSE file distributed with
2548 or http://www.sudo.ws/sudo/license.html for complete details.