granicus.if.org Git - sudo/blob - doc/sudo_plugin.mdoc.in

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