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 passed as options to the plugin's _
\bo_
\bp_
\be_
\bn function. Lines that don't
36 begin with Plugin, Path, Debug or Set are silently ignored.
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 plugin_options ...
49 # Path askpass /path/to/askpass
50 # Path noexec /path/to/sudo_noexec.so
51 # Debug sudo /var/log/sudo_debug all@warn
52 # Set disable_coredump true
54 # The plugin_path is relative to /usr/local/libexec unless
56 # The plugin_name corresponds to a global symbol in the plugin
57 # that contains the plugin interface structure.
58 # The plugin_options are optional.
60 Plugin sudoers_policy sudoers.so
61 Plugin sudoers_io sudoers.so
63 P
\bPo
\bol
\bli
\bic
\bcy
\by P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
64 A policy plugin must declare and populate a policy_plugin struct in the
65 global scope. This structure contains pointers to the functions that
66 implement the s
\bsu
\bud
\bdo
\bo policy checks. The name of the symbol should be
67 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
68 s
\bsu
\bud
\bdo
\bo can load it.
70 struct policy_plugin {
71 #define SUDO_POLICY_PLUGIN 1
72 unsigned int type; /* always SUDO_POLICY_PLUGIN */
73 unsigned int version; /* always SUDO_API_VERSION */
74 int (*open)(unsigned int version, sudo_conv_t conversation,
75 sudo_printf_t plugin_printf, char * const settings[],
76 char * const user_info[], char * const user_env[],
77 char * const plugin_options[]);
78 void (*close)(int exit_status, int error);
79 int (*show_version)(int verbose);
80 int (*check_policy)(int argc, char * const argv[],
81 char *env_add[], char **command_info[],
82 char **argv_out[], char **user_env_out[]);
83 int (*list)(int argc, char * const argv[], int verbose,
84 const char *list_user);
85 int (*validate)(void);
86 void (*invalidate)(int remove);
87 int (*init_session)(struct passwd *pwd, char **user_env[]);
88 void (*register_hooks)(int version,
89 int (*register_hook)(struct sudo_hook *hook));
90 void (*deregister_hooks)(int version,
91 int (*deregister_hook)(struct sudo_hook *hook));
94 The policy_plugin struct has the following fields:
97 The type field should always be set to SUDO_POLICY_PLUGIN.
100 The version field should be set to SUDO_API_VERSION.
102 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
106 int (*open)(unsigned int version, sudo_conv_t conversation,
107 sudo_printf_t plugin_printf, char * const settings[],
108 char * const user_info[], char * const user_env[],
109 char * const plugin_options[]);
111 Returns 1 on success, 0 on failure, -1 if a general error occurred,
112 or -2 if there was a usage error. In the latter case, s
\bsu
\bud
\bdo
\bo will
113 print a usage message before it exits. If an error occurs, the
114 plugin may optionally call the conversation or plugin_printf
115 function with SUDO_CONF_ERROR_MSG to present additional error
116 information to the user.
118 The function arguments are as follows:
121 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
122 the major and minor version number of the plugin API supported
126 A pointer to the conversation function that can be used by the
127 plugin to interact with the user (see below). Returns 0 on
128 success and -1 on failure.
131 A pointer to a printf-style function that may be used to
132 display informational or error messages (see below). Returns
133 the number of characters printed on success and -1 on failure.
136 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
137 "name=value" strings. The vector is terminated by a NULL
138 pointer. These settings correspond to flags the user specified
139 when running s
\bsu
\bud
\bdo
\bo. As such, they will only be present when the
140 corresponding flag has been specified on the command line.
142 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
143 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
144 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
147 A comma-separated list of debug flags that correspond to
148 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
149 flags are passed to the plugin as they appear in
150 _
\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
151 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
152 a different format so long as it does not include a command
155 For reference, the priorities supported by the s
\bsu
\bud
\bdo
\bo front
156 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,
157 _
\bt_
\br_
\ba_
\bc_
\be and _
\bd_
\be_
\bb_
\bu_
\bg.
159 The following subsystems are defined: _
\bm_
\ba_
\bi_
\bn, _
\bm_
\be_
\bm_
\bo_
\br_
\by, _
\ba_
\br_
\bg_
\bs,
160 _
\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,
161 _
\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,
162 _
\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
163 _
\ba_
\bl_
\bl includes every subsystem.
165 There is not currently a way to specify a set of debug
166 flags specific to the plugin--the flags are shared by s
\bsu
\bud
\bdo
\bo
170 This setting has been deprecated in favor of _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs.
173 The user name or uid to to run the command as, if specified
177 The group name or gid to to run the command as, if
178 specified via the -g flag.
181 The prompt to use when requesting a password, if specified
185 Set to true if the user specified the -H flag. If true,
186 set the HOME environment variable to the target user's home
189 preserve_environment=bool
190 Set to true if the user specified the -E flag, indicating
191 that the user wishes to preserve the environment.
194 Set to true if the user specified the -s flag, indicating
195 that the user wishes to run a shell.
198 Set to true if the user specified the -i flag, indicating
199 that the user wishes to run a login shell.
202 If the user does not specify a program on the command line,
203 s
\bsu
\bud
\bdo
\bo will pass the plugin the path to the user's shell and
204 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
205 arguments to be used similarly to _
\bs_
\bu(1). If the plugin
206 does not to support this usage, it may return a value of -2
207 from the check_policy function, which will cause s
\bsu
\bud
\bdo
\bo to
208 print a usage message and exit.
211 Set to true if the user specified the -P flag, indicating
212 that the user wishes to preserve the group vector instead
213 of setting it based on the runas user.
216 Set to true if the user specified the -k flag along with a
217 command, indicating that the user wishes to ignore any
218 cached authentication credentials.
221 Set to true if the user specified the -n flag, indicating
222 that s
\bsu
\bud
\bdo
\bo should operate in non-interactive mode. The
223 plugin may reject a command run in non-interactive mode if
224 user interaction is required.
227 BSD login class to use when setting resource limits and
228 nice value, if specified by the -c flag.
231 SELinux role to use when executing the command, if
232 specified by the -r flag.
235 SELinux type to use when executing the command, if
236 specified by the -t flag.
239 Authentication type, if specified by the -a flag, to use on
240 systems where BSD authentication is supported.
243 A space-separated list of IP network addresses and netmasks
244 in the form "addr/netmask", e.g.
245 "192.168.1.2/255.255.255.0". The address and netmask pairs
246 may be either IPv4 or IPv6, depending on what the operating
247 system supports. If the address contains a colon (':'), it
248 is an IPv6 address, else it is IPv4.
251 The command name that sudo was run as, typically "sudo" or
255 Set to true when the -e flag is is specified or if invoked
256 as s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt. The plugin shall substitute an editor into
257 _
\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
258 error if the plugin does not support _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt. For more
259 information, see the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by section.
262 If specified, the user has requested via the -C flag that
263 s
\bsu
\bud
\bdo
\bo close all files descriptors with a value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or
264 higher. The plugin may optionally pass this, or another
265 value, back in the _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
267 Additional settings may be added in the future so the plugin
268 should silently ignore settings that it does not recognize.
271 A vector of information about the user running the command in
272 the form of "name=value" strings. The vector is terminated by
275 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
276 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
277 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
280 The process ID of the running s
\bsu
\bud
\bdo
\bo process. Only available
281 starting with API version 1.2
284 The parent process ID of the running s
\bsu
\bud
\bdo
\bo process. Only
285 available starting with API version 1.2
288 The session ID of the running s
\bsu
\bud
\bdo
\bo process or 0 if s
\bsu
\bud
\bdo
\bo is
289 not part of a POSIX job control session. Only available
290 starting with API version 1.2
293 The ID of the process group that the running s
\bsu
\bud
\bdo
\bo process
294 belongs to. Only available starting with API version 1.2
297 The ID of the forground process group associated with the
298 terminal device associcated with the s
\bsu
\bud
\bdo
\bo process or -1 if
299 there is no terminal present. Only available starting with
303 The name of the user invoking s
\bsu
\bud
\bdo
\bo.
306 The effective user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
309 The real user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
312 The effective group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
315 The real group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
318 The user's supplementary group list formatted as a string
319 of comma-separated group IDs.
322 The user's current working directory.
325 The path to the user's terminal device. If the user has no
326 terminal device associated with the session, the value will
327 be empty, as in tty=.
330 The local machine's hostname as returned by the
331 gethostname() system call.
334 The number of lines the user's terminal supports. If there
335 is no terminal device available, a default value of 24 is
339 The number of columns the user's terminal supports. If
340 there is no terminal device available, a default value of
344 The user's environment in the form of a NULL-terminated vector
345 of "name=value" strings.
347 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
348 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
349 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
352 Any (non-comment) strings immediately after the plugin path are
353 treated as arguments to the plugin. These arguments are split
354 on a white space boundary and are passed to the plugin in the
355 form of a NULL-terminated array of strings. If no arguments
356 were specified, _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs will be the NULL pointer.
358 NOTE: the _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs parameter is only available starting
359 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
360 specified by the s
\bsu
\bud
\bdo
\bo front end before using _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs.
361 Failure to do so may result in a crash.
364 void (*close)(int exit_status, int error);
366 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
369 The function arguments are as follows:
372 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
373 call. The value of exit_status is undefined if error is non-
377 If the command could not be executed, this is set to the value
378 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. The plugin is
379 responsible for displaying error information via the
380 conversation or plugin_printf function. If the command was
381 successfully executed, the value of error is 0.
384 int (*show_version)(int verbose);
386 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
387 the -V option. The plugin may display its version information to
388 the user via the conversation or plugin_printf function using
389 SUDO_CONV_INFO_MSG. If the user requests detailed version
390 information, the verbose flag will be set.
393 int (*check_policy)(int argc, char * const argv[]
394 char *env_add[], char **command_info[],
395 char **argv_out[], char **user_env_out[]);
397 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
398 the user is allowed to run the specified commands.
400 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
401 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
402 is a mechanism for editing one or more files where an editor is run
403 with the user's credentials instead of with elevated privileges.
404 s
\bsu
\bud
\bdo
\bo achieves this by creating user-writable temporary copies of
405 the files to be edited and then overwriting the originals with the
406 temporary copies after editing is complete. If the plugin supports
407 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt, it should choose the editor to be used, potentially from
408 a variable in the user's environment, such as EDITOR, and include
409 it in _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt (note that environment variables may include command
410 line flags). The files to be edited should be copied from _
\ba_
\br_
\bg_
\bv
411 into _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt, separated from the editor and its arguments by a
412 "--" element. The "--" will be removed by s
\bsu
\bud
\bdo
\bo before the editor
413 is executed. The plugin should also set _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt_
\b=_
\bt_
\br_
\bu_
\be in the
414 _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
416 The _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function returns 1 if the command is allowed, 0 if
417 not allowed, -1 for a general error, or -2 for a usage error or if
418 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt was specified but is unsupported by the plugin. In the
419 latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits. If
420 an error occurs, the plugin may optionally call the conversation or
421 plugin_printf function with SUDO_CONF_ERROR_MSG to present
422 additional error information to the user.
424 The function arguments are as follows:
427 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
431 The argument vector describing the command the user wishes to
432 run, in the same form as what would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
433 system call. The vector is terminated by a NULL pointer.
436 Additional environment variables specified by the user on the
437 command line in the form of a NULL-terminated vector of
438 "name=value" strings. The plugin may reject the command if one
439 or more variables are not allowed to be set, or it may silently
440 ignore such variables.
442 When parsing _
\be_
\bn_
\bv_
\b__
\ba_
\bd_
\bd, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
443 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
444 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
447 Information about the command being run in the form of
448 "name=value" strings. These values are used by s
\bsu
\bud
\bdo
\bo to set the
449 execution environment when running a command. The plugin is
450 responsible for creating and populating the vector, which must
451 be terminated with a NULL pointer. The following values are
452 recognized by s
\bsu
\bud
\bdo
\bo:
455 Fully qualified path to the command to be executed.
458 User ID to run the command as.
461 Effective user ID to run the command as. If not specified,
462 the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bu_
\bi_
\bd is used.
465 Group ID to run the command as.
468 Effective group ID to run the command as. If not
469 specified, the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bg_
\bi_
\bd is used.
472 The supplementary group vector to use for the command in
473 the form of a comma-separated list of group IDs. If
474 _
\bp_
\br_
\be_
\bs_
\be_
\br_
\bv_
\be_
\b__
\bg_
\br_
\bo_
\bu_
\bp_
\bs is set, this option is ignored.
477 BSD login class to use when setting resource limits and
478 nice value (optional). This option is only set on systems
479 that support login classes.
482 If set, s
\bsu
\bud
\bdo
\bo will preserve the user's group vector instead
483 of initializing the group vector based on runas_user.
486 The current working directory to change to when executing
490 If set, prevent the command from executing other programs.
493 The root directory to use when running the command.
496 Nice value (priority) to use when executing the command.
497 The nice value, if specified, overrides the priority
498 associated with the _
\bl_
\bo_
\bg_
\bi_
\bn_
\b__
\bc_
\bl_
\ba_
\bs_
\bs on BSD systems.
501 The file creation mask to use when executing the command.
504 SELinux role to use when executing the command.
507 SELinux type to use when executing the command.
510 Command timeout. If non-zero then when the timeout expires
511 the command will be killed.
514 Set to true when in _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode. The plugin may enable
515 _
\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.
516 This allows the plugin to perform command substitution and
517 transparently enable _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt when the user attempts to run
521 If specified, s
\bsu
\bud
\bdo
\bo will close all files descriptors with a
522 value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or higher.
525 Set to true if the I/O logging plugins, if any, should
526 compress the log data. This is a hint to the I/O logging
527 plugin which may choose to ignore it.
530 Fully qualified path to the file or directory in which I/O
531 log is to be stored. This is a hint to the I/O logging
532 plugin which may choose to ignore it. If no I/O logging
533 plugin is loaded, this setting has no effect.
536 Set to true if the I/O logging plugins, if any, should log
537 the standard input if it is not connected to a terminal
538 device. This is a hint to the I/O logging plugin which may
542 Set to true if the I/O logging plugins, if any, should log
543 the standard output if it is not connected to a terminal
544 device. This is a hint to the I/O logging plugin which may
548 Set to true if the I/O logging plugins, if any, should log
549 the standard error if it is not connected to a terminal
550 device. This is a hint to the I/O logging plugin which may
554 Set to true if the I/O logging plugins, if any, should log
555 all terminal input. This only includes input typed by the
556 user and not from a pipe or redirected from a file. This
557 is a hint to the I/O logging plugin which may choose to
561 Set to true if the I/O logging plugins, if any, should log
562 all terminal output. This only includes output to the
563 screen, not output to a pipe or file. This is a hint to
564 the I/O logging plugin which may choose to ignore it.
567 Allocate a pseudo-tty to run the command in, regardless of
568 whether or not I/O logging is in use. By default, s
\bsu
\bud
\bdo
\bo
569 will only run the command in a pty when an I/O log plugin
573 Create a utmp (or utmpx) entry when a pseudo-tty is
574 allocated. By default, the new entry will be a copy of the
575 user's existing utmp entry (if any), with the tty, time,
576 type and pid fields updated.
579 User name to use when constructing a new utmp (or utmpx)
580 entry when _
\bs_
\be_
\bt_
\b__
\bu_
\bt_
\bm_
\bp is enabled. This option can be used to
581 set the user field in the utmp entry to the user the
582 command runs as rather than the invoking user. If not set,
583 s
\bsu
\bud
\bdo
\bo will base the new entry on the invoking user's
586 Unsupported values will be ignored.
589 The NULL-terminated argument vector to pass to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b)
590 system call when executing the command. The plugin is
591 responsible for allocating and populating the vector.
594 The NULL-terminated environment vector to use when executing
595 the command. The plugin is responsible for allocating and
596 populating the vector.
599 int (*list)(int verbose, const char *list_user,
600 int argc, char * const argv[]);
602 List available privileges for the invoking user. Returns 1 on
603 success, 0 on failure and -1 on error. On error, the plugin may
604 optionally call the conversation or plugin_printf function with
605 SUDO_CONF_ERROR_MSG to present additional error information to the
608 Privileges should be output via the conversation or plugin_printf
609 function using SUDO_CONV_INFO_MSG.
612 Flag indicating whether to list in verbose mode or not.
615 The name of a different user to list privileges for if the
616 policy allows it. If NULL, the plugin should list the
617 privileges of the invoking user.
620 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
624 If non-NULL, an argument vector describing a command the user
625 wishes to check against the policy in the same form as what
626 would be passed to the _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call. If the command is
627 permitted by the policy, the fully-qualified path to the
628 command should be displayed along with any command line
632 int (*validate)(void);
634 The validate function is called when s
\bsu
\bud
\bdo
\bo is run with the -v flag.
635 For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache authentication
636 credentials, this function will validate and cache the credentials.
638 The validate function should be NULL if the plugin does not support
641 Returns 1 on success, 0 on failure and -1 on error. On error, the
642 plugin may optionally call the conversation or plugin_printf
643 function with SUDO_CONF_ERROR_MSG to present additional error
644 information to the user.
647 void (*invalidate)(int remove);
649 The invalidate function is called when s
\bsu
\bud
\bdo
\bo is called with the -k
650 or -K flag. For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache
651 authentication credentials, this function will invalidate the
652 credentials. If the _
\br_
\be_
\bm_
\bo_
\bv_
\be flag is set, the plugin may remove the
653 credentials instead of simply invalidating them.
655 The invalidate function should be NULL if the plugin does not
656 support credential caching.
659 int (*init_session)(struct passwd *pwd, char **user_envp[);
661 The init_session function is called before s
\bsu
\bud
\bdo
\bo sets up the
662 execution environment for the command. It is run in the parent
663 s
\bsu
\bud
\bdo
\bo process and before any uid or gid changes. This can be used
664 to perform session setup that is not supported by _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo,
665 such as opening the PAM session. The close function can be used to
666 tear down the session that was opened by init_session.
668 The _
\bp_
\bw_
\bd argument points to a passwd struct for the user the command
669 will be run as if the uid the command will run as was found in the
670 password database, otherwise it will be NULL.
672 The _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv argument points to the environment the command will
673 run in, in the form of a NULL-terminated vector of "name=value"
674 strings. This is the same string passed back to the front end via
675 the Policy Plugin's _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv_
\b__
\bo_
\bu_
\bt parameter. If the init_session
676 function needs to modify the user environment, it should update the
677 pointer stored in _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. The expected use case is to merge the
678 contents of the PAM environment (if any) with the contents of
679 _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. NOTE: the _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv parameter is only available starting
680 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
681 specified by the s
\bsu
\bud
\bdo
\bo front end before using _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. Failure to
682 do so may result in a crash.
684 Returns 1 on success, 0 on failure and -1 on error. On error, the
685 plugin may optionally call the conversation or plugin_printf
686 function with SUDO_CONF_ERROR_MSG to present additional error
687 information to the user.
690 void (*register_hooks)(int version,
691 int (*register_hook)(struct sudo_hook *hook));
693 The register_hooks function is called by the sudo front end to
694 register any hooks the plugin needs. If the plugin does not
695 support hooks, register_hooks should be set to the NULL pointer.
697 The _
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn argument describes the version of the hooks API
698 supported by the s
\bsu
\bud
\bdo
\bo front end.
700 The register_hook function should be used to register any supported
701 hooks the plugin needs. It returns 0 on success, 1 if the hook
702 type is not supported and -1 if the major version in struct hook
703 does not match the front end's major hook API version.
705 See the "Hook Function API" section below for more information
708 NOTE: the register_hooks function is only available starting with
709 API version 1.2. If the s
\bsu
\bud
\bdo
\bo front end doesn't support API version
710 1.2 or higher, register_hooks will not be called.
713 void (*deregister_hooks)(int version,
714 int (*deregister_hook)(struct sudo_hook *hook));
716 The deregister_hooks function is called by the sudo front end to
717 deregister any hooks the plugin has registered. If the plugin does
718 not support hooks, deregister_hooks should be set to the NULL
721 The _
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn argument describes the version of the hooks API
722 supported by the s
\bsu
\bud
\bdo
\bo front end.
724 The deregister_hook function should be used to deregister any hooks
725 that were put in place by the register_hook function. If the
726 plugin tries to deregister a hook that the front end does not
727 support, deregister_hook will return an error.
729 See the "Hook Function API" section below for more information
732 NOTE: the deregister_hooks function is only available starting with
733 API version 1.2. If the s
\bsu
\bud
\bdo
\bo front end doesn't support API version
734 1.2 or higher, deregister_hooks will not be called.
736 _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bP_
\bl_
\bu_
\bg_
\bi_
\bn _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
738 /* Plugin API version major/minor. */
739 #define SUDO_API_VERSION_MAJOR 1
740 #define SUDO_API_VERSION_MINOR 2
741 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
742 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
743 SUDO_API_VERSION_MINOR)
745 /* Getters and setters for API version */
746 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
747 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
748 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
749 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
751 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
752 *(vp) = (*(vp) & 0xffff0000) | (n); \
755 I
\bI/
\b/O
\bO P
\bPl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
757 #define SUDO_IO_PLUGIN 2
758 unsigned int type; /* always SUDO_IO_PLUGIN */
759 unsigned int version; /* always SUDO_API_VERSION */
760 int (*open)(unsigned int version, sudo_conv_t conversation
761 sudo_printf_t plugin_printf, char * const settings[],
762 char * const user_info[], int argc, char * const argv[],
763 char * const user_env[], char * const plugin_options[]);
764 void (*close)(int exit_status, int error); /* wait status or error */
765 int (*show_version)(int verbose);
766 int (*log_ttyin)(const char *buf, unsigned int len);
767 int (*log_ttyout)(const char *buf, unsigned int len);
768 int (*log_stdin)(const char *buf, unsigned int len);
769 int (*log_stdout)(const char *buf, unsigned int len);
770 int (*log_stderr)(const char *buf, unsigned int len);
771 void (*register_hooks)(int version,
772 int (*register_hook)(struct sudo_hook *hook));
773 void (*deregister_hooks)(int version,
774 int (*deregister_hook)(struct sudo_hook *hook));
777 When an I/O plugin is loaded, s
\bsu
\bud
\bdo
\bo runs the command in a pseudo-tty.
778 This makes it possible to log the input and output from the user's
779 session. If any of the standard input, standard output or standard
780 error do not correspond to a tty, s
\bsu
\bud
\bdo
\bo will open a pipe to capture the
781 I/O for logging before passing it on.
783 The log_ttyin function receives the raw user input from the terminal
784 device (note that this will include input even when echo is disabled,
785 such as when a password is read). The log_ttyout function receives
786 output from the pseudo-tty that is suitable for replaying the user's
787 session at a later time. The log_stdin, log_stdout and log_stderr
788 functions are only called if the standard input, standard output or
789 standard error respectively correspond to something other than a tty.
791 Any of the logging functions may be set to the NULL pointer if no
792 logging is to be performed. If the open function returns 0, no I/O
793 will be sent to the plugin.
795 The io_plugin struct has the following fields:
798 The type field should always be set to SUDO_IO_PLUGIN
801 The version field should be set to SUDO_API_VERSION.
803 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
807 int (*open)(unsigned int version, sudo_conv_t conversation
808 sudo_printf_t plugin_printf, char * const settings[],
809 char * const user_info[], int argc, char * const argv[],
810 char * const user_env[], char * const plugin_options[]);
812 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
813 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn functions are called. It is only called if the
814 version is being requested or the _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by function has
815 returned successfully. It returns 1 on success, 0 on failure, -1
816 if a general error occurred, or -2 if there was a usage error. In
817 the latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits.
818 If an error occurs, the plugin may optionally call the conversation
819 or plugin_printf function with SUDO_CONF_ERROR_MSG to present
820 additional error information to the user.
822 The function arguments are as follows:
825 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
826 the major and minor version number of the plugin API supported
830 A pointer to the conversation function that may be used by the
831 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
832 show_version below). The conversation function may also be
833 used to display additional error message to the user. The
834 conversation function returns 0 on success and -1 on failure.
837 A pointer to a printf-style function that may be used by the
838 _
\bs_
\bh_
\bo_
\bw_
\b__
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn function to display version information (see
839 show_version below). The plugin_printf function may also be
840 used to display additional error message to the user. The
841 plugin_printf function returns number of characters printed on
842 success and -1 on failure.
845 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
846 "name=value" strings. The vector is terminated by a NULL
847 pointer. These settings correspond to flags the user specified
848 when running s
\bsu
\bud
\bdo
\bo. As such, they will only be present when the
849 corresponding flag has been specified on the command line.
851 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
852 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
853 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
855 See the "Policy Plugin API" section for a list of all possible
859 A vector of information about the user running the command in
860 the form of "name=value" strings. The vector is terminated by
863 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
864 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
865 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
867 See the "Policy Plugin API" section for a list of all possible
871 The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
875 If non-NULL, an argument vector describing a command the user
876 wishes to run in the same form as what would be passed to the
877 _
\be_
\bx_
\be_
\bc_
\bv_
\be_
\b(_
\b) system call.
880 The user's environment in the form of a NULL-terminated vector
881 of "name=value" strings.
883 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
884 equal sign ('=') since the _
\bn_
\ba_
\bm_
\be field will never include one
885 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
888 Any (non-comment) strings immediately after the plugin path are
889 treated as arguments to the plugin. These arguments are split
890 on a white space boundary and are passed to the plugin in the
891 form of a NULL-terminated array of strings. If no arguments
892 were specified, _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs will be the NULL pointer.
894 NOTE: the _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs parameter is only available starting
895 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
896 specified by the s
\bsu
\bud
\bdo
\bo front end before using _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs.
897 Failure to do so may result in a crash.
900 void (*close)(int exit_status, int error);
902 The close function is called when the command being run by s
\bsu
\bud
\bdo
\bo
905 The function arguments are as follows:
908 The command's exit status, as returned by the _
\bw_
\ba_
\bi_
\bt(2) system
909 call. The value of exit_status is undefined if error is non-
913 If the command could not be executed, this is set to the value
914 of errno set by the _
\be_
\bx_
\be_
\bc_
\bv_
\be(2) system call. If the command was
915 successfully executed, the value of error is 0.
918 int (*show_version)(int verbose);
920 The show_version function is called by s
\bsu
\bud
\bdo
\bo when the user specifies
921 the -V option. The plugin may display its version information to
922 the user via the conversation or plugin_printf function using
923 SUDO_CONV_INFO_MSG. If the user requests detailed version
924 information, the verbose flag will be set.
927 int (*log_ttyin)(const char *buf, unsigned int len);
929 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bi_
\bn function is called whenever data can be read from the
930 user but before it is passed to the running command. This allows
931 the plugin to reject data if it chooses to (for instance if the
932 input contains banned content). Returns 1 if the data should be
933 passed to the command, 0 if the data is rejected (which will
934 terminate the command) or -1 if an error occurred.
936 The function arguments are as follows:
938 buf The buffer containing user input.
940 len The length of _
\bb_
\bu_
\bf in bytes.
943 int (*log_ttyout)(const char *buf, unsigned int len);
945 The _
\bl_
\bo_
\bg_
\b__
\bt_
\bt_
\by_
\bo_
\bu_
\bt function is called whenever data can be read from
946 the command but before it is written to the user's terminal. This
947 allows the plugin to reject data if it chooses to (for instance if
948 the output contains banned content). Returns 1 if the data should
949 be passed to the user, 0 if the data is rejected (which will
950 terminate the command) or -1 if an error occurred.
952 The function arguments are as follows:
954 buf The buffer containing command output.
956 len The length of _
\bb_
\bu_
\bf in bytes.
959 int (*log_stdin)(const char *buf, unsigned int len);
961 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bi_
\bn function is only used if the standard input does not
962 correspond to a tty device. It is called whenever data can be read
963 from the standard input but before it is passed to the running
964 command. This allows the plugin to reject data if it chooses to
965 (for instance if the input contains banned content). Returns 1 if
966 the data should be passed to the command, 0 if the data is rejected
967 (which will terminate the command) or -1 if an error occurred.
969 The function arguments are as follows:
971 buf The buffer containing user input.
973 len The length of _
\bb_
\bu_
\bf in bytes.
976 int (*log_stdout)(const char *buf, unsigned int len);
978 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\bo_
\bu_
\bt function is only used if the standard output does
979 not correspond to a tty device. It is called whenever data can be
980 read from the command but before it is written to the standard
981 output. This allows the plugin to reject data if it chooses to
982 (for instance if the output contains banned content). Returns 1 if
983 the data should be passed to the user, 0 if the data is rejected
984 (which will terminate the command) or -1 if an error occurred.
986 The function arguments are as follows:
988 buf The buffer containing command output.
990 len The length of _
\bb_
\bu_
\bf in bytes.
993 int (*log_stderr)(const char *buf, unsigned int len);
995 The _
\bl_
\bo_
\bg_
\b__
\bs_
\bt_
\bd_
\be_
\br_
\br function is only used if the standard error does not
996 correspond to a tty device. It is called whenever data can be read
997 from the command but before it is written to the standard error.
998 This allows the plugin to reject data if it chooses to (for
999 instance if the output contains banned content). Returns 1 if the
1000 data should be passed to the user, 0 if the data is rejected (which
1001 will terminate the command) or -1 if an error occurred.
1003 The function arguments are as follows:
1005 buf The buffer containing command output.
1007 len The length of _
\bb_
\bu_
\bf in bytes.
1010 See the "Policy Plugin API" section for a description of
1014 See the "Policy Plugin API" section for a description of
1017 _
\bI_
\b/_
\bO _
\bP_
\bl_
\bu_
\bg_
\bi_
\bn _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1019 Same as for the "Policy Plugin API".
1021 H
\bHo
\boo
\bok
\bk F
\bFu
\bun
\bnc
\bct
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
1022 Beginning with plugin API version 1.2, it is possible to install hooks
1023 for certain functions called by the s
\bsu
\bud
\bdo
\bo front end.
1025 Currently, the only supported hooks relate to the handling of
1026 environment variables. Hooks can be used to intercept attempts to get,
1027 set, or remove environment variables so that these changes can be
1028 reflected in the version of the environment that is used to execute a
1029 command. A future version of the API will support hooking internal
1030 s
\bsu
\bud
\bdo
\bo front end functions as well.
1032 _
\bH_
\bo_
\bo_
\bk _
\bs_
\bt_
\br_
\bu_
\bc_
\bt_
\bu_
\br_
\be
1034 Hooks in s
\bsu
\bud
\bdo
\bo are described by the following structure:
1036 typedef int (*sudo_hook_fn_t)();
1041 sudo_hook_fn_t hook_fn;
1045 The sudo_hook structure has the following fields:
1048 The hook_version field should be set to SUDO_HOOK_VERSION.
1051 The hook_type field may be one of the following supported hook
1055 The C library setenv() function. Any registered hooks will run
1056 before the C library implementation. The hook_fn field should
1057 be a function that matches the following typedef:
1059 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1060 const char *value, int overwrite, void *closure);
1062 If the registered hook does not match the typedef the results
1066 The C library unsetenv() function. Any registered hooks will
1067 run before the C library implementation. The hook_fn field
1068 should be a function that matches the following typedef:
1070 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1074 The C library getenv() function. Any registered hooks will run
1075 before the C library implementation. The hook_fn field should
1076 be a function that matches the following typedef:
1078 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1079 char **value, void *closure);
1081 If the registered hook does not match the typedef the results
1085 The C library putenv() function. Any registered hooks will run
1086 before the C library implementation. The hook_fn field should
1087 be a function that matches the following typedef:
1089 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1092 If the registered hook does not match the typedef the results
1096 sudo_hook_fn_t hook_fn;
1098 The hook_fn field should be set to the plugin's hook
1099 implementation. The actual function arguments will vary depending
1100 on the hook_type (see hook_type above). In all cases, the closure
1101 field of struct sudo_hook is passed as the last function parameter.
1102 This can be used to pass arbitrary data to the plugin's hook
1105 The function return value may be one of the following:
1108 The hook function encountered an error.
1111 The hook completed without error, go on to the next hook
1112 (including the native implementation if applicable). For
1113 example, a getenv hook might return SUDO_HOOK_RET_NEXT if the
1114 specified variable was not found in the private copy of the
1118 The hook completed without error, stop processing hooks for
1119 this invocation. This can be used to replace the native
1120 implementation. For example, a setenv hook that operates on a
1121 private copy of the environment but leaves environ unchanged.
1123 Note that it is very easy to create an infinite loop when hooking C
1124 library functions. For example, a getenv hook that calls the snprintf
1125 function may create a loop if the snprintf implementation calls getenv
1126 to check the locale. To prevent this, you may wish to use a static
1127 variable in the hook function to guard against nested calls. E.g.
1129 static int in_progress = 0; /* avoid recursion */
1131 return SUDO_HOOK_RET_NEXT;
1135 return SUDO_HOOK_RET_STOP;
1137 _
\bH_
\bo_
\bo_
\bk _
\bA_
\bP_
\bI _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1139 /* Hook API version major/minor */
1140 #define SUDO_HOOK_VERSION_MAJOR 1
1141 #define SUDO_HOOK_VERSION_MINOR 0
1142 #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1143 #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1144 SUDO_HOOK_VERSION_MINOR)
1146 /* Getters and setters for hook API version */
1147 #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1148 #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1149 #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \
1150 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1152 #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \
1153 *(vp) = (*(vp) & 0xffff0000) | (n); \
1156 C
\bCo
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
1157 If the plugin needs to interact with the user, it may do so via the
1158 conversation function. A plugin should not attempt to read directly
1159 from the standard input or the user's tty (neither of which are
1160 guaranteed to exist). The caller must include a trailing newline in
1161 msg if one is to be printed.
1163 A printf-style function is also available that can be used to display
1164 informational or error messages to the user, which is usually more
1165 convenient for simple messages where no use input is required.
1167 struct sudo_conv_message {
1168 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1169 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1170 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1171 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1172 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1173 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1174 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1180 struct sudo_conv_reply {
1184 typedef int (*sudo_conv_t)(int num_msgs,
1185 const struct sudo_conv_message msgs[],
1186 struct sudo_conv_reply replies[]);
1188 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1190 Pointers to the conversation and printf-style functions are passed in
1191 to the plugin's open function when the plugin is initialized.
1193 To use the conversation function, the plugin must pass an array of
1194 sudo_conv_message and sudo_conv_reply structures. There must be a
1195 struct sudo_conv_message and struct sudo_conv_reply for each message in
1196 the conversation. The plugin is responsible for freeing the reply
1197 buffer filled in to the struct sudo_conv_reply, if any.
1199 The printf-style function uses the same underlying mechanism as the
1200 conversation function but only supports SUDO_CONV_INFO_MSG,
1201 SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be parameter.
1202 It can be more convenient than using the conversation function if no
1203 user reply is needed and supports standard _
\bp_
\br_
\bi_
\bn_
\bt_
\bf_
\b(_
\b) escape sequences.
1205 Unlike, SUDO_CONV_INFO_MSG and SUDO_CONV_ERROR_MSG, messages sent with
1206 the <SUDO_CONV_DEBUG_MSG> _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be are not directly user-visible.
1207 Instead, they are logged to the file specified in the Debug statement
1208 (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
1209 debugging information and is intended to be used in conjunction with
1210 the _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs setting.
1212 See the sample plugin for an example of the conversation function
1215 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
1216 The _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs module supports a plugin interface to allow non-Unix group
1217 lookups. This can be used to query a group source other than the
1218 standard Unix group database. A sample group plugin is bundled with
1219 s
\bsu
\bud
\bdo
\bo that implements file-based lookups. Third party group plugins
1220 include a QAS AD plugin available from Quest Software.
1222 A group plugin must declare and populate a sudoers_group_plugin struct
1223 in the global scope. This structure contains pointers to the functions
1224 that implement plugin initialization, cleanup and group lookup.
1226 struct sudoers_group_plugin {
1227 unsigned int version;
1228 int (*init)(int version, sudo_printf_t sudo_printf,
1229 char *const argv[]);
1230 void (*cleanup)(void);
1231 int (*query)(const char *user, const char *group,
1232 const struct passwd *pwd);
1235 The sudoers_group_plugin struct has the following fields:
1238 The version field should be set to GROUP_API_VERSION.
1240 This allows _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs to determine the API version the group plugin
1244 int (*init)(int version, sudo_printf_t plugin_printf,
1245 char *const argv[]);
1247 The _
\bi_
\bn_
\bi_
\bt function is called after _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has been parsed but
1248 before any policy checks. It returns 1 on success, 0 on failure
1249 (or if the plugin is not configured), and -1 if a error occurred.
1250 If an error occurs, the plugin may call the plugin_printf function
1251 with SUDO_CONF_ERROR_MSG to present additional error information to
1254 The function arguments are as follows:
1257 The version passed in by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs allows the plugin to determine
1258 the major and minor version number of the group plugin API
1259 supported by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs.
1262 A pointer to a printf-style function that may be used to
1263 display informational or error message to the user. Returns
1264 the number of characters printed on success and -1 on failure.
1267 A NULL-terminated array of arguments generated from the
1268 _
\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,
1269 _
\ba_
\br_
\bg_
\bv will be NULL.
1274 The _
\bc_
\bl_
\be_
\ba_
\bn_
\bu_
\bp function is called when _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has finished its group
1275 checks. The plugin should free any memory it has allocated and
1276 close open file handles.
1279 int (*query)(const char *user, const char *group,
1280 const struct passwd *pwd);
1282 The _
\bq_
\bu_
\be_
\br_
\by function is used to ask the group plugin whether _
\bu_
\bs_
\be_
\br is
1283 a member of _
\bg_
\br_
\bo_
\bu_
\bp.
1285 The function arguments are as follows:
1288 The name of the user being looked up in the external group
1292 The name of the group being queried.
1294 pwd The password database entry for _
\bu_
\bs_
\be_
\br, if any. If _
\bu_
\bs_
\be_
\br is not
1295 present in the password database, _
\bp_
\bw_
\bd will be NULL.
1297 _
\bG_
\br_
\bo_
\bu_
\bp _
\bA_
\bP_
\bI _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1299 /* Sudoers group plugin version major/minor */
1300 #define GROUP_API_VERSION_MAJOR 1
1301 #define GROUP_API_VERSION_MINOR 0
1302 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1303 GROUP_API_VERSION_MINOR)
1305 /* Getters and setters for group version */
1306 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1307 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1308 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1309 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1311 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1312 *(vp) = (*(vp) & 0xffff0000) | (n); \
1315 P
\bPL
\bLU
\bUG
\bGI
\bIN
\bN A
\bAP
\bPI
\bI C
\bCH
\bHA
\bAN
\bNG
\bGE
\bEL
\bLO
\bOG
\bG
1316 The following revisions have been made to the Sudo Plugin API.
1319 Initial API version.
1322 The I/O logging plugin's open function was modified to take the
1323 command_info list as an argument.
1326 The Policy and I/O logging plugins' open functions are now passed a
1327 list of plugin options if any are specified in _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf.
1329 A simple hooks API has been introduced to allow plugins to hook in
1330 to the system's environment handling functions.
1332 The init_session Policy plugin function is now passed a pointer to
1333 the user environment which can be updated as needed. This can be
1334 used to merge in environment variables stored in the PAM handle
1335 before a command is run.
1337 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1338 _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs(4), _
\bs_
\bu_
\bd_
\bo(1m)
1341 If you feel you have found a bug in s
\bsu
\bud
\bdo
\bo, please submit a bug report at
1342 http://www.sudo.ws/sudo/bugs/
1344 S
\bSU
\bUP
\bPP
\bPO
\bOR
\bRT
\bT
1345 Limited free support is available via the sudo-workers mailing list,
1346 see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
1347 search the archives.
1349 D
\bDI
\bIS
\bSC
\bCL
\bLA
\bAI
\bIM
\bME
\bER
\bR
1350 s
\bsu
\bud
\bdo
\bo is provided ``AS IS'' and any express or implied warranties,
1351 including, but not limited to, the implied warranties of
1352 merchantability and fitness for a particular purpose are disclaimed.
1353 See the LICENSE file distributed with s
\bsu
\bud
\bdo
\bo or
1354 http://www.sudo.ws/sudo/license.html for complete details.
1358 1.8.5 April 23, 2012 SUDO_PLUGIN(1m)