1SUDO_PLUGIN(5)              BSD File Formats Manual             SUDO_PLUGIN(5)
2

NAME

4     sudo_plugin — Sudo Plugin API
5

DESCRIPTION

7     Starting with version 1.8, sudo supports a plugin API for policy and ses‐
8     sion logging.  Plugins may be compiled as dynamic shared objects (the de‐
9     fault on systems that support them) or compiled statically into the sudo
10     binary itself.  By default, the sudoers plugin provides audit, security
11     policy and I/O logging capabilities.  Via the plugin API, sudo can be
12     configured to use alternate plugins provided by third parties.  The plug‐
13     ins to be used are specified in the sudo.conf(5) file.
14
15     The API is versioned with a major and minor number.  The minor version
16     number is incremented when additions are made.  The major number is in‐
17     cremented when incompatible changes are made.  A plugin should be check
18     the version passed to it and make sure that the major version matches.
19
20     The plugin API is defined by the <sudo_plugin.h> header file.
21
22   Policy plugin API
23     A policy plugin must declare and populate a struct policy_plugin in the
24     global scope.  This structure contains pointers to the functions that im‐
25     plement the sudo policy checks.  The name of the symbol should be speci‐
26     fied in sudo.conf(5) along with a path to the plugin so that sudo can
27     load it.
28
29     struct policy_plugin {
30     #define SUDO_POLICY_PLUGIN     1
31         unsigned int type; /* always SUDO_POLICY_PLUGIN */
32         unsigned int version; /* always SUDO_API_VERSION */
33         int (*open)(unsigned int version, sudo_conv_t conversation,
34             sudo_printf_t sudo_plugin_printf, char * const settings[],
35             char * const user_info[], char * const user_env[],
36             char * const plugin_options[], const char **errstr);
37         void (*close)(int exit_status, int error);
38         int (*show_version)(int verbose);
39         int (*check_policy)(int argc, char * const argv[],
40             char *env_add[], char **command_info[],
41             char **argv_out[], char **user_env_out[], const char **errstr);
42         int (*list)(int argc, char * const argv[], int verbose,
43             const char *user, const char **errstr);
44         int (*validate)(const char **errstr);
45         void (*invalidate)(int rmcred);
46         int (*init_session)(struct passwd *pwd, char **user_env[],
47             const char **errstr);
48         void (*register_hooks)(int version,
49            int (*register_hook)(struct sudo_hook *hook));
50         void (*deregister_hooks)(int version,
51            int (*deregister_hook)(struct sudo_hook *hook));
52         struct sudo_plugin_event * (*event_alloc)(void);
53     };
54
55     A struct policy_plugin has the following fields:
56
57     type  The type field should always be set to SUDO_POLICY_PLUGIN.
58
59     version
60           The version field should be set to SUDO_API_VERSION.
61
62           This allows sudo to determine the API version the plugin was built
63           against.
64
65     open
66           int (*open)(unsigned int version, sudo_conv_t conversation,
67               sudo_printf_t sudo_plugin_printf, char * const settings[],
68               char * const user_info[], char * const user_env[],
69               char * const plugin_options[], const char **errstr);
70
71           Returns 1 on success, 0 on failure, -1 if a general error occurred,
72           or -2 if there was a usage error.  In the latter case, sudo will
73           print a usage message before it exits.  If an error occurs, the
74           plugin may optionally call the conversation() or
75           sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
76           additional error information to the user.
77
78           The function arguments are as follows:
79
80           version
81                 The version passed in by sudo allows the plugin to determine
82                 the major and minor version number of the plugin API sup‐
83                 ported by sudo.
84
85           conversation
86                 A pointer to the conversation() function that can be used by
87                 the plugin to interact with the user (see Conversation API
88                 for details).  Returns 0 on success and -1 on failure.
89
90           sudo_plugin_printf
91                 A pointer to a printf()-style function that may be used to
92                 display informational or error messages (see Conversation API
93                 for details).  Returns the number of characters printed on
94                 success and -1 on failure.
95
96           settings
97                 A vector of user-supplied sudo settings in the form of
98                 “name=value” strings.  The vector is terminated by a NULL
99                 pointer.  These settings correspond to options the user spec‐
100                 ified when running sudo.  As such, they will only be present
101                 when the corresponding option has been specified on the com‐
102                 mand line.
103
104                 When parsing settings, the plugin should split on the first
105                 equal sign (‘=’) since the name field will never include one
106                 itself but the value might.
107
108                 The following values may be set by sudo:
109
110                 bsdauth_type=string
111                       Authentication type, if specified by the -a option, to
112                       use on systems where BSD authentication is supported.
113
114                 closefrom=number
115                       If specified, the user has requested via the -C option
116                       that sudo close all files descriptors with a value of
117                       number or higher.  The plugin may optionally pass this,
118                       or another value, back in the command_info list.
119
120                 cmnd_chroot=string
121                       The root directory (see chroot(2)) to run the command
122                       in, as specified by the user via the -R option.  The
123                       plugin may ignore or restrict the user's ability to
124                       specify a new root directory.  Only available starting
125                       with API version 1.16.
126
127                 cmnd_cwd=string
128                       The working directory to run the command in, as speci‐
129                       fied by the user via the -D option.  The plugin may ig‐
130                       nore or restrict the user's ability to specify a new
131                       working directory.  Only available starting with API
132                       version 1.16.
133
134                 debug_flags=string
135                       A debug file path name followed by a space and a comma-
136                       separated list of debug flags that correspond to the
137                       plugin's Debug entry in sudo.conf(5), if there is one.
138                       The flags are passed to the plugin exactly as they ap‐
139                       pear in sudo.conf(5).  The syntax used by sudo and the
140                       sudoers plugin is subsystem@priority but a plugin is
141                       free to use a different format so long as it does not
142                       include a comma (‘,’).  Prior to sudo 1.8.12, there was
143                       no way to specify plugin-specific debug_flags so the
144                       value was always the same as that used by the sudo
145                       front-end and did not include a path name, only the
146                       flags themselves.  As of version 1.7 of the plugin in‐
147                       terface, sudo will only pass debug_flags if
148                       sudo.conf(5) contains a plugin-specific Debug entry.
149
150                 ignore_ticket=bool
151                       Set to true if the user specified the -k option along
152                       with a command, indicating that the user wishes to ig‐
153                       nore any cached authentication credentials.
154                       implied_shell to true.  This allows sudo with no argu‐
155                       ments to be used similarly to su(1).  If the plugin
156                       does not to support this usage, it may return a value
157                       of -2 from the check_policy() function, which will
158                       cause sudo to print a usage message and exit.
159
160                 implied_shell=bool
161                       If the user does not specify a program on the command
162                       line, sudo will pass the plugin the path to the user's
163                       shell and set implied_shell.
164
165                 intercept_ptrace=bool
166                       Indicates whether or not the system supports intercept
167                       mode using ptrace(2).  This is currently only true for
168                       Linux systems that support seccomp(2) filtering and the
169                       “trap” action.  Other systems will use a dynamic shared
170                       object to implement intercept.  Only available starting
171                       with API version 1.19.
172
173                 intercept_setid=bool
174                       Indicates whether or not the system supports running
175                       set-user-ID and set-group-ID binaries in intercept
176                       mode.  This is currently only true for Linux systems
177                       that support seccomp(2) filtering and the “trap” ac‐
178                       tion.  On systems that use a dynamic shared object to
179                       implement intercept, the dynamic linker (ld.so or the
180                       equivalent) will disable preloading of shared objects
181                       when executing a set-user-ID or set-group-ID binary.
182                       This will disable intercept mode for that program and
183                       any other programs that it executes.  The policy plugin
184                       may refuse to execute a set-user-ID or set-group-ID bi‐
185                       nary in intercept mode to avoid this.  Only available
186                       starting with API version 1.19.
187
188                 login_class=string
189                       BSD login class to use when setting resource limits and
190                       nice value, if specified by the -c option.
191
192                 login_shell=bool
193                       Set to true if the user specified the -i option, indi‐
194                       cating that the user wishes to run a login shell.
195
196                 max_groups=int
197                       The maximum number of groups a user may belong to.
198                       This will only be present if there is a corresponding
199                       setting in sudo.conf(5).
200
201                 network_addrs=list
202                       A space-separated list of IP network addresses and net‐
203                       masks in the form “addr/netmask”, e.g.,
204                       “192.168.1.2/255.255.255.0”.  The address and netmask
205                       pairs may be either IPv4 or IPv6, depending on what the
206                       operating system supports.  If the address contains a
207                       colon (‘:’), it is an IPv6 address, else it is IPv4.
208
209                 noninteractive=bool
210                       Set to true if the user specified the -n option, indi‐
211                       cating that sudo should operate in non-interactive
212                       mode.  The plugin may reject a command run in non-in‐
213                       teractive mode if user interaction is required.
214
215                 plugin_dir=string
216                       The default plugin directory used by the sudo front-
217                       end.  This is the default directory set at compile time
218                       and may not correspond to the directory the running
219                       plugin was loaded from.  It may be used by a plugin to
220                       locate support files.
221
222                 plugin_path=string
223                       The path name of plugin loaded by the sudo front-end.
224                       The path name will be a fully-qualified unless the
225                       plugin was statically compiled into sudo.
226
227                 preserve_environment=bool
228                       Set to true if the user specified the -E option, indi‐
229                       cating that the user wishes to preserve the environ‐
230                       ment.
231
232                 preserve_groups=bool
233                       Set to true if the user specified the -P option, indi‐
234                       cating that the user wishes to preserve the group vec‐
235                       tor instead of setting it based on the runas user.
236
237                 progname=string
238                       The command name that sudo was run as, typically “sudo”
239                       or “sudoedit”.
240
241                 prompt=string
242                       The prompt to use when requesting a password, if speci‐
243                       fied via the -p option.
244
245                 remote_host=string
246                       The name of the remote host to run the command on, if
247                       specified via the -h option.  Support for running the
248                       command on a remote host is meant to be implemented via
249                       a helper program that is executed in place of the user-
250                       specified command.  The sudo front-end is only capable
251                       of executing commands on the local host.  Only avail‐
252                       able starting with API version 1.4.
253
254                 run_shell=bool
255                       Set to true if the user specified the -s option, indi‐
256                       cating that the user wishes to run a shell.
257
258                 runas_group=string
259                       The group name or group-ID to run the command as, if
260                       specified via the -g option.
261
262                 runas_user=string
263                       The user name or user-ID to run the command as, if
264                       specified via the -u option.
265
266                 selinux_role=string
267                       SELinux role to use when executing the command, if
268                       specified by the -r option.
269
270                 selinux_type=string
271                       SELinux type to use when executing the command, if
272                       specified by the -t option.
273
274                 set_home=bool
275                       Set to true if the user specified the -H option.  If
276                       true, set the HOME environment variable to the target
277                       user's home directory.
278
279                 sudoedit=bool
280                       Set to true when the -e option is specified or if in‐
281                       voked as sudoedit.  The plugin shall substitute an edi‐
282                       tor into argv in the check_policy() function or return
283                       -2 with a usage error if the plugin does not support
284                       sudoedit.  For more information, see the check_policy()
285                       section.
286
287                 timeout=string
288                       Command timeout specified by the user via the -T op‐
289                       tion.  Not all plugins support command timeouts and the
290                       ability of the user to set a timeout may be restricted
291                       by policy.  The format of the timeout string is plugin-
292                       specific.
293
294                 update_ticket=bool
295                       Set to false if the user specified the -N option, indi‐
296                       cating that the user wishes to avoid updating any
297                       cached authentication credentials.  Only available
298                       starting with API version 1.20.
299
300                 Additional settings may be added in the future so the plugin
301                 should silently ignore settings that it does not recognize.
302
303           user_info
304                 A vector of information about the user running the command in
305                 the form of “name=value” strings.  The vector is terminated
306                 by a NULL pointer.
307
308                 When parsing user_info, the plugin should split on the first
309                 equal sign (‘=’) since the name field will never include one
310                 itself but the value might.
311
312                 The following values may be set by sudo:
313
314                 cols=int
315                       The number of columns the user's terminal supports.  If
316                       there is no terminal device available, a default value
317                       of 80 is used.
318
319                 cwd=string
320                       The user's current working directory.
321
322                 egid=gid_t
323                       The effective group-ID of the user invoking sudo.
324
325                 euid=uid_t
326                       The effective user-ID of the user invoking sudo.
327
328                 gid=gid_t
329                       The real group-ID of the user invoking sudo.
330
331                 groups=list
332                       The user's supplementary group list formatted as a
333                       string of comma-separated group-IDs.
334
335                 host=string
336                       The local machine's hostname as returned by the
337                       gethostname(2) system call.
338
339                 lines=int
340                       The number of lines the user's terminal supports.  If
341                       there is no terminal device available, a default value
342                       of 24 is used.
343
344                 pgid=int
345                       The ID of the process group that the running sudo
346                       process is a member of.  Only available starting with
347                       API version 1.2.
348
349                 pid=int
350                       The process ID of the running sudo process.  Only
351                       available starting with API version 1.2.
352
353                 ppid=int
354                       The parent process ID of the running sudo process.
355                       Only available starting with API version 1.2.
356
357                 rlimit_as=soft,hard
358                       The maximum size to which the process's address space
359                       may grow (in bytes), if supported by the operating sys‐
360                       tem.  The soft and hard limits are separated by a
361                       comma.  A value of “infinity” indicates that there is
362                       no limit.  Only available starting with API version
363                       1.16.
364
365                 rlimit_core=soft,hard
366                       The largest size core dump file that may be created (in
367                       bytes).  The soft and hard limits are separated by a
368                       comma.  A value of “infinity” indicates that there is
369                       no limit.  Only available starting with API version
370                       1.16.
371
372                 rlimit_cpu=soft,hard
373                       The maximum amount of CPU time that the process may use
374                       (in seconds).  The soft and hard limits are separated
375                       by a comma.  A value of “infinity” indicates that there
376                       is no limit.  Only available starting with API version
377                       1.16.
378
379                 rlimit_data=soft,hard
380                       The maximum size of the data segment for the process
381                       (in bytes).  The soft and hard limits are separated by
382                       a comma.  A value of “infinity” indicates that there is
383                       no limit.  Only available starting with API version
384                       1.16.
385
386                 rlimit_fsize=soft,hard
387                       The largest size file that the process may create (in
388                       bytes).  The soft and hard limits are separated by a
389                       comma.  A value of “infinity” indicates that there is
390                       no limit.  Only available starting with API version
391                       1.16.
392
393                 rlimit_locks=soft,hard
394                       The maximum number of locks that the process may estab‐
395                       lish, if supported by the operating system.  The soft
396                       and hard limits are separated by a comma.  A value of
397                       “infinity” indicates that there is no limit.  Only
398                       available starting with API version 1.16.
399
400                 rlimit_memlock=soft,hard
401                       The maximum size that the process may lock in memory
402                       (in bytes), if supported by the operating system.  The
403                       soft and hard limits are separated by a comma.  A value
404                       of “infinity” indicates that there is no limit.  Only
405                       available starting with API version 1.16.
406
407                 rlimit_nofile=soft,hard
408                       The maximum number of files that the process may have
409                       open.  The soft and hard limits are separated by a
410                       comma.  A value of “infinity” indicates that there is
411                       no limit.  Only available starting with API version
412                       1.16.
413
414                 rlimit_nproc=soft,hard
415                       The maximum number of processes that the user may run
416                       simultaneously.  The soft and hard limits are separated
417                       by a comma.  A value of “infinity” indicates that there
418                       is no limit.  Only available starting with API version
419                       1.16.
420
421                 rlimit_rss=soft,hard
422                       The maximum size to which the process's resident set
423                       size may grow (in bytes).  The soft and hard limits are
424                       separated by a comma.  A value of “infinity” indicates
425                       that there is no limit.  Only available starting with
426                       API version 1.16.
427
428                 rlimit_stack=soft,hard
429                       The maximum size to which the process's stack may grow
430                       (in bytes).  The soft and hard limits are separated by
431                       a comma.  A value of “infinity” indicates that there is
432                       no limit.  Only available starting with API version
433                       1.16.
434
435                 sid=int
436                       The session ID of the running sudo process or 0 if sudo
437                       is not part of a POSIX job control session.  Only
438                       available starting with API version 1.2.
439
440                 tcpgid=int
441                       The ID of the foreground process group associated with
442                       the terminal device associated with the sudo process or
443                       0 if there is no terminal present.  Only available
444                       starting with API version 1.2.
445
446                 tty=string
447                       The path to the user's terminal device.  If the user
448                       has no terminal device associated with the session, the
449                       value will be empty, as in ‘tty=’.
450
451                 uid=uid_t
452                       The real user-ID of the user invoking sudo.
453
454                 umask=octal
455                       The invoking user's file creation mask.  Only available
456                       starting with API version 1.10.
457
458                 user=string
459                       The name of the user invoking sudo.
460
461           user_env
462                 The user's environment in the form of a NULL-terminated
463                 vector of “name=value” strings.
464
465                 When parsing user_env, the plugin should split on the first
466                 equal sign (‘=’) since the name field will never include one
467                 itself but the value might.
468
469           plugin_options
470                 Any (non-comment) strings immediately after the plugin path
471                 are passed as arguments to the plugin.  These arguments are
472                 split on a white space boundary and are passed to the plugin
473                 in the form of a NULL-terminated array of strings.  If no ar‐
474                 guments were specified, plugin_options will be the NULL
475                 pointer.
476
477                 The plugin_options parameter is only available starting with
478                 API version 1.2.  A plugin must check the API version speci‐
479                 fied by the sudo front-end before using plugin_options.
480                 Failure to do so may result in a crash.
481
482           errstr
483                 If the open() function returns a value other than 1, the
484                 plugin may store a message describing the failure or error in
485                 errstr.  The sudo front-end will then pass this value to any
486                 registered audit plugins.  The string stored in errstr must
487                 remain valid until the plugin's close() function is called.
488
489                 The errstr parameter is only available starting with API ver‐
490                 sion 1.15.  A plugin must check the API version specified by
491                 the sudo front-end before using errstr.  Failure to do so may
492                 result in a crash.
493
494     close
495           void (*close)(int exit_status, int error);
496
497           The close() function is called when sudo is finished, shortly be‐
498           fore it exits.  Starting with API version 1.15, close() is called
499           regardless of whether or not a command was actually executed.  This
500           makes it possible for plugins to perform cleanup even when a com‐
501           mand was not run.  It is not possible to tell whether a command was
502           run based solely on the arguments passed to the close() function.
503           To determine if a command was actually run, the plugin must keep
504           track of whether or not the check_policy() function returned suc‐
505           cessfully.
506
507           The function arguments are as follows:
508
509           exit_status
510                 The command's exit status, as returned by the wait(2) system
511                 call, or zero if no command was run.  The value of
512                 exit_status is undefined if error is non-zero.
513
514           error
515                 If the command could not be executed, this is set to the
516                 value of errno set by the execve(2) system call.  The plugin
517                 is responsible for displaying error information via the
518                 conversation() or sudo_plugin_printf() function.  If the com‐
519                 mand was successfully executed, the value of error is zero.
520
521           If no close() function is defined, no I/O logging plugins are
522           loaded, and neither the timeout nor use_pty options are set in the
523           command_info list, the sudo front-end may execute the command di‐
524           rectly instead of running it as a child process.
525
526     show_version
527           int (*show_version)(int verbose);
528
529           The show_version() function is called by sudo when the user speci‐
530           fies the -V option.  The plugin may display its version information
531           to the user via the conversation() or sudo_plugin_printf() function
532           using SUDO_CONV_INFO_MSG.  If the user requests detailed version
533           information, the verbose flag will be non-zero.
534
535           Returns 1 on success, 0 on failure, -1 if a general error occurred,
536           or -2 if there was a usage error, although the return value is cur‐
537           rently ignored.
538
539     check_policy
540           int (*check_policy)(int argc, char * const argv[], char *env_add[],
541               char **command_info[], char **argv_out[], char **user_env_out[],
542               const char **errstr);
543
544           The check_policy() function is called by sudo to determine whether
545           the user is allowed to run the specified commands.
546
547           If the sudoedit option was enabled in the settings array passed to
548           the open() function, the user has requested sudoedit mode.
549           sudoedit is a mechanism for editing one or more files where an edi‐
550           tor is run with the user's credentials instead of with elevated
551           privileges.  sudo achieves this by creating user-writable temporary
552           copies of the files to be edited and then overwriting the originals
553           with the temporary copies after editing is complete.  If the plugin
554           supports sudoedit, it must set sudoedit=true in the command_info
555           list.  The plugin is responsible for choosing the editor to be
556           used, potentially from a variable in the user's environment, such
557           as EDITOR, and should be stored in argv_out (environment variables
558           may include command line options).  The files to be edited should
559           be copied from argv to argv_out, separated from the editor and its
560           arguments by a ‘--’ element.  The ‘--’ will be removed by sudo be‐
561           fore the editor is executed.  The plugin may also set
562           sudoedit_nfiles to the number of files to be edited in the
563           command_info list; this will only be used by the sudo front-end
564           starting with API version 1.21.
565
566           The check_policy() function returns 1 if the command is allowed, 0
567           if not allowed, -1 for a general error, or -2 for a usage error or
568           if sudoedit was specified but is unsupported by the plugin.  In the
569           latter case, sudo will print a usage message before it exits.  If
570           an error occurs, the plugin may optionally call the conversation()
571           or sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to
572           present additional error information to the user.
573
574           The function arguments are as follows:
575
576           argc  The number of elements in argv, not counting the final NULL
577                 pointer.
578
579           argv  The argument vector describing the command the user wishes to
580                 run, in the same form as what would be passed to the
581                 execve(2) system call.  The vector is terminated by a NULL
582                 pointer.
583
584           env_add
585                 Additional environment variables specified by the user on the
586                 command line in the form of a NULL-terminated vector of
587                 “name=value” strings.  The plugin may reject the command if
588                 one or more variables are not allowed to be set, or it may
589                 silently ignore such variables.
590
591                 When parsing env_add, the plugin should split on the first
592                 equal sign (‘=’) since the name field will never include one
593                 itself but the value might.
594
595           command_info
596                 Information about the command being run in the form of
597                 “name=value” strings.  These values are used by sudo to set
598                 the execution environment when running a command.  The plugin
599                 is responsible for creating and populating the vector, which
600                 must be terminated with a NULL pointer.  The following values
601                 are recognized by sudo:
602
603                 apparmor_profile=string
604                       AppArmor profile to transition to when executing the
605                       command.  Only available starting with API version
606                       1.19.
607
608                 chroot=string
609                       The root directory to use when running the command.
610
611                 closefrom=number
612                       If specified, sudo will close all files descriptors
613                       with a value of number or higher.
614
615                 command=string
616                       Fully qualified path to the command to be executed.
617
618                 cwd=string
619                       The current working directory to change to when execut‐
620                       ing the command.  If sudo is unable to change to the
621                       new working directory, the command will not be run un‐
622                       less cwd_optional is also set (see below).
623
624                 cwd_optional=bool
625                       If set, sudo will treat an inability to change to the
626                       new working directory as a non-fatal error.  This set‐
627                       ting has no effect unless cwd is also set.
628
629                 exec_background=bool
630                       By default, sudo runs a command as the foreground
631                       process as long as sudo itself is running in the fore‐
632                       ground.  When exec_background is enabled and the com‐
633                       mand is being run in a pseudo-terminal (due to I/O log‐
634                       ging or the use_pty setting), the command will be run
635                       as a background process.  Attempts to read from the
636                       controlling terminal (or to change terminal settings)
637                       will result in the command being suspended with the
638                       SIGTTIN signal (or SIGTTOU in the case of terminal set‐
639                       tings).  If this happens when sudo is a foreground
640                       process, the command will be granted the controlling
641                       terminal and resumed in the foreground with no user in‐
642                       tervention required.  The advantage of initially run‐
643                       ning the command in the background is that sudo need
644                       not read from the terminal unless the command explic‐
645                       itly requests it.  Otherwise, any terminal input must
646                       be passed to the command, whether it has required it or
647                       not (the kernel buffers terminals so it is not possible
648                       to tell whether the command really wants the input).
649                       This is different from historic sudo behavior or when
650                       the command is not being run in a pseudo-terminal.
651
652                       For this to work seamlessly, the operating system must
653                       support the automatic restarting of system calls.  Un‐
654                       fortunately, not all operating systems do this by de‐
655                       fault, and even those that do may have bugs.  For exam‐
656                       ple, macOS fails to restart the tcgetattr() and
657                       tcsetattr() system calls (this is a bug in macOS).
658                       Furthermore, because this behavior depends on the com‐
659                       mand stopping with the SIGTTIN or SIGTTOU signals, pro‐
660                       grams that catch these signals and suspend themselves
661                       with a different signal (usually SIGTOP) will not be
662                       automatically foregrounded.  Some versions of the linux
663                       su(1) command behave this way.  Because of this, a
664                       plugin should not set exec_background unless it is ex‐
665                       plicitly enabled by the administrator and there should
666                       be a way to enabled or disable it on a per-command ba‐
667                       sis.
668
669                       This setting has no effect unless I/O logging is en‐
670                       abled or use_pty is enabled.
671
672                 execfd=number
673                       If specified, sudo will use the fexecve(2) system call
674                       to execute the command instead of execve(2).  The spec‐
675                       ified number must refer to an open file descriptor.
676
677                 intercept=bool
678                       If set, sudo will intercept attempts to execute a sub‐
679                       sequent command and perform a policy check via the pol‐
680                       icy plugin's check_policy() function to determine
681                       whether or not the command is permitted.  This can be
682                       used to prevent shell escapes on supported platforms
683                       but it has a number of limitations.  See Preventing
684                       shell escapes in sudoers(5) for details.  Only avail‐
685                       able starting with API version 1.18.
686
687                 intercept_verify=bool
688                       If set, sudo will attempt to verify that a command run
689                       in intercept mode has the expected path name, command
690                       line arguments and environment.  This setting has no
691                       effect unless use_ptrace is also enabled.  Only avail‐
692                       able starting with API version 1.20.
693
694                 iolog_compress=bool
695                       Set to true if the I/O logging plugins, if any, should
696                       compress the log data.  This is a hint to the I/O log‐
697                       ging plugin which may choose to ignore it.
698
699                 iolog_group=string
700                       The group that will own newly created I/O log files and
701                       directories.  This is a hint to the I/O logging plugin
702                       which may choose to ignore it.
703
704                 iolog_mode=octal
705                       The file permission mode to use when creating I/O log
706                       files and directories.  This is a hint to the I/O log‐
707                       ging plugin which may choose to ignore it.
708
709                 iolog_user=string
710                       The user that will own newly created I/O log files and
711                       directories.  This is a hint to the I/O logging plugin
712                       which may choose to ignore it.
713
714                 iolog_path=string
715                       Fully qualified path to the file or directory in which
716                       I/O log is to be stored.  This is a hint to the I/O
717                       logging plugin which may choose to ignore it.  If no
718                       I/O logging plugin is loaded, this setting has no ef‐
719                       fect.
720
721                 iolog_stdin=bool
722                       Set to true if the I/O logging plugins, if any, should
723                       log the standard input if it is not connected to a ter‐
724                       minal device.  This is a hint to the I/O logging plugin
725                       which may choose to ignore it.
726
727                 iolog_stdout=bool
728                       Set to true if the I/O logging plugins, if any, should
729                       log the standard output if it is not connected to a
730                       terminal device.  This is a hint to the I/O logging
731                       plugin which may choose to ignore it.
732
733                 iolog_stderr=bool
734                       Set to true if the I/O logging plugins, if any, should
735                       log the standard error if it is not connected to a ter‐
736                       minal device.  This is a hint to the I/O logging plugin
737                       which may choose to ignore it.
738
739                 iolog_ttyin=bool
740                       Set to true if the I/O logging plugins, if any, should
741                       log all terminal input.  This only includes input typed
742                       by the user and not from a pipe or redirected from a
743                       file.  This is a hint to the I/O logging plugin which
744                       may choose to ignore it.
745
746                 iolog_ttyout=bool
747                       Set to true if the I/O logging plugins, if any, should
748                       log all terminal output.  This only includes output to
749                       the screen, not output to a pipe or file.  This is a
750                       hint to the I/O logging plugin which may choose to ig‐
751                       nore it.
752
753                 login_class=string
754                       BSD login class to use when setting resource limits and
755                       nice value (optional).  This option is only set on sys‐
756                       tems that support login classes.
757
758                 nice=int
759                       Nice value (priority) to use when executing the com‐
760                       mand.  The nice value, if specified, overrides the pri‐
761                       ority associated with the login_class on BSD systems.
762
763                 log_subcmds=bool
764                       If set, sudo will call the audit plugin's accept()
765                       function to log when the command runs a subsequent com‐
766                       mand, if supported by the system.  If intercept is also
767                       specified, log_subcmds will be ignored.  See Preventing
768                       shell escapes in sudoers(5) for more information.  Only
769                       available starting with API version 1.18.
770
771                 noexec=bool
772                       If set, prevent the command from executing other pro‐
773                       grams.
774
775                 preserve_fds=list
776                       A comma-separated list of file descriptors that should
777                       be preserved, regardless of the value of the closefrom
778                       setting.  Only available starting with API version 1.5.
779
780                 preserve_groups=bool
781                       If set, sudo will preserve the user's group vector in‐
782                       stead of initializing the group vector based on
783                       runas_user.
784
785                 rlimit_as=soft,hard
786                       The maximum size to which the process's address space
787                       may grow (in bytes), if supported by the operating sys‐
788                       tem.  The soft and hard limits are separated by a
789                       comma.  If only a single value is specified, both the
790                       hard and soft limits are set.  A value of “infinity”
791                       indicates that there is no limit.  A value of “user”
792                       will cause the invoking user's resource limit to be
793                       preserved.  A value of “default” will cause the target
794                       user's default resource limit to be used on systems
795                       that allow per-user resource limits to be configured.
796                       Only available starting with API version 1.18.
797
798                 rlimit_core=soft,hard
799                       The largest size core dump file that may be created (in
800                       bytes).  The soft and hard limits are separated by a
801                       comma.  If only a single value is specified, both the
802                       hard and soft limits are set.  A value of “infinity”
803                       indicates that there is no limit.  A value of “user”
804                       will cause the invoking user's resource limit to be
805                       preserved.  A value of “default” will cause the target
806                       user's default resource limit to be used on systems
807                       that allow per-user resource limits to be configured.
808                       Only available starting with API version 1.18.
809
810                 rlimit_cpu=soft,hard
811                       The maximum amount of CPU time that the process may use
812                       (in seconds).  The soft and hard limits are separated
813                       by a comma.  If only a single value is specified, both
814                       the hard and soft limits are set.  A value of
815                       “infinity” indicates that there is no limit.  A value
816                       of “user” will cause the invoking user's resource limit
817                       to be preserved.  A value of “default” will cause the
818                       target user's default resource limit to be used on sys‐
819                       tems that allow per-user resource limits to be config‐
820                       ured.  Only available starting with API version 1.18.
821
822                 rlimit_data=soft,hard
823                       The maximum size of the data segment for the process
824                       (in bytes).  The soft and hard limits are separated by
825                       a comma.  If only a single value is specified, both the
826                       hard and soft limits are set.  A value of “infinity”
827                       indicates that there is no limit.  A value of “user”
828                       will cause the invoking user's resource limit to be
829                       preserved.  A value of “default” will cause the target
830                       user's default resource limit to be used on systems
831                       that allow per-user resource limits to be configured.
832                       Only available starting with API version 1.18.
833
834                 rlimit_fsize=soft,hard
835                       The largest size file that the process may create (in
836                       bytes).  The soft and hard limits are separated by a
837                       comma.  If only a single value is specified, both the
838                       hard and soft limits are set.  A value of “infinity”
839                       indicates that there is no limit.  A value of “user”
840                       will cause the invoking user's resource limit to be
841                       preserved.  A value of “default” will cause the target
842                       user's default resource limit to be used on systems
843                       that allow per-user resource limits to be configured.
844                       Only available starting with API version 1.18.
845
846                 rlimit_locks=soft,hard
847                       The maximum number of locks that the process may estab‐
848                       lish, if supported by the operating system.  The soft
849                       and hard limits are separated by a comma.  If only a
850                       single value is specified, both the hard and soft lim‐
851                       its are set.  A value of “infinity” indicates that
852                       there is no limit.  A value of “user” will cause the
853                       invoking user's resource limit to be preserved.  A
854                       value of “default” will cause the target user's default
855                       resource limit to be used on systems that allow per-
856                       user resource limits to be configured.  Only available
857                       starting with API version 1.18.
858
859                 rlimit_memlock=soft,hard
860                       The maximum size that the process may lock in memory
861                       (in bytes), if supported by the operating system.  The
862                       soft and hard limits are separated by a comma.  If only
863                       a single value is specified, both the hard and soft
864                       limits are set.  A value of “infinity” indicates that
865                       there is no limit.  A value of “user” will cause the
866                       invoking user's resource limit to be preserved.  A
867                       value of “default” will cause the target user's default
868                       resource limit to be used on systems that allow per-
869                       user resource limits to be configured.  Only available
870                       starting with API version 1.18.
871
872                 rlimit_nofile=soft,hard
873                       The maximum number of files that the process may have
874                       open.  The soft and hard limits are separated by a
875                       comma.  If only a single value is specified, both the
876                       hard and soft limits are set.  A value of “infinity”
877                       indicates that there is no limit.  A value of “user”
878                       will cause the invoking user's resource limit to be
879                       preserved.  A value of “default” will cause the target
880                       user's default resource limit to be used on systems
881                       that allow per-user resource limits to be configured.
882                       Only available starting with API version 1.18.
883
884                 rlimit_nproc=soft,hard
885                       The maximum number of processes that the user may run
886                       simultaneously.  The soft and hard limits are separated
887                       by a comma.  If only a single value is specified, both
888                       the hard and soft limits are set.  A value of
889                       “infinity” indicates that there is no limit.  A value
890                       of “user” will cause the invoking user's resource limit
891                       to be preserved.  A value of “default” will cause the
892                       target user's default resource limit to be used on sys‐
893                       tems that allow per-user resource limits to be config‐
894                       ured.  Only available starting with API version 1.18.
895
896                 rlimit_rss=soft,hard
897                       The maximum size to which the process's resident set
898                       size may grow (in bytes).  The soft and hard limits are
899                       separated by a comma.  If only a single value is speci‐
900                       fied, both the hard and soft limits are set.  A value
901                       of “infinity” indicates that there is no limit.  A
902                       value of “user” will cause the invoking user's resource
903                       limit to be preserved.  A value of “default” will cause
904                       the target user's default resource limit to be used on
905                       systems that allow per-user resource limits to be con‐
906                       figured.  Only available starting with API version
907                       1.18.
908
909                 rlimit_stack=soft,hard
910                       The maximum size to which the process's stack may grow
911                       (in bytes).  The soft and hard limits are separated by
912                       a comma.  If only a single value is specified, both the
913                       hard and soft limits are set.  A value of “infinity”
914                       indicates that there is no limit.  A value of “user”
915                       will cause the invoking user's resource limit to be
916                       preserved.  A value of “default” will cause the target
917                       user's default resource limit to be used on systems
918                       that allow per-user resource limits to be configured.
919                       Only available starting with API version 1.18.
920
921                 runas_egid=gid
922                       Effective group-ID to run the command as.  If not spec‐
923                       ified, the value of runas_gid is used.
924
925                 runas_euid=uid
926                       Effective user-ID to run the command as.  If not speci‐
927                       fied, the value of runas_uid is used.
928
929                 runas_gid=gid
930                       Group-ID to run the command as.
931
932                 runas_group=string
933                       The name of the group the command will run as, if it is
934                       different from the runas_user's default group.  This
935                       value is provided for auditing purposes only, the sudo
936                       front-end uses runas_egid and runas_gid when executing
937                       the command.
938
939                 runas_groups=list
940                       The supplementary group vector to use for the command
941                       in the form of a comma-separated list of group-IDs.  If
942                       preserve_groups is set, this option is ignored.
943
944                 runas_uid=uid
945                       User-ID to run the command as.
946
947                 runas_user=string
948                       The name of the user the command will run as, which
949                       should correspond to runas_euid (or runas_uid if
950                       runas_euid is not set).  This value is provided for au‐
951                       diting purposes only, the sudo front-end uses
952                       runas_euid and runas_uid when executing the command.
953
954                 selinux_role=string
955                       SELinux role to use when executing the command.
956
957                 selinux_type=string
958                       SELinux type to use when executing the command.
959
960                 set_utmp=bool
961                       Create a utmp (or utmpx) entry when a pseudo-terminal
962                       is allocated.  By default, the new entry will be a copy
963                       of the user's existing utmp entry (if any), with the
964                       tty, time, type, and pid fields updated.
965
966                 sudoedit=bool
967                       Set to true when in sudoedit mode.  The plugin may en‐
968                       able sudoedit mode even if sudo was not invoked as
969                       sudoedit.  This allows the plugin to perform command
970                       substitution and transparently enable sudoedit when the
971                       user attempts to run an editor.
972
973                 sudoedit_checkdir=bool
974                       Set to false to disable directory writability checks in
975                       sudoedit.  By default, sudoedit 1.8.16 and higher will
976                       check all directory components of the path to be edited
977                       for writability by the invoking user.  Symbolic links
978                       will not be followed in writable directories and
979                       sudoedit will refuse to edit a file located in a
980                       writable directory.  These restrictions are not en‐
981                       forced when sudoedit is run by root.  The
982                       sudoedit_checkdir option can be set to false to disable
983                       this check.  Only available starting with API version
984                       1.8.
985
986                 sudoedit_follow=bool
987                       Set to true to allow sudoedit to edit files that are
988                       symbolic links.  By default, sudoedit 1.8.15 and higher
989                       will refuse to open a symbolic link.  The
990                       sudoedit_follow option can be used to restore the older
991                       behavior and allow sudoedit to open symbolic links.
992                       Only available starting with API version 1.8.
993
994                 sudoedit_nfiles=number
995                       The number of files to be edited by the user.  If
996                       present, this is will be used by the sudo front-end to
997                       determine which elements of the argv_out vector are
998                       files to be edited.  The ‘--’ element must immediately
999                       precede the first file to be editied.  If
1000                       sudoedit_nfiles is not specified, the sudo front-end
1001                       will use the position of the ‘--’ element to determine
1002                       where the file list begins.  Only available starting
1003                       with API version 1.21.
1004
1005                 timeout=int
1006                       Command timeout.  If non-zero then when the timeout ex‐
1007                       pires the command will be killed.
1008
1009                 umask=octal
1010                       The file creation mask to use when executing the com‐
1011                       mand.  This value may be overridden by PAM or lo‐
1012                       gin.conf on some systems unless the umask_override op‐
1013                       tion is also set.
1014
1015                 umask_override=bool
1016                       Force the value specified by the umask option to over‐
1017                       ride any umask set by PAM or login.conf.
1018
1019                 use_ptrace=bool
1020                       If set, sudo will use ptrace(2) to implement intercept
1021                       mode if supported by the system.  This setting has no
1022                       effect unless intercept is also set.  Only available
1023                       starting with API version 1.19.
1024
1025                 use_pty=bool
1026                       Allocate a pseudo-terminal to run the command in, re‐
1027                       gardless of whether or not I/O logging is in use.  By
1028                       default, sudo will only run the command in a pseudo-
1029                       terminal when an I/O log plugin is loaded.
1030
1031                 utmp_user=string
1032                       User name to use when constructing a new utmp (or
1033                       utmpx) entry when set_utmp is enabled.  This option can
1034                       be used to set the user field in the utmp entry to the
1035                       user the command runs as rather than the invoking user.
1036                       If not set, sudo will base the new entry on the invok‐
1037                       ing user's existing entry.
1038
1039                 Unsupported values will be ignored.
1040
1041           argv_out
1042                 The NULL-terminated argument vector to pass to the execve(2)
1043                 system call when executing the command.  The plugin is re‐
1044                 sponsible for allocating and populating the vector.
1045
1046           user_env_out
1047                 The NULL-terminated environment vector to use when executing
1048                 the command.  The plugin is responsible for allocating and
1049                 populating the vector.
1050
1051           errstr
1052                 If the check_policy() function returns a value other than 1,
1053                 the plugin may store a message describing the failure or er‐
1054                 ror in errstr.  The sudo front-end will then pass this value
1055                 to any registered audit plugins.  The string stored in errstr
1056                 must remain valid until the plugin's close() function is
1057                 called.
1058
1059                 The errstr parameter is only available starting with API ver‐
1060                 sion 1.15.  A plugin must check the API version specified by
1061                 the sudo front-end before using errstr.  Failure to do so may
1062                 result in a crash.
1063
1064     list
1065           int (*list)(int argc, char * const argv[], int verbose,
1066               const char *user, const char **errstr);
1067
1068           List available privileges for the invoking user.  Returns 1 on suc‐
1069           cess, 0 on failure, and -1 on error.  On error, the plugin may op‐
1070           tionally call the conversation() or sudo_plugin_printf() function
1071           with SUDO_CONF_ERROR_MSG to present additional error information to
1072           the user.
1073
1074           Privileges should be output via the conversation() or
1075           sudo_plugin_printf() function using SUDO_CONV_INFO_MSG.
1076
1077           The function arguments are as follows:
1078
1079           argc  The number of elements in argv, not counting the final NULL
1080                 pointer.
1081
1082           argv  If non-NULL, an argument vector describing a command the user
1083                 wishes to check against the policy in the same form as what
1084                 would be passed to the execve(2) system call.  If the command
1085                 is permitted by the policy, the fully-qualified path to the
1086                 command should be displayed along with any command line argu‐
1087                 ments.
1088
1089           verbose
1090                 Flag indicating whether to list in verbose mode or not.
1091
1092           user  The name of a different user to list privileges for if the
1093                 policy allows it.  If NULL, the plugin should list the privi‐
1094                 leges of the invoking user.
1095
1096           errstr
1097                 If the list() function returns a value other than 1, the
1098                 plugin may store a message describing the failure or error in
1099                 errstr.  The sudo front-end will then pass this value to any
1100                 registered audit plugins.  The string stored in errstr must
1101                 remain valid until the plugin's close() function is called.
1102
1103                 The errstr parameter is only available starting with API ver‐
1104                 sion 1.15.  A plugin must check the API version specified by
1105                 the sudo front-end before using errstr.  Failure to do so may
1106                 result in a crash.
1107
1108     validate
1109           int (*validate)(const char **errstr);
1110
1111           The validate() function is called when sudo is run with the -v op‐
1112           tion.  For policy plugins such as sudoers that cache authentication
1113           credentials, this function will validate and cache the credentials.
1114
1115           The validate() function should be NULL if the plugin does not sup‐
1116           port credential caching.
1117
1118           Returns 1 on success, 0 on failure, and -1 on error.  On error, the
1119           plugin may optionally call the conversation() or
1120           sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1121           additional error information to the user.
1122
1123           The function arguments are as follows:
1124
1125           errstr
1126                 If the validate() function returns a value other than 1, the
1127                 plugin may store a message describing the failure or error in
1128                 errstr.  The sudo front-end will then pass this value to any
1129                 registered audit plugins.  The string stored in errstr must
1130                 remain valid until the plugin's close() function is called.
1131
1132                 The errstr parameter is only available starting with API ver‐
1133                 sion 1.15.  A plugin must check the API version specified by
1134                 the sudo front-end before using errstr.  Failure to do so may
1135                 result in a crash.
1136
1137     invalidate
1138           void (*invalidate)(int rmcred);
1139
1140           The invalidate() function is called when sudo is run with the -k or
1141           -K option.  For policy plugins such as sudoers that cache authenti‐
1142           cation credentials, this function will invalidate the credentials.
1143           If the rmcred flag is non-zero, the plugin may remove the creden‐
1144           tials instead of simply invalidating them.
1145
1146           The invalidate() function should be NULL if the plugin does not
1147           support credential caching.
1148
1149     init_session
1150           int (*init_session)(struct passwd *pwd, char **user_env[],
1151               const char **errstr);
1152
1153           The init_session() function is called before sudo sets up the exe‐
1154           cution environment for the command.  It is run in the parent sudo
1155           process before any user-ID or group-ID changes.  This can be used
1156           to perform session setup that is not supported by command_info,
1157           such as opening the PAM session.  The close() function can be used
1158           to tear down the session that was opened by init_session().
1159
1160           Returns 1 on success, 0 on failure, and -1 on error.  On error, the
1161           plugin may optionally call the conversation() or
1162           sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1163           additional error information to the user.
1164
1165           The function arguments are as follows:
1166
1167           pwd   If the user-ID the command will run as was found in the pass‐
1168                 word database, pwd will describe that user, otherwise it will
1169                 be NULL.
1170
1171           user_env_out
1172                 The NULL-terminated environment vector to use when executing
1173                 the command.  This is the same string passed back to the
1174                 front-end via the Policy Plugin's user_env_out parameter.  If
1175                 the init_session() function needs to modify the user environ‐
1176                 ment, it should update the pointer stored in user_env_out.
1177                 The expected use case is to merge the contents of the PAM en‐
1178                 vironment (if any) with the contents of user_env_out.  The
1179                 user_env_out parameter is only available starting with API
1180                 version 1.2.  A plugin must check the API version specified
1181                 by the sudo front-end before using user_env_out.  Failure to
1182                 do so may result in a crash.
1183
1184           errstr
1185                 If the init_session() function returns a value other than 1,
1186                 the plugin may store a message describing the failure or er‐
1187                 ror in errstr.  The sudo front-end will then pass this value
1188                 to any registered audit plugins.  The string stored in errstr
1189                 must remain valid until the plugin's close() function is
1190                 called.
1191
1192                 The errstr parameter is only available starting with API ver‐
1193                 sion 1.15.  A plugin must check the API version specified by
1194                 the sudo front-end before using errstr.  Failure to do so may
1195                 result in a crash.
1196
1197     register_hooks
1198           void (*register_hooks)(int version,
1199              int (*register_hook)(struct sudo_hook *hook));
1200
1201           The register_hooks() function is called by the sudo front-end to
1202           register any hooks the plugin needs.  If the plugin does not sup‐
1203           port hooks, register_hooks should be set to the NULL pointer.
1204
1205           The version argument describes the version of the hooks API sup‐
1206           ported by the sudo front-end.
1207
1208           The register_hook() function should be used to register any sup‐
1209           ported hooks the plugin needs.  It returns 0 on success, 1 if the
1210           hook type is not supported, and -1 if the major version in struct
1211           sudo_hook does not match the front-end's major hook API version.
1212
1213           See the Hook function API section below for more information about
1214           hooks.
1215
1216           The register_hooks() function is only available starting with API
1217           version 1.2.  If the sudo front-end doesn't support API version 1.2
1218           or higher, register_hooks() will not be called.
1219
1220     deregister_hooks
1221           void (*deregister_hooks)(int version,
1222              int (*deregister_hook)(struct sudo_hook *hook));
1223
1224           The deregister_hooks() function is called by the sudo front-end to
1225           deregister any hooks the plugin has registered.  If the plugin does
1226           not support hooks, deregister_hooks should be set to the NULL
1227           pointer.
1228
1229           The version argument describes the version of the hooks API sup‐
1230           ported by the sudo front-end.
1231
1232           The deregister_hook() function should be used to deregister any
1233           hooks that were put in place by the register_hook() function.  If
1234           the plugin tries to deregister a hook that the front-end does not
1235           support, deregister_hook() will return an error.
1236
1237           See the Hook function API section below for more information about
1238           hooks.
1239
1240           The deregister_hooks() function is only available starting with API
1241           version 1.2.  If the sudo front-end doesn't support API version 1.2
1242           or higher, deregister_hooks() will not be called.
1243
1244     event_alloc
1245           struct sudo_plugin_event * (*event_alloc)(void);
1246
1247           The event_alloc() function is used to allocate a struct
1248           sudo_plugin_event which provides access to the main sudo event
1249           loop.  Unlike the other fields, the event_alloc pointer is filled
1250           in by the sudo front-end, not by the plugin.
1251
1252           See the Event API section below for more information about events.
1253
1254           The event_alloc() function is only available starting with API ver‐
1255           sion 1.15.  If the sudo front-end doesn't support API version 1.15
1256           or higher, event_alloc will not be set.
1257
1258     Policy Plugin Version Macros
1259
1260     /* Plugin API version major/minor. */
1261     #define SUDO_API_VERSION_MAJOR 1
1262     #define SUDO_API_VERSION_MINOR 13
1263     #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
1264     #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
1265                                                 SUDO_API_VERSION_MINOR)
1266
1267     /* Getters and setters for API version */
1268     #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1269     #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1270     #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
1271         *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1272     } while(0)
1273     #define SUDO_API_VERSION_SET_MINOR(vp, n) do { \
1274         *(vp) = (*(vp) & 0xffff0000) | (n); \
1275     } while(0)
1276
1277   I/O plugin API
1278     struct io_plugin {
1279     #define SUDO_IO_PLUGIN 2
1280         unsigned int type; /* always SUDO_IO_PLUGIN */
1281         unsigned int version; /* always SUDO_API_VERSION */
1282         int (*open)(unsigned int version, sudo_conv_t conversation,
1283             sudo_printf_t sudo_plugin_printf, char * const settings[],
1284             char * const user_info[], char * const command_info[],
1285             int argc, char * const argv[], char * const user_env[],
1286             char * const plugin_options[], const char **errstr);
1287         void (*close)(int exit_status, int error); /* wait status or error */
1288         int (*show_version)(int verbose);
1289         int (*log_ttyin)(const char *buf, unsigned int len,
1290             const char **errstr);
1291         int (*log_ttyout)(const char *buf, unsigned int len,
1292             const char **errstr);
1293         int (*log_stdin)(const char *buf, unsigned int len,
1294             const char **errstr);
1295         int (*log_stdout)(const char *buf, unsigned int len,
1296             const char **errstr);
1297         int (*log_stderr)(const char *buf, unsigned int len,
1298             const char **errstr);
1299         void (*register_hooks)(int version,
1300            int (*register_hook)(struct sudo_hook *hook));
1301         void (*deregister_hooks)(int version,
1302            int (*deregister_hook)(struct sudo_hook *hook));
1303         int (*change_winsize)(unsigned int lines, unsigned int cols,
1304             const char **errstr);
1305         int (*log_suspend)(int signo, const char **errstr);
1306         struct sudo_plugin_event * (*event_alloc)(void);
1307     };
1308
1309     When an I/O plugin is loaded, sudo runs the command in a pseudo-terminal.
1310     This makes it possible to log the input and output from the user's ses‐
1311     sion.  If any of the standard input, standard output, or standard error
1312     do not correspond to a tty, sudo will open a pipe to capture the I/O for
1313     logging before passing it on.
1314
1315     The log_ttyin() function receives the raw user input from the terminal
1316     device (this will include input even when echo is disabled, such as when
1317     a password is read).  The log_ttyout() function receives output from the
1318     pseudo-terminal that is suitable for replaying the user's session at a
1319     later time.  The log_stdin(), log_stdout(), and log_stderr() functions
1320     are only called if the standard input, standard output, or standard error
1321     respectively correspond to something other than a tty.
1322
1323     Any of the logging functions may be set to the NULL pointer if no logging
1324     is to be performed.  If the open function returns 0, no I/O will be sent
1325     to the plugin.
1326
1327     If a logging function returns an error (-1), the running command will be
1328     terminated and all of the plugin's logging functions will be disabled.
1329     Other I/O logging plugins will still receive any remaining input or out‐
1330     put that has not yet been processed.
1331
1332     If an input logging function rejects the data by returning 0, the command
1333     will be terminated and the data will not be passed to the command, though
1334     it will still be sent to any other I/O logging plugins.  If an output
1335     logging function rejects the data by returning 0, the command will be
1336     terminated and the data will not be written to the terminal, though it
1337     will still be sent to any other I/O logging plugins.
1338
1339     A struct audit_plugin has the following fields:
1340
1341     type  The type field should always be set to SUDO_IO_PLUGIN.
1342
1343     version
1344           The version field should be set to SUDO_API_VERSION.
1345
1346           This allows sudo to determine the API version the plugin was built
1347           against.
1348
1349     open
1350           int (*open)(unsigned int version, sudo_conv_t conversation,
1351               sudo_printf_t sudo_plugin_printf, char * const settings[],
1352               char * const user_info[], char * const command_info[],
1353               int argc, char * const argv[], char * const user_env[],
1354               char * const plugin_options[]);
1355
1356           The open() function is run before the log_ttyin(), log_ttyout(),
1357           log_stdin(), log_stdout(), log_stderr(), log_suspend(),
1358           change_winsize(), or show_version() functions are called.  It is
1359           only called if the version is being requested or if the policy
1360           plugin's check_policy() function has returned successfully.  It re‐
1361           turns 1 on success, 0 on failure, -1 if a general error occurred,
1362           or -2 if there was a usage error.  In the latter case, sudo will
1363           print a usage message before it exits.  If an error occurs, the
1364           plugin may optionally call the conversation() or
1365           sudo_plugin_printf() function with SUDO_CONF_ERROR_MSG to present
1366           additional error information to the user.
1367
1368           The function arguments are as follows:
1369
1370           version
1371                 The version passed in by sudo allows the plugin to determine
1372                 the major and minor version number of the plugin API sup‐
1373                 ported by sudo.
1374
1375           conversation
1376                 A pointer to the conversation() function that may be used by
1377                 the Fa(show_version) function to display version information
1378                 (see show_version() below).  The conversation() function may
1379                 also be used to display additional error message to the user.
1380                 The conversation() function returns 0 on success and -1 on
1381                 failure.
1382
1383           sudo_plugin_printf
1384                 A pointer to a printf()-style function that may be used by
1385                 the show_version() function to display version information
1386                 (see show_version below).  The sudo_plugin_printf() function
1387                 may also be used to display additional error message to the
1388                 user.  The sudo_plugin_printf() function returns number of
1389                 characters printed on success and -1 on failure.
1390
1391           settings
1392                 A vector of user-supplied sudo settings in the form of
1393                 “name=value” strings.  The vector is terminated by a NULL
1394                 pointer.  These settings correspond to options the user spec‐
1395                 ified when running sudo.  As such, they will only be present
1396                 when the corresponding option has been specified on the com‐
1397                 mand line.
1398
1399                 When parsing settings, the plugin should split on the first
1400                 equal sign (‘=’) since the name field will never include one
1401                 itself but the value might.
1402
1403                 See the Policy plugin API section for a list of all possible
1404                 settings.
1405
1406           user_info
1407                 A vector of information about the user running the command in
1408                 the form of “name=value” strings.  The vector is terminated
1409                 by a NULL pointer.
1410
1411                 When parsing user_info, the plugin should split on the first
1412                 equal sign (‘=’) since the name field will never include one
1413                 itself but the value might.
1414
1415                 See the Policy plugin API section for a list of all possible
1416                 strings.
1417
1418           command_info
1419                 A vector of information describing the command being run in
1420                 the form of “name=value” strings.  The vector is terminated
1421                 by a NULL pointer.
1422
1423                 When parsing command_info, the plugin should split on the
1424                 first equal sign (‘=’) since the name field will never in‐
1425                 clude one itself but the value might.
1426
1427                 See the Policy plugin API section for a list of all possible
1428                 strings.
1429
1430           argc  The number of elements in argv, not counting the final NULL
1431                 pointer.  It can be zero, such as when sudo is called with
1432                 the -V option.
1433
1434           argv  If non-NULL, an argument vector describing a command the user
1435                 wishes to run in the same form as what would be passed to the
1436                 execve(2) system call.
1437
1438           user_env
1439                 The user's environment in the form of a NULL-terminated vec‐
1440                 tor of “name=value” strings.
1441
1442                 When parsing user_env, the plugin should split on the first
1443                 equal sign (‘=’) since the name field will never include one
1444                 itself but the value might.
1445
1446           plugin_options
1447                 Any (non-comment) strings immediately after the plugin path
1448                 are treated as arguments to the plugin.  These arguments are
1449                 split on a white space boundary and are passed to the plugin
1450                 in the form of a NULL-terminated array of strings.  If no ar‐
1451                 guments were specified, plugin_options will be the NULL
1452                 pointer.
1453
1454                 The plugin_options parameter is only available starting with
1455                 API version 1.2.  A plugin must check the API version speci‐
1456                 fied by the sudo front-end before using plugin_options.
1457                 Failure to do so may result in a crash.
1458
1459           errstr
1460                 If the open() function returns a value other than 1, the
1461                 plugin may store a message describing the failure or error in
1462                 errstr.  The sudo front-end will then pass this value to any
1463                 registered audit plugins.  The string stored in errstr must
1464                 remain valid until the plugin's close() function is called.
1465
1466                 The errstr parameter is only available starting with API ver‐
1467                 sion 1.15.  A plugin must check the API version specified by
1468                 the sudo front-end before using errstr.  Failure to do so may
1469                 result in a crash.
1470
1471     close
1472           void (*close)(int exit_status, int error);
1473
1474           The close() function is called when sudo is finished, shortly be‐
1475           fore it exits.
1476
1477           The function arguments are as follows:
1478
1479           exit_status
1480                 The command's exit status, as returned by the wait(2) system
1481                 call, or zero if no command was run.  The value of
1482                 exit_status is undefined if error is non-zero.
1483
1484           error
1485                 If the command could not be executed, this is set to the
1486                 value of errno set by the execve(2) system call.  If the com‐
1487                 mand was successfully executed, the value of error is zero.
1488
1489     show_version
1490           int (*show_version)(int verbose);
1491
1492           The show_version() function is called by sudo when the user speci‐
1493           fies the -V option.  The plugin may display its version information
1494           to the user via the conversation() or sudo_plugin_printf() function
1495           using SUDO_CONV_INFO_MSG.  If the user requests detailed version
1496           information, the verbose flag will be non-zero.
1497
1498           Returns 1 on success, 0 on failure, -1 if a general error occurred,
1499           or -2 if there was a usage error, although the return value is cur‐
1500           rently ignored.
1501
1502     log_ttyin
1503           int (*log_ttyin)(const char *buf, unsigned int len,
1504               const char **errstr);
1505
1506           The log_ttyin() function is called whenever data can be read from
1507           the user but before it is passed to the running command.  This al‐
1508           lows the plugin to reject data if it chooses to (for instance if
1509           the input contains banned content).  Returns 1 if the data should
1510           be passed to the command, 0 if the data is rejected (which will
1511           terminate the running command), or -1 if an error occurred.
1512
1513           The function arguments are as follows:
1514
1515           buf   The buffer containing user input.
1516
1517           len   The length of buf in bytes.
1518
1519           errstr
1520                 If the log_ttyin() function returns a value other than 1, the
1521                 plugin may store a message describing the failure or error in
1522                 errstr.  The sudo front-end will then pass this value to any
1523                 registered audit plugins.  The string stored in errstr must
1524                 remain valid until the plugin's close() function is called.
1525
1526                 The errstr parameter is only available starting with API ver‐
1527                 sion 1.15.  A plugin must check the API version specified by
1528                 the sudo front-end before using errstr.  Failure to do so may
1529                 result in a crash.
1530
1531     log_ttyout
1532           int (*log_ttyout)(const char *buf, unsigned int len,
1533               const char **errstr);
1534
1535           The log_ttyout() function is called whenever data can be read from
1536           the command but before it is written to the user's terminal.  This
1537           allows the plugin to reject data if it chooses to (for instance if
1538           the output contains banned content).  Returns 1 if the data should
1539           be passed to the user, 0 if the data is rejected (which will termi‐
1540           nate the running command), or -1 if an error occurred.
1541
1542           The function arguments are as follows:
1543
1544           buf   The buffer containing command output.
1545
1546           len   The length of buf in bytes.
1547
1548           errstr
1549                 If the log_ttyout() function returns a value other than 1,
1550                 the plugin may store a message describing the failure or er‐
1551                 ror in errstr.  The sudo front-end will then pass this value
1552                 to any registered audit plugins.  The string stored in errstr
1553                 must remain valid until the plugin's close() function is
1554                 called.
1555
1556                 The errstr parameter is only available starting with API ver‐
1557                 sion 1.15.  A plugin must check the API version specified by
1558                 the sudo front-end before using errstr.  Failure to do so may
1559                 result in a crash.
1560
1561     log_stdin
1562           int (*log_stdin)(const char *buf, unsigned int len,
1563               const char **errstr);
1564
1565           The log_stdin() function is only used if the standard input does
1566           not correspond to a tty device.  It is called whenever data can be
1567           read from the standard input but before it is passed to the running
1568           command.  This allows the plugin to reject data if it chooses to
1569           (for instance if the input contains banned content).  Returns 1 if
1570           the data should be passed to the command, 0 if the data is rejected
1571           (which will terminate the running command), or -1 if an error oc‐
1572           curred.
1573
1574           The function arguments are as follows:
1575
1576           buf   The buffer containing user input.
1577
1578           len   The length of buf in bytes.
1579
1580           errstr
1581                 If the log_stdin() function returns a value other than 1, the
1582                 plugin may store a message describing the failure or error in
1583                 errstr.  The sudo front-end will then pass this value to any
1584                 registered audit plugins.  The string stored in errstr must
1585                 remain valid until the plugin's close() function is called.
1586
1587                 The errstr parameter is only available starting with API ver‐
1588                 sion 1.15.  A plugin must check the API version specified by
1589                 the sudo front-end before using errstr.  Failure to do so may
1590                 result in a crash.
1591
1592     log_stdout
1593           int (*log_stdout)(const char *buf, unsigned int len,
1594               const char **errstr);
1595
1596           The log_stdout() function is only used if the standard output does
1597           not correspond to a tty device.  It is called whenever data can be
1598           read from the command but before it is written to the standard out‐
1599           put.  This allows the plugin to reject data if it chooses to (for
1600           instance if the output contains banned content).  Returns 1 if the
1601           data should be passed to the user, 0 if the data is rejected (which
1602           will terminate the running command), or -1 if an error occurred.
1603
1604           The function arguments are as follows:
1605
1606           buf   The buffer containing command output.
1607
1608           len   The length of buf in bytes.
1609
1610           errstr
1611                 If the log_stdout() function returns a value other than 1,
1612                 the plugin may store a message describing the failure or er‐
1613                 ror in errstr.  The sudo front-end will then pass this value
1614                 to any registered audit plugins.  The string stored in errstr
1615                 must remain valid until the plugin's close() function is
1616                 called.
1617
1618                 The errstr parameter is only available starting with API ver‐
1619                 sion 1.15.  A plugin must check the API version specified by
1620                 the sudo front-end before using errstr.  Failure to do so may
1621                 result in a crash.
1622
1623     log_stderr
1624           int (*log_stderr)(const char *buf, unsigned int len,
1625               const char **errstr);
1626
1627           The log_stderr() function is only used if the standard error does
1628           not correspond to a tty device.  It is called whenever data can be
1629           read from the command but before it is written to the standard er‐
1630           ror.  This allows the plugin to reject data if it chooses to (for
1631           instance if the output contains banned content).  Returns 1 if the
1632           data should be passed to the user, 0 if the data is rejected (which
1633           will terminate the running command), or -1 if an error occurred.
1634
1635           The function arguments are as follows:
1636
1637           buf   The buffer containing command output.
1638
1639           len   The length of buf in bytes.
1640
1641           errstr
1642                 If the log_stderr() function returns a value other than 1,
1643                 the plugin may store a message describing the failure or er‐
1644                 ror in errstr.  The sudo front-end will then pass this value
1645                 to any registered audit plugins.  The string stored in errstr
1646                 must remain valid until the plugin's close() function is
1647                 called.
1648
1649                 The errstr parameter is only available starting with API ver‐
1650                 sion 1.15.  A plugin must check the API version specified by
1651                 the sudo front-end before using errstr.  Failure to do so may
1652                 result in a crash.
1653
1654     register_hooks
1655           See the Policy plugin API section for a description of
1656           register_hooks().
1657
1658     deregister_hooks
1659           See the Policy plugin API section for a description of
1660           deregister_hooks().
1661
1662     change_winsize
1663           int (*change_winsize)(unsigned int lines, unsigned int cols,
1664               const char **errstr);
1665
1666           The change_winsize() function is called whenever the window size of
1667           the terminal changes from the initial values specified in the
1668           user_info list.  Returns -1 if an error occurred, in which case no
1669           further calls to change_winsize() will be made,
1670
1671           The function arguments are as follows:
1672
1673           lines
1674                 The number of lines (rows) in the re-sized terminal.
1675
1676           cols  The number of columns in the re-sized terminal.
1677
1678           errstr
1679                 If the change_winsize() function returns a value other than
1680                 1, the plugin may store a message describing the failure or
1681                 error in errstr.  The sudo front-end will then pass this
1682                 value to any registered audit plugins.  The string stored in
1683                 errstr must remain valid until the plugin's close() function
1684                 is called.
1685
1686                 The errstr parameter is only available starting with API ver‐
1687                 sion 1.15.  A plugin must check the API version specified by
1688                 the sudo front-end before using errstr.  Failure to do so may
1689                 result in a crash.
1690
1691     log_suspend
1692           int (*log_suspend)(int signo, const char **errstr);
1693
1694           The log_suspend() function is called whenever a command is sus‐
1695           pended or resumed.  Logging this information makes it possible to
1696           skip the period of time when the command was suspended during play‐
1697           back of a session.  Returns -1 if an error occurred, in which case
1698           no further calls to log_suspend() will be made,
1699
1700           The function arguments are as follows:
1701
1702           signo
1703                 The signal that caused the command to be suspended, or
1704                 SIGCONT if the command was resumed.
1705
1706           errstr
1707                 If the log_suspend() function returns a value other than 1,
1708                 the plugin may store a message describing the failure or er‐
1709                 ror in errstr.  The sudo front-end will then pass this value
1710                 to any registered audit plugins.  The string stored in errstr
1711                 must remain valid until the plugin's close() function is
1712                 called.
1713
1714                 The errstr parameter is only available starting with API ver‐
1715                 sion 1.15.  A plugin must check the API version specified by
1716                 the sudo front-end before using errstr.  Failure to do so may
1717                 result in a crash.
1718
1719           event_alloc
1720                 struct sudo_plugin_event * (*event_alloc)(void);
1721
1722                 The event_alloc() function is used to allocate a struct
1723                 sudo_plugin_event which provides access to the main sudo
1724                 event loop.  Unlike the other fields, the event_alloc()
1725                 pointer is filled in by the sudo front-end, not by the
1726                 plugin.
1727
1728                 See the Event API section below for more information about
1729                 events.
1730
1731                 The event_alloc() function is only available starting with
1732                 API version 1.15.  If the sudo front-end doesn't support API
1733                 version 1.15 or higher, event_alloc() will not be set.
1734
1735           I/O Plugin Version Macros
1736
1737           Same as for the Policy plugin API.
1738
1739   Audit plugin API
1740     /* Audit plugin close function status types. */
1741     #define SUDO_PLUGIN_NO_STATUS           0
1742     #define SUDO_PLUGIN_WAIT_STATUS         1
1743     #define SUDO_PLUGIN_EXEC_ERROR          2
1744     #define SUDO_PLUGIN_SUDO_ERROR          3
1745
1746     #define SUDO_AUDIT_PLUGIN 3
1747     struct audit_plugin {
1748         unsigned int type; /* always SUDO_AUDIT_PLUGIN */
1749         unsigned int version; /* always SUDO_API_VERSION */
1750         int (*open)(unsigned int version, sudo_conv_t conversation,
1751             sudo_printf_t sudo_plugin_printf, char * const settings[],
1752             char * const user_info[], int submit_optind,
1753             char * const submit_argv[], char * const submit_envp[],
1754             char * const plugin_options[], const char **errstr);
1755         void (*close)(int status_type, int status);
1756         int (*accept)(const char *plugin_name,
1757             unsigned int plugin_type, char * const command_info[],
1758             char * const run_argv[], char * const run_envp[],
1759             const char **errstr);
1760         int (*reject)(const char *plugin_name, unsigned int plugin_type,
1761             const char *audit_msg, char * const command_info[],
1762             const char **errstr);
1763         int (*error)(const char *plugin_name, unsigned int plugin_type,
1764             const char *audit_msg, char * const command_info[],
1765             const char **errstr);
1766         int (*show_version)(int verbose);
1767         void (*register_hooks)(int version,
1768             int (*register_hook)(struct sudo_hook *hook));
1769         void (*deregister_hooks)(int version,
1770             int (*deregister_hook)(struct sudo_hook *hook));
1771         struct sudo_plugin_event * (*event_alloc)(void);
1772     }
1773
1774     An audit plugin can be used to log successful and unsuccessful attempts
1775     to run sudo independent of the policy or any I/O plugins.  Multiple audit
1776     plugins may be specified in sudo.conf(5).
1777
1778     A struct audit_plugin has the following fields:
1779
1780     type  The type field should always be set to SUDO_AUDIT_PLUGIN.
1781
1782     version
1783           The version field should be set to SUDO_API_VERSION.
1784
1785           This allows sudo to determine the API version the plugin was built
1786           against.
1787
1788     open
1789           int (*open)(unsigned int version, sudo_conv_t conversation,
1790               sudo_printf_t sudo_plugin_printf, char * const settings[],
1791               char * const user_info[], int submit_optind,
1792               char * const submit_argv[], char * const submit_envp[],
1793               char * const plugin_options[], const char **errstr);
1794
1795           The audit open() function is run before any other sudo plugin API
1796           functions.  This makes it possible to audit failures in the other
1797           plugins.  It returns 1 on success, 0 on failure, -1 if a general
1798           error occurred, or -2 if there was a usage error.  In the latter
1799           case, sudo will print a usage message before it exits.  If an error
1800           occurs, the plugin may optionally call the conversation() or
1801           plugin_printf() function with SUDO_CONF_ERROR_MSG to present addi‐
1802           tional error information to the user.
1803
1804           The function arguments are as follows:
1805
1806           version
1807                 The version passed in by sudo allows the plugin to determine
1808                 the major and minor version number of the plugin API sup‐
1809                 ported by sudo.
1810
1811           conversation
1812                 A pointer to the conversation() function that may be used by
1813                 the show_version() function to display version information
1814                 (see show_version() below).  The conversation() function may
1815                 also be used to display additional error message to the user.
1816                 The conversation() function returns 0 on success, and -1 on
1817                 failure.
1818
1819           plugin_printf
1820                 A pointer to a printf()-style function that may be used by
1821                 the show_version() function to display version information
1822                 (see show_version below).  The plugin_printf() function may
1823                 also be used to display additional error message to the user.
1824                 The plugin_printf() function returns number of characters
1825                 printed on success and -1 on failure.
1826
1827           settings
1828                 A vector of user-supplied sudo settings in the form of
1829                 “name=value” strings.  The vector is terminated by a NULL
1830                 pointer.  These settings correspond to options the user spec‐
1831                 ified when running sudo.  As such, they will only be present
1832                 when the corresponding option has been specified on the com‐
1833                 mand line.
1834
1835                 When parsing settings, the plugin should split on the first
1836                 equal sign (‘=’) since the name field will never include one
1837                 itself but the value might.
1838
1839                 See the Policy plugin API section for a list of all possible
1840                 settings.
1841
1842           user_info
1843                 A vector of information about the user running the command in
1844                 the form of “name=value” strings.  The vector is terminated
1845                 by a NULL pointer.
1846
1847                 When parsing user_info, the plugin should split on the first
1848                 equal sign (‘=’) since the name field will never include one
1849                 itself but the value might.
1850
1851                 See the Policy plugin API section for a list of all possible
1852                 strings.
1853
1854           submit_optind
1855                 The index into submit_argv that corresponds to the first en‐
1856                 try that is not a command line option.  If submit_argv only
1857                 consists of options, which may be the case with the -l or -v
1858                 options, submit_argv[submit_optind] will evaluate to the NULL
1859                 pointer.
1860
1861           submit_argv
1862                 The argument vector sudo was invoked with, including all com‐
1863                 mand line options.  The submit_optind argument can be used to
1864                 determine the end of the command line options.
1865
1866           submit_envp
1867                 The invoking user's environment in the form of a
1868                 NULL-terminated vector of “name=value” strings.
1869
1870                 When parsing submit_envp, the plugin should split on the
1871                 first equal sign (‘=’) since the name field will never in‐
1872                 clude one itself but the value might.
1873
1874           plugin_options
1875                 Any (non-comment) strings immediately after the plugin path
1876                 are treated as arguments to the plugin.  These arguments are
1877                 split on a white space boundary and are passed to the plugin
1878                 in the form of a NULL-terminated array of strings.  If no ar‐
1879                 guments were specified, plugin_options will be the NULL
1880                 pointer.
1881
1882           errstr
1883                 If the open() function returns a value other than 1, the
1884                 plugin may store a message describing the failure or error in
1885                 errstr.  The sudo front-end will then pass this value to any
1886                 registered audit plugins.  The string stored in errstr must
1887                 remain valid until the plugin's close() function is called.
1888
1889     close
1890           void (*close)(int status_type, int status);
1891
1892           The close() function is called when sudo is finished, shortly be‐
1893           fore it exits.
1894
1895           The function arguments are as follows:
1896
1897           status_type
1898                 The type of status being passed.  One of
1899                 SUDO_PLUGIN_NO_STATUS, SUDO_PLUGIN_WAIT_STATUS,
1900                 SUDO_PLUGIN_EXEC_ERROR or SUDO_PLUGIN_SUDO_ERROR.
1901
1902           status
1903                 Depending on the value of status_type, this value is either
1904                 ignored, the command's exit status as returned by the wait(2)
1905                 system call, the value of errno set by the execve(2) system
1906                 call, or the value of errno resulting from an error in the
1907                 sudo front-end.
1908
1909     accept
1910           int (*accept)(const char *plugin_name, unsigned int plugin_type,
1911               char * const command_info[], char * const run_argv[],
1912               char * const run_envp[], const char **errstr);
1913
1914           The accept() function is called when a command or action is ac‐
1915           cepted by a policy or approval plugin.  The function arguments are
1916           as follows:
1917
1918           plugin_name
1919                 The name of the plugin that accepted the command or “sudo”
1920                 for the sudo front-end.
1921
1922           plugin_type
1923                 The type of plugin that accepted the command, currently ei‐
1924                 ther SUDO_POLICY_PLUGIN, SUDO_POLICY_APPROVAL, or
1925                 SUDO_FRONT_END.  The accept() function is called multiple
1926                 times--once for each policy or approval plugin that succeeds
1927                 and once for the sudo front-end.  When called on behalf of
1928                 the sudo front-end, command_info may include information from
1929                 an I/O logging plugin as well.
1930
1931                 Typically, an audit plugin is interested in either the accept
1932                 status from the sudo front-end or from the various policy and
1933                 approval plugins, but not both.  It is possible for the pol‐
1934                 icy plugin to accept a command that is later rejected by an
1935                 approval plugin, in which case the audit plugin's accept()
1936                 and reject() functions will both be called.
1937
1938           command_info
1939                 An optional vector of information describing the command be‐
1940                 ing run in the form of “name=value” strings.  The vector is
1941                 terminated by a NULL pointer.
1942
1943                 When parsing command_info, the plugin should split on the
1944                 first equal sign (‘=’) since the name field will never in‐
1945                 clude one itself but the value might.
1946
1947                 See the Policy plugin API section for a list of all possible
1948                 strings.
1949
1950           run_argv
1951                 A NULL-terminated argument vector describing a command that
1952                 will be run in the same form as what would be passed to the
1953                 execve(2) system call.
1954
1955           run_envp
1956                 The environment the command will be run with in the form of a
1957                 NULL-terminated vector of “name=value” strings.
1958
1959                 When parsing run_envp, the plugin should split on the first
1960                 equal sign (‘=’) since the name field will never include one
1961                 itself but the value might.
1962
1963           errstr
1964                 If the accept() function returns a value other than 1, the
1965                 plugin may store a message describing the failure or error in
1966                 errstr.  The sudo front-end will then pass this value to any
1967                 registered audit plugins.  The string stored in errstr must
1968                 remain valid until the plugin's close() function is called.
1969
1970     reject
1971           int (*reject)(const char *plugin_name, unsigned int plugin_type,
1972               const char *audit_msg, char * const command_info[],
1973               const char **errstr);
1974
1975           The reject() function is called when a command or action is re‐
1976           jected by a plugin.  The function arguments are as follows:
1977
1978           plugin_name
1979                 The name of the plugin that rejected the command.
1980
1981           plugin_type
1982                 The type of plugin that rejected the command, currently ei‐
1983                 ther SUDO_POLICY_PLUGIN, SUDO_APPROVAL_PLUGIN, or
1984                 SUDO_IO_PLUGIN.
1985
1986                 Unlike the accept() function, the reject() function is not
1987                 called on behalf of the sudo front-end.
1988
1989           audit_msg
1990                 An optional string describing the reason the command was re‐
1991                 jected by the plugin.  If the plugin did not provide a rea‐
1992                 son, audit_msg will be the NULL pointer.
1993
1994           command_info
1995                 An optional vector of information describing the command be‐
1996                 ing run in the form of “name=value” strings.  The vector is
1997                 terminated by a NULL pointer.
1998
1999                 When parsing command_info, the plugin should split on the
2000                 first equal sign (‘=’) since the name field will never in‐
2001                 clude one itself but the value might.
2002
2003                 See the Policy plugin API section for a list of all possible
2004                 strings.
2005
2006           errstr
2007                 If the reject() function returns a value other than 1, the
2008                 plugin may store a message describing the failure or error in
2009                 errstr.  The sudo front-end will then pass this value to any
2010                 registered audit plugins.  The string stored in errstr must
2011                 remain valid until the plugin's close() function is called.
2012
2013     error
2014           int (*error)(const char *plugin_name, unsigned int plugin_type,
2015               const char *audit_msg, char * const command_info[],
2016               const char **errstr);
2017
2018           The error() function is called when a plugin or the sudo front-end
2019           returns an error.  The function arguments are as follows:
2020
2021           plugin_name
2022                 The name of the plugin that generated the error or “sudo” for
2023                 the sudo front-end.
2024
2025           plugin_type
2026                 The type of plugin that generated the error, or
2027                 SUDO_FRONT_END for the sudo front-end.
2028
2029           audit_msg
2030                 An optional string describing the plugin error.  If the
2031                 plugin did not provide a description, audit_msg will be the
2032                 NULL pointer.
2033
2034           command_info
2035                 An optional vector of information describing the command be‐
2036                 ing run in the form of “name=value” strings.  The vector is
2037                 terminated by a NULL pointer.
2038
2039                 When parsing command_info, the plugin should split on the
2040                 first equal sign (‘=’) since the name field will never in‐
2041                 clude one itself but the value might.
2042
2043                 See the Policy plugin API section for a list of all possible
2044                 strings.
2045
2046           errstr
2047                 If the error() function returns a value other than 1, the
2048                 plugin may store a message describing the failure or error in
2049                 errstr.  The sudo front-end will then pass this value to any
2050                 registered audit plugins.  The string stored in errstr must
2051                 remain valid until the plugin's close() function is called.
2052
2053     show_version
2054           int (*show_version)(int verbose);
2055
2056           The show_version() function is called by sudo when the user speci‐
2057           fies the -V option.  The plugin may display its version information
2058           to the user via the conversation() or plugin_printf() function us‐
2059           ing SUDO_CONV_INFO_MSG.  If the user requests detailed version in‐
2060           formation, the verbose flag will be set.
2061
2062           Returns 1 on success, 0 on failure, -1 if a general error occurred,
2063           or -2 if there was a usage error, although the return value is cur‐
2064           rently ignored.
2065
2066     register_hooks
2067           See the Policy plugin API section for a description of
2068           register_hooks().
2069
2070     deregister_hooks
2071           See the Policy plugin API section for a description of
2072           deregister_hooks().
2073
2074     event_alloc
2075           struct sudo_plugin_event * (*event_alloc)(void);
2076
2077           The event_alloc() function is used to allocate a struct
2078           sudo_plugin_event which provides access to the main sudo event
2079           loop.  Unlike the other fields, the event_alloc pointer is filled
2080           in by the sudo front-end, not by the plugin.
2081
2082           See the Event API section below for more information about events.
2083
2084           The event_alloc() function is only available starting with API ver‐
2085           sion 1.17.  If the sudo front-end doesn't support API version 1.17
2086           or higher, event_alloc() will not be set.
2087
2088   Approval plugin API
2089     struct approval_plugin {
2090     #define SUDO_APPROVAL_PLUGIN 4
2091         unsigned int type; /* always SUDO_APPROVAL_PLUGIN */
2092         unsigned int version; /* always SUDO_API_VERSION */
2093         int (*open)(unsigned int version, sudo_conv_t conversation,
2094             sudo_printf_t sudo_plugin_printf, char * const settings[],
2095             char * const user_info[], int submit_optind,
2096             char * const submit_argv[], char * const submit_envp[],
2097             char * const plugin_options[], const char **errstr);
2098         void (*close)(void);
2099         int (*check)(char * const command_info[], char * const run_argv[],
2100             char * const run_envp[], const char **errstr);
2101         int (*show_version)(int verbose);
2102     };
2103
2104     An approval plugin can be used to apply extra constraints after a command
2105     has been accepted by the policy plugin.  Unlike the other plugin types,
2106     it does not remain open until the command completes.  The plugin is
2107     opened before a call to check() or show_version() and closed shortly
2108     thereafter (audit plugin functions must be called before the plugin is
2109     closed).  Multiple approval plugins may be specified in sudo.conf(5).
2110
2111     A struct approval_plugin has the following fields:
2112
2113     type  The type field should always be set to SUDO_APPROVAL_PLUGIN.
2114
2115     version
2116           The version field should be set to SUDO_API_VERSION.
2117
2118           This allows sudo to determine the API version the plugin was built
2119           against.
2120
2121     open
2122           int (*open)(unsigned int version, sudo_conv_t conversation,
2123               sudo_printf_t sudo_plugin_printf, char * const settings[],
2124               char * const user_info[], int submit_optind,
2125               char * const submit_argv[], char * const submit_envp[],
2126               char * const plugin_options[], const char **errstr);
2127
2128           The approval open() function is run immediately before a call to
2129           the plugin's check() or show_version() functions.  It is only
2130           called if the version is being requested or if the policy plugin's
2131           check_policy() function has returned successfully.  It returns 1 on
2132           success, 0 on failure, -1 if a general error occurred, or -2 if
2133           there was a usage error.  In the latter case, sudo will print a us‐
2134           age message before it exits.  If an error occurs, the plugin may
2135           optionally call the conversation() or plugin_printf() function with
2136           SUDO_CONF_ERROR_MSG to present additional error information to the
2137           user.
2138
2139           The function arguments are as follows:
2140
2141           version
2142                 The version passed in by sudo allows the plugin to determine
2143                 the major and minor version number of the plugin API sup‐
2144                 ported by sudo.
2145
2146           conversation
2147                 A pointer to the conversation() function that can be used by
2148                 the plugin to interact with the user (see Conversation API
2149                 for details).  Returns 0 on success and -1 on failure.
2150
2151           plugin_printf
2152                 A pointer to a printf()-style function that may be used to
2153                 display informational or error messages (see Conversation API
2154                 for details).  Returns the number of characters printed on
2155                 success and -1 on failure.
2156
2157           settings
2158                 A vector of user-supplied sudo settings in the form of
2159                 “name=value” strings.  The vector is terminated by a NULL
2160                 pointer.  These settings correspond to options the user spec‐
2161                 ified when running sudo.  As such, they will only be present
2162                 when the corresponding option has been specified on the com‐
2163                 mand line.
2164
2165                 When parsing settings, the plugin should split on the first
2166                 equal sign (‘=’) since the name field will never include one
2167                 itself but the value might.
2168
2169                 See the Policy plugin API section for a list of all possible
2170                 settings.
2171
2172           user_info
2173                 A vector of information about the user running the command in
2174                 the form of “name=value” strings.  The vector is terminated
2175                 by a NULL pointer.
2176
2177                 When parsing user_info, the plugin should split on the first
2178                 equal sign (‘=’) since the name field will never include one
2179                 itself but the value might.
2180
2181                 See the Policy plugin API section for a list of all possible
2182                 strings.
2183
2184           submit_optind
2185                 The index into submit_argv that corresponds to the first en‐
2186                 try that is not a command line option.  If submit_argv only
2187                 consists of options, which may be the case with the -l or -v
2188                 options, submit_argv[submit_optind] will evaluate to the NULL
2189                 pointer.
2190
2191           submit_argv
2192                 The argument vector sudo was invoked with, including all com‐
2193                 mand line options.  The submit_optind argument can be used to
2194                 determine the end of the command line options.
2195
2196           submit_envp
2197                 The invoking user's environment in the form of a
2198                 NULL-terminated vector of “name=value” strings.
2199
2200                 When parsing submit_envp, the plugin should split on the
2201                 first equal sign (‘=’) since the name field will never in‐
2202                 clude one itself but the value might.
2203
2204           plugin_options
2205                 Any (non-comment) strings immediately after the plugin path
2206                 are treated as arguments to the plugin.  These arguments are
2207                 split on a white space boundary and are passed to the plugin
2208                 in the form of a NULL-terminated array of strings.  If no ar‐
2209                 guments were specified, plugin_options will be the NULL
2210                 pointer.
2211
2212           errstr
2213                 If the open() function returns a value other than 1, the
2214                 plugin may store a message describing the failure or error in
2215                 errstr.  The sudo front-end will then pass this value to any
2216                 registered audit plugins.  The string stored in errstr must
2217                 remain valid until the plugin's close() function is called.
2218
2219     close
2220           void (*close)(void);
2221
2222           The close() function is called after the approval plugin's check()
2223           or show_version() functions have been called.  It takes no argu‐
2224           ments.  The close() function is typically used to perform plugin-
2225           specific cleanup, such as the freeing of memory objects allocated
2226           by the plugin.  If the plugin does not need to perform any cleanup,
2227           close() may be set to the NULL pointer.
2228
2229     check
2230           int (*check)(char * const command_info[], char * const run_argv[],
2231               char * const run_envp[], const char **errstr);
2232
2233           The approval check() function is run after the policy plugin
2234           check_policy() function and before any I/O logging plugins.  If
2235           multiple approval plugins are loaded, they must all succeed for the
2236           command to be allowed.  It returns 1 on success, 0 on failure, -1
2237           if a general error occurred, or -2 if there was a usage error.  In
2238           the latter case, sudo will print a usage message before it exits.
2239           If an error occurs, the plugin may optionally call the
2240           conversation() or plugin_printf() function with SUDO_CONF_ERROR_MSG
2241           to present additional error information to the user.
2242
2243           The function arguments are as follows:
2244
2245           command_info
2246                 A vector of information describing the command being run in
2247                 the form of “name=value” strings.  The vector is terminated
2248                 by a NULL pointer.
2249
2250                 When parsing command_info, the plugin should split on the
2251                 first equal sign (‘=’) since the name field will never in‐
2252                 clude one itself but the value might.
2253
2254                 See the Policy plugin API section for a list of all possible
2255                 strings.
2256
2257           run_argv
2258                 A NULL-terminated argument vector describing a command that
2259                 will be run in the same form as what would be passed to the
2260                 execve(2) system call.
2261
2262           run_envp
2263                 The environment the command will be run with in the form of a
2264                 NULL-terminated vector of “name=value” strings.
2265
2266                 When parsing run_envp, the plugin should split on the first
2267                 equal sign (‘=’) since the name field will never include one
2268                 itself but the value might.
2269
2270           errstr
2271                 If the open() function returns a value other than 1, the
2272                 plugin may store a message describing the failure or error in
2273                 errstr.  The sudo front-end will then pass this value to any
2274                 registered audit plugins.  The string stored in errstr must
2275                 remain valid until the plugin's close() function is called.
2276
2277     show_version
2278           int (*show_version)(int verbose);
2279
2280           The show_version() function is called by sudo when the user speci‐
2281           fies the -V option.  The plugin may display its version information
2282           to the user via the conversation() or plugin_printf() function us‐
2283           ing SUDO_CONV_INFO_MSG.  If the user requests detailed version in‐
2284           formation, the verbose flag will be set.
2285
2286           Returns 1 on success, 0 on failure, -1 if a general error occurred,
2287           or -2 if there was a usage error, although the return value is cur‐
2288           rently ignored.
2289
2290   Signal handlers
2291     The sudo front-end installs default signal handlers to trap common sig‐
2292     nals while the plugin functions are run.  The following signals are
2293     trapped by default before the command is executed:
2294
2295     SIGALRM
2296     SIGHUP
2297     SIGINT
2298     SIGPIPE
2299     SIGQUIT
2300     SIGTERM
2301     SIGTSTP
2302     SIGUSR1
2303     SIGUSR2
2304
2305     If a fatal signal is received before the command is executed, sudo will
2306     call the plugin's close() function with an exit status of 128 plus the
2307     value of the signal that was received.  This allows for consistent log‐
2308     ging of commands killed by a signal for plugins that log such information
2309     in their close() function.  An exception to this is SIGPIPE, which is ig‐
2310     nored until the command is executed.
2311
2312     A plugin may temporarily install its own signal handlers but must restore
2313     the original handler before the plugin function returns.
2314
2315   Hook function API
2316     Beginning with plugin API version 1.2, it is possible to install hooks
2317     for certain functions called by the sudo front-end.
2318
2319     Currently, the only supported hooks relate to the handling of environment
2320     variables.  Hooks can be used to intercept attempts to get, set, or re‐
2321     move environment variables so that these changes can be reflected in the
2322     version of the environment that is used to execute a command.  A future
2323     version of the API will support hooking internal sudo front-end functions
2324     as well.
2325
2326     Hook structure
2327
2328     Hooks in sudo are described by the following structure:
2329
2330     typedef int (*sudo_hook_fn_t)();
2331
2332     struct sudo_hook {
2333         unsigned int hook_version;
2334         unsigned int hook_type;
2335         sudo_hook_fn_t hook_fn;
2336         void *closure;
2337     };
2338
2339     A struct sudo_hook has the following fields:
2340
2341     hook_version
2342           The hook_version field should be set to SUDO_HOOK_VERSION.
2343
2344     hook_type
2345           The hook_type field may be one of the following supported hook
2346           types:
2347
2348           SUDO_HOOK_SETENV
2349                 The C library setenv(3) function.  Any registered hooks will
2350                 run before the C library implementation.  The hook_fn field
2351                 should be a function that matches the following typedef:
2352
2353                 typedef int (*sudo_hook_fn_setenv_t)(const char *name,
2354                    const char *value, int overwrite, void *closure);
2355
2356                 If the registered hook does not match the typedef the results
2357                 are unspecified.
2358
2359           SUDO_HOOK_UNSETENV
2360                 The C library unsetenv(3) function.  Any registered hooks
2361                 will run before the C library implementation.  The hook_fn
2362                 field should be a function that matches the following type‐
2363                 def:
2364
2365                 typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
2366                    void *closure);
2367
2368           SUDO_HOOK_GETENV
2369                 The C library getenv(3) function.  Any registered hooks will
2370                 run before the C library implementation.  The hook_fn field
2371                 should be a function that matches the following typedef:
2372
2373                 typedef int (*sudo_hook_fn_getenv_t)(const char *name,
2374                    char **value, void *closure);
2375
2376                 If the registered hook does not match the typedef the results
2377                 are unspecified.
2378
2379           SUDO_HOOK_PUTENV
2380                 The C library putenv(3) function.  Any registered hooks will
2381                 run before the C library implementation.  The hook_fn field
2382                 should be a function that matches the following typedef:
2383
2384                 typedef int (*sudo_hook_fn_putenv_t)(char *string,
2385                    void *closure);
2386
2387                 If the registered hook does not match the typedef the results
2388                 are unspecified.
2389
2390     hook_fn
2391           sudo_hook_fn_t hook_fn;
2392
2393           The hook_fn field should be set to the plugin's hook implementa‐
2394           tion.  The actual function arguments will vary depending on the
2395           hook_type (see hook_type above).  In all cases, the closure field
2396           of struct sudo_hook is passed as the last function parameter.  This
2397           can be used to pass arbitrary data to the plugin's hook implementa‐
2398           tion.
2399
2400           The function return value may be one of the following:
2401
2402           SUDO_HOOK_RET_ERROR
2403                 The hook function encountered an error.
2404
2405           SUDO_HOOK_RET_NEXT
2406                 The hook completed without error, go on to the next hook (in‐
2407                 cluding the system implementation if applicable).  For exam‐
2408                 ple, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if the
2409                 specified variable was not found in the private copy of the
2410                 environment.
2411
2412           SUDO_HOOK_RET_STOP
2413                 The hook completed without error, stop processing hooks for
2414                 this invocation.  This can be used to replace the system im‐
2415                 plementation.  For example, a setenv hook that operates on a
2416                 private copy of the environment but leaves environ unchanged.
2417
2418     Care must be taken when hooking C library functions, it is very easy to
2419     create an infinite loop.  For example, a getenv(3) hook that calls the
2420     snprintf(3) function may create a loop if the snprintf(3) implementation
2421     calls getenv(3) to check the locale.  To prevent this, you may wish to
2422     use a static variable in the hook function to guard against nested calls.
2423     For example:
2424
2425           static int in_progress = 0; /* avoid recursion */
2426           if (in_progress)
2427               return SUDO_HOOK_RET_NEXT;
2428           in_progress = 1;
2429           ...
2430           in_progress = 0;
2431           return SUDO_HOOK_RET_STOP;
2432
2433     Hook API Version Macros
2434
2435     /* Hook API version major/minor */
2436     #define SUDO_HOOK_VERSION_MAJOR 1
2437     #define SUDO_HOOK_VERSION_MINOR 0
2438     #define SUDO_HOOK_VERSION SUDO_API_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
2439                                                   SUDO_HOOK_VERSION_MINOR)
2440
2441     For getters and setters see the Policy plugin API.
2442
2443   Event API
2444     When sudo runs a command, it uses an event loop to service signals and
2445     I/O.  Events may be triggered based on time, a file or socket descriptor
2446     becoming ready, or due to receipt of a signal.  Starting with API version
2447     1.15, it is possible for a plugin to participate in this event loop by
2448     calling the event_alloc() function.
2449
2450     Event structure
2451
2452     Events are described by the following structure:
2453
2454     typedef void (*sudo_plugin_ev_callback_t)(int fd, int what, void *closure);
2455
2456     struct sudo_plugin_event {
2457         int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2458             sudo_plugin_ev_callback_t callback, void *closure);
2459         int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2460         int (*del)(struct sudo_plugin_event *pev);
2461         int (*pending)(struct sudo_plugin_event *pev, int events,
2462             struct timespec *ts);
2463         int (*fd)(struct sudo_plugin_event *pev);
2464         void (*setbase)(struct sudo_plugin_event *pev, void *base);
2465         void (*loopbreak)(struct sudo_plugin_event *pev);
2466         void (*free)(struct sudo_plugin_event *pev);
2467     };
2468
2469     A struct sudo_plugin_event contains the following function pointers:
2470
2471     set
2472           int (*set)(struct sudo_plugin_event *pev, int fd, int events,
2473               sudo_plugin_ev_callback_t callback, void *closure);
2474
2475           The set() function takes the following arguments:
2476
2477           struct sudo_plugin_event *pev
2478                 A pointer to the struct sudo_plugin_event itself.
2479
2480           fd    The file or socket descriptor for I/O-based events or the
2481                 signal number for signal events.  For time-based events, fd
2482                 must be -1.
2483
2484           events
2485                 The following values determine what will trigger the event
2486                 callback:
2487
2488                 SUDO_PLUGIN_EV_TIMEOUT
2489                       callback is run after the specified timeout expires
2490
2491                 SUDO_PLUGIN_EV_READ
2492                       callback is run when the file descriptor is readable
2493
2494                 SUDO_PLUGIN_EV_WRITE
2495                       callback is run when the file descriptor is writable
2496
2497                 SUDO_PLUGIN_EV_PERSIST
2498                       event is persistent and remains enabled until explic‐
2499                       itly deleted
2500
2501                 SUDO_PLUGIN_EV_SIGNAL
2502                       callback is run when the specified signal is received
2503
2504                 The SUDO_PLUGIN_EV_PERSIST flag may be ORed with any of the
2505                 event types.  It is also possible to OR SUDO_PLUGIN_EV_READ
2506                 and SUDO_PLUGIN_EV_WRITE together to run the callback when a
2507                 descriptor is ready to be either read from or written to.
2508                 All other event values are mutually exclusive.
2509
2510           sudo_plugin_ev_callback_t callback
2511                 typedef void (*sudo_plugin_ev_callback_t)(int fd, int what,
2512                     void *closure);
2513
2514                 The function to call when an event is triggered.  The
2515                 callback() function is run with the following arguments:
2516
2517                 fd    The file or socket descriptor for I/O-based events or
2518                       the signal number for signal events.
2519
2520                 what  The event type that triggered that callback.  For
2521                       events that have multiple event types (for example
2522                       SUDO_PLUGIN_EV_READ and SUDO_PLUGIN_EV_WRITE) or have
2523                       an associated timeout, what can be used to determine
2524                       why the callback was run.
2525
2526                 closure
2527                       The generic pointer that was specified in the set()
2528                       function.
2529
2530           closure
2531                 A generic pointer that will be passed to the callback func‐
2532                 tion.
2533
2534           The set() function returns 1 on success, and -1 if a error oc‐
2535           curred.
2536
2537     add
2538           int (*add)(struct sudo_plugin_event *pev, struct timespec *timeout);
2539
2540           The add() function adds the event pev to sudo's event loop.  The
2541           event must have previously been initialized via the set() function.
2542           If the timeout argument is not NULL, it should specify a (relative)
2543           timeout after which the event will be triggered if the main event
2544           criteria has not been met.  This is often used to implement an I/O
2545           timeout where the event will fire if a descriptor is not ready
2546           within a certain time period.  If the event is already present in
2547           the event loop, its timeout will be adjusted to match the new
2548           value, if any.
2549
2550           The add() function returns 1 on success, and -1 if a error oc‐
2551           curred.
2552
2553     del
2554           int (*del)(struct sudo_plugin_event *pev);
2555
2556           The del() function deletes the event pev from sudo's event loop.
2557           Deleted events can be added back via the add() function.
2558
2559           The del() function returns 1 on success, and -1 if a error oc‐
2560           curred.
2561
2562     pending
2563           int (*pending)(struct sudo_plugin_event *pev, int events,
2564               struct timespec *ts);
2565
2566           The pending() function can be used to determine whether one or more
2567           events is pending.  The events argument specifies which events to
2568           check for.  See the set() function for a list of valid event types.
2569           If SUDO_PLUGIN_EV_TIMEOUT is specified in events, the event has an
2570           associated timeout and the ts pointer is non-NULL, it will be
2571           filled in with the remaining time.
2572
2573     fd
2574           int (*fd)(struct sudo_plugin_event *pev);
2575
2576           The fd() function returns the descriptor or signal number associ‐
2577           ated with the event pev.
2578
2579     setbase
2580           void (*setbase)(struct sudo_plugin_event *pev, void *base);
2581
2582           The setbase() function sets the underlying event base for pev to
2583           the specified value.  This can be used to move an event created via
2584           event_alloc() to a new event loop allocated by sudo's event subsys‐
2585           tem.  If base is NULL, pev's event base is reset to the default
2586           value, which corresponds to sudo's main event loop.  Using this
2587           function requires linking the plugin with the sudo_util library.
2588           It is unlikely to be used outside of the sudoers plugin.
2589
2590     loopbreak
2591           void (*loopbreak)(struct sudo_plugin_event *pev);
2592
2593           The loopbreak() function causes sudo's event loop to exit immedi‐
2594           ately and the running command to be terminated.
2595
2596     free
2597           void (*free)(struct sudo_plugin_event *pev);
2598
2599           The free() function deletes the event pev from the event loop and
2600           frees the memory associated with it.
2601
2602   Remote command execution
2603     The sudo front-end does not support running remote commands.  However,
2604     starting with sudo 1.8.8, the -h option may be used to specify a remote
2605     host that is passed to the policy plugin.  A plugin may also accept a
2606     runas_user in the form of “user@hostname” which will work with older ver‐
2607     sions of sudo.  It is anticipated that remote commands will be supported
2608     by executing a “helper” program.  The policy plugin should setup the exe‐
2609     cution environment such that the sudo front-end will run the helper
2610     which, in turn, will connect to the remote host and run the command.
2611
2612     For example, the policy plugin could utilize ssh to perform remote com‐
2613     mand execution.  The helper program would be responsible for running ssh
2614     with the proper options to use a private key or certificate that the re‐
2615     mote host will accept and run a program on the remote host that would
2616     setup the execution environment accordingly.
2617
2618     Remote sudoedit functionality must be handled by the policy plugin, not
2619     sudo itself as the front-end has no knowledge that a remote command is
2620     being executed.  This may be addressed in a future revision of the plugin
2621     API.
2622
2623   Conversation API
2624     If the plugin needs to interact with the user, it may do so via the
2625     conversation() function.  A plugin should not attempt to read directly
2626     from the standard input or the user's terminal (neither of which are
2627     guaranteed to exist).  The caller must include a trailing newline in msg
2628     if one is to be printed.
2629
2630     A printf()-style function is also available that can be used to display
2631     informational or error messages to the user, which is usually more conve‐
2632     nient for simple messages where no use input is required.
2633
2634     Conversation function structures
2635
2636     The conversation function takes as arguments pointers to the following
2637     structures:
2638
2639     struct sudo_conv_message {
2640     #define SUDO_CONV_PROMPT_ECHO_OFF  0x0001 /* do not echo user input */
2641     #define SUDO_CONV_PROMPT_ECHO_ON   0x0002 /* echo user input */
2642     #define SUDO_CONV_ERROR_MSG        0x0003 /* error message */
2643     #define SUDO_CONV_INFO_MSG         0x0004 /* informational message */
2644     #define SUDO_CONV_PROMPT_MASK      0x0005 /* mask user input */
2645     #define SUDO_CONV_PROMPT_ECHO_OK   0x1000 /* flag: allow echo if no tty */
2646     #define SUDO_CONV_PREFER_TTY       0x2000 /* flag: use tty if possible */
2647         int msg_type;
2648         int timeout;
2649         const char *msg;
2650     };
2651
2652     #define SUDO_CONV_REPL_MAX      1023
2653
2654     struct sudo_conv_reply {
2655         char *reply;
2656     };
2657
2658     typedef int (*sudo_conv_callback_fn_t)(int signo, void *closure);
2659     struct sudo_conv_callback {
2660         unsigned int version;
2661         void *closure;
2662         sudo_conv_callback_fn_t on_suspend;
2663         sudo_conv_callback_fn_t on_resume;
2664     };
2665
2666     Pointers to the conversation() and printf()-style functions are passed in
2667     to the plugin's open() function when the plugin is initialized.  The fol‐
2668     lowing type definitions can be used in the declaration of the open()
2669     function:
2670
2671     typedef int (*sudo_conv_t)(int num_msgs,
2672         const struct sudo_conv_message msgs[],
2673         struct sudo_conv_reply replies[], struct sudo_conv_callback *callback);
2674
2675     typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
2676
2677     To use the conversation() function, the plugin must pass an array of
2678     struct sudo_conv_message and struct sudo_conv_reply.  There must be a
2679     struct sudo_conv_message and struct sudo_conv_reply for each message in
2680     the conversation, that is, both arrays must have the same number of ele‐
2681     ments.  Each struct sudo_conv_reply must have its reply member initial‐
2682     ized to NULL.  The struct sudo_conv_callback pointer, if not NULL, should
2683     contain function pointers to be called when the sudo process is suspended
2684     and/or resumed during conversation input.  The on_suspend and on_resume
2685     functions are called with the signal that caused sudo to be suspended and
2686     the closure pointer from the struct sudo_conv_callback.  These functions
2687     should return 0 on success and -1 on error.  On error, the conversation
2688     will end and the conversation function will return a value of -1.  The
2689     intended use is to allow the plugin to release resources, such as locks,
2690     that should not be held indefinitely while suspended and then reacquire
2691     them when the process is resumed.  The functions are not actually invoked
2692     from within a signal handler.
2693
2694     The msg_type must be set to one of the following values:
2695
2696     SUDO_CONV_PROMPT_ECHO_OFF
2697           Prompt the user for input with echo disabled; this is generally
2698           used for passwords.  The reply will be stored in the replies array,
2699           and it will never be NULL.
2700
2701     SUDO_CONV_PROMPT_ECHO_ON
2702           Prompt the user for input with echo enabled.  The reply will be
2703           stored in the replies array, and it will never be NULL.
2704
2705     SUDO_CONV_ERROR_MSG
2706           Display an error message.  The message is written to the standard
2707           error unless the SUDO_CONV_PREFER_TTY flag is set, in which case it
2708           is written to the user's terminal if possible.
2709
2710     SUDO_CONV_INFO_MSG
2711           Display a message.  The message is written to the standard output
2712           unless the SUDO_CONV_PREFER_TTY flag is set, in which case it is
2713           written to the user's terminal if possible.
2714
2715     SUDO_CONV_PROMPT_MASK
2716           Prompt the user for input but echo an asterisk character for each
2717           character read.  The reply will be stored in the replies array, and
2718           it will never be NULL.  This can be used to provide visual feedback
2719           to the user while reading sensitive information that should not be
2720           displayed.
2721
2722     In addition to the above values, the following flag bits may also be set:
2723
2724     SUDO_CONV_PROMPT_ECHO_OK
2725           Allow input to be read when echo cannot be disabled when the mes‐
2726           sage type is SUDO_CONV_PROMPT_ECHO_OFF or SUDO_CONV_PROMPT_MASK.
2727           By default, sudo will refuse to read input if the echo cannot be
2728           disabled for those message types.
2729
2730     SUDO_CONV_PREFER_TTY
2731           When displaying a message via SUDO_CONV_ERROR_MSG or
2732           SUDO_CONV_INFO_MSG, try to write the message to the user's termi‐
2733           nal.  If the terminal is unavailable, the standard error or stan‐
2734           dard output will be used, depending upon whether
2735           SUDO_CONV_ERROR_MSG or SUDO_CONV_INFO_MSG was used.  The user's
2736           terminal is always used when possible for input, this flag is only
2737           used for output.
2738
2739     The timeout in seconds until the prompt will wait for no more input.  A
2740     zero value implies an infinite timeout.
2741
2742     The plugin is responsible for freeing the reply buffer located in each
2743     struct sudo_conv_reply, if it is not NULL.  SUDO_CONV_REPL_MAX represents
2744     the maximum length of the reply buffer (not including the trailing NUL
2745     character).  In practical terms, this is the longest password sudo will
2746     support.
2747
2748     The printf()-style function uses the same underlying mechanism as the
2749     conversation() function but only supports SUDO_CONV_INFO_MSG and
2750     SUDO_CONV_ERROR_MSG for the msg_type parameter.  It can be more conve‐
2751     nient than using the conversation() function if no user reply is needed
2752     and supports standard printf() escape sequences.
2753
2754     See the sample plugin for an example of the conversation() function us‐
2755     age.
2756
2757   Plugin invocation order
2758     As of sudo 1.9.0, the plugin open() and close() functions are called in
2759     the following order:
2760
2761     1.   audit open
2762
2763     2.   policy open
2764
2765     3.   approval open
2766
2767     4.   approval close
2768
2769     5.   I/O log open
2770
2771     6.   command runs
2772
2773     7.   command exits
2774
2775     8.   I/O log close
2776
2777     9.   policy close
2778
2779     10.  audit close
2780
2781     11.  sudo exits
2782
2783     Prior to sudo 1.9.0, the I/O log close() function was called after the
2784     policy close() function.
2785
2786   Sudoers group plugin API
2787     The sudoers plugin supports its own plugin interface to allow non-Unix
2788     group lookups.  This can be used to query a group source other than the
2789     standard Unix group database.  Two sample group plugins are bundled with
2790     sudo, group_file, and system_group, are detailed in sudoers(5).  Third
2791     party group plugins include a QAS AD plugin available from Quest Soft‐
2792     ware.
2793
2794     A group plugin must declare and populate a struct sudoers_group_plugin in
2795     the global scope.  This structure contains pointers to the functions that
2796     implement plugin initialization, cleanup, and group lookup.
2797
2798     struct sudoers_group_plugin {
2799         unsigned int version;
2800         int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2801             char *const argv[]);
2802         void (*cleanup)(void);
2803         int (*query)(const char *user, const char *group,
2804             const struct passwd *pwd);
2805     };
2806
2807     A struct sudoers_group_plugin has the following fields:
2808
2809     version
2810           The version field should be set to GROUP_API_VERSION.
2811
2812           This allows sudoers to determine the API version the group plugin
2813           was built against.
2814
2815     init
2816           int (*init)(int version, sudo_printf_t sudo_plugin_printf,
2817               char *const argv[]);
2818
2819           The init() function is called after sudoers has been parsed but be‐
2820           fore any policy checks.  It returns 1 on success, 0 on failure (or
2821           if the plugin is not configured), and -1 if a error occurred.  If
2822           an error occurs, the plugin may call the plugin_printf() function
2823           with SUDO_CONF_ERROR_MSG to present additional error information to
2824           the user.
2825
2826           The function arguments are as follows:
2827
2828           version
2829                 The version passed in by sudoers allows the plugin to deter‐
2830                 mine the major and minor version number of the group plugin
2831                 API supported by sudoers.
2832
2833           plugin_printf
2834                 A pointer to a printf()-style function that may be used to
2835                 display informational or error message to the user.  Returns
2836                 the number of characters printed on success and -1 on fail‐
2837                 ure.
2838
2839           argv  A NULL-terminated array of arguments generated from the
2840                 group_plugin option in sudoers.  If no arguments were given,
2841                 argv will be NULL.
2842
2843     cleanup
2844           void (*cleanup)();
2845
2846           The cleanup() function is called when sudoers has finished its
2847           group checks.  The plugin should free any memory it has allocated
2848           and close open file handles.
2849
2850     query
2851           int (*query)(const char *user, const char *group,
2852               const struct passwd *pwd);
2853
2854           The query() function is used to ask the group plugin whether user
2855           is a member of group.
2856
2857           The function arguments are as follows:
2858
2859           user  The name of the user being looked up in the external group
2860                 database.
2861
2862           group
2863                 The name of the group being queried.
2864
2865           pwd   The password database entry for user, if any.  If user is not
2866                 present in the password database, pwd will be NULL.
2867
2868     Group API Version Macros
2869
2870     /* Sudoers group plugin version major/minor */
2871     #define GROUP_API_VERSION_MAJOR 1
2872     #define GROUP_API_VERSION_MINOR 0
2873     #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
2874                                GROUP_API_VERSION_MINOR)
2875     For getters and setters see the Policy plugin API.
2876

PLUGIN API CHANGELOG

2878     The following revisions have been made to the Sudo Plugin API.
2879
2880     Version 1.0
2881           Initial API version.
2882
2883     Version 1.1 (sudo 1.8.0)
2884           The I/O logging plugin's open() function was modified to take the
2885           command_info list as an argument.
2886
2887     Version 1.2 (sudo 1.8.5)
2888           The Policy and I/O logging plugins' open() functions are now passed
2889           a list of plugin parameters if any are specified in sudo.conf(5).
2890
2891           A simple hooks API has been introduced to allow plugins to hook in
2892           to the system's environment handling functions.
2893
2894           The init_session() Policy plugin function is now passed a pointer
2895           to the user environment which can be updated as needed.  This can
2896           be used to merge in environment variables stored in the PAM handle
2897           before a command is run.
2898
2899     Version 1.3 (sudo 1.8.7)
2900           Support for the exec_background entry has been added to the
2901           command_info list.
2902
2903           The max_groups and plugin_dir entries were added to the settings
2904           list.
2905
2906           The version() and close() functions are now optional.  Previously,
2907           a missing version() or close() function would result in a crash.
2908           If no policy plugin close() function is defined, a default close()
2909           function will be provided by the sudo front-end that displays a
2910           warning if the command could not be executed.
2911
2912           The sudo front-end now installs default signal handlers to trap
2913           common signals while the plugin functions are run.
2914
2915     Version 1.4 (sudo 1.8.8)
2916           The remote_host entry was added to the settings list.
2917
2918     Version 1.5 (sudo 1.8.9)
2919           The preserve_fds entry was added to the command_info list.
2920
2921     Version 1.6 (sudo 1.8.11)
2922           The behavior when an I/O logging plugin returns an error (-1) has
2923           changed.  Previously, the sudo front-end took no action when the
2924           log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
2925           log_stderr() function returned an error.
2926
2927           The behavior when an I/O logging plugin returns 0 has changed.
2928           Previously, output from the command would be displayed to the ter‐
2929           minal even if an output logging function returned 0.
2930
2931     Version 1.7 (sudo 1.8.12)
2932           The plugin_path entry was added to the settings list.
2933
2934           The debug_flags entry now starts with a debug file path name and
2935           may occur multiple times if there are multiple plugin-specific De‐
2936           bug lines in the sudo.conf(5) file.
2937
2938     Version 1.8 (sudo 1.8.15)
2939           The sudoedit_checkdir and sudoedit_follow entries were added to the
2940           command_info list.  The default value of sudoedit_checkdir was
2941           changed to true in sudo 1.8.16.
2942
2943           The sudo conversation() function now takes a pointer to a struct
2944           sudo_conv_callback as its fourth argument.  The sudo_conv_t defini‐
2945           tion has been updated to match.  The plugin must specify that it
2946           supports plugin API version 1.8 or higher to receive a conversation
2947           function pointer that supports this argument.
2948
2949     Version 1.9 (sudo 1.8.16)
2950           The execfd entry was added to the command_info list.
2951
2952     Version 1.10 (sudo 1.8.19)
2953           The umask entry was added to the user_info list.  The iolog_group,
2954           iolog_mode, and iolog_user entries were added to the command_info
2955           list.
2956
2957     Version 1.11 (sudo 1.8.20)
2958           The timeout entry was added to the settings list.
2959
2960     Version 1.12 (sudo 1.8.21)
2961           The change_winsize() function was added to struct io_plugin.
2962
2963     Version 1.13 (sudo 1.8.26)
2964           The log_suspend() function was added to struct io_plugin.
2965
2966     Version 1.14 (sudo 1.8.29)
2967           The umask_override entry was added to the command_info list.
2968
2969     Version 1.15 (sudo 1.9.0)
2970           The cwd_optional entry was added to the command_info list.
2971
2972           The event_alloc() function was added to struct policy_plugin and
2973           struct io_plugin.
2974
2975           The errstr argument was added to the policy and I/O plugin func‐
2976           tions which the plugin function can use to return an error string.
2977           This string may be used by the audit plugin to report failure or
2978           error conditions set by the other plugins.
2979
2980           The close() function is now is called regardless of whether or not
2981           a command was actually executed.  This makes it possible for plug‐
2982           ins to perform cleanup even when a command was not run.
2983
2984           SUDO_CONV_REPL_MAX has increased from 255 to 1023 bytes.
2985
2986           Support for audit and approval plugins was added.
2987
2988     Version 1.16 (sudo 1.9.3)
2989           Initial resource limit values were added to the user_info list.
2990
2991           The cmnd_chroot and cmnd_cwd entries were added to the settings
2992           list.
2993
2994     Version 1.17 (sudo 1.9.4)
2995           The event_alloc() function was added to struct audit_plugin and
2996           struct approval_plugin.
2997
2998     Version 1.18 (sudo 1.9.9)
2999           The policy may now set resource limit values in the command_info
3000           list.  The intercept and log_subcmds entries were added to the
3001           command_info list.
3002
3003     Version 1.19 (sudo 1.9.11)
3004           The intercept_ptrace and intercept_setid entries were added to the
3005           settings list.  The apparmor_profile and use_ptrace entries were
3006           added to the command_info list.
3007
3008     Version 1.20 (sudo 1.9.12)
3009           The update_ticket entry was added to the settings list.  The
3010           intercept_verify entry was added to the command_info list.
3011
3012     Version 1.21 (sudo 1.9.13)
3013           The sudoedit_nfiles entry was added to the command_info list.
3014

SEE ALSO

3016     sudo.conf(5), sudoers(5), sudo(8)
3017

AUTHORS

3019     Many people have worked on sudo over the years; this version consists of
3020     code written primarily by:
3021
3022           Todd C. Miller
3023
3024     See the CONTRIBUTORS.md file in the sudo distribution
3025     (https://www.sudo.ws/about/contributors/) for an exhaustive list of peo‐
3026     ple who have contributed to sudo.
3027

BUGS

3029     If you believe you have found a bug in sudo, you can submit a bug report
3030     at https://bugzilla.sudo.ws/
3031

SUPPORT

3033     Limited free support is available via the sudo-users mailing list, see
3034     https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
3035     the archives.
3036

DISCLAIMER

3038     sudo is provided “AS IS” and any express or implied warranties, includ‐
3039     ing, but not limited to, the implied warranties of merchantability and
3040     fitness for a particular purpose are disclaimed.  See the LICENSE.md file
3041     distributed with sudo or https://www.sudo.ws/about/license/ for complete
3042     details.
3043
3044Sudo 1.9.14p3                  January 18, 2023                  Sudo 1.9.14p3
Impressum