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 comma-separated list of debug flags that correspond to
138 s
\bsu
\bud
\bdo
\bo's Debug entry in _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf, if there is one. The
139 flags are passed to the plugin as they appear in
140 _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf. The syntax used by s
\bsu
\bud
\bdo
\bo and the _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs
141 plugin is _
\bs_
\bu_
\bb_
\bs_
\by_
\bs_
\bt_
\be_
\bm@_
\bp_
\br_
\bi_
\bo_
\br_
\bi_
\bt_
\by but the plugin is free to use
142 a different format so long as it does not include a command
145 For reference, the priorities supported by the s
\bsu
\bud
\bdo
\bo front
146 end and _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs are: _
\bc_
\br_
\bi_
\bt, _
\be_
\br_
\br, _
\bw_
\ba_
\br_
\bn, _
\bn_
\bo_
\bt_
\bi_
\bc_
\be, _
\bd_
\bi_
\ba_
\bg, _
\bi_
\bn_
\bf_
\bo,
147 _
\bt_
\br_
\ba_
\bc_
\be and _
\bd_
\be_
\bb_
\bu_
\bg.
149 The following subsystems are defined: _
\bm_
\ba_
\bi_
\bn, _
\bm_
\be_
\bm_
\bo_
\br_
\by, _
\ba_
\br_
\bg_
\bs,
150 _
\be_
\bx_
\be_
\bc, _
\bp_
\bt_
\by, _
\bu_
\bt_
\bm_
\bp, _
\bc_
\bo_
\bn_
\bv, _
\bp_
\bc_
\bo_
\bm_
\bm, _
\bu_
\bt_
\bi_
\bl, _
\bl_
\bi_
\bs_
\bt, _
\bn_
\be_
\bt_
\bi_
\bf, _
\ba_
\bu_
\bd_
\bi_
\bt,
151 _
\be_
\bd_
\bi_
\bt, _
\bs_
\be_
\bl_
\bi_
\bn_
\bu_
\bx, _
\bl_
\bd_
\ba_
\bp, _
\bm_
\ba_
\bt_
\bc_
\bh, _
\bp_
\ba_
\br_
\bs_
\be_
\br, _
\ba_
\bl_
\bi_
\ba_
\bs, _
\bd_
\be_
\bf_
\ba_
\bu_
\bl_
\bt_
\bs, _
\ba_
\bu_
\bt_
\bh,
152 _
\be_
\bn_
\bv, _
\bl_
\bo_
\bg_
\bg_
\bi_
\bn_
\bg, _
\bn_
\bs_
\bs, _
\br_
\bb_
\bt_
\br_
\be_
\be, _
\bp_
\be_
\br_
\bm_
\bs, _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn. The subsystem
153 _
\ba_
\bl_
\bl includes every subsystem.
155 There is not currently a way to specify a set of debug
156 flags specific to the plugin--the flags are shared by s
\bsu
\bud
\bdo
\bo
160 This setting has been deprecated in favor of _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs.
163 The user name or uid to to run the command as, if specified
167 The group name or gid to to run the command as, if
168 specified via the -g flag.
171 The prompt to use when requesting a password, if specified
175 Set to true if the user specified the -H flag. If true,
176 set the HOME environment variable to the target user's home
179 preserve_environment=bool
180 Set to true if the user specified the -E flag, indicating
181 that the user wishes to preserve the environment.
184 Set to true if the user specified the -s flag, indicating
185 that the user wishes to run a shell.
188 Set to true if the user specified the -i flag, indicating
189 that the user wishes to run a login shell.
192 If the user does not specify a program on the command line,
193 s
\bsu
\bud
\bdo
\bo will pass the plugin the path to the user's shell and
194 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
195 arguments to be used similarly to _
\bs_
\bu(1). If the plugin
196 does not to support this usage, it may return a value of -2
197 from the check_policy function, which will cause s
\bsu
\bud
\bdo
\bo to
198 print a usage message and exit.
201 Set to true if the user specified the -P flag, indicating
202 that the user wishes to preserve the group vector instead
203 of setting it based on the runas user.
206 Set to true if the user specified the -k flag along with a
207 command, indicating that the user wishes to ignore any
208 cached authentication credentials.
211 Set to true if the user specified the -n flag, indicating
212 that s
\bsu
\bud
\bdo
\bo should operate in non-interactive mode. The
213 plugin may reject a command run in non-interactive mode if
214 user interaction is required.
217 BSD login class to use when setting resource limits and
218 nice value, if specified by the -c flag.
221 SELinux role to use when executing the command, if
222 specified by the -r flag.
225 SELinux type to use when executing the command, if
226 specified by the -t flag.
229 Authentication type, if specified by the -a flag, to use on
230 systems where BSD authentication is supported.
233 A space-separated list of IP network addresses and netmasks
234 in the form "addr/netmask", e.g.
235 "192.168.1.2/255.255.255.0". The address and netmask pairs
236 may be either IPv4 or IPv6, depending on what the operating
237 system supports. If the address contains a colon (':'), it
238 is an IPv6 address, else it is IPv4.
241 The command name that sudo was run as, typically "sudo" or
245 Set to true when the -e flag is is specified or if invoked
246 as s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt. The plugin shall substitute an editor into
247 _
\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
248 error if the plugin does not support _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt. For more
249 information, see the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by section.
252 If specified, the user has requested via the -C flag that
253 s
\bsu
\bud
\bdo
\bo close all files descriptors with a value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or
254 higher. The plugin may optionally pass this, or another
255 value, back in the _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
257 Additional settings may be added in the future so the plugin
258 should silently ignore settings that it does not recognize.
261 A vector of information about the user running the command in
262 the form of "name=value" strings. The vector is terminated by
265 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
266 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
267 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
270 The name of the user invoking s
\bsu
\bud
\bdo
\bo.
273 The real user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
276 The real group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
279 The user's supplementary group list formatted as a string
280 of comma-separated group IDs.
283 The user's current working directory.
286 The path to the user's terminal device. If the user has no
287 terminal device associated with the session, the value will
288 be empty, as in tty=.
291 The local machine's hostname as returned by the
292 gethostname() system call.
295 The number of lines the user's terminal supports. If there
296 is no terminal device available, a default value of 24 is
300 The number of columns the user's terminal supports. If
301 there is no terminal device available, a default value of
305 The user's environment in the form of a NULL-terminated vector
306 of "name=value" strings.
308 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
309 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
310 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
313 void (*close)(int exit_status, int error);
315 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
318 The function arguments are as follows:
321 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
322 call. The value of exit_status is undefined if error is non-
326 If the command could not be executed, this is set to the value
327 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. The plugin is
328 responsible for displaying error information via the
329 conversation or plugin_printf function. If the command was
330 successfully executed, the value of error is 0.
333 int (*show_version)(int verbose);
335 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
336 the -V option. The plugin may display its version information to
337 the user via the conversation or plugin_printf function using
338 SUDO_CONV_INFO_MSG. If the user requests detailed version
339 information, the verbose flag will be set.
342 int (*check_policy)(int argc, char * const argv[]
343 char *env_add[], char **command_info[],
344 char **argv_out[], char **user_env_out[]);
346 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
347 the user is allowed to run the specified commands.
349 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
350 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
351 is a mechanism for editing one or more files where an editor is run
352 with the user's credentials instead of with elevated privileges.
353 s
\bsu
\bud
\bdo
\bo achieves this by creating user-writable temporary copies of
354 the files to be edited and then overwriting the originals with the
355 temporary copies after editing is complete. If the plugin supports
356 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt, it should choose the editor to be used, potentially from
357 a variable in the user's environment, such as EDITOR, and include
358 it in _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt (note that environment variables may include command
359 line flags). The files to be edited should be copied from _
\ba_
\br_
\bg_
\bv
360 into _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt, separated from the editor and its arguments by a
361 "--" element. The "--" will be removed by s
\bsu
\bud
\bdo
\bo before the editor
362 is executed. The plugin should also set _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt_
\b=_
\bt_
\br_
\bu_
\be in the
363 _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
365 The _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function returns 1 if the command is allowed, 0 if
366 not allowed, -1 for a general error, or -2 for a usage error or if
367 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt was specified but is unsupported by the plugin. In the
368 latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits. If
369 an error occurs, the plugin may optionally call the conversation or
370 plugin_printf function with SUDO_CONF_ERROR_MSG to present
371 additional error information to the user.
373 The function arguments are as follows:
376 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
380 The argument vector describing the command the user wishes to
381 run, in the same form as what would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
382 system call. The vector is terminated by a NULL pointer.
385 Additional environment variables specified by the user on the
386 command line in the form of a NULL-terminated vector of
387 "name=value" strings. The plugin may reject the command if one
388 or more variables are not allowed to be set, or it may silently
389 ignore such variables.
391 When parsing _
\be_
\bn_
\bv_
\b__
\ba_
\bd_
\bd, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
392 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
393 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
396 Information about the command being run in the form of
397 "name=value" strings. These values are used by s
\bsu
\bud
\bdo
\bo to set the
398 execution environment when running a command. The plugin is
399 responsible for creating and populating the vector, which must
400 be terminated with a NULL pointer. The following values are
401 recognized by s
\bsu
\bud
\bdo
\bo:
404 Fully qualified path to the command to be executed.
407 User ID to run the command as.
410 Effective user ID to run the command as. If not specified,
411 the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bu_
\bi_
\bd is used.
414 Group ID to run the command as.
417 Effective group ID to run the command as. If not
418 specified, the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bg_
\bi_
\bd is used.
421 The supplementary group vector to use for the command in
422 the form of a comma-separated list of group IDs. If
423 _
\bp_
\br_
\be_
\bs_
\be_
\br_
\bv_
\be_
\b__
\bg_
\br_
\bo_
\bu_
\bp_
\bs is set, this option is ignored.
426 BSD login class to use when setting resource limits and
427 nice value (optional). This option is only set on systems
428 that support login classes.
431 If set, s
\bsu
\bud
\bdo
\bo will preserve the user's group vector instead
432 of initializing the group vector based on runas_user.
435 The current working directory to change to when executing
439 If set, prevent the command from executing other programs.
442 The root directory to use when running the command.
445 Nice value (priority) to use when executing the command.
446 The nice value, if specified, overrides the priority
447 associated with the _
\bl_
\bo_
\bg_
\bi_
\bn_
\b__
\bc_
\bl_
\ba_
\bs_
\bs on BSD systems.
450 The file creation mask to use when executing the command.
453 SELinux role to use when executing the command.
456 SELinux type to use when executing the command.
459 Command timeout. If non-zero then when the timeout expires
460 the command will be killed.
463 Set to true when in _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode. The plugin may enable
464 _
\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.
465 This allows the plugin to perform command substitution and
466 transparently enable _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt when the user attempts to run
470 If specified, s
\bsu
\bud
\bdo
\bo will close all files descriptors with a
471 value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or higher.
474 Set to true if the I/O logging plugins, if any, should
475 compress the log data. This is a hint to the I/O logging
476 plugin which may choose to ignore it.
479 Fully qualified path to the file or directory in which I/O
480 log is to be stored. This is a hint to the I/O logging
481 plugin which may choose to ignore it. If no I/O logging
482 plugin is loaded, this setting has no effect.
485 Set to true if the I/O logging plugins, if any, should log
486 the standard input if it is not connected to a terminal
487 device. This is a hint to the I/O logging plugin which may
491 Set to true if the I/O logging plugins, if any, should log
492 the standard output if it is not connected to a terminal
493 device. This is a hint to the I/O logging plugin which may
497 Set to true if the I/O logging plugins, if any, should log
498 the standard error if it is not connected to a terminal
499 device. This is a hint to the I/O logging plugin which may
503 Set to true if the I/O logging plugins, if any, should log
504 all terminal input. This only includes input typed by the
505 user and not from a pipe or redirected from a file. This
506 is a hint to the I/O logging plugin which may choose to
510 Set to true if the I/O logging plugins, if any, should log
511 all terminal output. This only includes output to the
512 screen, not output to a pipe or file. This is a hint to
513 the I/O logging plugin which may choose to ignore it.
516 Allocate a pseudo-tty to run the command in, regardless of
517 whether or not I/O logging is in use. By default, s
\bsu
\bud
\bdo
\bo
518 will only run the command in a pty when an I/O log plugin
522 Create a utmp (or utmpx) entry when a pseudo-tty is
523 allocated. By default, the new entry will be a copy of the
524 user's existing utmp entry (if any), with the tty, time,
525 type and pid fields updated.
528 User name to use when constructing a new utmp (or utmpx)
529 entry when _
\bs_
\be_
\bt_
\b__
\bu_
\bt_
\bm_
\bp is enabled. This option can be used to
530 set the user field in the utmp entry to the user the
531 command runs as rather than the invoking user. If not set,
532 s
\bsu
\bud
\bdo
\bo will base the new entry on the invoking user's
535 Unsupported values will be ignored.
538 The NULL-terminated argument vector to pass to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
539 system call when executing the command. The plugin is
540 responsible for allocating and populating the vector.
543 The NULL-terminated environment vector to use when executing
544 the command. The plugin is responsible for allocating and
545 populating the vector.
548 int (*list)(int verbose, const char *list_user,
549 int argc, char * const argv[]);
551 List available privileges for the invoking user. Returns 1 on
552 success, 0 on failure and -1 on error. On error, the plugin may
553 optionally call the conversation or plugin_printf function with
554 SUDO_CONF_ERROR_MSG to present additional error information to the
557 Privileges should be output via the conversation or plugin_printf
558 function using SUDO_CONV_INFO_MSG.
561 Flag indicating whether to list in verbose mode or not.
564 The name of a different user to list privileges for if the
565 policy allows it. If NULL, the plugin should list the
566 privileges of the invoking user.
569 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
573 If non-NULL, an argument vector describing a command the user
574 wishes to check against the policy in the same form as what
575 would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call. If the command is
576 permitted by the policy, the fully-qualified path to the
577 command should be displayed along with any command line
581 int (*validate)(void);
583 The validate function is called when s
\bsu
\bud
\bdo
\bo is run with the -v flag.
584 For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache authentication
585 credentials, this function will validate and cache the credentials.
587 The validate function should be NULL if the plugin does not support
590 Returns 1 on success, 0 on failure and -1 on error. On error, the
591 plugin may optionally call the conversation or plugin_printf
592 function with SUDO_CONF_ERROR_MSG to present additional error
593 information to the user.
596 void (*invalidate)(int remove);
598 The invalidate function is called when s
\bsu
\bud
\bdo
\bo is called with the -k
599 or -K flag. For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache
600 authentication credentials, this function will invalidate the
601 credentials. If the _
\br_
\be_
\bm_
\bo_
\bv_
\be flag is set, the plugin may remove the
602 credentials instead of simply invalidating them.
604 The invalidate function should be NULL if the plugin does not
605 support credential caching.
608 int (*init_session)(struct passwd *pwd);
610 The init_session function is called when s
\bsu
\bud
\bdo
\bo sets up the execution
611 environment for the command, immediately before the contents of the
612 _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list are applied (before the uid changes). This can
613 be used to do session setup that is not supported by _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo,
614 such as opening the PAM session.
616 The _
\bp_
\bw_
\bd argument points to a passwd struct for the user the command
617 will be run as if the uid the command will run as was found in the
618 password database, otherwise it will be NULL.
620 Returns 1 on success, 0 on failure and -1 on error. On error, the
621 plugin may optionally call the conversation or plugin_printf
622 function with SUDO_CONF_ERROR_MSG to present additional error
623 information to the user.
625 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bm_
\ba_
\bc_
\br_
\bo_
\bs
627 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
628 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
629 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
630 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
632 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
633 *(vp) = (*(vp) & 0xffff0000) | (n); \
636 #define SUDO_API_VERSION_MAJOR 1
637 #define SUDO_API_VERSION_MINOR 0
638 #define SUDO_API_VERSION ((SUDO_API_VERSION_MAJOR << 16) | \
639 SUDO_API_VERSION_MINOR)
641 I
\bI/
\b/O
\bO P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
643 #define SUDO_IO_PLUGIN 2
644 unsigned int type; /* always SUDO_IO_PLUGIN */
645 unsigned int version; /* always SUDO_API_VERSION */
646 int (*open)(unsigned int version, sudo_conv_t conversation
647 sudo_printf_t plugin_printf, char * const settings[],
648 char * const user_info[], int argc, char * const argv[],
649 char * const user_env[]);
650 void (*close)(int exit_status, int error); /* wait status or error */
651 int (*show_version)(int verbose);
652 int (*log_ttyin)(const char *buf, unsigned int len);
653 int (*log_ttyout)(const char *buf, unsigned int len);
654 int (*log_stdin)(const char *buf, unsigned int len);
655 int (*log_stdout)(const char *buf, unsigned int len);
656 int (*log_stderr)(const char *buf, unsigned int len);
659 When an I/O plugin is loaded, s
\bsu
\bud
\bdo
\bo runs the command in a pseudo-tty.
660 This makes it possible to log the input and output from the user's
661 session. If any of the standard input, standard output or standard
662 error do not correspond to a tty, s
\bsu
\bud
\bdo
\bo will open a pipe to capture the
663 I/O for logging before passing it on.
665 The log_ttyin function receives the raw user input from the terminal
666 device (note that this will include input even when echo is disabled,
667 such as when a password is read). The log_ttyout function receives
668 output from the pseudo-tty that is suitable for replaying the user's
669 session at a later time. The log_stdin, log_stdout and log_stderr
670 functions are only called if the standard input, standard output or
671 standard error respectively correspond to something other than a tty.
673 Any of the logging functions may be set to the NULL pointer if no
674 logging is to be performed. If the open function returns 0, no I/O
675 will be sent to the plugin.
677 The io_plugin struct has the following fields:
680 The type field should always be set to SUDO_IO_PLUGIN
683 The version field should be set to SUDO_API_VERSION.
685 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
689 int (*open)(unsigned int version, sudo_conv_t conversation
690 sudo_printf_t plugin_printf, char * const settings[],
691 char * const user_info[], int argc, char * const argv[],
692 char * const user_env[]);
694 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
695 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn functions are called. It is only called if the
696 version is being requested or the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function has
697 returned successfully. It returns 1 on success, 0 on failure, -1
698 if a general error occurred, or -2 if there was a usage error. In
699 the latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits.
700 If an error occurs, the plugin may optionally call the conversation
701 or plugin_printf function with SUDO_CONF_ERROR_MSG to present
702 additional error information to the user.
704 The function arguments are as follows:
707 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
708 the major and minor version number of the plugin API supported
712 A pointer to the conversation function that may be used by the
713 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
714 show_version below). The conversation function may also be
715 used to display additional error message to the user. The
716 conversation function returns 0 on success and -1 on failure.
719 A pointer to a printf-style function that may be used by the
720 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
721 show_version below). The plugin_printf function may also be
722 used to display additional error message to the user. The
723 plugin_printf function returns number of characters printed on
724 success and -1 on failure.
727 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
728 "name=value" strings. The vector is terminated by a NULL
729 pointer. These settings correspond to flags the user specified
730 when running s
\bsu
\bud
\bdo
\bo. As such, they will only be present when the
731 corresponding flag has been specified on the command line.
733 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
734 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
735 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
737 See the "Policy Plugin API" section for a list of all possible
741 A vector of information about the user running the command in
742 the form of "name=value" strings. The vector is terminated by
745 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
746 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
747 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
749 See the "Policy Plugin API" section for a list of all possible
753 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
757 If non-NULL, an argument vector describing a command the user
758 wishes to run in the same form as what would be passed to the
759 _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call.
762 The user's environment in the form of a NULL-terminated vector
763 of "name=value" strings.
765 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
766 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
767 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
770 void (*close)(int exit_status, int error);
772 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
775 The function arguments are as follows:
778 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
779 call. The value of exit_status is undefined if error is non-
783 If the command could not be executed, this is set to the value
784 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. If the command was
785 successfully executed, the value of error is 0.
788 int (*show_version)(int verbose);
790 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
791 the -V option. The plugin may display its version information to
792 the user via the conversation or plugin_printf function using
793 SUDO_CONV_INFO_MSG. If the user requests detailed version
794 information, the verbose flag will be set.
797 int (*log_ttyin)(const char *buf, unsigned int len);
799 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bi_
\bn function is called whenever data can be read from the
800 user but before it is passed to the running command. This allows
801 the plugin to reject data if it chooses to (for instance if the
802 input contains banned content). Returns 1 if the data should be
803 passed to the command, 0 if the data is rejected (which will
804 terminate the command) or -1 if an error occurred.
806 The function arguments are as follows:
808 buf The buffer containing user input.
810 len The length of _
\bb_
\bu_
\bf in bytes.
813 int (*log_ttyout)(const char *buf, unsigned int len);
815 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bo_
\bu_
\bt function is called whenever data can be read from
816 the command but before it is written to the user's terminal. This
817 allows the plugin to reject data if it chooses to (for instance if
818 the output contains banned content). Returns 1 if the data should
819 be passed to the user, 0 if the data is rejected (which will
820 terminate the command) or -1 if an error occurred.
822 The function arguments are as follows:
824 buf The buffer containing command output.
826 len The length of _
\bb_
\bu_
\bf in bytes.
829 int (*log_stdin)(const char *buf, unsigned int len);
831 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bi_
\bn function is only used if the standard input does not
832 correspond to a tty device. It is called whenever data can be read
833 from the standard input but before it is passed to the running
834 command. This allows the plugin to reject data if it chooses to
835 (for instance if the input contains banned content). Returns 1 if
836 the data should be passed to the command, 0 if the data is rejected
837 (which will terminate the command) or -1 if an error occurred.
839 The function arguments are as follows:
841 buf The buffer containing user input.
843 len The length of _
\bb_
\bu_
\bf in bytes.
846 int (*log_stdout)(const char *buf, unsigned int len);
848 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bo_
\bu_
\bt function is only used if the standard output does
849 not correspond to a tty device. It is called whenever data can be
850 read from the command but before it is written to the standard
851 output. This allows the plugin to reject data if it chooses to
852 (for instance if the output contains banned content). Returns 1 if
853 the data should be passed to the user, 0 if the data is rejected
854 (which will terminate the command) or -1 if an error occurred.
856 The function arguments are as follows:
858 buf The buffer containing command output.
860 len The length of _
\bb_
\bu_
\bf in bytes.
863 int (*log_stderr)(const char *buf, unsigned int len);
865 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\be_
\br_
\br function is only used if the standard error does not
866 correspond to a tty device. It is called whenever data can be read
867 from the command but before it is written to the standard error.
868 This allows the plugin to reject data if it chooses to (for
869 instance if the output contains banned content). Returns 1 if the
870 data should be passed to the user, 0 if the data is rejected (which
871 will terminate the command) or -1 if an error occurred.
873 The function arguments are as follows:
875 buf The buffer containing command output.
877 len The length of _
\bb_
\bu_
\bf in bytes.
879 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bm_
\ba_
\bc_
\br_
\bo_
\bs
881 Same as for the "Policy Plugin API".
883 C
\bCo
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
884 If the plugin needs to interact with the user, it may do so via the
885 conversation function. A plugin should not attempt to read directly
886 from the standard input or the user's tty (neither of which are
887 guaranteed to exist). The caller must include a trailing newline in
888 msg if one is to be printed.
890 A printf-style function is also available that can be used to display
891 informational or error messages to the user, which is usually more
892 convenient for simple messages where no use input is required.
894 struct sudo_conv_message {
895 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
896 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
897 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
898 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
899 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
900 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
901 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
907 struct sudo_conv_reply {
911 typedef int (*sudo_conv_t)(int num_msgs,
912 const struct sudo_conv_message msgs[],
913 struct sudo_conv_reply replies[]);
915 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
917 Pointers to the conversation and printf-style functions are passed in
918 to the plugin's open function when the plugin is initialized.
920 To use the conversation function, the plugin must pass an array of
921 sudo_conv_message and sudo_conv_reply structures. There must be a
922 struct sudo_conv_message and struct sudo_conv_reply for each message in
923 the conversation. The plugin is responsible for freeing the reply
924 buffer filled in to the struct sudo_conv_reply, if any.
926 The printf-style function uses the same underlying mechanism as the
927 conversation function but only supports SUDO_CONV_INFO_MSG,
928 SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be parameter.
929 It can be more convenient than using the conversation function if no
930 user reply is needed and supports standard _
\bp_
\br_
\bi_
\bn_
\bt_
\bf_
\b(_
\b) escape sequences.
932 Unlike, SUDO_CONV_INFO_MSG and SUDO_CONV_ERROR_MSG, messages sent with
933 the <SUDO_CONV_DEBUG_MSG> _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be are not directly user-visible.
934 Instead, they are logged to the file specified in the Debug statement
935 (if any) in the _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf file. This allows a plugin to log
936 debugging information and is intended to be used in conjunction with
937 the _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs setting.
939 See the sample plugin for an example of the conversation function
942 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
943 The _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs module supports a plugin interface to allow non-Unix group
944 lookups. This can be used to query a group source other than the
945 standard Unix group database. A sample group plugin is bundled with
946 s
\bsu
\bud
\bdo
\bo that implements file-based lookups. Third party group plugins
947 include a QAS AD plugin available from Quest Software.
949 A group plugin must declare and populate a sudoers_group_plugin struct
950 in the global scope. This structure contains pointers to the functions
951 that implement plugin initialization, cleanup and group lookup.
953 struct sudoers_group_plugin {
954 unsigned int version;
955 int (*init)(int version, sudo_printf_t sudo_printf,
957 void (*cleanup)(void);
958 int (*query)(const char *user, const char *group,
959 const struct passwd *pwd);
962 The sudoers_group_plugin struct has the following fields:
965 The version field should be set to GROUP_API_VERSION.
967 This allows _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs to determine the API version the group plugin
971 int (*init)(int version, sudo_printf_t plugin_printf,
974 The _
\bi_
\bn_
\bi_
\bt function is called after _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has been parsed but
975 before any policy checks. It returns 1 on success, 0 on failure
976 (or if the plugin is not configured), and -1 if a error occurred.
977 If an error occurs, the plugin may call the plugin_printf function
978 with SUDO_CONF_ERROR_MSG to present additional error information to
981 The function arguments are as follows:
984 The version passed in by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs allows the plugin to determine
985 the major and minor version number of the group plugin API
986 supported by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs.
989 A pointer to a printf-style function that may be used to
990 display informational or error message to the user. Returns
991 the number of characters printed on success and -1 on failure.
994 A NULL-terminated array of arguments generated from the
995 _
\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,
996 _
\ba_
\br_
\bg_
\bv will be NULL.
1001 The _
\bc_
\bl_
\be_
\ba_
\bn_
\bu_
\bp function is called when _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has finished its group
1002 checks. The plugin should free any memory it has allocated and
1003 close open file handles.
1006 int (*query)(const char *user, const char *group,
1007 const struct passwd *pwd);
1009 The _
\bq_
\bu_
\be_
\br_
\by function is used to ask the group plugin whether _
\bu_
\bs_
\be_
\br is
1010 a member of _
\bg_
\br_
\bo_
\bu_
\bp.
1012 The function arguments are as follows:
1015 The name of the user being looked up in the external group
1019 The name of the group being queried.
1021 pwd The password database entry for _
\bu_
\bs_
\be_
\br, if any. If _
\bu_
\bs_
\be_
\br is not
1022 present in the password database, _
\bp_
\bw_
\bd will be NULL.
1024 _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1026 /* Sudoers group plugin version major/minor */
1027 #define GROUP_API_VERSION_MAJOR 1
1028 #define GROUP_API_VERSION_MINOR 0
1029 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1030 GROUP_API_VERSION_MINOR)
1032 /* Getters and setters for group version */
1033 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1034 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1035 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1036 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1038 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1039 *(vp) = (*(vp) & 0xffff0000) | (n); \
1042 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1043 _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs(4), _
\bs_
\bu_
\bd_
\bo(1m)
1046 If you feel you have found a bug in s
\bsu
\bud
\bdo
\bo, please submit a bug report at
1047 http://www.sudo.ws/sudo/bugs/
1049 S
\bSU
\bUP
\bPP
\bPO
\bOR
\bRT
\bT
1050 Limited free support is available via the sudo-workers mailing list,
1051 see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1052 search the archives.
1054 D
\bDI
\bIS
\bSC
\bCL
\bLA
\bAI
\bIM
\bME
\bER
\bR
1055 s
\bsu
\bud
\bdo
\bo is provided ``AS IS'' and any express or implied warranties,
1056 including, but not limited to, the implied warranties of
1057 merchantability and fitness for a particular purpose are disclaimed.
1058 See the LICENSE file distributed with s
\bsu
\bud
\bdo
\bo or
1059 http://www.sudo.ws/sudo/license.html for complete details.
1063 1.8.4 January 6, 2012 SUDO_PLUGIN(1m)