git.gag.com Git - debian/sudo/blob - doc/sudo_plugin.cat

   1 SUDO_PLUGIN(4)                Programmer's Manual               SUDO_PLUGIN(4)
   2
   3 N\bNA\bAM\bME\bE
   4      s\bsu\bud\bdo\bo_\b_p\bpl\blu\bug\bgi\bin\bn - Sudo Plugin API
   5
   6 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
   7      Starting with version 1.8, s\bsu\bud\bdo\bo supports a plugin API for policy and
   8      session logging.  By default, the s\bsu\bud\bdo\boe\ber\brs\bs policy plugin and an associated
   9      I/O logging plugin are used.  Via the plugin API, s\bsu\bud\bdo\bo can be configured
  10      to use alternate policy and/or I/O logging plugins provided by third
  11      parties.  The plugins to be used are specified in the sudo.conf(4) file.
  12
  13      The API is versioned with a major and minor number.  The minor version
  14      number is incremented when additions are made.  The major number is
  15      incremented when incompatible changes are made.  A plugin should be check
  16      the version passed to it and make sure that the major version matches.
  17
  18      The plugin API is defined by the sudo_plugin.h header file.
  19
  20    P\bPo\bol\bli\bic\bcy\by p\bpl\blu\bug\bgi\bin\bn A\bAP\bPI\bI
  21      A policy plugin must declare and populate a policy_plugin struct in the
  22      global scope.  This structure contains pointers to the functions that
  23      implement the s\bsu\bud\bdo\bo policy checks.  The name of the symbol should be
  24      specified in sudo.conf(4) along with a path to the plugin so that s\bsu\bud\bdo\bo
  25      can load it.
  26
  27      struct policy_plugin {
  28      #define SUDO_POLICY_PLUGIN     1
  29          unsigned int type; /* always SUDO_POLICY_PLUGIN */
  30          unsigned int version; /* always SUDO_API_VERSION */
  31          int (*open)(unsigned int version, sudo_conv_t conversation,
  32                      sudo_printf_t plugin_printf, char * const settings[],
  33                      char * const user_info[], char * const user_env[],
  34                      char * const plugin_options[]);
  35          void (*close)(int exit_status, int error);
  36          int (*show_version)(int verbose);
  37          int (*check_policy)(int argc, char * const argv[],
  38                              char *env_add[], char **command_info[],
  39                              char **argv_out[], char **user_env_out[]);
  40          int (*list)(int argc, char * const argv[], int verbose,
  41                      const char *list_user);
  42          int (*validate)(void);
  43          void (*invalidate)(int remove);
  44          int (*init_session)(struct passwd *pwd, char **user_env[]);
  45          void (*register_hooks)(int version,
  46             int (*register_hook)(struct sudo_hook *hook));
  47          void (*deregister_hooks)(int version,
  48             int (*deregister_hook)(struct sudo_hook *hook));
  49      };
  50
  51      The policy_plugin struct has the following fields:
  52
  53      type  The type field should always be set to SUDO_POLICY_PLUGIN.
  54
  55      version
  56            The version field should be set to SUDO_API_VERSION.
  57
  58            This allows s\bsu\bud\bdo\bo to determine the API version the plugin was built
  59            against.
  60
  61      open
  62            int (*open)(unsigned int version, sudo_conv_t conversation,
  63                        sudo_printf_t plugin_printf, char * const settings[],
  64                        char * const user_info[], char * const user_env[],
  65                        char * const plugin_options[]);
  66
  67            Returns 1 on success, 0 on failure, -1 if a general error occurred,
  68            or -2 if there was a usage error.  In the latter case, s\bsu\bud\bdo\bo will
  69            print a usage message before it exits.  If an error occurs, the
  70            plugin may optionally call the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
  71            function with SUDO_CONF_ERROR_MSG to present additional error
  72            information to the user.
  73
  74            The function arguments are as follows:
  75
  76            version
  77                  The version passed in by s\bsu\bud\bdo\bo allows the plugin to determine
  78                  the major and minor version number of the plugin API
  79                  supported by s\bsu\bud\bdo\bo.
  80
  81            conversation
  82                  A pointer to the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function that can be used by
  83                  the plugin to interact with the user (see below).  Returns 0
  84                  on success and -1 on failure.
  85
  86            plugin_printf
  87                  A pointer to a p\bpr\bri\bin\bnt\btf\bf()-style function that may be used to
  88                  display informational or error messages (see below).  Returns
  89                  the number of characters printed on success and -1 on
  90                  failure.
  91
  92            settings
  93                  A vector of user-supplied s\bsu\bud\bdo\bo settings in the form of
  94                  ``name=value'' strings.  The vector is terminated by a NULL
  95                  pointer.  These settings correspond to flags the user
  96                  specified when running s\bsu\bud\bdo\bo.  As such, they will only be
  97                  present when the corresponding flag has been specified on the
  98                  command line.
  99
 100                  When parsing _\bs_\be_\bt_\bt_\bi_\bn_\bg_\bs, the plugin should split on the f\bfi\bir\brs\bst\bt
 101                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 102                  itself but the _\bv_\ba_\bl_\bu_\be might.
 103
 104                  bsdauth_type=string
 105                        Authentication type, if specified by the -\b-a\ba flag, to
 106                        use on systems where BSD authentication is supported.
 107
 108                  closefrom=number
 109                        If specified, the user has requested via the -\b-C\bC flag
 110                        that s\bsu\bud\bdo\bo close all files descriptors with a value of
 111                        _\bn_\bu_\bm_\bb_\be_\br or higher.  The plugin may optionally pass this,
 112                        or another value, back in the _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bi_\bn_\bf_\bo list.
 113
 114                  debug_flags=string
 115                        A comma-separated list of debug flags that correspond
 116                        to s\bsu\bud\bdo\bo's Debug entry in sudo.conf(4), if there is one.
 117                        The flags are passed to the plugin as they appear in
 118                        sudo.conf(4).  The syntax used by s\bsu\bud\bdo\bo and the s\bsu\bud\bdo\boe\ber\brs\bs
 119                        plugin is _\bs_\bu_\bb_\bs_\by_\bs_\bt_\be_\bm@_\bp_\br_\bi_\bo_\br_\bi_\bt_\by but the plugin is free to
 120                        use a different format so long as it does not include a
 121                        comma (`,').  There is not currently a way to specify a
 122                        set of debug flags specific to the plugin--the flags
 123                        are shared by s\bsu\bud\bdo\bo and the plugin.
 124
 125                  debug_level=number
 126                        This setting has been deprecated in favor of
 127                        _\bd_\be_\bb_\bu_\bg_\b__\bf_\bl_\ba_\bg_\bs.
 128
 129                  ignore_ticket=bool
 130                        Set to true if the user specified the -\b-k\bk flag along
 131                        with a command, indicating that the user wishes to
 132                        ignore any cached authentication credentials.
 133                        _\bi_\bm_\bp_\bl_\bi_\be_\bd_\b__\bs_\bh_\be_\bl_\bl to true.  This allows s\bsu\bud\bdo\bo with no
 134                        arguments to be used similarly to su(1).  If the plugin
 135                        does not to support this usage, it may return a value
 136                        of -2 from the c\bch\bhe\bec\bck\bk_\b_p\bpo\bol\bli\bic\bcy\by() function, which will
 137                        cause s\bsu\bud\bdo\bo to print a usage message and exit.
 138
 139                  implied_shell=bool
 140                        If the user does not specify a program on the command
 141                        line, s\bsu\bud\bdo\bo will pass the plugin the path to the user's
 142                        shell and set
 143
 144                  login_class=string
 145                        BSD login class to use when setting resource limits and
 146                        nice value, if specified by the -\b-c\bc flag.
 147
 148                  login_shell=bool
 149                        Set to true if the user specified the -\b-i\bi flag,
 150                        indicating that the user wishes to run a login shell.
 151
 152                  max_groups=int
 153                        The maximum number of groups a user may belong to.
 154                        This will only be present if there is a corresponding
 155                        setting in sudo.conf(4).
 156
 157                  network_addrs=list
 158                        A space-separated list of IP network addresses and
 159                        netmasks in the form ``addr/netmask'', e.g.
 160                        ``192.168.1.2/255.255.255.0''.  The address and netmask
 161                        pairs may be either IPv4 or IPv6, depending on what the
 162                        operating system supports.  If the address contains a
 163                        colon (`:'), it is an IPv6 address, else it is IPv4.
 164
 165                  noninteractive=bool
 166                        Set to true if the user specified the -\b-n\bn flag,
 167                        indicating that s\bsu\bud\bdo\bo should operate in non-interactive
 168                        mode.  The plugin may reject a command run in non-
 169                        interactive mode if user interaction is required.
 170
 171                  plugin_dir=string
 172                        The default plugin directory used by the s\bsu\bud\bdo\bo front
 173                        end.  This is the default directory set at compile time
 174                        and may not correspond to the directory the running
 175                        plugin was loaded from.  It may be used by a plugin to
 176                        locate support files.
 177
 178                  preserve_environment=bool
 179                        Set to true if the user specified the -\b-E\bE flag,
 180                        indicating that the user wishes to preserve the
 181                        environment.
 182
 183                  preserve_groups=bool
 184                        Set to true if the user specified the -\b-P\bP flag,
 185                        indicating that the user wishes to preserve the group
 186                        vector instead of setting it based on the runas user.
 187
 188                  progname=string
 189                        The command name that sudo was run as, typically
 190                        ``sudo'' or ``sudoedit''.
 191
 192                  prompt=string
 193                        The prompt to use when requesting a password, if
 194                        specified via the -\b-p\bp flag.
 195
 196                  run_shell=bool
 197                        Set to true if the user specified the -\b-s\bs flag,
 198                        indicating that the user wishes to run a shell.
 199
 200                  runas_group=string
 201                        The group name or gid to to run the command as, if
 202                        specified via the -\b-g\bg flag.
 203
 204                  runas_user=string
 205                        The user name or uid to to run the command as, if
 206                        specified via the -\b-u\bu flag.
 207
 208                  selinux_role=string
 209                        SELinux role to use when executing the command, if
 210                        specified by the -\b-r\br flag.
 211
 212                  selinux_type=string
 213                        SELinux type to use when executing the command, if
 214                        specified by the -\b-t\bt flag.
 215
 216                  set_home=bool
 217                        Set to true if the user specified the -\b-H\bH flag.  If
 218                        true, set the HOME environment variable to the target
 219                        user's home directory.
 220
 221                  sudoedit=bool
 222                        Set to true when the -\b-e\be flag is is specified or if
 223                        invoked as s\bsu\bud\bdo\boe\bed\bdi\bit\bt.  The plugin shall substitute an
 224                        editor into _\ba_\br_\bg_\bv in the c\bch\bhe\bec\bck\bk_\b_p\bpo\bol\bli\bic\bcy\by() function or
 225                        return -2 with a usage error if the plugin does not
 226                        support _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt.  For more information, see the
 227                        _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by section.
 228
 229                  Additional settings may be added in the future so the plugin
 230                  should silently ignore settings that it does not recognize.
 231
 232            user_info
 233                  A vector of information about the user running the command in
 234                  the form of ``name=value'' strings.  The vector is terminated
 235                  by a NULL pointer.
 236
 237                  When parsing _\bu_\bs_\be_\br_\b__\bi_\bn_\bf_\bo, the plugin should split on the f\bfi\bir\brs\bst\bt
 238                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 239                  itself but the _\bv_\ba_\bl_\bu_\be might.
 240
 241                  cols=int
 242                        The number of columns the user's terminal supports.  If
 243                        there is no terminal device available, a default value
 244                        of 80 is used.
 245
 246                  cwd=string
 247                        The user's current working directory.
 248
 249                  egid=gid_t
 250                        The effective group ID of the user invoking s\bsu\bud\bdo\bo.
 251
 252                  euid=uid_t
 253                        The effective user ID of the user invoking s\bsu\bud\bdo\bo.
 254
 255                  gid=gid_t
 256                        The real group ID of the user invoking s\bsu\bud\bdo\bo.
 257
 258                  groups=list
 259                        The user's supplementary group list formatted as a
 260                        string of comma-separated group IDs.
 261
 262                  host=string
 263                        The local machine's hostname as returned by the
 264                        gethostname(2) system call.
 265
 266                  lines=int
 267                        The number of lines the user's terminal supports.  If
 268                        there is no terminal device available, a default value
 269                        of 24 is used.
 270
 271                  pgid=int
 272                        The ID of the process group that the running s\bsu\bud\bdo\bo
 273                        process is a member of.  Only available starting with
 274                        API version 1.2
 275
 276                  pid=int
 277                        The process ID of the running s\bsu\bud\bdo\bo process.  Only
 278                        available starting with API version 1.2
 279
 280                  plugin_options
 281                        Any (non-comment) strings immediately after the plugin
 282                        path are passed as arguments to the plugin.  These
 283                        arguments are split on a white space boundary and are
 284                        passed to the plugin in the form of a NULL-terminated
 285                        array of strings.  If no arguments were specified,
 286                        _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs will be the NULL pointer.
 287
 288                        NOTE: the _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs parameter is only available
 289                        starting with API version 1.2.  A plugin m\bmu\bus\bst\bt check the
 290                        API version specified by the s\bsu\bud\bdo\bo front end before
 291                        using _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs.  Failure to do so may result in a
 292                        crash.
 293
 294                  ppid=int
 295                        The parent process ID of the running s\bsu\bud\bdo\bo process.
 296                        Only available starting with API version 1.2
 297
 298                  sid=int
 299                        The session ID of the running s\bsu\bud\bdo\bo process or 0 if s\bsu\bud\bdo\bo
 300                        is not part of a POSIX job control session.  Only
 301                        available starting with API version 1.2
 302
 303                  tcpgid=int
 304                        The ID of the foreground process group associated with
 305                        the terminal device associated with the s\bsu\bud\bdo\bo process or
 306                        -1 if there is no terminal present.  Only available
 307                        starting with API version 1.2
 308
 309                  tty=string
 310                        The path to the user's terminal device.  If the user
 311                        has no terminal device associated with the session, the
 312                        value will be empty, as in ``tty=''.
 313
 314                  uid=uid_t
 315                        The real user ID of the user invoking s\bsu\bud\bdo\bo.
 316
 317                  user=string
 318                        The name of the user invoking s\bsu\bud\bdo\bo.
 319
 320            user_env
 321                  The user's environment in the form of a NULL-terminated
 322                  vector of ``name=value'' strings.
 323
 324                  When parsing _\bu_\bs_\be_\br_\b__\be_\bn_\bv, the plugin should split on the f\bfi\bir\brs\bst\bt
 325                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 326                  itself but the _\bv_\ba_\bl_\bu_\be might.
 327
 328      close
 329            void (*close)(int exit_status, int error);
 330
 331            The c\bcl\blo\bos\bse\be() function is called when the command being run by s\bsu\bud\bdo\bo
 332            finishes.
 333
 334            The function arguments are as follows:
 335
 336            exit_status
 337                  The command's exit status, as returned by the wait(2) system
 338                  call.  The value of exit_status is undefined if error is non-
 339                  zero.
 340
 341            error
 342                  If the command could not be executed, this is set to the
 343                  value of errno set by the execve(2) system call.  The plugin
 344                  is responsible for displaying error information via the
 345                  c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function.  If the command
 346                  was successfully executed, the value of error is 0.
 347
 348            If no c\bcl\blo\bos\bse\be() function is defined, no I/O logging plugins are
 349            loaded, and neither the _\bt_\bi_\bm_\be_\bo_\bu_\bt not _\bu_\bs_\be_\b__\bp_\bt_\by options are set in the
 350            command_info list, the s\bsu\bud\bdo\bo front end may execute the command
 351            directly instead of running it as a child process.
 352
 353      show_version
 354            int (*show_version)(int verbose);
 355
 356            The s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() function is called by s\bsu\bud\bdo\bo when the user
 357            specifies the -\b-V\bV option.  The plugin may display its version
 358            information to the user via the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
 359            function using SUDO_CONV_INFO_MSG.  If the user requests detailed
 360            version information, the verbose flag will be set.
 361
 362      check_policy
 363            int (*check_policy)(int argc, char * const argv[]
 364                                char *env_add[], char **command_info[],
 365                                char **argv_out[], char **user_env_out[]);
 366
 367            The c\bch\bhe\bec\bck\bk_\b_p\bpo\bol\bli\bic\bcy\by() function is called by s\bsu\bud\bdo\bo to determine whether
 368            the user is allowed to run the specified commands.
 369
 370            If the _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt option was enabled in the _\bs_\be_\bt_\bt_\bi_\bn_\bg_\bs array passed to
 371            the o\bop\bpe\ben\bn() function, the user has requested _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode.
 372            _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt is a mechanism for editing one or more files where an
 373            editor is run with the user's credentials instead of with elevated
 374            privileges.  s\bsu\bud\bdo\bo achieves this by creating user-writable temporary
 375            copies of the files to be edited and then overwriting the originals
 376            with the temporary copies after editing is complete.  If the plugin
 377            supports _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt, it should choose the editor to be used,
 378            potentially from a variable in the user's environment, such as
 379            EDITOR, and include it in _\ba_\br_\bg_\bv_\b__\bo_\bu_\bt (note that environment variables
 380            may include command line flags).  The files to be edited should be
 381            copied from _\ba_\br_\bg_\bv into _\ba_\br_\bg_\bv_\b__\bo_\bu_\bt, separated from the editor and its
 382            arguments by a ``--'' element.  The ``--'' will be removed by s\bsu\bud\bdo\bo
 383            before the editor is executed.  The plugin should also set
 384            _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt_\b=_\bt_\br_\bu_\be in the _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bi_\bn_\bf_\bo list.
 385
 386            The c\bch\bhe\bec\bck\bk_\b_p\bpo\bol\bli\bic\bcy\by() function returns 1 if the command is allowed, 0
 387            if not allowed, -1 for a general error, or -2 for a usage error or
 388            if _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt was specified but is unsupported by the plugin.  In the
 389            latter case, s\bsu\bud\bdo\bo will print a usage message before it exits.  If
 390            an error occurs, the plugin may optionally call the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn()
 391            or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function with SUDO_CONF_ERROR_MSG to present
 392            additional error information to the user.
 393
 394            The function arguments are as follows:
 395
 396            argc  The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
 397                  pointer.
 398
 399            argv  The argument vector describing the command the user wishes to
 400                  run, in the same form as what would be passed to the
 401                  execve(2) system call.  The vector is terminated by a NULL
 402                  pointer.
 403
 404            env_add
 405                  Additional environment variables specified by the user on the
 406                  command line in the form of a NULL-terminated vector of
 407                  ``name=value'' strings.  The plugin may reject the command if
 408                  one or more variables are not allowed to be set, or it may
 409                  silently ignore such variables.
 410
 411                  When parsing _\be_\bn_\bv_\b__\ba_\bd_\bd, the plugin should split on the f\bfi\bir\brs\bst\bt
 412                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 413                  itself but the _\bv_\ba_\bl_\bu_\be might.
 414
 415            command_info
 416                  Information about the command being run in the form of
 417                  ``name=value'' strings.  These values are used by s\bsu\bud\bdo\bo to set
 418                  the execution environment when running a command.  The plugin
 419                  is responsible for creating and populating the vector, which
 420                  must be terminated with a NULL pointer.  The following values
 421                  are recognized by s\bsu\bud\bdo\bo:
 422
 423                  chroot=string
 424                        The root directory to use when running the command.
 425
 426                  closefrom=number
 427                        If specified, s\bsu\bud\bdo\bo will close all files descriptors
 428                        with a value of _\bn_\bu_\bm_\bb_\be_\br or higher.
 429
 430                  command=string
 431                        Fully qualified path to the command to be executed.
 432
 433                  cwd=string
 434                        The current working directory to change to when
 435                        executing the command.
 436
 437                  exec_background=bool
 438                        By default, s\bsu\bud\bdo\bo runs a command as the foreground
 439                        process as long as s\bsu\bud\bdo\bo itself is running in the
 440                        foreground.  When _\be_\bx_\be_\bc_\b__\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd is enabled and the
 441                        command is being run in a pty (due to I/O logging or
 442                        the _\bu_\bs_\be_\b__\bp_\bt_\by setting), the command will be run as a
 443                        background process.  Attempts to read from the
 444                        controlling terminal (or to change terminal settings)
 445                        will result in the command being suspended with the
 446                        SIGTTIN signal (or SIGTTOU in the case of terminal
 447                        settings).  If this happens when s\bsu\bud\bdo\bo is a foreground
 448                        process, the command will be granted the controlling
 449                        terminal and resumed in the foreground with no user
 450                        intervention required.  The advantage of initially
 451                        running the command in the background is that s\bsu\bud\bdo\bo need
 452                        not read from the terminal unless the command
 453                        explicitly requests it.  Otherwise, any terminal input
 454                        must be passed to the command, whether it has required
 455                        it or not (the kernel buffers terminals so it is not
 456                        possible to tell whether the command really wants the
 457                        input).  This is different from historic _\bs_\bu_\bd_\bo behavior
 458                        or when the command is not being run in a pty.
 459
 460                        For this to work seamlessly, the operating system must
 461                        support the automatic restarting of system calls.
 462                        Unfortunately, not all operating systems do this by
 463                        default, and even those that do may have bugs.  For
 464                        example, Mac OS X fails to restart the t\btc\bcg\bge\bet\bta\bat\btt\btr\br() and
 465                        t\btc\bcs\bse\bet\bta\bat\btt\btr\br() system calls (this is a bug in Mac OS X).
 466                        Furthermore, because this behavior depends on the
 467                        command stopping with the SIGTTIN or SIGTTOU signals,
 468                        programs that catch these signals and suspend
 469                        themselves with a different signal (usually SIGTOP)
 470                        will not be automatically foregrounded.  Some versions
 471                        of the linux su(1) command behave this way.  Because of
 472                        this, a plugin should not set _\be_\bx_\be_\bc_\b__\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd unless it
 473                        is explicitly enabled by the administrator and there
 474                        should be a way to enabled or disable it on a per-
 475                        command basis.
 476
 477                        This setting has no effect unless I/O logging is
 478                        enabled or _\bu_\bs_\be_\b__\bp_\bt_\by is enabled.
 479
 480                  iolog_compress=bool
 481                        Set to true if the I/O logging plugins, if any, should
 482                        compress the log data.  This is a hint to the I/O
 483                        logging plugin which may choose to ignore it.
 484
 485                  iolog_path=string
 486                        Fully qualified path to the file or directory in which
 487                        I/O log is to be stored.  This is a hint to the I/O
 488                        logging plugin which may choose to ignore it.  If no
 489                        I/O logging plugin is loaded, this setting has no
 490                        effect.
 491
 492                  iolog_stdin=bool
 493                        Set to true if the I/O logging plugins, if any, should
 494                        log the standard input if it is not connected to a
 495                        terminal device.  This is a hint to the I/O logging
 496                        plugin which may choose to ignore it.
 497
 498                  iolog_stdout=bool
 499                        Set to true if the I/O logging plugins, if any, should
 500                        log the standard output if it is not connected to a
 501                        terminal device.  This is a hint to the I/O logging
 502                        plugin which may choose to ignore it.
 503
 504                  iolog_stderr=bool
 505                        Set to true if the I/O logging plugins, if any, should
 506                        log the standard error if it is not connected to a
 507                        terminal device.  This is a hint to the I/O logging
 508                        plugin which may choose to ignore it.
 509
 510                  iolog_ttyin=bool
 511                        Set to true if the I/O logging plugins, if any, should
 512                        log all terminal input.  This only includes input typed
 513                        by the user and not from a pipe or redirected from a
 514                        file.  This is a hint to the I/O logging plugin which
 515                        may choose to ignore it.
 516
 517                  iolog_ttyout=bool
 518                        Set to true if the I/O logging plugins, if any, should
 519                        log all terminal output.  This only includes output to
 520                        the screen, not output to a pipe or file.  This is a
 521                        hint to the I/O logging plugin which may choose to
 522                        ignore it.
 523
 524                  login_class=string
 525                        BSD login class to use when setting resource limits and
 526                        nice value (optional).  This option is only set on
 527                        systems that support login classes.
 528
 529                  nice=int
 530                        Nice value (priority) to use when executing the
 531                        command.  The nice value, if specified, overrides the
 532                        priority associated with the _\bl_\bo_\bg_\bi_\bn_\b__\bc_\bl_\ba_\bs_\bs on BSD
 533                        systems.
 534
 535                  noexec=bool
 536                        If set, prevent the command from executing other
 537                        programs.
 538
 539                  preserve_groups=bool
 540                        If set, s\bsu\bud\bdo\bo will preserve the user's group vector
 541                        instead of initializing the group vector based on
 542                        runas_user.
 543
 544                  runas_egid=gid
 545                        Effective group ID to run the command as.  If not
 546                        specified, the value of _\br_\bu_\bn_\ba_\bs_\b__\bg_\bi_\bd is used.
 547
 548                  runas_euid=uid
 549                        Effective user ID to run the command as.  If not
 550                        specified, the value of _\br_\bu_\bn_\ba_\bs_\b__\bu_\bi_\bd is used.
 551
 552                  runas_gid=gid
 553                        Group ID to run the command as.
 554
 555                  runas_groups=list
 556                        The supplementary group vector to use for the command
 557                        in the form of a comma-separated list of group IDs.  If
 558                        _\bp_\br_\be_\bs_\be_\br_\bv_\be_\b__\bg_\br_\bo_\bu_\bp_\bs is set, this option is ignored.
 559
 560                  runas_uid=uid
 561                        User ID to run the command as.
 562
 563                  selinux_role=string
 564                        SELinux role to use when executing the command.
 565
 566                  selinux_type=string
 567                        SELinux type to use when executing the command.
 568
 569                  set_utmp=bool
 570                        Create a utmp (or utmpx) entry when a pseudo-tty is
 571                        allocated.  By default, the new entry will be a copy of
 572                        the user's existing utmp entry (if any), with the tty,
 573                        time, type and pid fields updated.
 574
 575                  sudoedit=bool
 576                        Set to true when in _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode.  The plugin may
 577                        enable _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode even if s\bsu\bud\bdo\bo was not invoked as
 578                        s\bsu\bud\bdo\boe\bed\bdi\bit\bt.  This allows the plugin to perform command
 579                        substitution and transparently enable _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt when the
 580                        user attempts to run an editor.
 581
 582                  timeout=int
 583                        Command timeout.  If non-zero then when the timeout
 584                        expires the command will be killed.
 585
 586                  umask=octal
 587                        The file creation mask to use when executing the
 588                        command.
 589
 590                  use_pty=bool
 591                        Allocate a pseudo-tty to run the command in, regardless
 592                        of whether or not I/O logging is in use.  By default,
 593                        s\bsu\bud\bdo\bo will only run the command in a pty when an I/O log
 594                        plugin is loaded.
 595
 596                  utmp_user=string
 597                        User name to use when constructing a new utmp (or
 598                        utmpx) entry when _\bs_\be_\bt_\b__\bu_\bt_\bm_\bp is enabled.  This option can
 599                        be used to set the user field in the utmp entry to the
 600                        user the command runs as rather than the invoking user.
 601                        If not set, s\bsu\bud\bdo\bo will base the new entry on the
 602                        invoking user's existing entry.
 603
 604                  Unsupported values will be ignored.
 605
 606            argv_out
 607                  The NULL-terminated argument vector to pass to the execve(2)
 608                  system call when executing the command.  The plugin is
 609                  responsible for allocating and populating the vector.
 610
 611            user_env_out
 612                  The NULL-terminated environment vector to use when executing
 613                  the command.  The plugin is responsible for allocating and
 614                  populating the vector.
 615
 616      list
 617            int (*list)(int verbose, const char *list_user,
 618                        int argc, char * const argv[]);
 619
 620            List available privileges for the invoking user.  Returns 1 on
 621            success, 0 on failure and -1 on error.  On error, the plugin may
 622            optionally call the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function with
 623            SUDO_CONF_ERROR_MSG to present additional error information to the
 624            user.
 625
 626            Privileges should be output via the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or
 627            p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function using SUDO_CONV_INFO_MSG,
 628
 629            verbose
 630                  Flag indicating whether to list in verbose mode or not.
 631
 632            list_user
 633                  The name of a different user to list privileges for if the
 634                  policy allows it.  If NULL, the plugin should list the
 635                  privileges of the invoking user.
 636
 637            argc  The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
 638                  pointer.
 639
 640            argv  If non-NULL, an argument vector describing a command the user
 641                  wishes to check against the policy in the same form as what
 642                  would be passed to the execve(2) system call.  If the command
 643                  is permitted by the policy, the fully-qualified path to the
 644                  command should be displayed along with any command line
 645                  arguments.
 646
 647      validate
 648            int (*validate)(void);
 649
 650            The v\bva\bal\bli\bid\bda\bat\bte\be() function is called when s\bsu\bud\bdo\bo is run with the -\b-v\bv
 651            flag.  For policy plugins such as s\bsu\bud\bdo\boe\ber\brs\bs that cache authentication
 652            credentials, this function will validate and cache the credentials.
 653
 654            The v\bva\bal\bli\bid\bda\bat\bte\be() function should be NULL if the plugin does not
 655            support credential caching.
 656
 657            Returns 1 on success, 0 on failure and -1 on error.  On error, the
 658            plugin may optionally call the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
 659            function with SUDO_CONF_ERROR_MSG to present additional error
 660            information to the user.
 661
 662      invalidate
 663            void (*invalidate)(int remove);
 664
 665            The i\bin\bnv\bva\bal\bli\bid\bda\bat\bte\be() function is called when s\bsu\bud\bdo\bo is called with the -\b-k\bk
 666            or -\b-K\bK flag.  For policy plugins such as s\bsu\bud\bdo\boe\ber\brs\bs that cache
 667            authentication credentials, this function will invalidate the
 668            credentials.  If the _\br_\be_\bm_\bo_\bv_\be flag is set, the plugin may remove the
 669            credentials instead of simply invalidating them.
 670
 671            The i\bin\bnv\bva\bal\bli\bid\bda\bat\bte\be() function should be NULL if the plugin does not
 672            support credential caching.
 673
 674      init_session
 675            int (*init_session)(struct passwd *pwd, char **user_envp[);
 676
 677            The i\bin\bni\bit\bt_\b_s\bse\bes\bss\bsi\bio\bon\bn() function is called before s\bsu\bud\bdo\bo sets up the
 678            execution environment for the command.  It is run in the parent
 679            s\bsu\bud\bdo\bo process and before any uid or gid changes.  This can be used
 680            to perform session setup that is not supported by _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bi_\bn_\bf_\bo,
 681            such as opening the PAM session.  The c\bcl\blo\bos\bse\be() function can be used
 682            to tear down the session that was opened by init_session.
 683
 684            The _\bp_\bw_\bd argument points to a passwd struct for the user the command
 685            will be run as if the uid the command will run as was found in the
 686            password database, otherwise it will be NULL.
 687
 688            The _\bu_\bs_\be_\br_\b__\be_\bn_\bv argument points to the environment the command will
 689            run in, in the form of a NULL-terminated vector of ``name=value''
 690            strings.  This is the same string passed back to the front end via
 691            the Policy Plugin's _\bu_\bs_\be_\br_\b__\be_\bn_\bv_\b__\bo_\bu_\bt parameter.  If the i\bin\bni\bit\bt_\b_s\bse\bes\bss\bsi\bio\bon\bn()
 692            function needs to modify the user environment, it should update the
 693            pointer stored in _\bu_\bs_\be_\br_\b__\be_\bn_\bv.  The expected use case is to merge the
 694            contents of the PAM environment (if any) with the contents of
 695            _\bu_\bs_\be_\br_\b__\be_\bn_\bv.  NOTE: the _\bu_\bs_\be_\br_\b__\be_\bn_\bv parameter is only available starting
 696            with API version 1.2.  A plugin m\bmu\bus\bst\bt check the API version
 697            specified by the s\bsu\bud\bdo\bo front end before using _\bu_\bs_\be_\br_\b__\be_\bn_\bv.  Failure to
 698            do so may result in a crash.
 699
 700            Returns 1 on success, 0 on failure and -1 on error.  On error, the
 701            plugin may optionally call the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
 702            function with SUDO_CONF_ERROR_MSG to present additional error
 703            information to the user.
 704
 705      register_hooks
 706            void (*register_hooks)(int version,
 707               int (*register_hook)(struct sudo_hook *hook));
 708
 709            The r\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bks\bs() function is called by the sudo front end to
 710            register any hooks the plugin needs.  If the plugin does not
 711            support hooks, register_hooks should be set to the NULL pointer.
 712
 713            The _\bv_\be_\br_\bs_\bi_\bo_\bn argument describes the version of the hooks API
 714            supported by the s\bsu\bud\bdo\bo front end.
 715
 716            The r\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bk() function should be used to register any
 717            supported hooks the plugin needs.  It returns 0 on success, 1 if
 718            the hook type is not supported and -1 if the major version in
 719            struct hook does not match the front end's major hook API version.
 720
 721            See the _\bH_\bo_\bo_\bk _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bA_\bP_\bI section below for more information about
 722            hooks.
 723
 724            NOTE: the r\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bks\bs() function is only available starting with
 725            API version 1.2.  If the s\bsu\bud\bdo\bo front end doesn't support API version
 726            1.2 or higher, register_hooks will not be called.
 727
 728      deregister_hooks
 729            void (*deregister_hooks)(int version,
 730               int (*deregister_hook)(struct sudo_hook *hook));
 731
 732            The d\bde\ber\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bks\bs() function is called by the sudo front end to
 733            deregister any hooks the plugin has registered.  If the plugin does
 734            not support hooks, deregister_hooks should be set to the NULL
 735            pointer.
 736
 737            The _\bv_\be_\br_\bs_\bi_\bo_\bn argument describes the version of the hooks API
 738            supported by the s\bsu\bud\bdo\bo front end.
 739
 740            The d\bde\ber\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bk() function should be used to deregister any
 741            hooks that were put in place by the r\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bk() function.  If
 742            the plugin tries to deregister a hook that the front end does not
 743            support, deregister_hook will return an error.
 744
 745            See the _\bH_\bo_\bo_\bk _\bf_\bu_\bn_\bc_\bt_\bi_\bo_\bn _\bA_\bP_\bI section below for more information about
 746            hooks.
 747
 748            NOTE: the d\bde\ber\bre\beg\bgi\bis\bst\bte\ber\br_\b_h\bho\boo\bok\bks\bs() function is only available starting
 749            with API version 1.2.  If the s\bsu\bud\bdo\bo front end doesn't support API
 750            version 1.2 or higher, deregister_hooks will not be called.
 751
 752      _\bP_\bo_\bl_\bi_\bc_\by _\bP_\bl_\bu_\bg_\bi_\bn _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
 753
 754      /* Plugin API version major/minor. */
 755      #define SUDO_API_VERSION_MAJOR 1
 756      #define SUDO_API_VERSION_MINOR 2
 757      #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
 758      #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
 759                                                  SUDO_API_VERSION_MINOR)
 760
 761      /* Getters and setters for API version */
 762      #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
 763      #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
 764      #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
 765          *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
 766      } while(0)
 767      #define SUDO_VERSION_SET_MINOR(vp, n) do { \
 768          *(vp) = (*(vp) & 0xffff0000) | (n); \
 769      } while(0)
 770
 771    I\bI/\b/O\bO p\bpl\blu\bug\bgi\bin\bn A\bAP\bPI\bI
 772      struct io_plugin {
 773      #define SUDO_IO_PLUGIN 2
 774          unsigned int type; /* always SUDO_IO_PLUGIN */
 775          unsigned int version; /* always SUDO_API_VERSION */
 776          int (*open)(unsigned int version, sudo_conv_t conversation,
 777                      sudo_printf_t plugin_printf, char * const settings[],
 778                      char * const user_info[], char * const command_info[],
 779                      int argc, char * const argv[], char * const user_env[],
 780                      char * const plugin_options[]);
 781          void (*close)(int exit_status, int error); /* wait status or error */
 782          int (*show_version)(int verbose);
 783          int (*log_ttyin)(const char *buf, unsigned int len);
 784          int (*log_ttyout)(const char *buf, unsigned int len);
 785          int (*log_stdin)(const char *buf, unsigned int len);
 786          int (*log_stdout)(const char *buf, unsigned int len);
 787          int (*log_stderr)(const char *buf, unsigned int len);
 788          void (*register_hooks)(int version,
 789             int (*register_hook)(struct sudo_hook *hook));
 790          void (*deregister_hooks)(int version,
 791             int (*deregister_hook)(struct sudo_hook *hook));
 792      };
 793
 794      When an I/O plugin is loaded, s\bsu\bud\bdo\bo runs the command in a pseudo-tty.
 795      This makes it possible to log the input and output from the user's
 796      session.  If any of the standard input, standard output or standard error
 797      do not correspond to a tty, s\bsu\bud\bdo\bo will open a pipe to capture the I/O for
 798      logging before passing it on.
 799
 800      The log_ttyin function receives the raw user input from the terminal
 801      device (note that this will include input even when echo is disabled,
 802      such as when a password is read).  The log_ttyout function receives
 803      output from the pseudo-tty that is suitable for replaying the user's
 804      session at a later time.  The l\blo\bog\bg_\b_s\bst\btd\bdi\bin\bn(), l\blo\bog\bg_\b_s\bst\btd\bdo\bou\but\bt() and l\blo\bog\bg_\b_s\bst\btd\bde\ber\brr\br()
 805      functions are only called if the standard input, standard output or
 806      standard error respectively correspond to something other than a tty.
 807
 808      Any of the logging functions may be set to the NULL pointer if no logging
 809      is to be performed.  If the open function returns 0, no I/O will be sent
 810      to the plugin.
 811
 812      The io_plugin struct has the following fields:
 813
 814      type  The type field should always be set to SUDO_IO_PLUGIN.
 815
 816      version
 817            The version field should be set to SUDO_API_VERSION.
 818
 819            This allows s\bsu\bud\bdo\bo to determine the API version the plugin was built
 820            against.
 821
 822      open
 823            int (*open)(unsigned int version, sudo_conv_t conversation,
 824                        sudo_printf_t plugin_printf, char * const settings[],
 825                        char * const user_info[], int argc, char * const argv[],
 826                        char * const user_env[], char * const plugin_options[]);
 827
 828            The o\bop\bpe\ben\bn() function is run before the l\blo\bog\bg_\b_i\bin\bnp\bpu\but\bt(), l\blo\bog\bg_\b_o\bou\but\btp\bpu\but\bt() or
 829            s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() functions are called.  It is only called if the
 830            version is being requested or the c\bch\bhe\bec\bck\bk_\b_p\bpo\bol\bli\bic\bcy\by() function has
 831            returned successfully.  It returns 1 on success, 0 on failure, -1
 832            if a general error occurred, or -2 if there was a usage error.  In
 833            the latter case, s\bsu\bud\bdo\bo will print a usage message before it exits.
 834            If an error occurs, the plugin may optionally call the
 835            c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function with SUDO_CONF_ERROR_MSG
 836            to present additional error information to the user.
 837
 838            The function arguments are as follows:
 839
 840            version
 841                  The version passed in by s\bsu\bud\bdo\bo allows the plugin to determine
 842                  the major and minor version number of the plugin API
 843                  supported by s\bsu\bud\bdo\bo.
 844
 845            conversation
 846                  A pointer to the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function that may be used by
 847                  the s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() function to display version information
 848                  (see s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() below).  The c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function may
 849                  also be used to display additional error message to the user.
 850                  The c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function returns 0 on success and -1 on
 851                  failure.
 852
 853            plugin_printf
 854                  A pointer to a p\bpr\bri\bin\bnt\btf\bf()-style function that may be used by
 855                  the s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() function to display version information
 856                  (see show_version below).  The p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function may
 857                  also be used to display additional error message to the user.
 858                  The p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf() function returns number of characters
 859                  printed on success and -1 on failure.
 860
 861            settings
 862                  A vector of user-supplied s\bsu\bud\bdo\bo settings in the form of
 863                  ``name=value'' strings.  The vector is terminated by a NULL
 864                  pointer.  These settings correspond to flags the user
 865                  specified when running s\bsu\bud\bdo\bo.  As such, they will only be
 866                  present when the corresponding flag has been specified on the
 867                  command line.
 868
 869                  When parsing _\bs_\be_\bt_\bt_\bi_\bn_\bg_\bs, the plugin should split on the f\bfi\bir\brs\bst\bt
 870                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 871                  itself but the _\bv_\ba_\bl_\bu_\be might.
 872
 873                  See the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI section for a list of all possible
 874                  settings.
 875
 876            user_info
 877                  A vector of information about the user running the command in
 878                  the form of ``name=value'' strings.  The vector is terminated
 879                  by a NULL pointer.
 880
 881                  When parsing _\bu_\bs_\be_\br_\b__\bi_\bn_\bf_\bo, the plugin should split on the f\bfi\bir\brs\bst\bt
 882                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 883                  itself but the _\bv_\ba_\bl_\bu_\be might.
 884
 885                  See the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI section for a list of all possible
 886                  strings.
 887
 888            argc  The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
 889                  pointer.
 890
 891            argv  If non-NULL, an argument vector describing a command the user
 892                  wishes to run in the same form as what would be passed to the
 893                  execve(2) system call.
 894
 895            user_env
 896                  The user's environment in the form of a NULL-terminated
 897                  vector of ``name=value'' strings.
 898
 899                  When parsing _\bu_\bs_\be_\br_\b__\be_\bn_\bv, the plugin should split on the f\bfi\bir\brs\bst\bt
 900                  equal sign (`=') since the _\bn_\ba_\bm_\be field will never include one
 901                  itself but the _\bv_\ba_\bl_\bu_\be might.
 902
 903            plugin_options
 904                  Any (non-comment) strings immediately after the plugin path
 905                  are treated as arguments to the plugin.  These arguments are
 906                  split on a white space boundary and are passed to the plugin
 907                  in the form of a NULL-terminated array of strings.  If no
 908                  arguments were specified, _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs will be the NULL
 909                  pointer.
 910
 911                  NOTE: the _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs parameter is only available starting
 912                  with API version 1.2.  A plugin m\bmu\bus\bst\bt check the API version
 913                  specified by the s\bsu\bud\bdo\bo front end before using _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs.
 914                  Failure to do so may result in a crash.
 915
 916      close
 917            void (*close)(int exit_status, int error);
 918
 919            The c\bcl\blo\bos\bse\be() function is called when the command being run by s\bsu\bud\bdo\bo
 920            finishes.
 921
 922            The function arguments are as follows:
 923
 924            exit_status
 925                  The command's exit status, as returned by the wait(2) system
 926                  call.  The value of exit_status is undefined if error is non-
 927                  zero.
 928
 929            error
 930                  If the command could not be executed, this is set to the
 931                  value of errno set by the execve(2) system call.  If the
 932                  command was successfully executed, the value of error is 0.
 933
 934      show_version
 935            int (*show_version)(int verbose);
 936
 937            The s\bsh\bho\bow\bw_\b_v\bve\ber\brs\bsi\bio\bon\bn() function is called by s\bsu\bud\bdo\bo when the user
 938            specifies the -\b-V\bV option.  The plugin may display its version
 939            information to the user via the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() or p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
 940            function using SUDO_CONV_INFO_MSG.  If the user requests detailed
 941            version information, the verbose flag will be set.
 942
 943      log_ttyin
 944            int (*log_ttyin)(const char *buf, unsigned int len);
 945
 946            The l\blo\bog\bg_\b_t\btt\bty\byi\bin\bn() function is called whenever data can be read from
 947            the user but before it is passed to the running command.  This
 948            allows the plugin to reject data if it chooses to (for instance if
 949            the input contains banned content).  Returns 1 if the data should
 950            be passed to the command, 0 if the data is rejected (which will
 951            terminate the command) or -1 if an error occurred.
 952
 953            The function arguments are as follows:
 954
 955            buf   The buffer containing user input.
 956
 957            len   The length of _\bb_\bu_\bf in bytes.
 958
 959      log_ttyout
 960            int (*log_ttyout)(const char *buf, unsigned int len);
 961
 962            The l\blo\bog\bg_\b_t\btt\bty\byo\bou\but\bt() function is called whenever data can be read from
 963            the command but before it is written to the user's terminal.  This
 964            allows the plugin to reject data if it chooses to (for instance if
 965            the output contains banned content).  Returns 1 if the data should
 966            be passed to the user, 0 if the data is rejected (which will
 967            terminate the command) or -1 if an error occurred.
 968
 969            The function arguments are as follows:
 970
 971            buf   The buffer containing command output.
 972
 973            len   The length of _\bb_\bu_\bf in bytes.
 974
 975      log_stdin
 976            int (*log_stdin)(const char *buf, unsigned int len);
 977
 978            The l\blo\bog\bg_\b_s\bst\btd\bdi\bin\bn() function is only used if the standard input does
 979            not correspond to a tty device.  It is called whenever data can be
 980            read from the standard input but before it is passed to the running
 981            command.  This allows the plugin to reject data if it chooses to
 982            (for instance if the input contains banned content).  Returns 1 if
 983            the data should be passed to the command, 0 if the data is rejected
 984            (which will terminate the command) or -1 if an error occurred.
 985
 986            The function arguments are as follows:
 987
 988            buf   The buffer containing user input.
 989
 990            len   The length of _\bb_\bu_\bf in bytes.
 991
 992      log_stdout
 993            int (*log_stdout)(const char *buf, unsigned int len);
 994
 995            The l\blo\bog\bg_\b_s\bst\btd\bdo\bou\but\bt() function is only used if the standard output does
 996            not correspond to a tty device.  It is called whenever data can be
 997            read from the command but before it is written to the standard
 998            output.  This allows the plugin to reject data if it chooses to
 999            (for instance if the output contains banned content).  Returns 1 if
1000            the data should be passed to the user, 0 if the data is rejected
1001            (which will terminate the command) or -1 if an error occurred.
1002
1003            The function arguments are as follows:
1004
1005            buf   The buffer containing command output.
1006
1007            len   The length of _\bb_\bu_\bf in bytes.
1008
1009      log_stderr
1010            int (*log_stderr)(const char *buf, unsigned int len);
1011
1012            The l\blo\bog\bg_\b_s\bst\btd\bde\ber\brr\br() function is only used if the standard error does
1013            not correspond to a tty device.  It is called whenever data can be
1014            read from the command but before it is written to the standard
1015            error.  This allows the plugin to reject data if it chooses to (for
1016            instance if the output contains banned content).  Returns 1 if the
1017            data should be passed to the user, 0 if the data is rejected (which
1018            will terminate the command) or -1 if an error occurred.
1019
1020            The function arguments are as follows:
1021
1022            buf   The buffer containing command output.
1023
1024            len   The length of _\bb_\bu_\bf in bytes.
1025
1026      register_hooks
1027            See the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI section for a description of
1028            register_hooks.
1029
1030      deregister_hooks
1031            See the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI section for a description of
1032            deregister_hooks.
1033
1034      _\bI_\b/_\bO _\bP_\bl_\bu_\bg_\bi_\bn _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
1035
1036      Same as for the _\bP_\bo_\bl_\bi_\bc_\by _\bp_\bl_\bu_\bg_\bi_\bn _\bA_\bP_\bI.
1037
1038    S\bSi\big\bgn\bna\bal\bl h\bha\ban\bnd\bdl\ble\ber\brs\bs
1039      The s\bsu\bud\bdo\bo front end installs default signal handlers to trap common
1040      signals while the plugin functions are run.  The following signals are
1041      trapped by default before the command is executed:
1042
1043      o\bo   SIGALRM
1044      o\bo   SIGHUP
1045      o\bo   SIGINT
1046      o\bo   SIGQUIT
1047      o\bo   SIGTERM
1048      o\bo   SIGTSTP
1049      o\bo   SIGUSR1
1050      o\bo   SIGUSR2
1051
1052      If a fatal signal is received before the command is executed, s\bsu\bud\bdo\bo will
1053      call the plugin's c\bcl\blo\bos\bse\be() function with an exit status of 128 plus the
1054      value of the signal that was received.  This allows for consistent
1055      logging of commands killed by a signal for plugins that log such
1056      information in their c\bcl\blo\bos\bse\be() function.
1057
1058      A plugin may temporarily install its own signal handlers but must restore
1059      the original handler before the plugin function returns.
1060
1061    H\bHo\boo\bok\bk f\bfu\bun\bnc\bct\bti\bio\bon\bn A\bAP\bPI\bI
1062      Beginning with plugin API version 1.2, it is possible to install hooks
1063      for certain functions called by the s\bsu\bud\bdo\bo front end.
1064
1065      Currently, the only supported hooks relate to the handling of environment
1066      variables.  Hooks can be used to intercept attempts to get, set, or
1067      remove environment variables so that these changes can be reflected in
1068      the version of the environment that is used to execute a command.  A
1069      future version of the API will support hooking internal s\bsu\bud\bdo\bo front end
1070      functions as well.
1071
1072      _\bH_\bo_\bo_\bk _\bs_\bt_\br_\bu_\bc_\bt_\bu_\br_\be
1073
1074      Hooks in s\bsu\bud\bdo\bo are described by the following structure:
1075
1076      typedef int (*sudo_hook_fn_t)();
1077
1078      struct sudo_hook {
1079          int hook_version;
1080          int hook_type;
1081          sudo_hook_fn_t hook_fn;
1082          void *closure;
1083      };
1084
1085      The sudo_hook structure has the following fields:
1086
1087      hook_version
1088            The hook_version field should be set to SUDO_HOOK_VERSION.
1089
1090      hook_type
1091            The hook_type field may be one of the following supported hook
1092            types:
1093
1094            SUDO_HOOK_SETENV
1095                  The C library setenv(3) function.  Any registered hooks will
1096                  run before the C library implementation.  The hook_fn field
1097                  should be a function that matches the following typedef:
1098
1099                  typedef int (*sudo_hook_fn_setenv_t)(const char *name,
1100                     const char *value, int overwrite, void *closure);
1101
1102                  If the registered hook does not match the typedef the results
1103                  are unspecified.
1104
1105            SUDO_HOOK_UNSETENV
1106                  The C library unsetenv(3) function.  Any registered hooks
1107                  will run before the C library implementation.  The hook_fn
1108                  field should be a function that matches the following
1109                  typedef:
1110
1111                  typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
1112                     void *closure);
1113
1114            SUDO_HOOK_GETENV
1115                  The C library getenv(3) function.  Any registered hooks will
1116                  run before the C library implementation.  The hook_fn field
1117                  should be a function that matches the following typedef:
1118
1119                  typedef int (*sudo_hook_fn_getenv_t)(const char *name,
1120                     char **value, void *closure);
1121
1122                  If the registered hook does not match the typedef the results
1123                  are unspecified.
1124
1125            SUDO_HOOK_PUTENV
1126                  The C library putenv(3) function.  Any registered hooks will
1127                  run before the C library implementation.  The hook_fn field
1128                  should be a function that matches the following typedef:
1129
1130                  typedef int (*sudo_hook_fn_putenv_t)(char *string,
1131                     void *closure);
1132
1133                  If the registered hook does not match the typedef the results
1134                  are unspecified.
1135
1136      hook_fn
1137            sudo_hook_fn_t hook_fn;
1138
1139            The hook_fn field should be set to the plugin's hook
1140            implementation.  The actual function arguments will vary depending
1141            on the hook_type (see hook_type above).  In all cases, the closure
1142            field of struct sudo_hook is passed as the last function parameter.
1143            This can be used to pass arbitrary data to the plugin's hook
1144            implementation.
1145
1146            The function return value may be one of the following:
1147
1148            SUDO_HOOK_RET_ERROR
1149                  The hook function encountered an error.
1150
1151            SUDO_HOOK_RET_NEXT
1152                  The hook completed without error, go on to the next hook
1153                  (including the native implementation if applicable).  For
1154                  example, a getenv(3) hook might return SUDO_HOOK_RET_NEXT if
1155                  the specified variable was not found in the private copy of
1156                  the environment.
1157
1158            SUDO_HOOK_RET_STOP
1159                  The hook completed without error, stop processing hooks for
1160                  this invocation.  This can be used to replace the native
1161                  implementation.  For example, a setenv hook that operates on
1162                  a private copy of the environment but leaves environ
1163                  unchanged.
1164
1165      Note that it is very easy to create an infinite loop when hooking C
1166      library functions.  For example, a getenv(3) hook that calls the
1167      snprintf(3) function may create a loop if the snprintf(3) implementation
1168      calls getenv(3) to check the locale.  To prevent this, you may wish to
1169      use a static variable in the hook function to guard against nested calls.
1170      For example:
1171
1172      static int in_progress = 0; /* avoid recursion */
1173      if (in_progress)
1174          return SUDO_HOOK_RET_NEXT;
1175      in_progress = 1;
1176      ...
1177      in_progress = 0;
1178      return SUDO_HOOK_RET_STOP;
1179
1180      _\bH_\bo_\bo_\bk _\bA_\bP_\bI _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
1181
1182      /* Hook API version major/minor */
1183      #define SUDO_HOOK_VERSION_MAJOR 1
1184      #define SUDO_HOOK_VERSION_MINOR 0
1185      #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
1186      #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
1187                                                    SUDO_HOOK_VERSION_MINOR)
1188
1189      /* Getters and setters for hook API version */
1190      #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
1191      #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
1192      #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \
1193          *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1194      } while(0)
1195      #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \
1196          *(vp) = (*(vp) & 0xffff0000) | (n); \
1197      } while(0)
1198
1199    C\bCo\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn A\bAP\bPI\bI
1200      If the plugin needs to interact with the user, it may do so via the
1201      c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function.  A plugin should not attempt to read directly
1202      from the standard input or the user's tty (neither of which are
1203      guaranteed to exist).  The caller must include a trailing newline in msg
1204      if one is to be printed.
1205
1206      A p\bpr\bri\bin\bnt\btf\bf()-style function is also available that can be used to display
1207      informational or error messages to the user, which is usually more
1208      convenient for simple messages where no use input is required.
1209
1210      struct sudo_conv_message {
1211      #define SUDO_CONV_PROMPT_ECHO_OFF  0x0001 /* do not echo user input */
1212      #define SUDO_CONV_PROMPT_ECHO_ON   0x0002 /* echo user input */
1213      #define SUDO_CONV_ERROR_MSG        0x0003 /* error message */
1214      #define SUDO_CONV_INFO_MSG         0x0004 /* informational message */
1215      #define SUDO_CONV_PROMPT_MASK      0x0005 /* mask user input */
1216      #define SUDO_CONV_DEBUG_MSG        0x0006 /* debugging message */
1217      #define SUDO_CONV_PROMPT_ECHO_OK   0x1000 /* flag: allow echo if no tty */
1218          int msg_type;
1219          int timeout;
1220          const char *msg;
1221      };
1222
1223      struct sudo_conv_reply {
1224          char *reply;
1225      };
1226
1227      typedef int (*sudo_conv_t)(int num_msgs,
1228                   const struct sudo_conv_message msgs[],
1229                   struct sudo_conv_reply replies[]);
1230
1231      typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
1232
1233      Pointers to the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() and p\bpr\bri\bin\bnt\btf\bf()-style functions are passed in
1234      to the plugin's o\bop\bpe\ben\bn() function when the plugin is initialized.
1235
1236      To use the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function, the plugin must pass an array of
1237      sudo_conv_message and sudo_conv_reply structures.  There must be a struct
1238      sudo_conv_message and struct sudo_conv_reply for each message in the
1239      conversation.  The plugin is responsible for freeing the reply buffer
1240      filled in to the struct sudo_conv_reply, if any.
1241
1242      The p\bpr\bri\bin\bnt\btf\bf()-style function uses the same underlying mechanism as the
1243      c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function but only supports SUDO_CONV_INFO_MSG,
1244      SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _\bm_\bs_\bg_\b__\bt_\by_\bp_\be parameter.
1245      It can be more convenient than using the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function if no
1246      user reply is needed and supports standard p\bpr\bri\bin\bnt\btf\bf() escape sequences.
1247
1248      Unlike, SUDO_CONV_INFO_MSG and Dv SUDO_CONV_ERROR_MSG , messages sent
1249      with the SUDO_CONV_DEBUG_MSG _\bm_\bs_\bg_\b__\bt_\by_\bp_\be are not directly user-visible.
1250      Instead, they are logged to the file specified in the Debug statement (if
1251      any) in the sudo.conf(4).  file.  This allows a plugin to log debugging
1252      information and is intended to be used in conjunction with the
1253      _\bd_\be_\bb_\bu_\bg_\b__\bf_\bl_\ba_\bg_\bs setting.
1254
1255      See the sample plugin for an example of the c\bco\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn() function
1256      usage.
1257
1258    S\bSu\bud\bdo\boe\ber\brs\bs g\bgr\bro\bou\bup\bp p\bpl\blu\bug\bgi\bin\bn A\bAP\bPI\bI
1259      The s\bsu\bud\bdo\boe\ber\brs\bs plugin supports its own plugin interface to allow non-Unix
1260      group lookups.  This can be used to query a group source other than the
1261      standard Unix group database.  Two sample group plugins are bundled with
1262      s\bsu\bud\bdo\bo, _\bg_\br_\bo_\bu_\bp_\b__\bf_\bi_\bl_\be and _\bs_\by_\bs_\bt_\be_\bm_\b__\bg_\br_\bo_\bu_\bp, are detailed in sudoers(4).  Third
1263      party group plugins include a QAS AD plugin available from Quest
1264      Software.
1265
1266      A group plugin must declare and populate a sudoers_group_plugin struct in
1267      the global scope.  This structure contains pointers to the functions that
1268      implement plugin initialization, cleanup and group lookup.
1269
1270      struct sudoers_group_plugin {
1271         unsigned int version;
1272         int (*init)(int version, sudo_printf_t sudo_printf,
1273                     char *const argv[]);
1274         void (*cleanup)(void);
1275         int (*query)(const char *user, const char *group,
1276                      const struct passwd *pwd);
1277      };
1278
1279      The sudoers_group_plugin struct has the following fields:
1280
1281      version
1282            The version field should be set to GROUP_API_VERSION.
1283
1284            This allows s\bsu\bud\bdo\boe\ber\brs\bs to determine the API version the group plugin
1285            was built against.
1286
1287      init
1288            int (*init)(int version, sudo_printf_t plugin_printf,
1289                        char *const argv[]);
1290
1291            The i\bin\bni\bit\bt() function is called after _\bs_\bu_\bd_\bo_\be_\br_\bs has been parsed but
1292            before any policy checks.  It returns 1 on success, 0 on failure
1293            (or if the plugin is not configured), and -1 if a error occurred.
1294            If an error occurs, the plugin may call the p\bpl\blu\bug\bgi\bin\bn_\b_p\bpr\bri\bin\bnt\btf\bf()
1295            function with SUDO_CONF_ERROR_MSG to present additional error
1296            information to the user.
1297
1298            The function arguments are as follows:
1299
1300            version
1301                  The version passed in by s\bsu\bud\bdo\boe\ber\brs\bs allows the plugin to
1302                  determine the major and minor version number of the group
1303                  plugin API supported by s\bsu\bud\bdo\boe\ber\brs\bs.
1304
1305            plugin_printf
1306                  A pointer to a p\bpr\bri\bin\bnt\btf\bf()-style function that may be used to
1307                  display informational or error message to the user.  Returns
1308                  the number of characters printed on success and -1 on
1309                  failure.
1310
1311            argv  A NULL-terminated array of arguments generated from the
1312                  _\bg_\br_\bo_\bu_\bp_\b__\bp_\bl_\bu_\bg_\bi_\bn option in _\bs_\bu_\bd_\bo_\be_\br_\bs.  If no arguments were given,
1313                  _\ba_\br_\bg_\bv will be NULL.
1314
1315      cleanup
1316            void (*cleanup)();
1317
1318            The c\bcl\ble\bea\ban\bnu\bup\bp() function is called when s\bsu\bud\bdo\boe\ber\brs\bs has finished its
1319            group checks.  The plugin should free any memory it has allocated
1320            and close open file handles.
1321
1322      query
1323            int (*query)(const char *user, const char *group,
1324                         const struct passwd *pwd);
1325
1326            The q\bqu\bue\ber\bry\by() function is used to ask the group plugin whether _\bu_\bs_\be_\br
1327            is a member of _\bg_\br_\bo_\bu_\bp.
1328
1329            The function arguments are as follows:
1330
1331            user  The name of the user being looked up in the external group
1332                  database.
1333
1334            group
1335                  The name of the group being queried.
1336
1337            pwd   The password database entry for _\bu_\bs_\be_\br, if any.  If _\bu_\bs_\be_\br is not
1338                  present in the password database, _\bp_\bw_\bd will be NULL.
1339
1340      _\bG_\br_\bo_\bu_\bp _\bA_\bP_\bI _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
1341
1342      /* Sudoers group plugin version major/minor */
1343      #define GROUP_API_VERSION_MAJOR 1
1344      #define GROUP_API_VERSION_MINOR 0
1345      #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
1346                                 GROUP_API_VERSION_MINOR)
1347
1348      /* Getters and setters for group version */
1349      #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
1350      #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
1351      #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
1352          *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
1353      } while(0)
1354      #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
1355          *(vp) = (*(vp) & 0xffff0000) | (n); \
1356      } while(0)
1357
1358 P\bPL\bLU\bUG\bGI\bIN\bN A\bAP\bPI\bI C\bCH\bHA\bAN\bNG\bGE\bEL\bLO\bOG\bG
1359      The following revisions have been made to the Sudo Plugin API.
1360
1361      Version 1.0
1362            Initial API version.
1363
1364      Version 1.1 (sudo 1.8.0)
1365            The I/O logging plugin's o\bop\bpe\ben\bn() function was modified to take the
1366            command_info list as an argument.
1367
1368      Version 1.2 (sudo 1.8.5)
1369            The Policy and I/O logging plugins' o\bop\bpe\ben\bn() functions are now passed
1370            a list of plugin parameters if any are specified in sudo.conf(4).
1371
1372            A simple hooks API has been introduced to allow plugins to hook in
1373            to the system's environment handling functions.
1374
1375            The init_session Policy plugin function is now passed a pointer to
1376            the user environment which can be updated as needed.  This can be
1377            used to merge in environment variables stored in the PAM handle
1378            before a command is run.
1379
1380      Version 1.3 (sudo 1.8.7)
1381            Support for the _\be_\bx_\be_\bc_\b__\bb_\ba_\bc_\bk_\bg_\br_\bo_\bu_\bn_\bd entry has been added to the
1382            command_info list.
1383
1384            The _\bm_\ba_\bx_\b__\bg_\br_\bo_\bu_\bp_\bs and _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bd_\bi_\br entries were added to the settings
1385            list.
1386
1387            The v\bve\ber\brs\bsi\bio\bon\bn() and c\bcl\blo\bos\bse\be() functions are now optional.  Previously,
1388            a missing v\bve\ber\brs\bsi\bio\bon\bn() or c\bcl\blo\bos\bse\be() function would result in a crash.
1389            If no policy plugin c\bcl\blo\bos\bse\be() function is defined, a default c\bcl\blo\bos\bse\be()
1390            function will be provided by the s\bsu\bud\bdo\bo front end that displays a
1391            warning if the command could not be executed.
1392
1393            The s\bsu\bud\bdo\bo front end now installs default signal handlers to trap
1394            common signals while the plugin functions are run.
1395
1396 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
1397      sudo.conf(4), sudoers(4), sudo(1m)
1398
1399 B\bBU\bUG\bGS\bS
1400      If you feel you have found a bug in s\bsu\bud\bdo\bo, please submit a bug report at
1401      http://www.sudo.ws/sudo/bugs/
1402
1403 S\bSU\bUP\bPP\bPO\bOR\bRT\bT
1404      Limited free support is available via the sudo-users mailing list, see
1405      http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the
1406      archives.
1407
1408 D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
1409      s\bsu\bud\bdo\bo is provided ``AS IS'' and any express or implied warranties,
1410      including, but not limited to, the implied warranties of merchantability
1411      and fitness for a particular purpose are disclaimed.  See the LICENSE
1412      file distributed with s\bsu\bud\bdo\bo or http://www.sudo.ws/sudo/license.html for
1413      complete details.
1414
1415 Sudo 1.8.7                       March 5, 2013                      Sudo 1.8.7