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

PLUGIN API CHANGELOG

2656     The following revisions have been made to the Sudo Plugin API.
2657
2658     Version 1.0
2659           Initial API version.
2660
2661     Version 1.1 (sudo 1.8.0)
2662           The I/O logging plugin's open() function was modified to take the
2663           command_info list as an argument.
2664
2665     Version 1.2 (sudo 1.8.5)
2666           The Policy and I/O logging plugins' open() functions are now passed
2667           a list of plugin parameters if any are specified in sudo.conf(5).
2668
2669           A simple hooks API has been introduced to allow plugins to hook in
2670           to the system's environment handling functions.
2671
2672           The init_session Policy plugin function is now passed a pointer to
2673           the user environment which can be updated as needed.  This can be
2674           used to merge in environment variables stored in the PAM handle be‐
2675           fore a command is run.
2676
2677     Version 1.3 (sudo 1.8.7)
2678           Support for the exec_background entry has been added to the
2679           command_info list.
2680
2681           The max_groups and plugin_dir entries were added to the settings
2682           list.
2683
2684           The version() and close() functions are now optional.  Previously,
2685           a missing version() or close() function would result in a crash.
2686           If no policy plugin close() function is defined, a default close()
2687           function will be provided by the sudo front end that displays a
2688           warning if the command could not be executed.
2689
2690           The sudo front end now installs default signal handlers to trap
2691           common signals while the plugin functions are run.
2692
2693     Version 1.4 (sudo 1.8.8)
2694           The remote_host entry was added to the settings list.
2695
2696     Version 1.5 (sudo 1.8.9)
2697           The preserve_fds entry was added to the command_info list.
2698
2699     Version 1.6 (sudo 1.8.11)
2700           The behavior when an I/O logging plugin returns an error (-1) has
2701           changed.  Previously, the sudo front end took no action when the
2702           log_ttyin(), log_ttyout(), log_stdin(), log_stdout(), or
2703           log_stderr() function returned an error.
2704
2705           The behavior when an I/O logging plugin returns 0 has changed.
2706           Previously, output from the command would be displayed to the ter‐
2707           minal even if an output logging function returned 0.
2708
2709     Version 1.7 (sudo 1.8.12)
2710           The plugin_path entry was added to the settings list.
2711
2712           The debug_flags entry now starts with a debug file path name and
2713           may occur multiple times if there are multiple plugin-specific De‐
2714           bug lines in the sudo.conf(5) file.
2715
2716     Version 1.8 (sudo 1.8.15)
2717           The sudoedit_checkdir and sudoedit_follow entries were added to the
2718           command_info list.  The default value of sudoedit_checkdir was
2719           changed to true in sudo 1.8.16.
2720
2721           The sudo conversation function now takes a pointer to a struct
2722           sudo_conv_callback as its fourth argument.  The sudo_conv_t defini‐
2723           tion has been updated to match.  The plugin must specify that it
2724           supports plugin API version 1.8 or higher to receive a conversation
2725           function pointer that supports this argument.
2726
2727     Version 1.9 (sudo 1.8.16)
2728           The execfd entry was added to the command_info list.
2729
2730     Version 1.10 (sudo 1.8.19)
2731           The umask entry was added to the user_info list.  The iolog_group,
2732           iolog_mode, and iolog_user entries were added to the command_info
2733           list.
2734
2735     Version 1.11 (sudo 1.8.20)
2736           The timeout entry was added to the settings list.
2737
2738     Version 1.12 (sudo 1.8.21)
2739           The change_winsize field was added to the io_plugin struct.
2740
2741     Version 1.13 (sudo 1.8.26)
2742           The log_suspend field was added to the io_plugin struct.
2743
2744     Version 1.14 (sudo 1.8.29)
2745           The umask_override entry was added to the command_info list.
2746
2747     Version 1.15 (sudo 1.9.0)
2748           The cwd_optional entry was added to the command_info list.
2749
2750           The event_alloc field was added to the policy_plugin and io_plugin
2751           structs.
2752
2753           The errstr argument was added to the policy and I/O plugin func‐
2754           tions which the plugin function can use to return an error string.
2755           This string may be used by the audit plugin to report failure or
2756           error conditions set by the other plugins.
2757
2758           The close() function is now is called regardless of whether or not
2759           a command was actually executed.  This makes it possible for plug‐
2760           ins to perform cleanup even when a command was not run.
2761
2762           SUDO_CONV_REPL_MAX has increased from 255 to 1023 bytes.
2763
2764           Support for audit and approval plugins was added.
2765
2766     Version 1.16 (sudo 1.9.3)
2767           Initial resource limit values were added to the user_info list.
2768
2769           The cmnd_chroot and cmnd_cwd enties were added to the settings
2770           list.
2771
2772     Version 1.17 (sudo 1.9.4)
2773           The event_alloc field was added to the audit_plugin and ap‐
2774           proval_plugin structs.
2775

SEE ALSO

2777     sudo.conf(5), sudoers(5), sudo(8)
2778

AUTHORS

2780     Many people have worked on sudo over the years; this version consists of
2781     code written primarily by:
2782
2783           Todd C. Miller
2784
2785     See the CONTRIBUTORS file in the sudo distribution
2786     (https://www.sudo.ws/contributors.html) for an exhaustive list of people
2787     who have contributed to sudo.
2788

BUGS

2790     If you feel you have found a bug in sudo, please submit a bug report at
2791     https://bugzilla.sudo.ws/
2792

SUPPORT

2794     Limited free support is available via the sudo-users mailing list, see
2795     https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search
2796     the archives.
2797

DISCLAIMER

2799     sudo is provided “AS IS” and any express or implied warranties, includ‐
2800     ing, but not limited to, the implied warranties of merchantability and
2801     fitness for a particular purpose are disclaimed.  See the LICENSE file
2802     distributed with sudo or https://www.sudo.ws/license.html for complete
2803     details.
2804
2805Sudo 1.9.8p2                   November 17, 2020                  Sudo 1.9.8p2
Impressum