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

PLUGIN API CHANGELOG

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

SEE ALSO

2780     sudo.conf(5), sudoers(5), sudo(8)
2781

AUTHORS

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

BUGS

2793     If you feel you have found a bug in sudo, please submit a bug report at
2794     https://bugzilla.sudo.ws/
2795

SUPPORT

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

DISCLAIMER

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