1 SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m)
6 sudo_plugin - Sudo Plugin API
8 D
\bDE
\bES
\bSC
\bCR
\bRI
\bIP
\bPT
\bTI
\bIO
\bON
\bN
9 Starting with version 1.8, s
\bsu
\bud
\bdo
\bo supports a plugin API for policy and
10 session logging. By default, the _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs policy plugin and an
11 associated I/O logging plugin are used. Via the plugin API, s
\bsu
\bud
\bdo
\bo can
12 be configured to use alternate policy and/or I/O logging plugins
13 provided by third parties. The plugins to be used are specified via
14 the _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf file.
16 The API is versioned with a major and minor number. The minor version
17 number is incremented when additions are made. The major number is
18 incremented when incompatible changes are made. A plugin should be
19 check the version passed to it and make sure that the major version
22 The plugin API is defined by the sudo_plugin.h header file.
24 T
\bTh
\bhe
\be s
\bsu
\bud
\bdo
\bo.
\b.c
\bco
\bon
\bnf
\bf F
\bFi
\bil
\ble
\be
25 The _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf file contains plugin configuration directives.
26 Currently, the only supported keyword is the Plugin directive, which
27 causes a plugin plugin to be loaded.
29 A Plugin line consists of the Plugin keyword, followed by the
30 _
\bs_
\by_
\bm_
\bb_
\bo_
\bl_
\b__
\bn_
\ba_
\bm_
\be and the _
\bp_
\ba_
\bt_
\bh to the shared object containing the plugin.
31 The _
\bs_
\by_
\bm_
\bb_
\bo_
\bl_
\b__
\bn_
\ba_
\bm_
\be is the name of the struct policy_plugin or struct
32 io_plugin in the plugin shared object. The _
\bp_
\ba_
\bt_
\bh may be fully qualified
33 or relative. If not fully qualified it is relative to the
34 _
\b/_
\bu_
\bs_
\br_
\b/_
\bl_
\bo_
\bc_
\ba_
\bl_
\b/_
\bl_
\bi_
\bb_
\be_
\bx_
\be_
\bc directory. Any additional parameters after the _
\bp_
\ba_
\bt_
\bh
35 are ignored. Lines that don't begin with Plugin or Path are silently
38 The same shared object may contain multiple plugins, each with a
39 different symbol name. The shared object file must be owned by uid 0
40 and only writable by its owner. Because of ambiguities that arise from
41 composite policies, only a single policy plugin may be specified. This
42 limitation does not apply to I/O plugins.
45 # Default /etc/sudo.conf file
48 # Plugin plugin_name plugin_path
49 # Path askpass /path/to/askpass
51 # The plugin_path is relative to /usr/local/libexec unless
53 # The plugin_name corresponds to a global symbol in the plugin
54 # that contains the plugin interface structure.
56 Plugin sudoers_policy sudoers.so
57 Plugin sudoers_io sudoers.so
59 P
\bPo
\bol
\bli
\bic
\bcy
\by P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
60 A policy plugin must declare and populate a policy_plugin struct in the
61 global scope. This structure contains pointers to the functions that
62 implement the s
\bsu
\bud
\bdo
\bo policy checks. The name of the symbol should be
63 specified in _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf along with a path to the plugin so that
64 s
\bsu
\bud
\bdo
\bo can load it.
66 struct policy_plugin {
67 #define SUDO_POLICY_PLUGIN 1
68 unsigned int type; /* always SUDO_POLICY_PLUGIN */
69 unsigned int version; /* always SUDO_API_VERSION */
70 int (*open)(unsigned int version, sudo_conv_t conversation,
71 sudo_printf_t plugin_printf, char * const settings[],
72 char * const user_info[], char * const user_env[]);
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);
85 The policy_plugin struct has the following fields:
88 The type field should always be set to SUDO_POLICY_PLUGIN.
91 The version field should be set to SUDO_API_VERSION.
93 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
97 int (*open)(unsigned int version, sudo_conv_t conversation,
98 sudo_printf_t plugin_printf, char * const settings[],
99 char * const user_info[], char * const user_env[]);
101 Returns 1 on success, 0 on failure, -1 if a general error occurred,
102 or -2 if there was a usage error. In the latter case, s
\bsu
\bud
\bdo
\bo will
103 print a usage message before it exits. If an error occurs, the
104 plugin may optionally call the conversation or plugin_printf
105 function with SUDO_CONF_ERROR_MSG to present additional error
106 information to the user.
108 The function arguments are as follows:
111 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
112 the major and minor version number of the plugin API supported
116 A pointer to the conversation function that can be used by the
117 plugin to interact with the user (see below). Returns 0 on
118 success and -1 on failure.
121 A pointer to a printf-style function that may be used to
122 display informational or error messages (see below). Returns
123 the number of characters printed on success and -1 on failure.
126 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
127 "name=value" strings. The vector is terminated by a NULL
128 pointer. These settings correspond to flags the user specified
129 when running s
\bsu
\bud
\bdo
\bo. As such, they will only be present when the
130 corresponding flag has been specified on the command line.
132 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
133 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
134 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
137 A numeric debug level, from 1-9, if specified via the -D
141 The user name or uid to to run the command as, if specified
145 The group name or gid to to run the command as, if
146 specified via the -g flag.
149 The prompt to use when requesting a password, if specified
153 Set to true if the user specified the -H flag. If true,
154 set the HOME environment variable to the target user's home
157 preserve_environment=bool
158 Set to true if the user specified the -E flag, indicating
159 that the user wishes to preserve the environment.
162 Set to true if the user specified the -s flag, indicating
163 that the user wishes to run a shell.
166 Set to true if the user specified the -i flag, indicating
167 that the user wishes to run a login shell.
170 If the user does not specify a program on the command line,
171 s
\bsu
\bud
\bdo
\bo will pass the plugin the path to the user's shell and
172 set _
\bi_
\bm_
\bp_
\bl_
\bi_
\be_
\bd_
\b__
\bs_
\bh_
\be_
\bl_
\bl to true. This allows s
\bsu
\bud
\bdo
\bo with no
173 arguments to be used similarly to _
\bs_
\bu(1). If the plugin
174 does not to support this usage, it may return a value of -2
175 from the check_policy function, which will cause s
\bsu
\bud
\bdo
\bo to
176 print a usage message and exit.
179 Set to true if the user specified the -P flag, indicating
180 that the user wishes to preserve the group vector instead
181 of setting it based on the runas user.
184 Set to true if the user specified the -k flag along with a
185 command, indicating that the user wishes to ignore any
186 cached authentication credentials.
189 Set to true if the user specified the -n flag, indicating
190 that s
\bsu
\bud
\bdo
\bo should operate in non-interactive mode. The
191 plugin may reject a command run in non-interactive mode if
192 user interaction is required.
195 BSD login class to use when setting resource limits and
196 nice value, if specified by the -c flag.
199 SELinux role to use when executing the command, if
200 specified by the -r flag.
203 SELinux type to use when executing the command, if
204 specified by the -t flag.
207 Authentication type, if specified by the -a flag, to use on
208 systems where BSD authentication is supported.
211 A space-separated list of IP network addresses and netmasks
212 in the form "addr/netmask", e.g.
213 "192.168.1.2/255.255.255.0". The address and netmask pairs
214 may be either IPv4 or IPv6, depending on what the operating
215 system supports. If the address contains a colon (':'), it
216 is an IPv6 address, else it is IPv4.
219 The command name that sudo was run as, typically "sudo" or
223 Set to true when the -e flag is is specified or if invoked
224 as s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt. The plugin shall substitute an editor into
225 _
\ba_
\br_
\bg_
\bv in the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function or return -2 with a usage
226 error if the plugin does not support _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt. For more
227 information, see the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by section.
230 If specified, the user has requested via the -C flag that
231 s
\bsu
\bud
\bdo
\bo close all files descriptors with a value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or
232 higher. The plugin may optionally pass this, or another
233 value, back in the _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
235 Additional settings may be added in the future so the plugin
236 should silently ignore settings that it does not recognize.
239 A vector of information about the user running the command in
240 the form of "name=value" strings. The vector is terminated by
243 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
244 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
245 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
248 The name of the user invoking s
\bsu
\bud
\bdo
\bo.
251 The real user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
254 The real group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
257 The user's supplementary group list formatted as a string
258 of comma-separated group IDs.
261 The user's current working directory.
264 The path to the user's terminal device. If the user has no
265 terminal device associated with the session, the value will
266 be empty, as in tty=.
269 The local machine's hostname as returned by the
270 gethostname() system call.
273 The number of lines the user's terminal supports. If there
274 is no terminal device available, a default value of 24 is
278 The number of columns the user's terminal supports. If
279 there is no terminal device available, a default value of
283 The user's environment in the form of a NULL-terminated vector
284 of "name=value" strings.
286 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
287 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
288 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
291 void (*close)(int exit_status, int error);
293 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
296 The function arguments are as follows:
299 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
300 call. The value of exit_status is undefined if error is non-
304 If the command could not be executed, this is set to the value
305 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. The plugin is
306 responsible for displaying error information via the
307 conversation or plugin_printf function. If the command was
308 successfully executed, the value of error is 0.
311 int (*show_version)(int verbose);
313 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
314 the -V option. The plugin may display its version information to
315 the user via the conversation or plugin_printf function using
316 SUDO_CONV_INFO_MSG. If the user requests detailed version
317 information, the verbose flag will be set.
320 int (*check_policy)(int argc, char * const argv[]
321 char *env_add[], char **command_info[],
322 char **argv_out[], char **user_env_out[]);
324 The _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function is called by s
\bsu
\bud
\bdo
\bo to determine whether
325 the user is allowed to run the specified commands.
327 If the _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt option was enabled in the _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs array passed to
328 the _
\bo_
\bp_
\be_
\bn function, the user has requested _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode. _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt
329 is a mechanism for editing one or more files where an editor is run
330 with the user's credentials instead of with elevated privileges.
331 s
\bsu
\bud
\bdo
\bo achieves this by creating user-writable temporary copies of
332 the files to be edited and then overwriting the originals with the
333 temporary copies after editing is complete. If the plugin supports
334 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt, it should choose the editor to be used, potentially from
335 a variable in the user's environment, such as EDITOR, and include
336 it in _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt (note that environment variables may include command
337 line flags). The files to be edited should be copied from _
\ba_
\br_
\bg_
\bv
338 into _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt, separated from the editor and its arguments by a
339 "--" element. The "--" will be removed by s
\bsu
\bud
\bdo
\bo before the editor
340 is executed. The plugin should also set _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt_
\b=_
\bt_
\br_
\bu_
\be in the
341 _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
343 The _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function returns 1 if the command is allowed, 0 if
344 not allowed, -1 for a general error, or -2 for a usage error or if
345 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt was specified but is unsupported by the plugin. In the
346 latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits. If
347 an error occurs, the plugin may optionally call the conversation or
348 plugin_printf function with SUDO_CONF_ERROR_MSG to present
349 additional error information to the user.
351 The function arguments are as follows:
354 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
358 The argument vector describing the command the user wishes to
359 run, in the same form as what would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
360 system call. The vector is terminated by a NULL pointer.
363 Additional environment variables specified by the user on the
364 command line in the form of a NULL-terminated vector of
365 "name=value" strings. The plugin may reject the command if one
366 or more variables are not allowed to be set, or it may silently
367 ignore such variables.
369 When parsing _
\be_
\bn_
\bv_
\b__
\ba_
\bd_
\bd, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
370 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
371 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
374 Information about the command being run in the form of
375 "name=value" strings. These values are used by s
\bsu
\bud
\bdo
\bo to set the
376 execution environment when running a command. The plugin is
377 responsible for creating and populating the vector, which must
378 be terminated with a NULL pointer. The following values are
379 recognized by s
\bsu
\bud
\bdo
\bo:
382 Fully qualified path to the command to be executed.
385 User ID to run the command as.
388 Effective user ID to run the command as. If not specified,
389 the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bu_
\bi_
\bd is used.
392 Group ID to run the command as.
395 Effective group ID to run the command as. If not
396 specified, the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bg_
\bi_
\bd is used.
399 The supplementary group vector to use for the command in
400 the form of a comma-separated list of group IDs. If
401 _
\bp_
\br_
\be_
\bs_
\be_
\br_
\bv_
\be_
\b__
\bg_
\br_
\bo_
\bu_
\bp_
\bs is set, this option is ignored.
404 BSD login class to use when setting resource limits and
405 nice value (optional). This option is only set on systems
406 that support login classes.
409 If set, s
\bsu
\bud
\bdo
\bo will preserve the user's group vector instead
410 of initializing the group vector based on runas_user.
413 The current working directory to change to when executing
417 If set, prevent the command from executing other programs.
420 The root directory to use when running the command.
423 Nice value (priority) to use when executing the command.
424 The nice value, if specified, overrides the priority
425 associated with the _
\bl_
\bo_
\bg_
\bi_
\bn_
\b__
\bc_
\bl_
\ba_
\bs_
\bs on BSD systems.
428 The file creation mask to use when executing the command.
431 SELinux role to use when executing the command.
434 SELinux type to use when executing the command.
437 Command timeout. If non-zero then when the timeout expires
438 the command will be killed.
441 Set to true when in _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode. The plugin may enable
442 _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode even if s
\bsu
\bud
\bdo
\bo was not invoked as s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt.
443 This allows the plugin to perform command substitution and
444 transparently enable _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt when the user attempts to run
448 If specified, s
\bsu
\bud
\bdo
\bo will close all files descriptors with a
449 value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or higher.
452 Set to true if the I/O logging plugins, if any, should
453 compress the log data. This is a hint to the I/O logging
454 plugin which may choose to ignore it.
457 Fully qualified path to the file or directory in which I/O
458 log is to be stored. This is a hint to the I/O logging
459 plugin which may choose to ignore it. If no I/O logging
460 plugin is loaded, this setting has no effect.
463 Set to true if the I/O logging plugins, if any, should log
464 the standard input if it is not connected to a terminal
465 device. This is a hint to the I/O logging plugin which may
469 Set to true if the I/O logging plugins, if any, should log
470 the standard output if it is not connected to a terminal
471 device. This is a hint to the I/O logging plugin which may
475 Set to true if the I/O logging plugins, if any, should log
476 the standard error if it is not connected to a terminal
477 device. This is a hint to the I/O logging plugin which may
481 Set to true if the I/O logging plugins, if any, should log
482 all terminal input. This only includes input typed by the
483 user and not from a pipe or redirected from a file. This
484 is a hint to the I/O logging plugin which may choose to
488 Set to true if the I/O logging plugins, if any, should log
489 all terminal output. This only includes output to the
490 screen, not output to a pipe or file. This is a hint to
491 the I/O logging plugin which may choose to ignore it.
494 Allocate a pseudo-tty to run the command in, regardless of
495 whether or not I/O logging is in use. By default, s
\bsu
\bud
\bdo
\bo
496 will only run the command in a pty when an I/O log plugin
500 Create a utmp (or utmpx) entry when a pseudo-tty is
501 allocated. By default, the new entry will be a copy of the
502 user's existing utmp entry (if any), with the tty, time,
503 type and pid fields updated.
506 User name to use when constructing a new utmp (or utmpx)
507 entry when _
\bs_
\be_
\bt_
\b__
\bu_
\bt_
\bm_
\bp is enabled. This option can be used to
508 set the user field in the utmp entry to the user the
509 command runs as rather than the invoking user. If not set,
510 s
\bsu
\bud
\bdo
\bo will base the new entry on the invoking user's
513 Unsupported values will be ignored.
516 The NULL-terminated argument vector to pass to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
517 system call when executing the command. The plugin is
518 responsible for allocating and populating the vector.
521 The NULL-terminated environment vector to use when executing
522 the command. The plugin is responsible for allocating and
523 populating the vector.
526 int (*list)(int verbose, const char *list_user,
527 int argc, char * const argv[]);
529 List available privileges for the invoking user. Returns 1 on
530 success, 0 on failure and -1 on error. On error, the plugin may
531 optionally call the conversation or plugin_printf function with
532 SUDO_CONF_ERROR_MSG to present additional error information to the
535 Privileges should be output via the conversation or plugin_printf
536 function using SUDO_CONV_INFO_MSG.
539 Flag indicating whether to list in verbose mode or not.
542 The name of a different user to list privileges for if the
543 policy allows it. If NULL, the plugin should list the
544 privileges of the invoking user.
547 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
551 If non-NULL, an argument vector describing a command the user
552 wishes to check against the policy in the same form as what
553 would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call. If the command is
554 permitted by the policy, the fully-qualified path to the
555 command should be displayed along with any command line
559 int (*validate)(void);
561 The validate function is called when s
\bsu
\bud
\bdo
\bo is run with the -v flag.
562 For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache authentication
563 credentials, this function will validate and cache the credentials.
565 The validate function should be NULL if the plugin does not support
568 Returns 1 on success, 0 on failure and -1 on error. On error, the
569 plugin may optionally call the conversation or plugin_printf
570 function with SUDO_CONF_ERROR_MSG to present additional error
571 information to the user.
574 void (*invalidate)(int remove);
576 The invalidate function is called when s
\bsu
\bud
\bdo
\bo is called with the -k
577 or -K flag. For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache
578 authentication credentials, this function will invalidate the
579 credentials. If the _
\br_
\be_
\bm_
\bo_
\bv_
\be flag is set, the plugin may remove the
580 credentials instead of simply invalidating them.
582 The invalidate function should be NULL if the plugin does not
583 support credential caching.
586 int (*init_session)(struct passwd *pwd);
588 The init_session function is called when s
\bsu
\bud
\bdo
\bo sets up the execution
589 environment for the command, immediately before the contents of the
590 _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list are applied (before the uid changes). This can
591 be used to do session setup that is not supported by _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo,
592 such as opening the PAM session.
594 The _
\bp_
\bw_
\bd argument points to a passwd struct for the user the command
595 will be run as if the uid the command will run as was found in the
596 password database, otherwise it will be NULL.
598 Returns 1 on success, 0 on failure and -1 on error. On error, the
599 plugin may optionally call the conversation or plugin_printf
600 function with SUDO_CONF_ERROR_MSG to present additional error
601 information to the user.
603 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bm_
\ba_
\bc_
\br_
\bo_
\bs
605 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
606 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
607 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
608 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
610 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
611 *(vp) = (*(vp) & 0xffff0000) | (n); \
614 #define SUDO_API_VERSION_MAJOR 1
615 #define SUDO_API_VERSION_MINOR 0
616 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
617 SUDO_API_VERSION_MINOR)
619 I
\bI/
\b/O
\bO P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
621 #define SUDO_IO_PLUGIN 2
622 unsigned int type; /* always SUDO_IO_PLUGIN */
623 unsigned int version; /* always SUDO_API_VERSION */
624 int (*open)(unsigned int version, sudo_conv_t conversation
625 sudo_printf_t plugin_printf, char * const settings[],
626 char * const user_info[], int argc, char * const argv[],
627 char * const user_env[]);
628 void (*close)(int exit_status, int error); /* wait status or error */
629 int (*show_version)(int verbose);
630 int (*log_ttyin)(const char *buf, unsigned int len);
631 int (*log_ttyout)(const char *buf, unsigned int len);
632 int (*log_stdin)(const char *buf, unsigned int len);
633 int (*log_stdout)(const char *buf, unsigned int len);
634 int (*log_stderr)(const char *buf, unsigned int len);
637 When an I/O plugin is loaded, s
\bsu
\bud
\bdo
\bo runs the command in a pseudo-tty.
638 This makes it possible to log the input and output from the user's
639 session. If any of the standard input, standard output or standard
640 error do not correspond to a tty, s
\bsu
\bud
\bdo
\bo will open a pipe to capture the
641 I/O for logging before passing it on.
643 The log_ttyin function receives the raw user input from the terminal
644 device (note that this will include input even when echo is disabled,
645 such as when a password is read). The log_ttyout function receives
646 output from the pseudo-tty that is suitable for replaying the user's
647 session at a later time. The log_stdin, log_stdout and log_stderr
648 functions are only called if the standard input, standard output or
649 standard error respectively correspond to something other than a tty.
651 Any of the logging functions may be set to the NULL pointer if no
652 logging is to be performed. If the open function returns 0, no I/O
653 will be sent to the plugin.
655 The io_plugin struct has the following fields:
658 The type field should always be set to SUDO_IO_PLUGIN
661 The version field should be set to SUDO_API_VERSION.
663 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
667 int (*open)(unsigned int version, sudo_conv_t conversation
668 sudo_printf_t plugin_printf, char * const settings[],
669 char * const user_info[], int argc, char * const argv[],
670 char * const user_env[]);
672 The _
\bo_
\bp_
\be_
\bn function is run before the _
\bl_
\bo_
\bg_
\b__
\bi_
\bn_
\bp_
\bu_
\bt, _
\bl_
\bo_
\bg_
\b__
\bo_
\bu_
\bt_
\bp_
\bu_
\bt or
673 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn functions are called. It is only called if the
674 version is being requested or the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function has
675 returned successfully. It returns 1 on success, 0 on failure, -1
676 if a general error occurred, or -2 if there was a usage error. In
677 the latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits.
678 If an error occurs, the plugin may optionally call the conversation
679 or plugin_printf function with SUDO_CONF_ERROR_MSG to present
680 additional error information to the user.
682 The function arguments are as follows:
685 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
686 the major and minor version number of the plugin API supported
690 A pointer to the conversation function that may be used by the
691 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
692 show_version below). The conversation function may also be
693 used to display additional error message to the user. The
694 conversation function returns 0 on success and -1 on failure.
697 A pointer to a printf-style function that may be used by the
698 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
699 show_version below). The plugin_printf function may also be
700 used to display additional error message to the user. The
701 plugin_printf function returns number of characters printed on
702 success and -1 on failure.
705 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
706 "name=value" strings. The vector is terminated by a NULL
707 pointer. These settings correspond to flags the user specified
708 when running s
\bsu
\bud
\bdo
\bo. As such, they will only be present when the
709 corresponding flag has been specified on the command line.
711 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
712 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
713 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
715 See the "Policy Plugin API" section for a list of all possible
719 A vector of information about the user running the command in
720 the form of "name=value" strings. The vector is terminated by
723 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
724 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
725 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
727 See the "Policy Plugin API" section for a list of all possible
731 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
735 If non-NULL, an argument vector describing a command the user
736 wishes to run in the same form as what would be passed to the
737 _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call.
740 The user's environment in the form of a NULL-terminated vector
741 of "name=value" strings.
743 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
744 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
745 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
748 void (*close)(int exit_status, int error);
750 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
753 The function arguments are as follows:
756 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
757 call. The value of exit_status is undefined if error is non-
761 If the command could not be executed, this is set to the value
762 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. If the command was
763 successfully executed, the value of error is 0.
766 int (*show_version)(int verbose);
768 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
769 the -V option. The plugin may display its version information to
770 the user via the conversation or plugin_printf function using
771 SUDO_CONV_INFO_MSG. If the user requests detailed version
772 information, the verbose flag will be set.
775 int (*log_ttyin)(const char *buf, unsigned int len);
777 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bi_
\bn function is called whenever data can be read from the
778 user but before it is passed to the running command. This allows
779 the plugin to reject data if it chooses to (for instance if the
780 input contains banned content). Returns 1 if the data should be
781 passed to the command, 0 if the data is rejected (which will
782 terminate the command) or -1 if an error occurred.
784 The function arguments are as follows:
786 buf The buffer containing user input.
788 len The length of _
\bb_
\bu_
\bf in bytes.
791 int (*log_ttyout)(const char *buf, unsigned int len);
793 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bo_
\bu_
\bt function is called whenever data can be read from
794 the command but before it is written to the user's terminal. This
795 allows the plugin to reject data if it chooses to (for instance if
796 the output contains banned content). Returns 1 if the data should
797 be passed to the user, 0 if the data is rejected (which will
798 terminate the command) or -1 if an error occurred.
800 The function arguments are as follows:
802 buf The buffer containing command output.
804 len The length of _
\bb_
\bu_
\bf in bytes.
807 int (*log_stdin)(const char *buf, unsigned int len);
809 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bi_
\bn function is only used if the standard input does not
810 correspond to a tty device. It is called whenever data can be read
811 from the standard input but before it is passed to the running
812 command. This allows the plugin to reject data if it chooses to
813 (for instance if the input contains banned content). Returns 1 if
814 the data should be passed to the command, 0 if the data is rejected
815 (which will terminate the command) or -1 if an error occurred.
817 The function arguments are as follows:
819 buf The buffer containing user input.
821 len The length of _
\bb_
\bu_
\bf in bytes.
824 int (*log_stdout)(const char *buf, unsigned int len);
826 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bo_
\bu_
\bt function is only used if the standard output does
827 not correspond to a tty device. It is called whenever data can be
828 read from the command but before it is written to the standard
829 output. This allows the plugin to reject data if it chooses to
830 (for instance if the output contains banned content). Returns 1 if
831 the data should be passed to the user, 0 if the data is rejected
832 (which will terminate the command) or -1 if an error occurred.
834 The function arguments are as follows:
836 buf The buffer containing command output.
838 len The length of _
\bb_
\bu_
\bf in bytes.
841 int (*log_stderr)(const char *buf, unsigned int len);
843 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\be_
\br_
\br function is only used if the standard error does not
844 correspond to a tty device. It is called whenever data can be read
845 from the command but before it is written to the standard error.
846 This allows the plugin to reject data if it chooses to (for
847 instance if the output contains banned content). Returns 1 if the
848 data should be passed to the user, 0 if the data is rejected (which
849 will terminate the command) or -1 if an error occurred.
851 The function arguments are as follows:
853 buf The buffer containing command output.
855 len The length of _
\bb_
\bu_
\bf in bytes.
857 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bm_
\ba_
\bc_
\br_
\bo_
\bs
859 Same as for the "Policy Plugin API".
861 C
\bCo
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
862 If the plugin needs to interact with the user, it may do so via the
863 conversation function. A plugin should not attempt to read directly
864 from the standard input or the user's tty (neither of which are
865 guaranteed to exist). The caller must include a trailing newline in
866 msg if one is to be printed.
868 A printf-style function is also available that can be used to display
869 informational or error messages to the user, which is usually more
870 convenient for simple messages where no use input is required.
872 struct sudo_conv_message {
873 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
874 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
875 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
876 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
877 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
878 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
884 struct sudo_conv_reply {
888 typedef int (*sudo_conv_t)(int num_msgs,
889 const struct sudo_conv_message msgs[],
890 struct sudo_conv_reply replies[]);
892 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
894 Pointers to the conversation and printf-style functions are passed in
895 to the plugin's open function when the plugin is initialized.
897 To use the conversation function, the plugin must pass an array of
898 sudo_conv_message and sudo_conv_reply structures. There must be a
899 struct sudo_conv_message and struct sudo_conv_reply for each message in
900 the conversation. The plugin is responsible for freeing the reply
901 buffer filled in to the struct sudo_conv_reply, if any.
903 The printf-style function uses the same underlying mechanism as the
904 conversation function but only supports SUDO_CONV_INFO_MSG and
905 SUDO_CONV_ERROR_MSG for the _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be parameter. It can be more
906 convenient than using the conversation function if no user reply is
907 needed and supports standard _
\bp_
\br_
\bi_
\bn_
\bt_
\bf_
\b(_
\b) escape sequences.
909 See the sample plugin for an example of the conversation function
912 S
\bSu
\bud
\bdo
\boe
\ber
\brs
\bs G
\bGr
\bro
\bou
\bup
\bp P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
913 The _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs module supports a plugin interface to allow non-Unix group
914 lookups. This can be used to query a group source other than the
915 standard Unix group database. A sample group plugin is bundled with
916 s
\bsu
\bud
\bdo
\bo that implements file-based lookups. Third party group plugins
917 include a QAS AD plugin available from Quest Software.
919 A group plugin must declare and populate a sudoers_group_plugin struct
920 in the global scope. This structure contains pointers to the functions
921 that implement plugin initialization, cleanup and group lookup.
923 struct sudoers_group_plugin {
924 unsigned int version;
925 int (*init)(int version, sudo_printf_t sudo_printf,
927 void (*cleanup)(void);
928 int (*query)(const char *user, const char *group,
929 const struct passwd *pwd);
932 The sudoers_group_plugin struct has the following fields:
935 The version field should be set to GROUP_API_VERSION.
937 This allows _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs to determine the API version the group plugin
941 int (*init)(int version, sudo_printf_t plugin_printf,
944 The _
\bi_
\bn_
\bi_
\bt function is called after _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has been parsed but
945 before any policy checks. It returns 1 on success, 0 on failure
946 (or if the plugin is not configured), and -1 if a error occurred.
947 If an error occurs, the plugin may call the plugin_printf function
948 with SUDO_CONF_ERROR_MSG to present additional error information to
951 The function arguments are as follows:
954 The version passed in by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs allows the plugin to determine
955 the major and minor version number of the group plugin API
956 supported by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs.
959 A pointer to a printf-style function that may be used to
960 display informational or error message to the user. Returns
961 the number of characters printed on success and -1 on failure.
964 A NULL-terminated array of arguments generated from the
965 _
\bg_
\br_
\bo_
\bu_
\bp_
\b__
\bp_
\bl_
\bu_
\bg_
\bi_
\bn option in _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs. If no arguments were given,
966 _
\ba_
\br_
\bg_
\bv will be NULL.
971 The _
\bc_
\bl_
\be_
\ba_
\bn_
\bu_
\bp function is called when _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has finished its group
972 checks. The plugin should free any memory it has allocated and
973 close open file handles.
976 int (*query)(const char *user, const char *group,
977 const struct passwd *pwd);
979 The _
\bq_
\bu_
\be_
\br_
\by function is used to ask the group plugin whether _
\bu_
\bs_
\be_
\br is
980 a member of _
\bg_
\br_
\bo_
\bu_
\bp.
982 The function arguments are as follows:
985 The name of the user being looked up in the external group
989 The name of the group being queried.
991 pwd The password database entry for _
\bu_
\bs_
\be_
\br, if any. If _
\bu_
\bs_
\be_
\br is not
992 present in the password database, _
\bp_
\bw_
\bd will be NULL.
994 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
996 /* Sudoers group plugin version major/minor */
997 #define GROUP_API_VERSION_MAJOR 1
998 #define GROUP_API_VERSION_MINOR 0
999 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1000 GROUP_API_VERSION_MINOR)
1002 /* Getters and setters for group version */
1003 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1004 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1005 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1006 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1008 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1009 *(vp) = (*(vp) & 0xffff0000) | (n); \
1012 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1013 _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs(4), _
\bs_
\bu_
\bd_
\bo(1m)
1016 If you feel you have found a bug in s
\bsu
\bud
\bdo
\bo, please submit a bug report at
1017 http://www.sudo.ws/sudo/bugs/
1019 S
\bSU
\bUP
\bPP
\bPO
\bOR
\bRT
\bT
1020 Limited free support is available via the sudo-workers mailing list,
1021 see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1022 search the archives.
1024 D
\bDI
\bIS
\bSC
\bCL
\bLA
\bAI
\bIM
\bME
\bER
\bR
1025 s
\bsu
\bud
\bdo
\bo is provided ``AS IS'' and any express or implied warranties,
1026 including, but not limited to, the implied warranties of
1027 merchantability and fitness for a particular purpose are disclaimed.
1028 See the LICENSE file distributed with s
\bsu
\bud
\bdo
\bo or
1029 http://www.sudo.ws/sudo/license.html for complete details.
1033 1.8.1p2 May 16, 2011 SUDO_PLUGIN(1m)