1 SUDO_PLUGIN(4) Programmer's Manual SUDO_PLUGIN(4)
4 s
\bsu
\bud
\bdo
\bo_
\b_p
\bpl
\blu
\bug
\bgi
\bin
\bn - Sudo Plugin API
6 D
\bDE
\bES
\bSC
\bCR
\bRI
\bIP
\bPT
\bTI
\bIO
\bON
\bN
7 Starting with version 1.8, s
\bsu
\bud
\bdo
\bo supports a plugin API for policy and
8 session logging. By default, the _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs policy plugin and an associated
9 I/O logging plugin are used. Via the plugin API, s
\bsu
\bud
\bdo
\bo can be configured
10 to use alternate policy and/or I/O logging plugins provided by third
11 parties. The plugins to be used are specified via the _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf
14 The API is versioned with a major and minor number. The minor version
15 number is incremented when additions are made. The major number is
16 incremented when incompatible changes are made. A plugin should be check
17 the version passed to it and make sure that the major version matches.
19 The plugin API is defined by the sudo_plugin.h header file.
21 T
\bTh
\bhe
\be s
\bsu
\bud
\bdo
\bo.
\b.c
\bco
\bon
\bnf
\bf f
\bfi
\bil
\ble
\be
22 The _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf file contains plugin configuration directives. The
23 primary keyword is the Plugin directive, which causes a plugin to be
26 A Plugin line consists of the Plugin keyword, followed by the _
\bs_
\by_
\bm_
\bb_
\bo_
\bl_
\b__
\bn_
\ba_
\bm_
\be
27 and the _
\bp_
\ba_
\bt_
\bh to the shared object containing the plugin. The _
\bs_
\by_
\bm_
\bb_
\bo_
\bl_
\b__
\bn_
\ba_
\bm_
\be
28 is the name of the struct policy_plugin or struct io_plugin in the plugin
29 shared object. The _
\bp_
\ba_
\bt_
\bh may be fully qualified or relative. If not
30 fully qualified it is relative to the _
\b/_
\bu_
\bs_
\br_
\b/_
\bl_
\bo_
\bc_
\ba_
\bl_
\b/_
\bl_
\bi_
\bb_
\be_
\bx_
\be_
\bc directory. Any
31 additional parameters after the _
\bp_
\ba_
\bt_
\bh are passed as options to the
32 plugin's o
\bop
\bpe
\ben
\bn() function. Lines that don't begin with Plugin, Path,
33 Debug or Set are silently ignored.
35 The same shared object may contain multiple plugins, each with a
36 different symbol name. The shared object file must be owned by uid 0 and
37 only writable by its owner. Because of ambiguities that arise from
38 composite policies, only a single policy plugin may be specified. This
39 limitation does not apply to I/O plugins.
42 # Default /etc/sudo.conf file
45 # Plugin plugin_name plugin_path plugin_options ...
46 # Path askpass /path/to/askpass
47 # Path noexec /path/to/sudo_noexec.so
48 # Debug sudo /var/log/sudo_debug all@warn
49 # Set disable_coredump true
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.
55 # The plugin_options are optional.
57 Plugin sudoers_policy sudoers.so
58 Plugin sudoers_io sudoers.so
60 P
\bPo
\bol
\bli
\bic
\bcy
\by p
\bpl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
61 A policy plugin must declare and populate a policy_plugin struct in the
62 global scope. This structure contains pointers to the functions that
63 implement the s
\bsu
\bud
\bdo
\bo policy checks. The name of the symbol should be
64 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 s
\bsu
\bud
\bdo
\bo
67 struct policy_plugin {
68 #define SUDO_POLICY_PLUGIN 1
69 unsigned int type; /* always SUDO_POLICY_PLUGIN */
70 unsigned int version; /* always SUDO_API_VERSION */
71 int (*open)(unsigned int version, sudo_conv_t conversation,
72 sudo_printf_t plugin_printf, char * const settings[],
73 char * const user_info[], char * const user_env[],
74 char * const plugin_options[]);
75 void (*close)(int exit_status, int error);
76 int (*show_version)(int verbose);
77 int (*check_policy)(int argc, char * const argv[],
78 char *env_add[], char **command_info[],
79 char **argv_out[], char **user_env_out[]);
80 int (*list)(int argc, char * const argv[], int verbose,
81 const char *list_user);
82 int (*validate)(void);
83 void (*invalidate)(int remove);
84 int (*init_session)(struct passwd *pwd, char **user_env[]);
85 void (*register_hooks)(int version,
86 int (*register_hook)(struct sudo_hook *hook));
87 void (*deregister_hooks)(int version,
88 int (*deregister_hook)(struct sudo_hook *hook));
91 The policy_plugin struct has the following fields:
93 type The type field should always be set to SUDO_POLICY_PLUGIN.
96 The version field should be set to SUDO_API_VERSION.
98 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
102 int (*open)(unsigned int version, sudo_conv_t conversation,
103 sudo_printf_t plugin_printf, char * const settings[],
104 char * const user_info[], char * const user_env[],
105 char * const plugin_options[]);
107 Returns 1 on success, 0 on failure, -1 if a general error occurred,
108 or -2 if there was a usage error. In the latter case, s
\bsu
\bud
\bdo
\bo will
109 print a usage message before it exits. If an error occurs, the
110 plugin may optionally call the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
111 function with SUDO_CONF_ERROR_MSG to present additional error
112 information to the user.
114 The function arguments are as follows:
117 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
118 the major and minor version number of the plugin API
119 supported by s
\bsu
\bud
\bdo
\bo.
122 A pointer to the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function that can be used by
123 the plugin to interact with the user (see below). Returns 0
124 on success and -1 on failure.
127 A pointer to a p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style function that may be used to
128 display informational or error messages (see below). Returns
129 the number of characters printed on success and -1 on
133 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
134 ``name=value'' strings. The vector is terminated by a NULL
135 pointer. These settings correspond to flags the user
136 specified when running s
\bsu
\bud
\bdo
\bo. As such, they will only be
137 present when the corresponding flag has been specified on the
140 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
141 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
142 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
145 A comma-separated list of debug flags that correspond
146 to 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
147 one. The flags are passed to the plugin as they appear
148 in _
\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
149 _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs plugin is _
\bs_
\bu_
\bb_
\bs_
\by_
\bs_
\bt_
\be_
\bm@_
\bp_
\br_
\bi_
\bo_
\br_
\bi_
\bt_
\by but the plugin is
150 free to use a different format so long as it does not
151 include a comma (`,').
153 For reference, the priorities supported by the s
\bsu
\bud
\bdo
\bo
154 front 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,
155 _
\bd_
\bi_
\ba_
\bg, _
\bi_
\bn_
\bf_
\bo, _
\bt_
\br_
\ba_
\bc_
\be and _
\bd_
\be_
\bb_
\bu_
\bg.
157 The following subsystems are defined: _
\bm_
\ba_
\bi_
\bn, _
\bm_
\be_
\bm_
\bo_
\br_
\by,
158 _
\ba_
\br_
\bg_
\bs, _
\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,
159 _
\ba_
\bu_
\bd_
\bi_
\bt, _
\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,
160 _
\bd_
\be_
\bf_
\ba_
\bu_
\bl_
\bt_
\bs, _
\ba_
\bu_
\bt_
\bh, _
\be_
\bn_
\bv, _
\bl_
\bo_
\bg_
\bg_
\bi_
\bn_
\bg, _
\bn_
\bs_
\bs, _
\br_
\bb_
\bt_
\br_
\be_
\be, _
\bp_
\be_
\br_
\bm_
\bs,
161 _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn. The subsystem _
\ba_
\bl_
\bl includes every subsystem.
163 There is not currently a way to specify a set of debug
164 flags specific to the plugin--the flags are shared by
165 s
\bsu
\bud
\bdo
\bo and the plugin.
168 This setting has been deprecated in favor of
169 _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs.
172 The user name or uid to to run the command as, if
173 specified via the -
\b-u
\bu flag.
176 The group name or gid to to run the command as, if
177 specified via the -
\b-g
\bg flag.
180 The prompt to use when requesting a password, if
181 specified via the -
\b-p
\bp flag.
184 Set to true if the user specified the -
\b-H
\bH flag. If
185 true, set the HOME environment variable to the target
186 user's home directory.
188 preserve_environment=bool
189 Set to true if the user specified the -
\b-E
\bE flag,
190 indicating that the user wishes to preserve the
194 Set to true if the user specified the -
\b-s
\bs flag,
195 indicating that the user wishes to run a shell.
198 Set to true if the user specified the -
\b-i
\bi flag,
199 indicating that the user wishes to run a login shell.
202 If the user does not specify a program on the command
203 line, s
\bsu
\bud
\bdo
\bo will pass the plugin the path to the user's
204 shell and set _
\bi_
\bm_
\bp_
\bl_
\bi_
\be_
\bd_
\b__
\bs_
\bh_
\be_
\bl_
\bl to true. This allows s
\bsu
\bud
\bdo
\bo
205 with no arguments to be used similarly to su(1). If
206 the plugin does not to support this usage, it may
207 return a value of -2 from the c
\bch
\bhe
\bec
\bck
\bk_
\b_p
\bpo
\bol
\bli
\bic
\bcy
\by() function,
208 which will cause s
\bsu
\bud
\bdo
\bo to print a usage message and
212 Set to true if the user specified the -
\b-P
\bP flag,
213 indicating that the user wishes to preserve the group
214 vector instead of setting it based on the runas user.
217 Set to true if the user specified the -
\b-k
\bk flag along
218 with a command, indicating that the user wishes to
219 ignore any cached authentication credentials.
222 Set to true if the user specified the -
\b-n
\bn flag,
223 indicating that s
\bsu
\bud
\bdo
\bo should operate in non-interactive
224 mode. The plugin may reject a command run in non-
225 interactive mode if user interaction is required.
228 BSD login class to use when setting resource limits and
229 nice value, if specified by the -
\b-c
\bc flag.
232 SELinux role to use when executing the command, if
233 specified by the -
\b-r
\br flag.
236 SELinux type to use when executing the command, if
237 specified by the -
\b-t
\bt flag.
240 Authentication type, if specified by the -
\b-a
\ba flag, to
241 use on systems where BSD authentication is supported.
244 A space-separated list of IP network addresses and
245 netmasks in the form ``addr/netmask'', e.g.
246 ``192.168.1.2/255.255.255.0''. The address and netmask
247 pairs may be either IPv4 or IPv6, depending on what the
248 operating system supports. If the address contains a
249 colon (`:'), it is an IPv6 address, else it is IPv4.
252 The command name that sudo was run as, typically
253 ``sudo'' or ``sudoedit''.
256 Set to true when the -
\b-e
\be flag is is specified or if
257 invoked as s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt. The plugin shall substitute an
258 editor into _
\ba_
\br_
\bg_
\bv in the c
\bch
\bhe
\bec
\bck
\bk_
\b_p
\bpo
\bol
\bli
\bic
\bcy
\by() function or
259 return -2 with a usage error if the plugin does not
260 support _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt. For more information, see the
261 _
\bc_
\bh_
\be_
\bc_
\bk_
\b__
\bp_
\bo_
\bl_
\bi_
\bc_
\by section.
264 If specified, the user has requested via the -
\b-C
\bC flag
265 that s
\bsu
\bud
\bdo
\bo close all files descriptors with a value of
266 _
\bn_
\bu_
\bm_
\bb_
\be_
\br or higher. The plugin may optionally pass this,
267 or another value, back in the _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
269 Additional settings may be added in the future so the plugin
270 should silently ignore settings that it does not recognize.
273 A vector of information about the user running the command in
274 the form of ``name=value'' strings. The vector is terminated
277 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
278 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
279 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
282 The process ID of the running s
\bsu
\bud
\bdo
\bo process. Only
283 available starting with API version 1.2
286 The parent process ID of the running s
\bsu
\bud
\bdo
\bo process.
287 Only available starting with API version 1.2
290 The session ID of the running s
\bsu
\bud
\bdo
\bo process or 0 if s
\bsu
\bud
\bdo
\bo
291 is not part of a POSIX job control session. Only
292 available starting with API version 1.2
295 The ID of the process group that the running s
\bsu
\bud
\bdo
\bo
296 process belongs to. Only available starting with API
300 The ID of the forground process group associated with
301 the terminal device associcated with the s
\bsu
\bud
\bdo
\bo process
302 or -1 if there is no terminal present. Only available
303 starting with API version 1.2
306 The name of the user invoking s
\bsu
\bud
\bdo
\bo.
309 The effective user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
312 The real user ID of the user invoking s
\bsu
\bud
\bdo
\bo.
315 The effective group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
318 The real group ID of the user invoking s
\bsu
\bud
\bdo
\bo.
321 The user's supplementary group list formatted as a
322 string of comma-separated group IDs.
325 The user's current working directory.
328 The path to the user's terminal device. If the user
329 has no terminal device associated with the session, the
330 value will be empty, as in ``tty=''.
333 The local machine's hostname as returned by the
334 gethostname(2) system call.
337 The number of lines the user's terminal supports. If
338 there is no terminal device available, a default value
342 The number of columns the user's terminal supports. If
343 there is no terminal device available, a default value
347 The user's environment in the form of a NULL-terminated
348 vector of ``name=value'' strings.
350 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
351 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
352 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
355 Any (non-comment) strings immediately after the plugin path
356 are treated as arguments to the plugin. These arguments are
357 split on a white space boundary and are passed to the plugin
358 in the form of a NULL-terminated array of strings. If no
359 arguments were specified, _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs will be the NULL
362 NOTE: the _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs parameter is only available starting
363 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
364 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.
365 Failure to do so may result in a crash.
368 void (*close)(int exit_status, int error);
370 The c
\bcl
\blo
\bos
\bse
\be() function is called when the command being run by s
\bsu
\bud
\bdo
\bo
373 The function arguments are as follows:
376 The command's exit status, as returned by the wait(2) system
377 call. The value of exit_status is undefined if error is non-
381 If the command could not be executed, this is set to the
382 value of errno set by the execve(2) system call. The plugin
383 is responsible for displaying error information via the
384 c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function. If the command
385 was successfully executed, the value of error is 0.
388 int (*show_version)(int verbose);
390 The s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() function is called by s
\bsu
\bud
\bdo
\bo when the user
391 specifies the -
\b-V
\bV option. The plugin may display its version
392 information to the user via the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
393 function using SUDO_CONV_INFO_MSG. If the user requests detailed
394 version information, the verbose flag will be set.
397 int (*check_policy)(int argc, char * const argv[]
398 char *env_add[], char **command_info[],
399 char **argv_out[], char **user_env_out[]);
401 The c
\bch
\bhe
\bec
\bck
\bk_
\b_p
\bpo
\bol
\bli
\bic
\bcy
\by() function is called by s
\bsu
\bud
\bdo
\bo to determine whether
402 the user is allowed to run the specified commands.
404 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
405 the o
\bop
\bpe
\ben
\bn() function, the user has requested _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode.
406 _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt is a mechanism for editing one or more files where an
407 editor is run with the user's credentials instead of with elevated
408 privileges. s
\bsu
\bud
\bdo
\bo achieves this by creating user-writable temporary
409 copies of the files to be edited and then overwriting the originals
410 with the temporary copies after editing is complete. If the plugin
411 supports _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt, it should choose the editor to be used,
412 potentially from a variable in the user's environment, such as
413 EDITOR, and include it in _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt (note that environment variables
414 may include command line flags). The files to be edited should be
415 copied from _
\ba_
\br_
\bg_
\bv into _
\ba_
\br_
\bg_
\bv_
\b__
\bo_
\bu_
\bt, separated from the editor and its
416 arguments by a ``--'' element. The ``--'' will be removed by s
\bsu
\bud
\bdo
\bo
417 before the editor is executed. The plugin should also set
418 _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt_
\b=_
\bt_
\br_
\bu_
\be in the _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo list.
420 The c
\bch
\bhe
\bec
\bck
\bk_
\b_p
\bpo
\bol
\bli
\bic
\bcy
\by() function returns 1 if the command is allowed, 0
421 if not allowed, -1 for a general error, or -2 for a usage error or
422 if _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt was specified but is unsupported by the plugin. In the
423 latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits. If
424 an error occurs, the plugin may optionally call the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn()
425 or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function with SUDO_CONF_ERROR_MSG to present
426 additional error information to the user.
428 The function arguments are as follows:
430 argc The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
433 argv The argument vector describing the command the user wishes to
434 run, in the same form as what would be passed to the
435 execve(2) system call. The vector is terminated by a NULL
439 Additional environment variables specified by the user on the
440 command line in the form of a NULL-terminated vector of
441 ``name=value'' strings. The plugin may reject the command if
442 one or more variables are not allowed to be set, or it may
443 silently ignore such variables.
445 When parsing _
\be_
\bn_
\bv_
\b__
\ba_
\bd_
\bd, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
446 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
447 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
450 Information about the command being run in the form of
451 ``name=value'' strings. These values are used by s
\bsu
\bud
\bdo
\bo to set
452 the execution environment when running a command. The plugin
453 is responsible for creating and populating the vector, which
454 must be terminated with a NULL pointer. The following values
455 are recognized by s
\bsu
\bud
\bdo
\bo:
458 Fully qualified path to the command to be executed.
461 User ID to run the command as.
464 Effective user ID to run the command as. If not
465 specified, the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bu_
\bi_
\bd is used.
468 Group ID to run the command as.
471 Effective group ID to run the command as. If not
472 specified, the value of _
\br_
\bu_
\bn_
\ba_
\bs_
\b__
\bg_
\bi_
\bd is used.
475 The supplementary group vector to use for the command
476 in the form of a comma-separated list of group IDs. If
477 _
\bp_
\br_
\be_
\bs_
\be_
\br_
\bv_
\be_
\b__
\bg_
\br_
\bo_
\bu_
\bp_
\bs is set, this option is ignored.
480 BSD login class to use when setting resource limits and
481 nice value (optional). This option is only set on
482 systems that support login classes.
485 If set, s
\bsu
\bud
\bdo
\bo will preserve the user's group vector
486 instead of initializing the group vector based on
490 The current working directory to change to when
491 executing the command.
494 If set, prevent the command from executing other
498 The root directory to use when running the command.
501 Nice value (priority) to use when executing the
502 command. The nice value, if specified, overrides the
503 priority associated with the _
\bl_
\bo_
\bg_
\bi_
\bn_
\b__
\bc_
\bl_
\ba_
\bs_
\bs on BSD
507 The file creation mask to use when executing the
511 SELinux role to use when executing the command.
514 SELinux type to use when executing the command.
517 Command timeout. If non-zero then when the timeout
518 expires the command will be killed.
521 Set to true when in _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode. The plugin may
522 enable _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt mode even if s
\bsu
\bud
\bdo
\bo was not invoked as
523 s
\bsu
\bud
\bdo
\boe
\bed
\bdi
\bit
\bt. This allows the plugin to perform command
524 substitution and transparently enable _
\bs_
\bu_
\bd_
\bo_
\be_
\bd_
\bi_
\bt when the
525 user attempts to run an editor.
528 If specified, s
\bsu
\bud
\bdo
\bo will close all files descriptors
529 with a value of _
\bn_
\bu_
\bm_
\bb_
\be_
\br or higher.
532 Set to true if the I/O logging plugins, if any, should
533 compress the log data. This is a hint to the I/O
534 logging plugin which may choose to ignore it.
537 Fully qualified path to the file or directory in which
538 I/O log is to be stored. This is a hint to the I/O
539 logging plugin which may choose to ignore it. If no
540 I/O logging plugin is loaded, this setting has no
544 Set to true if the I/O logging plugins, if any, should
545 log the standard input if it is not connected to a
546 terminal device. This is a hint to the I/O logging
547 plugin which may choose to ignore it.
550 Set to true if the I/O logging plugins, if any, should
551 log the standard output if it is not connected to a
552 terminal device. This is a hint to the I/O logging
553 plugin which may choose to ignore it.
556 Set to true if the I/O logging plugins, if any, should
557 log the standard error if it is not connected to a
558 terminal device. This is a hint to the I/O logging
559 plugin which may choose to ignore it.
562 Set to true if the I/O logging plugins, if any, should
563 log all terminal input. This only includes input typed
564 by the user and not from a pipe or redirected from a
565 file. This is a hint to the I/O logging plugin which
566 may choose to ignore it.
569 Set to true if the I/O logging plugins, if any, should
570 log all terminal output. This only includes output to
571 the screen, not output to a pipe or file. This is a
572 hint to the I/O logging plugin which may choose to
576 Allocate a pseudo-tty to run the command in, regardless
577 of whether or not I/O logging is in use. By default,
578 s
\bsu
\bud
\bdo
\bo will only run the command in a pty when an I/O log
582 Create a utmp (or utmpx) entry when a pseudo-tty is
583 allocated. By default, the new entry will be a copy of
584 the user's existing utmp entry (if any), with the tty,
585 time, type and pid fields updated.
588 User name to use when constructing a new utmp (or
589 utmpx) entry when _
\bs_
\be_
\bt_
\b__
\bu_
\bt_
\bm_
\bp is enabled. This option can
590 be used to set the user field in the utmp entry to the
591 user the command runs as rather than the invoking user.
592 If not set, s
\bsu
\bud
\bdo
\bo will base the new entry on the
593 invoking user's existing entry.
595 Unsupported values will be ignored.
598 The NULL-terminated argument vector to pass to the execve(2)
599 system call when executing the command. The plugin is
600 responsible for allocating and populating the vector.
603 The NULL-terminated environment vector to use when executing
604 the command. The plugin is responsible for allocating and
605 populating the vector.
608 int (*list)(int verbose, const char *list_user,
609 int argc, char * const argv[]);
611 List available privileges for the invoking user. Returns 1 on
612 success, 0 on failure and -1 on error. On error, the plugin may
613 optionally call the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function with
614 SUDO_CONF_ERROR_MSG to present additional error information to the
617 Privileges should be output via the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or
618 p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function using SUDO_CONV_INFO_MSG,
621 Flag indicating whether to list in verbose mode or not.
624 The name of a different user to list privileges for if the
625 policy allows it. If NULL, the plugin should list the
626 privileges of the invoking user.
628 argc The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
631 argv If non-NULL, an argument vector describing a command the user
632 wishes to check against the policy in the same form as what
633 would be passed to the execve(2) system call. If the command
634 is permitted by the policy, the fully-qualified path to the
635 command should be displayed along with any command line
639 int (*validate)(void);
641 The v
\bva
\bal
\bli
\bid
\bda
\bat
\bte
\be() function is called when s
\bsu
\bud
\bdo
\bo is run with the -
\b-v
\bv
642 flag. For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache authentication
643 credentials, this function will validate and cache the credentials.
645 The v
\bva
\bal
\bli
\bid
\bda
\bat
\bte
\be() function should be NULL if the plugin does not
646 support credential caching.
648 Returns 1 on success, 0 on failure and -1 on error. On error, the
649 plugin may optionally call the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
650 function with SUDO_CONF_ERROR_MSG to present additional error
651 information to the user.
654 void (*invalidate)(int remove);
656 The i
\bin
\bnv
\bva
\bal
\bli
\bid
\bda
\bat
\bte
\be() function is called when s
\bsu
\bud
\bdo
\bo is called with the -
\b-k
\bk
657 or -
\b-K
\bK flag. For policy plugins such as _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs that cache
658 authentication credentials, this function will invalidate the
659 credentials. If the _
\br_
\be_
\bm_
\bo_
\bv_
\be flag is set, the plugin may remove the
660 credentials instead of simply invalidating them.
662 The i
\bin
\bnv
\bva
\bal
\bli
\bid
\bda
\bat
\bte
\be() function should be NULL if the plugin does not
663 support credential caching.
666 int (*init_session)(struct passwd *pwd, char **user_envp[);
668 The i
\bin
\bni
\bit
\bt_
\b_s
\bse
\bes
\bss
\bsi
\bio
\bon
\bn() function is called before s
\bsu
\bud
\bdo
\bo sets up the
669 execution environment for the command. It is run in the parent
670 s
\bsu
\bud
\bdo
\bo process and before any uid or gid changes. This can be used
671 to perform session setup that is not supported by _
\bc_
\bo_
\bm_
\bm_
\ba_
\bn_
\bd_
\b__
\bi_
\bn_
\bf_
\bo,
672 such as opening the PAM session. The c
\bcl
\blo
\bos
\bse
\be() function can be used
673 to tear down the session that was opened by init_session.
675 The _
\bp_
\bw_
\bd argument points to a passwd struct for the user the command
676 will be run as if the uid the command will run as was found in the
677 password database, otherwise it will be NULL.
679 The _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv argument points to the environment the command will
680 run in, in the form of a NULL-terminated vector of ``name=value''
681 strings. This is the same string passed back to the front end via
682 the Policy Plugin's _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv_
\b__
\bo_
\bu_
\bt parameter. If the i
\bin
\bni
\bit
\bt_
\b_s
\bse
\bes
\bss
\bsi
\bio
\bon
\bn()
683 function needs to modify the user environment, it should update the
684 pointer stored in _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. The expected use case is to merge the
685 contents of the PAM environment (if any) with the contents of
686 _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. NOTE: the _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv parameter is only available starting
687 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
688 specified by the s
\bsu
\bud
\bdo
\bo front end before using _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv. Failure to
689 do so may result in a crash.
691 Returns 1 on success, 0 on failure and -1 on error. On error, the
692 plugin may optionally call the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
693 function with SUDO_CONF_ERROR_MSG to present additional error
694 information to the user.
697 void (*register_hooks)(int version,
698 int (*register_hook)(struct sudo_hook *hook));
700 The r
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bks
\bs() function is called by the sudo front end to
701 register any hooks the plugin needs. If the plugin does not
702 support hooks, register_hooks should be set to the NULL pointer.
704 The _
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn argument describes the version of the hooks API
705 supported by the s
\bsu
\bud
\bdo
\bo front end.
707 The r
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bk() function should be used to register any
708 supported hooks the plugin needs. It returns 0 on success, 1 if
709 the hook type is not supported and -1 if the major version in
710 struct hook does not match the front end's major hook API version.
712 See the _
\bH_
\bo_
\bo_
\bk _
\bf_
\bu_
\bn_
\bc_
\bt_
\bi_
\bo_
\bn _
\bA_
\bP_
\bI section below for more information about
715 NOTE: the r
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bks
\bs() function is only available starting with
716 API version 1.2. If the s
\bsu
\bud
\bdo
\bo front end doesn't support API version
717 1.2 or higher, register_hooks will not be called.
720 void (*deregister_hooks)(int version,
721 int (*deregister_hook)(struct sudo_hook *hook));
723 The d
\bde
\ber
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bks
\bs() function is called by the sudo front end to
724 deregister any hooks the plugin has registered. If the plugin does
725 not support hooks, deregister_hooks should be set to the NULL
728 The _
\bv_
\be_
\br_
\bs_
\bi_
\bo_
\bn argument describes the version of the hooks API
729 supported by the s
\bsu
\bud
\bdo
\bo front end.
731 The d
\bde
\ber
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bk() function should be used to deregister any
732 hooks that were put in place by the r
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bk() function. If
733 the plugin tries to deregister a hook that the front end does not
734 support, deregister_hook will return an error.
736 See the _
\bH_
\bo_
\bo_
\bk _
\bf_
\bu_
\bn_
\bc_
\bt_
\bi_
\bo_
\bn _
\bA_
\bP_
\bI section below for more information about
739 NOTE: the d
\bde
\ber
\bre
\beg
\bgi
\bis
\bst
\bte
\ber
\br_
\b_h
\bho
\boo
\bok
\bks
\bs() function is only available starting
740 with API version 1.2. If the s
\bsu
\bud
\bdo
\bo front end doesn't support API
741 version 1.2 or higher, deregister_hooks will not be called.
743 _
\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
745 /* Plugin API version major/minor. */
746 #define SUDO_API_VERSION_MAJOR 1
747 #define SUDO_API_VERSION_MINOR 2
748 #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
749 #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
750 SUDO_API_VERSION_MINOR)
752 /* Getters and setters for API version */
753 #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
754 #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
755 #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
756 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
758 #define SUDO_VERSION_SET_MINOR(vp, n) do { \
759 *(vp) = (*(vp) & 0xffff0000) | (n); \
762 I
\bI/
\b/O
\bO p
\bpl
\blu
\bug
\bgi
\bin
\bn A
\bAP
\bPI
\bI
764 #define SUDO_IO_PLUGIN 2
765 unsigned int type; /* always SUDO_IO_PLUGIN */
766 unsigned int version; /* always SUDO_API_VERSION */
767 int (*open)(unsigned int version, sudo_conv_t conversation
768 sudo_printf_t plugin_printf, char * const settings[],
769 char * const user_info[], int argc, char * const argv[],
770 char * const user_env[], char * const plugin_options[]);
771 void (*close)(int exit_status, int error); /* wait status or error */
772 int (*show_version)(int verbose);
773 int (*log_ttyin)(const char *buf, unsigned int len);
774 int (*log_ttyout)(const char *buf, unsigned int len);
775 int (*log_stdin)(const char *buf, unsigned int len);
776 int (*log_stdout)(const char *buf, unsigned int len);
777 int (*log_stderr)(const char *buf, unsigned int len);
778 void (*register_hooks)(int version,
779 int (*register_hook)(struct sudo_hook *hook));
780 void (*deregister_hooks)(int version,
781 int (*deregister_hook)(struct sudo_hook *hook));
784 When an I/O plugin is loaded, s
\bsu
\bud
\bdo
\bo runs the command in a pseudo-tty.
785 This makes it possible to log the input and output from the user's
786 session. If any of the standard input, standard output or standard error
787 do not correspond to a tty, s
\bsu
\bud
\bdo
\bo will open a pipe to capture the I/O for
788 logging before passing it on.
790 The log_ttyin function receives the raw user input from the terminal
791 device (note that this will include input even when echo is disabled,
792 such as when a password is read). The log_ttyout function receives
793 output from the pseudo-tty that is suitable for replaying the user's
794 session at a later time. The l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bdi
\bin
\bn(), l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bdo
\bou
\but
\bt() and l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bde
\ber
\brr
\br()
795 functions are only called if the standard input, standard output or
796 standard error respectively correspond to something other than a tty.
798 Any of the logging functions may be set to the NULL pointer if no logging
799 is to be performed. If the open function returns 0, no I/O will be sent
802 The io_plugin struct has the following fields:
804 type The type field should always be set to SUDO_IO_PLUGIN.
807 The version field should be set to SUDO_API_VERSION.
809 This allows s
\bsu
\bud
\bdo
\bo to determine the API version the plugin was built
813 int (*open)(unsigned int version, sudo_conv_t conversation
814 sudo_printf_t plugin_printf, char * const settings[],
815 char * const user_info[], int argc, char * const argv[],
816 char * const user_env[], char * const plugin_options[]);
818 The o
\bop
\bpe
\ben
\bn() function is run before the l
\blo
\bog
\bg_
\b_i
\bin
\bnp
\bpu
\but
\bt(), l
\blo
\bog
\bg_
\b_o
\bou
\but
\btp
\bpu
\but
\bt() or
819 s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() functions are called. It is only called if the
820 version is being requested or the c
\bch
\bhe
\bec
\bck
\bk_
\b_p
\bpo
\bol
\bli
\bic
\bcy
\by() function has
821 returned successfully. It returns 1 on success, 0 on failure, -1
822 if a general error occurred, or -2 if there was a usage error. In
823 the latter case, s
\bsu
\bud
\bdo
\bo will print a usage message before it exits.
824 If an error occurs, the plugin may optionally call the
825 c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function with SUDO_CONF_ERROR_MSG
826 to present additional error information to the user.
828 The function arguments are as follows:
831 The version passed in by s
\bsu
\bud
\bdo
\bo allows the plugin to determine
832 the major and minor version number of the plugin API
833 supported by s
\bsu
\bud
\bdo
\bo.
836 A pointer to the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function that may be used by
837 the s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() function to display version information
838 (see s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() below). The c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function may
839 also be used to display additional error message to the user.
840 The c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function returns 0 on success and -1 on
844 A pointer to a p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style function that may be used by
845 the s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() function to display version information
846 (see show_version below). The p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function may
847 also be used to display additional error message to the user.
848 The p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf() function returns number of characters
849 printed on success and -1 on failure.
852 A vector of user-supplied s
\bsu
\bud
\bdo
\bo settings in the form of
853 ``name=value'' strings. The vector is terminated by a NULL
854 pointer. These settings correspond to flags the user
855 specified when running s
\bsu
\bud
\bdo
\bo. As such, they will only be
856 present when the corresponding flag has been specified on the
859 When parsing _
\bs_
\be_
\bt_
\bt_
\bi_
\bn_
\bg_
\bs, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
860 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
861 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
863 See the _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn _
\bA_
\bP_
\bI section for a list of all possible
867 A vector of information about the user running the command in
868 the form of ``name=value'' strings. The vector is terminated
871 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\bi_
\bn_
\bf_
\bo, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
872 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
873 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
875 See the _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn _
\bA_
\bP_
\bI section for a list of all possible
878 argc The number of elements in _
\ba_
\br_
\bg_
\bv, not counting the final NULL
881 argv If non-NULL, an argument vector describing a command the user
882 wishes to run in the same form as what would be passed to the
883 execve(2) system call.
886 The user's environment in the form of a NULL-terminated
887 vector of ``name=value'' strings.
889 When parsing _
\bu_
\bs_
\be_
\br_
\b__
\be_
\bn_
\bv, the plugin should split on the f
\bfi
\bir
\brs
\bst
\bt
890 equal sign (`=') since the _
\bn_
\ba_
\bm_
\be field will never include one
891 itself but the _
\bv_
\ba_
\bl_
\bu_
\be might.
894 Any (non-comment) strings immediately after the plugin path
895 are treated as arguments to the plugin. These arguments are
896 split on a white space boundary and are passed to the plugin
897 in the form of a NULL-terminated array of strings. If no
898 arguments were specified, _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs will be the NULL
901 NOTE: the _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn_
\b__
\bo_
\bp_
\bt_
\bi_
\bo_
\bn_
\bs parameter is only available starting
902 with API version 1.2. A plugin m
\bmu
\bus
\bst
\bt check the API version
903 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.
904 Failure to do so may result in a crash.
907 void (*close)(int exit_status, int error);
909 The c
\bcl
\blo
\bos
\bse
\be() function is called when the command being run by s
\bsu
\bud
\bdo
\bo
912 The function arguments are as follows:
915 The command's exit status, as returned by the wait(2) system
916 call. The value of exit_status is undefined if error is non-
920 If the command could not be executed, this is set to the
921 value of errno set by the execve(2) system call. If the
922 command was successfully executed, the value of error is 0.
925 int (*show_version)(int verbose);
927 The s
\bsh
\bho
\bow
\bw_
\b_v
\bve
\ber
\brs
\bsi
\bio
\bon
\bn() function is called by s
\bsu
\bud
\bdo
\bo when the user
928 specifies the -
\b-V
\bV option. The plugin may display its version
929 information to the user via the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() or p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
930 function using SUDO_CONV_INFO_MSG. If the user requests detailed
931 version information, the verbose flag will be set.
934 int (*log_ttyin)(const char *buf, unsigned int len);
936 The l
\blo
\bog
\bg_
\b_t
\btt
\bty
\byi
\bin
\bn() function is called whenever data can be read from
937 the user but before it is passed to the running command. This
938 allows the plugin to reject data if it chooses to (for instance if
939 the input contains banned content). Returns 1 if the data should
940 be passed to the command, 0 if the data is rejected (which will
941 terminate the command) or -1 if an error occurred.
943 The function arguments are as follows:
945 buf The buffer containing user input.
947 len The length of _
\bb_
\bu_
\bf in bytes.
950 int (*log_ttyout)(const char *buf, unsigned int len);
952 The l
\blo
\bog
\bg_
\b_t
\btt
\bty
\byo
\bou
\but
\bt() function is called whenever data can be read from
953 the command but before it is written to the user's terminal. This
954 allows the plugin to reject data if it chooses to (for instance if
955 the output contains banned content). Returns 1 if the data should
956 be passed to the user, 0 if the data is rejected (which will
957 terminate the command) or -1 if an error occurred.
959 The function arguments are as follows:
961 buf The buffer containing command output.
963 len The length of _
\bb_
\bu_
\bf in bytes.
966 int (*log_stdin)(const char *buf, unsigned int len);
968 The l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bdi
\bin
\bn() function is only used if the standard input does
969 not correspond to a tty device. It is called whenever data can be
970 read from the standard input but before it is passed to the running
971 command. This allows the plugin to reject data if it chooses to
972 (for instance if the input contains banned content). Returns 1 if
973 the data should be passed to the command, 0 if the data is rejected
974 (which will terminate the command) or -1 if an error occurred.
976 The function arguments are as follows:
978 buf The buffer containing user input.
980 len The length of _
\bb_
\bu_
\bf in bytes.
983 int (*log_stdout)(const char *buf, unsigned int len);
985 The l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bdo
\bou
\but
\bt() function is only used if the standard output does
986 not correspond to a tty device. It is called whenever data can be
987 read from the command but before it is written to the standard
988 output. This allows the plugin to reject data if it chooses to
989 (for instance if the output contains banned content). Returns 1 if
990 the data should be passed to the user, 0 if the data is rejected
991 (which will terminate the command) or -1 if an error occurred.
993 The function arguments are as follows:
995 buf The buffer containing command output.
997 len The length of _
\bb_
\bu_
\bf in bytes.
1000 int (*log_stderr)(const char *buf, unsigned int len);
1002 The l
\blo
\bog
\bg_
\b_s
\bst
\btd
\bde
\ber
\brr
\br() function is only used if the standard error does
1003 not correspond to a tty device. It is called whenever data can be
1004 read from the command but before it is written to the standard
1005 error. This allows the plugin to reject data if it chooses to (for
1006 instance if the output contains banned content). Returns 1 if the
1007 data should be passed to the user, 0 if the data is rejected (which
1008 will terminate the command) or -1 if an error occurred.
1010 The function arguments are as follows:
1012 buf The buffer containing command output.
1014 len The length of _
\bb_
\bu_
\bf in bytes.
1017 See the _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn _
\bA_
\bP_
\bI section for a description of
1021 See the _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn _
\bA_
\bP_
\bI section for a description of
1024 _
\bI_
\b/_
\bO _
\bP_
\bl_
\bu_
\bg_
\bi_
\bn _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1026 Same as for the _
\bP_
\bo_
\bl_
\bi_
\bc_
\by _
\bp_
\bl_
\bu_
\bg_
\bi_
\bn _
\bA_
\bP_
\bI.
1028 H
\bHo
\boo
\bok
\bk f
\bfu
\bun
\bnc
\bct
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
1029 Beginning with plugin API version 1.2, it is possible to install hooks
1030 for certain functions called by the s
\bsu
\bud
\bdo
\bo front end.
1032 Currently, the only supported hooks relate to the handling of environment
1033 variables. Hooks can be used to intercept attempts to get, set, or
1034 remove environment variables so that these changes can be reflected in
1035 the version of the environment that is used to execute a command. A
1036 future version of the API will support hooking internal s
\bsu
\bud
\bdo
\bo front end
1039 _
\bH_
\bo_
\bo_
\bk _
\bs_
\bt_
\br_
\bu_
\bc_
\bt_
\bu_
\br_
\be
1041 Hooks in s
\bsu
\bud
\bdo
\bo are described by the following structure:
1043 typedef int (*sudo_hook_fn_t)();
1048 sudo_hook_fn_t hook_fn;
1052 The sudo_hook structure has the following fields:
1055 The hook_version field should be set to SUDO_HOOK_VERSION.
1058 The hook_type field may be one of the following supported hook
1062 The C library setenv(3) function. Any registered hooks will
1063 run before the C library implementation. The hook_fn field
1064 should be a function that matches the following typedef:
1066 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1067 const char *value, int overwrite, void *closure);
1069 If the registered hook does not match the typedef the results
1073 The C library unsetenv(3) function. Any registered hooks
1074 will run before the C library implementation. The hook_fn
1075 field should be a function that matches the following
1078 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1082 The C library getenv(3) function. Any registered hooks will
1083 run before the C library implementation. The hook_fn field
1084 should be a function that matches the following typedef:
1086 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1087 char **value, void *closure);
1089 If the registered hook does not match the typedef the results
1093 The C library putenv(3) function. Any registered hooks will
1094 run before the C library implementation. The hook_fn field
1095 should be a function that matches the following typedef:
1097 typedef int (*sudo_hook_fn_putenv_t)(char *string,
1100 If the registered hook does not match the typedef the results
1104 sudo_hook_fn_t hook_fn;
1106 The hook_fn field should be set to the plugin's hook
1107 implementation. The actual function arguments will vary depending
1108 on the hook_type (see hook_type above). In all cases, the closure
1109 field of struct sudo_hook is passed as the last function parameter.
1110 This can be used to pass arbitrary data to the plugin's hook
1113 The function return value may be one of the following:
1116 The hook function encountered an error.
1119 The hook completed without error, go on to the next hook
1120 (including the native implementation if applicable). For
1121 example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1122 the specified variable was not found in the private copy of
1126 The hook completed without error, stop processing hooks for
1127 this invocation. This can be used to replace the native
1128 implementation. For example, a setenv hook that operates on
1129 a private copy of the environment but leaves environ
1132 Note that it is very easy to create an infinite loop when hooking C
1133 library functions. For example, a getenv(3) hook that calls the
1134 snprintf(3) function may create a loop if the snprintf(3) implementation
1135 calls getenv(3) to check the locale. To prevent this, you may wish to
1136 use a static variable in the hook function to guard against nested calls.
1139 static int in_progress = 0; /* avoid recursion */
1141 return SUDO_HOOK_RET_NEXT;
1145 return SUDO_HOOK_RET_STOP;
1147 _
\bH_
\bo_
\bo_
\bk _
\bA_
\bP_
\bI _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1149 /* Hook API version major/minor */
1150 #define SUDO_HOOK_VERSION_MAJOR 1
1151 #define SUDO_HOOK_VERSION_MINOR 0
1152 #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1153 #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1154 SUDO_HOOK_VERSION_MINOR)
1156 /* Getters and setters for hook API version */
1157 #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1158 #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1159 #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \
1160 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1162 #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \
1163 *(vp) = (*(vp) & 0xffff0000) | (n); \
1166 C
\bCo
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn A
\bAP
\bPI
\bI
1167 If the plugin needs to interact with the user, it may do so via the
1168 c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function. A plugin should not attempt to read directly
1169 from the standard input or the user's tty (neither of which are
1170 guaranteed to exist). The caller must include a trailing newline in msg
1171 if one is to be printed.
1173 A p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style function is also available that can be used to display
1174 informational or error messages to the user, which is usually more
1175 convenient for simple messages where no use input is required.
1177 struct sudo_conv_message {
1178 #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
1179 #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
1180 #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
1181 #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
1182 #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
1183 #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
1184 #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
1190 struct sudo_conv_reply {
1194 typedef int (*sudo_conv_t)(int num_msgs,
1195 const struct sudo_conv_message msgs[],
1196 struct sudo_conv_reply replies[]);
1198 typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1200 Pointers to the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() and p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style functions are passed in
1201 to the plugin's o
\bop
\bpe
\ben
\bn() function when the plugin is initialized.
1203 To use the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function, the plugin must pass an array of
1204 sudo_conv_message and sudo_conv_reply structures. There must be a struct
1205 sudo_conv_message and struct sudo_conv_reply for each message in the
1206 conversation. The plugin is responsible for freeing the reply buffer
1207 filled in to the struct sudo_conv_reply, if any.
1209 The p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style function uses the same underlying mechanism as the
1210 c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function but only supports SUDO_CONV_INFO_MSG,
1211 SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be parameter.
1212 It can be more convenient than using the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function if no
1213 user reply is needed and supports standard p
\bpr
\bri
\bin
\bnt
\btf
\bf() escape sequences.
1215 Unlike, SUDO_CONV_INFO_MSG and Dv SUDO_CONV_ERROR_MSG , messages sent
1216 with the SUDO_CONV_DEBUG_MSG _
\bm_
\bs_
\bg_
\b__
\bt_
\by_
\bp_
\be are not directly user-visible.
1217 Instead, they are logged to the file specified in the Debug statement (if
1218 any) in the _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf
1220 file. This allows a plugin to log debugging information and is intended
1221 to be used in conjunction with the _
\bd_
\be_
\bb_
\bu_
\bg_
\b__
\bf_
\bl_
\ba_
\bg_
\bs setting.
1223 See the sample plugin for an example of the c
\bco
\bon
\bnv
\bve
\ber
\brs
\bsa
\bat
\bti
\bio
\bon
\bn() function
1226 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
1227 The _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs module supports a plugin interface to allow non-Unix group
1228 lookups. This can be used to query a group source other than the
1229 standard Unix group database. A sample group plugin is bundled with s
\bsu
\bud
\bdo
\bo
1230 that implements file-based lookups. Third party group plugins include a
1231 QAS AD plugin available from Quest Software.
1233 A group plugin must declare and populate a sudoers_group_plugin struct in
1234 the global scope. This structure contains pointers to the functions that
1235 implement plugin initialization, cleanup and group lookup.
1237 struct sudoers_group_plugin {
1238 unsigned int version;
1239 int (*init)(int version, sudo_printf_t sudo_printf,
1240 char *const argv[]);
1241 void (*cleanup)(void);
1242 int (*query)(const char *user, const char *group,
1243 const struct passwd *pwd);
1246 The sudoers_group_plugin struct has the following fields:
1249 The version field should be set to GROUP_API_VERSION.
1251 This allows _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs to determine the API version the group plugin
1255 int (*init)(int version, sudo_printf_t plugin_printf,
1256 char *const argv[]);
1258 The i
\bin
\bni
\bit
\bt() function is called after _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has been parsed but
1259 before any policy checks. It returns 1 on success, 0 on failure
1260 (or if the plugin is not configured), and -1 if a error occurred.
1261 If an error occurs, the plugin may call the p
\bpl
\blu
\bug
\bgi
\bin
\bn_
\b_p
\bpr
\bri
\bin
\bnt
\btf
\bf()
1262 function with SUDO_CONF_ERROR_MSG to present additional error
1263 information to the user.
1265 The function arguments are as follows:
1268 The version passed in by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs allows the plugin to
1269 determine the major and minor version number of the group
1270 plugin API supported by _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs.
1273 A pointer to a p
\bpr
\bri
\bin
\bnt
\btf
\bf()-style function that may be used to
1274 display informational or error message to the user. Returns
1275 the number of characters printed on success and -1 on
1278 argv A NULL-terminated array of arguments generated from the
1279 _
\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,
1280 _
\ba_
\br_
\bg_
\bv will be NULL.
1285 The c
\bcl
\ble
\bea
\ban
\bnu
\bup
\bp() function is called when _
\bs_
\bu_
\bd_
\bo_
\be_
\br_
\bs has finished its
1286 group checks. The plugin should free any memory it has allocated
1287 and close open file handles.
1290 int (*query)(const char *user, const char *group,
1291 const struct passwd *pwd);
1293 The q
\bqu
\bue
\ber
\bry
\by() function is used to ask the group plugin whether _
\bu_
\bs_
\be_
\br
1294 is a member of _
\bg_
\br_
\bo_
\bu_
\bp.
1296 The function arguments are as follows:
1298 user The name of the user being looked up in the external group
1302 The name of the group being queried.
1304 pwd The password database entry for _
\bu_
\bs_
\be_
\br, if any. If _
\bu_
\bs_
\be_
\br is not
1305 present in the password database, _
\bp_
\bw_
\bd will be NULL.
1307 _
\bG_
\br_
\bo_
\bu_
\bp _
\bA_
\bP_
\bI _
\bV_
\be_
\br_
\bs_
\bi_
\bo_
\bn _
\bM_
\ba_
\bc_
\br_
\bo_
\bs
1309 /* Sudoers group plugin version major/minor */
1310 #define GROUP_API_VERSION_MAJOR 1
1311 #define GROUP_API_VERSION_MINOR 0
1312 #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1313 GROUP_API_VERSION_MINOR)
1315 /* Getters and setters for group version */
1316 #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1317 #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1318 #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1319 *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1321 #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1322 *(vp) = (*(vp) & 0xffff0000) | (n); \
1325 P
\bPL
\bLU
\bUG
\bGI
\bIN
\bN A
\bAP
\bPI
\bI C
\bCH
\bHA
\bAN
\bNG
\bGE
\bEL
\bLO
\bOG
\bG
1326 The following revisions have been made to the Sudo Plugin API.
1329 Initial API version.
1332 The I/O logging plugin's o
\bop
\bpe
\ben
\bn() function was modified to take the
1333 command_info list as an argument.
1336 The Policy and I/O logging plugins' o
\bop
\bpe
\ben
\bn() functions are now passed
1337 a list of plugin options if any are specified in _
\b/_
\be_
\bt_
\bc_
\b/_
\bs_
\bu_
\bd_
\bo_
\b._
\bc_
\bo_
\bn_
\bf.
1339 A simple hooks API has been introduced to allow plugins to hook in
1340 to the system's environment handling functions.
1342 The init_session Policy plugin function is now passed a pointer to
1343 the user environment which can be updated as needed. This can be
1344 used to merge in environment variables stored in the PAM handle
1345 before a command is run.
1347 S
\bSE
\bEE
\bE A
\bAL
\bLS
\bSO
\bO
1348 sudoers(4), sudo(1m)
1351 If you feel you have found a bug in s
\bsu
\bud
\bdo
\bo, please submit a bug report at
1352 http://www.sudo.ws/sudo/bugs/
1354 S
\bSU
\bUP
\bPP
\bPO
\bOR
\bRT
\bT
1355 Limited free support is available via the sudo-users mailing list, see
1356 http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the
1359 D
\bDI
\bIS
\bSC
\bCL
\bLA
\bAI
\bIM
\bME
\bER
\bR
1360 s
\bsu
\bud
\bdo
\bo is provided ``AS IS'' and any express or implied warranties,
1361 including, but not limited to, the implied warranties of merchantability
1362 and fitness for a particular purpose are disclaimed. See the LICENSE
1363 file distributed with s
\bsu
\bud
\bdo
\bo or http://www.sudo.ws/sudo/license.html for
1366 Sudo 1.8.6 July 16, 2012 Sudo 1.8.6