[BACK]Return to sudo_plugin.cat CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc

Diff for /embedaddon/sudo/doc/sudo_plugin.cat between versions 1.1.1.3 and 1.1.1.4

version 1.1.1.3, 2012/10/09 09:29:52 version 1.1.1.4, 2013/07/22 10:46:12
Line 5  NNAAMMEE Line 5  NNAAMMEE
   
 DDEESSCCRRIIPPTTIIOONN  DDEESSCCRRIIPPTTIIOONN
      Starting with version 1.8, ssuuddoo supports a plugin API for policy and       Starting with version 1.8, ssuuddoo supports a plugin API for policy and
     session logging.  By default, the _s_u_d_o_e_r_s policy plugin and an associated     session logging.  By default, the ssuuddooeerrss policy plugin and an associated
      I/O logging plugin are used.  Via the plugin API, ssuuddoo can be configured       I/O logging plugin are used.  Via the plugin API, ssuuddoo can be configured
      to use alternate policy and/or I/O logging plugins provided by third       to use alternate policy and/or I/O logging plugins provided by third
     parties.  The plugins to be used are specified via the _/_e_t_c_/_s_u_d_o_._c_o_n_f     parties.  The plugins to be used are specified in the sudo.conf(4) file.
     file. 
   
      The API is versioned with a major and minor number.  The minor version       The API is versioned with a major and minor number.  The minor version
      number is incremented when additions are made.  The major number is       number is incremented when additions are made.  The major number is
Line 18  DDEESSCCRRIIPPTTIIOONN Line 17  DDEESSCCRRIIPPTTIIOONN
   
      The plugin API is defined by the sudo_plugin.h header file.       The plugin API is defined by the sudo_plugin.h header file.
   
    TThhee ssuuddoo..ccoonnff ffiillee  
      The _/_e_t_c_/_s_u_d_o_._c_o_n_f file contains plugin configuration directives.  The  
      primary keyword is the Plugin directive, which causes a plugin to be  
      loaded.  
   
      A Plugin line consists of the Plugin keyword, followed by the _s_y_m_b_o_l___n_a_m_e  
      and the _p_a_t_h to the shared object containing the plugin.  The _s_y_m_b_o_l___n_a_m_e  
      is the name of the struct policy_plugin or struct io_plugin in the plugin  
      shared object.  The _p_a_t_h may be fully qualified or relative.  If not  
      fully qualified it is relative to the _/_u_s_r_/_l_o_c_a_l_/_l_i_b_e_x_e_c directory.  Any  
      additional parameters after the _p_a_t_h are passed as options to the  
      plugin's ooppeenn() function.  Lines that don't begin with Plugin, Path,  
      Debug or Set are silently ignored.  
   
      The same shared object may contain multiple plugins, each with a  
      different symbol name.  The shared object file must be owned by uid 0 and  
      only writable by its owner.  Because of ambiguities that arise from  
      composite policies, only a single policy plugin may be specified.  This  
      limitation does not apply to I/O plugins.  
   
      #  
      # Default /etc/sudo.conf file  
      #  
      # Format:  
      #   Plugin plugin_name plugin_path plugin_options ...  
      #   Path askpass /path/to/askpass  
      #   Path noexec /path/to/sudo_noexec.so  
      #   Debug sudo /var/log/sudo_debug all@warn  
      #   Set disable_coredump true  
      #  
      # The plugin_path is relative to /usr/local/libexec unless  
      #   fully qualified.  
      # The plugin_name corresponds to a global symbol in the plugin  
      #   that contains the plugin interface structure.  
      # The plugin_options are optional.  
      #  
      Plugin sudoers_policy sudoers.so  
      Plugin sudoers_io sudoers.so  
   
    PPoolliiccyy pplluuggiinn AAPPII     PPoolliiccyy pplluuggiinn AAPPII
      A policy plugin must declare and populate a policy_plugin struct in the       A policy plugin must declare and populate a policy_plugin struct in the
      global scope.  This structure contains pointers to the functions that       global scope.  This structure contains pointers to the functions that
      implement the ssuuddoo policy checks.  The name of the symbol should be       implement the ssuuddoo policy checks.  The name of the symbol should be
     specified in _/_e_t_c_/_s_u_d_o_._c_o_n_f along with a path to the plugin so that ssuuddoo     specified in sudo.conf(4) along with a path to the plugin so that ssuuddoo
      can load it.       can load it.
   
      struct policy_plugin {       struct policy_plugin {
Line 141  DDEESSCCRRIIPPTTIIOONN Line 101  DDEESSCCRRIIPPTTIIOONN
                  equal sign (`=') since the _n_a_m_e field will never include one                   equal sign (`=') since the _n_a_m_e field will never include one
                  itself but the _v_a_l_u_e might.                   itself but the _v_a_l_u_e might.
   
                    bsdauth_type=string
                          Authentication type, if specified by the --aa flag, to
                          use on systems where BSD authentication is supported.
   
                    closefrom=number
                          If specified, the user has requested via the --CC flag
                          that ssuuddoo close all files descriptors with a value of
                          _n_u_m_b_e_r or higher.  The plugin may optionally pass this,
                          or another value, back in the _c_o_m_m_a_n_d___i_n_f_o list.
   
                  debug_flags=string                   debug_flags=string
                        A comma-separated list of debug flags that correspond                         A comma-separated list of debug flags that correspond
                       to ssuuddoo's Debug entry in _/_e_t_c_/_s_u_d_o_._c_o_n_f, if there is                       to ssuuddoo's Debug entry in sudo.conf(4), if there is one.
                       one.  The flags are passed to the plugin as they appear                       The flags are passed to the plugin as they appear in
                       in _/_e_t_c_/_s_u_d_o_._c_o_n_f.  The syntax used by ssuuddoo and the                       sudo.conf(4).  The syntax used by ssuuddoo and the ssuuddooeerrss
                       _s_u_d_o_e_r_s plugin is _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y but the plugin is                       plugin is _s_u_b_s_y_s_t_e_m@_p_r_i_o_r_i_t_y but the plugin is free to
                       free to use a different format so long as it does not                       use a different format so long as it does not include a
                       include a comma (`,').                       comma (`,').  There is not currently a way to specify a
                        set of debug flags specific to the plugin--the flags
                        are shared by ssuuddoo and the plugin.
   
                        For reference, the priorities supported by the ssuuddoo  
                        front end and _s_u_d_o_e_r_s are: _c_r_i_t, _e_r_r, _w_a_r_n, _n_o_t_i_c_e,  
                        _d_i_a_g, _i_n_f_o, _t_r_a_c_e and _d_e_b_u_g.  
   
                        The following subsystems are defined: _m_a_i_n, _m_e_m_o_r_y,  
                        _a_r_g_s, _e_x_e_c, _p_t_y, _u_t_m_p, _c_o_n_v, _p_c_o_m_m, _u_t_i_l, _l_i_s_t, _n_e_t_i_f,  
                        _a_u_d_i_t, _e_d_i_t, _s_e_l_i_n_u_x, _l_d_a_p, _m_a_t_c_h, _p_a_r_s_e_r, _a_l_i_a_s,  
                        _d_e_f_a_u_l_t_s, _a_u_t_h, _e_n_v, _l_o_g_g_i_n_g, _n_s_s, _r_b_t_r_e_e, _p_e_r_m_s,  
                        _p_l_u_g_i_n.  The subsystem _a_l_l includes every subsystem.  
   
                        There is not currently a way to specify a set of debug  
                        flags specific to the plugin--the flags are shared by  
                        ssuuddoo and the plugin.  
   
                  debug_level=number                   debug_level=number
                        This setting has been deprecated in favor of                         This setting has been deprecated in favor of
                        _d_e_b_u_g___f_l_a_g_s.                         _d_e_b_u_g___f_l_a_g_s.
   
                 runas_user=string                 ignore_ticket=bool
                       The user name or uid to to run the command as, if                       Set to true if the user specified the --kk flag along
                       specified via the --uu flag.                       with a command, indicating that the user wishes to
                        ignore any cached authentication credentials.
                        _i_m_p_l_i_e_d___s_h_e_l_l to true.  This allows ssuuddoo with no
                        arguments to be used similarly to su(1).  If the plugin
                        does not to support this usage, it may return a value
                        of -2 from the cchheecckk__ppoolliiccyy() function, which will
                        cause ssuuddoo to print a usage message and exit.
   
                 runas_group=string                 implied_shell=bool
                       The group name or gid to to run the command as, if                       If the user does not specify a program on the command
                       specified via the --gg flag.                       line, ssuuddoo will pass the plugin the path to the user's
                        shell and set
   
                 prompt=string                 login_class=string
                       The prompt to use when requesting a password, if                       BSD login class to use when setting resource limits and
                       specified via the --pp flag.                       nice value, if specified by the --cc flag.
   
                 set_home=bool                 login_shell=bool
                       Set to true if the user specified the --HH flag.  If                       Set to true if the user specified the --ii flag,
                       true, set the HOME environment variable to the target                       indicating that the user wishes to run a login shell.
                       user's home directory. 
   
                    max_groups=int
                          The maximum number of groups a user may belong to.
                          This will only be present if there is a corresponding
                          setting in sudo.conf(4).
   
                    network_addrs=list
                          A space-separated list of IP network addresses and
                          netmasks in the form ``addr/netmask'', e.g.
                          ``192.168.1.2/255.255.255.0''.  The address and netmask
                          pairs may be either IPv4 or IPv6, depending on what the
                          operating system supports.  If the address contains a
                          colon (`:'), it is an IPv6 address, else it is IPv4.
   
                    noninteractive=bool
                          Set to true if the user specified the --nn flag,
                          indicating that ssuuddoo should operate in non-interactive
                          mode.  The plugin may reject a command run in non-
                          interactive mode if user interaction is required.
   
                    plugin_dir=string
                          The default plugin directory used by the ssuuddoo front
                          end.  This is the default directory set at compile time
                          and may not correspond to the directory the running
                          plugin was loaded from.  It may be used by a plugin to
                          locate support files.
   
                  preserve_environment=bool                   preserve_environment=bool
                        Set to true if the user specified the --EE flag,                         Set to true if the user specified the --EE flag,
                        indicating that the user wishes to preserve the                         indicating that the user wishes to preserve the
                        environment.                         environment.
   
                  run_shell=bool  
                        Set to true if the user specified the --ss flag,  
                        indicating that the user wishes to run a shell.  
   
                  login_shell=bool  
                        Set to true if the user specified the --ii flag,  
                        indicating that the user wishes to run a login shell.  
   
                  implied_shell=bool  
                        If the user does not specify a program on the command  
                        line, ssuuddoo will pass the plugin the path to the user's  
                        shell and set _i_m_p_l_i_e_d___s_h_e_l_l to true.  This allows ssuuddoo  
                        with no arguments to be used similarly to su(1).  If  
                        the plugin does not to support this usage, it may  
                        return a value of -2 from the cchheecckk__ppoolliiccyy() function,  
                        which will cause ssuuddoo to print a usage message and  
                        exit.  
   
                  preserve_groups=bool                   preserve_groups=bool
                        Set to true if the user specified the --PP flag,                         Set to true if the user specified the --PP flag,
                        indicating that the user wishes to preserve the group                         indicating that the user wishes to preserve the group
                        vector instead of setting it based on the runas user.                         vector instead of setting it based on the runas user.
   
                 ignore_ticket=bool                 progname=string
                       Set to true if the user specified the --kk flag along                       The command name that sudo was run as, typically
                       with a command, indicating that the user wishes to                       ``sudo'' or ``sudoedit''.
                       ignore any cached authentication credentials. 
   
                 noninteractive=bool                 prompt=string
                       Set to true if the user specified the --nn flag,                       The prompt to use when requesting a password, if
                       indicating that ssuuddoo should operate in non-interactive                       specified via the --pp flag.
                       mode.  The plugin may reject a command run in non- 
                       interactive mode if user interaction is required. 
   
                 login_class=string                 run_shell=bool
                       BSD login class to use when setting resource limits and                       Set to true if the user specified the --ss flag,
                       nice value, if specified by the --cc flag.                       indicating that the user wishes to run a shell.
   
                    runas_group=string
                          The group name or gid to to run the command as, if
                          specified via the --gg flag.
   
                    runas_user=string
                          The user name or uid to to run the command as, if
                          specified via the --uu flag.
   
                  selinux_role=string                   selinux_role=string
                        SELinux role to use when executing the command, if                         SELinux role to use when executing the command, if
                        specified by the --rr flag.                         specified by the --rr flag.
Line 236  DDEESSCCRRIIPPTTIIOONN Line 213  DDEESSCCRRIIPPTTIIOONN
                        SELinux type to use when executing the command, if                         SELinux type to use when executing the command, if
                        specified by the --tt flag.                         specified by the --tt flag.
   
                 bsdauth_type=string                 set_home=bool
                       Authentication type, if specified by the --aa flag, to                       Set to true if the user specified the --HH flag.  If
                       use on systems where BSD authentication is supported.                       true, set the HOME environment variable to the target
                        user's home directory.
   
                  network_addrs=list  
                        A space-separated list of IP network addresses and  
                        netmasks in the form ``addr/netmask'', e.g.  
                        ``192.168.1.2/255.255.255.0''.  The address and netmask  
                        pairs may be either IPv4 or IPv6, depending on what the  
                        operating system supports.  If the address contains a  
                        colon (`:'), it is an IPv6 address, else it is IPv4.  
   
                  progname=string  
                        The command name that sudo was run as, typically  
                        ``sudo'' or ``sudoedit''.  
   
                  sudoedit=bool                   sudoedit=bool
                        Set to true when the --ee flag is is specified or if                         Set to true when the --ee flag is is specified or if
                        invoked as ssuuddooeeddiitt.  The plugin shall substitute an                         invoked as ssuuddooeeddiitt.  The plugin shall substitute an
Line 260  DDEESSCCRRIIPPTTIIOONN Line 226  DDEESSCCRRIIPPTTIIOONN
                        support _s_u_d_o_e_d_i_t.  For more information, see the                         support _s_u_d_o_e_d_i_t.  For more information, see the
                        _c_h_e_c_k___p_o_l_i_c_y section.                         _c_h_e_c_k___p_o_l_i_c_y section.
   
                  closefrom=number  
                        If specified, the user has requested via the --CC flag  
                        that ssuuddoo close all files descriptors with a value of  
                        _n_u_m_b_e_r or higher.  The plugin may optionally pass this,  
                        or another value, back in the _c_o_m_m_a_n_d___i_n_f_o list.  
   
                  Additional settings may be added in the future so the plugin                   Additional settings may be added in the future so the plugin
                  should silently ignore settings that it does not recognize.                   should silently ignore settings that it does not recognize.
   
Line 278  DDEESSCCRRIIPPTTIIOONN Line 238  DDEESSCCRRIIPPTTIIOONN
                  equal sign (`=') since the _n_a_m_e field will never include one                   equal sign (`=') since the _n_a_m_e field will never include one
                  itself but the _v_a_l_u_e might.                   itself but the _v_a_l_u_e might.
   
                 pid=int                 cols=int
                       The process ID of the running ssuuddoo process.  Only                       The number of columns the user's terminal supports.  If
                       available starting with API version 1.2                       there is no terminal device available, a default value
                        of 80 is used.
   
                 ppid=int                 cwd=string
                       The parent process ID of the running ssuuddoo process.                       The user's current working directory.
                       Only available starting with API version 1.2 
   
                 sid=int                 egid=gid_t
                       The session ID of the running ssuuddoo process or 0 if ssuuddoo                       The effective group ID of the user invoking ssuuddoo.
                       is not part of a POSIX job control session.  Only 
                       available starting with API version 1.2 
   
                  pgid=int  
                        The ID of the process group that the running ssuuddoo  
                        process belongs to.  Only available starting with API  
                        version 1.2  
   
                  tcpgid=int  
                        The ID of the forground process group associated with  
                        the terminal device associcated with the ssuuddoo process  
                        or -1 if there is no terminal present.  Only available  
                        starting with API version 1.2  
   
                  user=string  
                        The name of the user invoking ssuuddoo.  
   
                  euid=uid_t                   euid=uid_t
                        The effective user ID of the user invoking ssuuddoo.                         The effective user ID of the user invoking ssuuddoo.
   
                  uid=uid_t  
                        The real user ID of the user invoking ssuuddoo.  
   
                  egid=gid_t  
                        The effective group ID of the user invoking ssuuddoo.  
   
                  gid=gid_t                   gid=gid_t
                        The real group ID of the user invoking ssuuddoo.                         The real group ID of the user invoking ssuuddoo.
   
Line 321  DDEESSCCRRIIPPTTIIOONN Line 259  DDEESSCCRRIIPPTTIIOONN
                        The user's supplementary group list formatted as a                         The user's supplementary group list formatted as a
                        string of comma-separated group IDs.                         string of comma-separated group IDs.
   
                  cwd=string  
                        The user's current working directory.  
   
                  tty=string  
                        The path to the user's terminal device.  If the user  
                        has no terminal device associated with the session, the  
                        value will be empty, as in ``tty=''.  
   
                  host=string                   host=string
                        The local machine's hostname as returned by the                         The local machine's hostname as returned by the
                        gethostname(2) system call.                         gethostname(2) system call.
Line 338  DDEESSCCRRIIPPTTIIOONN Line 268  DDEESSCCRRIIPPTTIIOONN
                        there is no terminal device available, a default value                         there is no terminal device available, a default value
                        of 24 is used.                         of 24 is used.
   
                 cols=int                 pgid=int
                       The number of columns the user's terminal supports.  If                       The ID of the process group that the running ssuuddoo
                       there is no terminal device available, a default value                       process is a member of.  Only available starting with
                       of 80 is used.                       API version 1.2
   
                    pid=int
                          The process ID of the running ssuuddoo process.  Only
                          available starting with API version 1.2
   
                    plugin_options
                          Any (non-comment) strings immediately after the plugin
                          path are passed as arguments to the plugin.  These
                          arguments are split on a white space boundary and are
                          passed to the plugin in the form of a NULL-terminated
                          array of strings.  If no arguments were specified,
                          _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL pointer.
   
                          NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available
                          starting with API version 1.2.  A plugin mmuusstt check the
                          API version specified by the ssuuddoo front end before
                          using _p_l_u_g_i_n___o_p_t_i_o_n_s.  Failure to do so may result in a
                          crash.
   
                    ppid=int
                          The parent process ID of the running ssuuddoo process.
                          Only available starting with API version 1.2
   
                    sid=int
                          The session ID of the running ssuuddoo process or 0 if ssuuddoo
                          is not part of a POSIX job control session.  Only
                          available starting with API version 1.2
   
                    tcpgid=int
                          The ID of the foreground process group associated with
                          the terminal device associated with the ssuuddoo process or
                          -1 if there is no terminal present.  Only available
                          starting with API version 1.2
   
                    tty=string
                          The path to the user's terminal device.  If the user
                          has no terminal device associated with the session, the
                          value will be empty, as in ``tty=''.
   
                    uid=uid_t
                          The real user ID of the user invoking ssuuddoo.
   
                    user=string
                          The name of the user invoking ssuuddoo.
   
            user_env             user_env
                  The user's environment in the form of a NULL-terminated                   The user's environment in the form of a NULL-terminated
                  vector of ``name=value'' strings.                   vector of ``name=value'' strings.
Line 351  DDEESSCCRRIIPPTTIIOONN Line 325  DDEESSCCRRIIPPTTIIOONN
                  equal sign (`=') since the _n_a_m_e field will never include one                   equal sign (`=') since the _n_a_m_e field will never include one
                  itself but the _v_a_l_u_e might.                   itself but the _v_a_l_u_e might.
   
            plugin_options  
                  Any (non-comment) strings immediately after the plugin path  
                  are treated as arguments to the plugin.  These arguments are  
                  split on a white space boundary and are passed to the plugin  
                  in the form of a NULL-terminated array of strings.  If no  
                  arguments were specified, _p_l_u_g_i_n___o_p_t_i_o_n_s will be the NULL  
                  pointer.  
   
                  NOTE: the _p_l_u_g_i_n___o_p_t_i_o_n_s parameter is only available starting  
                  with API version 1.2.  A plugin mmuusstt check the API version  
                  specified by the ssuuddoo front end before using _p_l_u_g_i_n___o_p_t_i_o_n_s.  
                  Failure to do so may result in a crash.  
   
      close       close
            void (*close)(int exit_status, int error);             void (*close)(int exit_status, int error);
   
Line 384  DDEESSCCRRIIPPTTIIOONN Line 345  DDEESSCCRRIIPPTTIIOONN
                  ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function.  If the command                   ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function.  If the command
                  was successfully executed, the value of error is 0.                   was successfully executed, the value of error is 0.
   
              If no cclloossee() function is defined, no I/O logging plugins are
              loaded, and neither the _t_i_m_e_o_u_t not _u_s_e___p_t_y options are set in the
              command_info list, the ssuuddoo front end may execute the command
              directly instead of running it as a child process.
   
      show_version       show_version
            int (*show_version)(int verbose);             int (*show_version)(int verbose);
   
Line 454  DDEESSCCRRIIPPTTIIOONN Line 420  DDEESSCCRRIIPPTTIIOONN
                  must be terminated with a NULL pointer.  The following values                   must be terminated with a NULL pointer.  The following values
                  are recognized by ssuuddoo:                   are recognized by ssuuddoo:
   
                    chroot=string
                          The root directory to use when running the command.
   
                    closefrom=number
                          If specified, ssuuddoo will close all files descriptors
                          with a value of _n_u_m_b_e_r or higher.
   
                  command=string                   command=string
                        Fully qualified path to the command to be executed.                         Fully qualified path to the command to be executed.
   
                  runas_uid=uid  
                        User ID to run the command as.  
   
                  runas_euid=uid  
                        Effective user ID to run the command as.  If not  
                        specified, the value of _r_u_n_a_s___u_i_d is used.  
   
                  runas_gid=gid  
                        Group ID to run the command as.  
   
                  runas_egid=gid  
                        Effective group ID to run the command as.  If not  
                        specified, the value of _r_u_n_a_s___g_i_d is used.  
   
                  runas_groups=list  
                        The supplementary group vector to use for the command  
                        in the form of a comma-separated list of group IDs.  If  
                        _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, this option is ignored.  
   
                  login_class=string  
                        BSD login class to use when setting resource limits and  
                        nice value (optional).  This option is only set on  
                        systems that support login classes.  
   
                  preserve_groups=bool  
                        If set, ssuuddoo will preserve the user's group vector  
                        instead of initializing the group vector based on  
                        runas_user.  
   
                  cwd=string                   cwd=string
                        The current working directory to change to when                         The current working directory to change to when
                        executing the command.                         executing the command.
   
                 noexec=bool                 exec_background=bool
                       If set, prevent the command from executing other                       By default, ssuuddoo runs a command as the foreground
                       programs.                       process as long as ssuuddoo itself is running in the
                        foreground.  When _e_x_e_c___b_a_c_k_g_r_o_u_n_d is enabled and the
                        command is being run in a pty (due to I/O logging or
                        the _u_s_e___p_t_y setting), the command will be run as a
                        background process.  Attempts to read from the
                        controlling terminal (or to change terminal settings)
                        will result in the command being suspended with the
                        SIGTTIN signal (or SIGTTOU in the case of terminal
                        settings).  If this happens when ssuuddoo is a foreground
                        process, the command will be granted the controlling
                        terminal and resumed in the foreground with no user
                        intervention required.  The advantage of initially
                        running the command in the background is that ssuuddoo need
                        not read from the terminal unless the command
                        explicitly requests it.  Otherwise, any terminal input
                        must be passed to the command, whether it has required
                        it or not (the kernel buffers terminals so it is not
                        possible to tell whether the command really wants the
                        input).  This is different from historic _s_u_d_o behavior
                        or when the command is not being run in a pty.
   
                 chroot=string                       For this to work seamlessly, the operating system must
                       The root directory to use when running the command.                       support the automatic restarting of system calls.
                        Unfortunately, not all operating systems do this by
                        default, and even those that do may have bugs.  For
                        example, Mac OS X fails to restart the ttccggeettaattttrr() and
                        ttccsseettaattttrr() system calls (this is a bug in Mac OS X).
                        Furthermore, because this behavior depends on the
                        command stopping with the SIGTTIN or SIGTTOU signals,
                        programs that catch these signals and suspend
                        themselves with a different signal (usually SIGTOP)
                        will not be automatically foregrounded.  Some versions
                        of the linux su(1) command behave this way.  Because of
                        this, a plugin should not set _e_x_e_c___b_a_c_k_g_r_o_u_n_d unless it
                        is explicitly enabled by the administrator and there
                        should be a way to enabled or disable it on a per-
                        command basis.
   
                 nice=int                       This setting has no effect unless I/O logging is
                       Nice value (priority) to use when executing the                       enabled or _u_s_e___p_t_y is enabled.
                       command.  The nice value, if specified, overrides the 
                       priority associated with the _l_o_g_i_n___c_l_a_s_s on BSD 
                       systems. 
   
                  umask=octal  
                        The file creation mask to use when executing the  
                        command.  
   
                  selinux_role=string  
                        SELinux role to use when executing the command.  
   
                  selinux_type=string  
                        SELinux type to use when executing the command.  
   
                  timeout=int  
                        Command timeout.  If non-zero then when the timeout  
                        expires the command will be killed.  
   
                  sudoedit=bool  
                        Set to true when in _s_u_d_o_e_d_i_t mode.  The plugin may  
                        enable _s_u_d_o_e_d_i_t mode even if ssuuddoo was not invoked as  
                        ssuuddooeeddiitt.  This allows the plugin to perform command  
                        substitution and transparently enable _s_u_d_o_e_d_i_t when the  
                        user attempts to run an editor.  
   
                  closefrom=number  
                        If specified, ssuuddoo will close all files descriptors  
                        with a value of _n_u_m_b_e_r or higher.  
   
                  iolog_compress=bool                   iolog_compress=bool
                        Set to true if the I/O logging plugins, if any, should                         Set to true if the I/O logging plugins, if any, should
                        compress the log data.  This is a hint to the I/O                         compress the log data.  This is a hint to the I/O
Line 572  DDEESSCCRRIIPPTTIIOONN Line 521  DDEESSCCRRIIPPTTIIOONN
                        hint to the I/O logging plugin which may choose to                         hint to the I/O logging plugin which may choose to
                        ignore it.                         ignore it.
   
                 use_pty=bool                 login_class=string
                       Allocate a pseudo-tty to run the command in, regardless                       BSD login class to use when setting resource limits and
                       of whether or not I/O logging is in use.  By default,                       nice value (optional).  This option is only set on
                       ssuuddoo will only run the command in a pty when an I/O log                       systems that support login classes.
                       plugin is loaded. 
   
                    nice=int
                          Nice value (priority) to use when executing the
                          command.  The nice value, if specified, overrides the
                          priority associated with the _l_o_g_i_n___c_l_a_s_s on BSD
                          systems.
   
                    noexec=bool
                          If set, prevent the command from executing other
                          programs.
   
                    preserve_groups=bool
                          If set, ssuuddoo will preserve the user's group vector
                          instead of initializing the group vector based on
                          runas_user.
   
                    runas_egid=gid
                          Effective group ID to run the command as.  If not
                          specified, the value of _r_u_n_a_s___g_i_d is used.
   
                    runas_euid=uid
                          Effective user ID to run the command as.  If not
                          specified, the value of _r_u_n_a_s___u_i_d is used.
   
                    runas_gid=gid
                          Group ID to run the command as.
   
                    runas_groups=list
                          The supplementary group vector to use for the command
                          in the form of a comma-separated list of group IDs.  If
                          _p_r_e_s_e_r_v_e___g_r_o_u_p_s is set, this option is ignored.
   
                    runas_uid=uid
                          User ID to run the command as.
   
                    selinux_role=string
                          SELinux role to use when executing the command.
   
                    selinux_type=string
                          SELinux type to use when executing the command.
   
                  set_utmp=bool                   set_utmp=bool
                        Create a utmp (or utmpx) entry when a pseudo-tty is                         Create a utmp (or utmpx) entry when a pseudo-tty is
                        allocated.  By default, the new entry will be a copy of                         allocated.  By default, the new entry will be a copy of
                        the user's existing utmp entry (if any), with the tty,                         the user's existing utmp entry (if any), with the tty,
                        time, type and pid fields updated.                         time, type and pid fields updated.
   
                    sudoedit=bool
                          Set to true when in _s_u_d_o_e_d_i_t mode.  The plugin may
                          enable _s_u_d_o_e_d_i_t mode even if ssuuddoo was not invoked as
                          ssuuddooeeddiitt.  This allows the plugin to perform command
                          substitution and transparently enable _s_u_d_o_e_d_i_t when the
                          user attempts to run an editor.
   
                    timeout=int
                          Command timeout.  If non-zero then when the timeout
                          expires the command will be killed.
   
                    umask=octal
                          The file creation mask to use when executing the
                          command.
   
                    use_pty=bool
                          Allocate a pseudo-tty to run the command in, regardless
                          of whether or not I/O logging is in use.  By default,
                          ssuuddoo will only run the command in a pty when an I/O log
                          plugin is loaded.
   
                  utmp_user=string                   utmp_user=string
                        User name to use when constructing a new utmp (or                         User name to use when constructing a new utmp (or
                        utmpx) entry when _s_e_t___u_t_m_p is enabled.  This option can                         utmpx) entry when _s_e_t___u_t_m_p is enabled.  This option can
Line 639  DDEESSCCRRIIPPTTIIOONN Line 648  DDEESSCCRRIIPPTTIIOONN
            int (*validate)(void);             int (*validate)(void);
   
            The vvaalliiddaattee() function is called when ssuuddoo is run with the --vv             The vvaalliiddaattee() function is called when ssuuddoo is run with the --vv
           flag.  For policy plugins such as _s_u_d_o_e_r_s that cache authentication           flag.  For policy plugins such as ssuuddooeerrss that cache authentication
            credentials, this function will validate and cache the credentials.             credentials, this function will validate and cache the credentials.
   
            The vvaalliiddaattee() function should be NULL if the plugin does not             The vvaalliiddaattee() function should be NULL if the plugin does not
Line 654  DDEESSCCRRIIPPTTIIOONN Line 663  DDEESSCCRRIIPPTTIIOONN
            void (*invalidate)(int remove);             void (*invalidate)(int remove);
   
            The iinnvvaalliiddaattee() function is called when ssuuddoo is called with the --kk             The iinnvvaalliiddaattee() function is called when ssuuddoo is called with the --kk
           or --KK flag.  For policy plugins such as _s_u_d_o_e_r_s that cache           or --KK flag.  For policy plugins such as ssuuddooeerrss that cache
            authentication credentials, this function will invalidate the             authentication credentials, this function will invalidate the
            credentials.  If the _r_e_m_o_v_e flag is set, the plugin may remove the             credentials.  If the _r_e_m_o_v_e flag is set, the plugin may remove the
            credentials instead of simply invalidating them.             credentials instead of simply invalidating them.
Line 764  DDEESSCCRRIIPPTTIIOONN Line 773  DDEESSCCRRIIPPTTIIOONN
      #define SUDO_IO_PLUGIN 2       #define SUDO_IO_PLUGIN 2
          unsigned int type; /* always SUDO_IO_PLUGIN */           unsigned int type; /* always SUDO_IO_PLUGIN */
          unsigned int version; /* always SUDO_API_VERSION */           unsigned int version; /* always SUDO_API_VERSION */
         int (*open)(unsigned int version, sudo_conv_t conversation         int (*open)(unsigned int version, sudo_conv_t conversation,
                      sudo_printf_t plugin_printf, char * const settings[],                       sudo_printf_t plugin_printf, char * const settings[],
                     char * const user_info[], int argc, char * const argv[],                     char * const user_info[], char * const command_info[],
                     char * const user_env[], char * const plugin_options[]);                     int argc, char * const argv[], char * const user_env[],
                      char * const plugin_options[]);
          void (*close)(int exit_status, int error); /* wait status or error */           void (*close)(int exit_status, int error); /* wait status or error */
          int (*show_version)(int verbose);           int (*show_version)(int verbose);
          int (*log_ttyin)(const char *buf, unsigned int len);           int (*log_ttyin)(const char *buf, unsigned int len);
Line 810  DDEESSCCRRIIPPTTIIOONN Line 820  DDEESSCCRRIIPPTTIIOONN
            against.             against.
   
      open       open
           int (*open)(unsigned int version, sudo_conv_t conversation           int (*open)(unsigned int version, sudo_conv_t conversation,
                        sudo_printf_t plugin_printf, char * const settings[],                         sudo_printf_t plugin_printf, char * const settings[],
                        char * const user_info[], int argc, char * const argv[],                         char * const user_info[], int argc, char * const argv[],
                        char * const user_env[], char * const plugin_options[]);                         char * const user_env[], char * const plugin_options[]);
Line 1025  DDEESSCCRRIIPPTTIIOONN Line 1035  DDEESSCCRRIIPPTTIIOONN
   
      Same as for the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I.       Same as for the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I.
   
      SSiiggnnaall hhaannddlleerrss
        The ssuuddoo front end installs default signal handlers to trap common
        signals while the plugin functions are run.  The following signals are
        trapped by default before the command is executed:
   
        oo   SIGALRM
        oo   SIGHUP
        oo   SIGINT
        oo   SIGQUIT
        oo   SIGTERM
        oo   SIGTSTP
        oo   SIGUSR1
        oo   SIGUSR2
   
        If a fatal signal is received before the command is executed, ssuuddoo will
        call the plugin's cclloossee() function with an exit status of 128 plus the
        value of the signal that was received.  This allows for consistent
        logging of commands killed by a signal for plugins that log such
        information in their cclloossee() function.
   
        A plugin may temporarily install its own signal handlers but must restore
        the original handler before the plugin function returns.
   
    HHooookk ffuunnccttiioonn AAPPII     HHooookk ffuunnccttiioonn AAPPII
      Beginning with plugin API version 1.2, it is possible to install hooks       Beginning with plugin API version 1.2, it is possible to install hooks
      for certain functions called by the ssuuddoo front end.       for certain functions called by the ssuuddoo front end.
Line 1215  DDEESSCCRRIIPPTTIIOONN Line 1248  DDEESSCCRRIIPPTTIIOONN
      Unlike, SUDO_CONV_INFO_MSG and Dv SUDO_CONV_ERROR_MSG , messages sent       Unlike, SUDO_CONV_INFO_MSG and Dv SUDO_CONV_ERROR_MSG , messages sent
      with the SUDO_CONV_DEBUG_MSG _m_s_g___t_y_p_e are not directly user-visible.       with the SUDO_CONV_DEBUG_MSG _m_s_g___t_y_p_e are not directly user-visible.
      Instead, they are logged to the file specified in the Debug statement (if       Instead, they are logged to the file specified in the Debug statement (if
     any) in the _/_e_t_c_/_s_u_d_o_._c_o_n_f     any) in the sudo.conf(4).  file.  This allows a plugin to log debugging
      information and is intended to be used in conjunction with the
      _d_e_b_u_g___f_l_a_g_s setting.
   
      file.  This allows a plugin to log debugging information and is intended  
      to be used in conjunction with the _d_e_b_u_g___f_l_a_g_s setting.  
   
      See the sample plugin for an example of the ccoonnvveerrssaattiioonn() function       See the sample plugin for an example of the ccoonnvveerrssaattiioonn() function
      usage.       usage.
   
    SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII     SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII
     The _s_u_d_o_e_r_s module supports a plugin interface to allow non-Unix group     The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix
     lookups.  This can be used to query a group source other than the     group lookups.  This can be used to query a group source other than the
     standard Unix group database.  A sample group plugin is bundled with ssuuddoo     standard Unix group database.  Two sample group plugins are bundled with
     that implements file-based lookups.  Third party group plugins include a     ssuuddoo, _g_r_o_u_p___f_i_l_e and _s_y_s_t_e_m___g_r_o_u_p, are detailed in sudoers(4).  Third
     QAS AD plugin available from Quest Software.     party group plugins include a QAS AD plugin available from Quest
      Software.
   
      A group plugin must declare and populate a sudoers_group_plugin struct in       A group plugin must declare and populate a sudoers_group_plugin struct in
      the global scope.  This structure contains pointers to the functions that       the global scope.  This structure contains pointers to the functions that
Line 1248  DDEESSCCRRIIPPTTIIOONN Line 1281  DDEESSCCRRIIPPTTIIOONN
      version       version
            The version field should be set to GROUP_API_VERSION.             The version field should be set to GROUP_API_VERSION.
   
           This allows _s_u_d_o_e_r_s to determine the API version the group plugin           This allows ssuuddooeerrss to determine the API version the group plugin
            was built against.             was built against.
   
      init       init
Line 1265  DDEESSCCRRIIPPTTIIOONN Line 1298  DDEESSCCRRIIPPTTIIOONN
            The function arguments are as follows:             The function arguments are as follows:
   
            version             version
                 The version passed in by _s_u_d_o_e_r_s allows the plugin to                 The version passed in by ssuuddooeerrss allows the plugin to
                  determine the major and minor version number of the group                   determine the major and minor version number of the group
                 plugin API supported by _s_u_d_o_e_r_s.                 plugin API supported by ssuuddooeerrss.
   
            plugin_printf             plugin_printf
                  A pointer to a pprriinnttff()-style function that may be used to                   A pointer to a pprriinnttff()-style function that may be used to
Line 1282  DDEESSCCRRIIPPTTIIOONN Line 1315  DDEESSCCRRIIPPTTIIOONN
      cleanup       cleanup
            void (*cleanup)();             void (*cleanup)();
   
           The cclleeaannuupp() function is called when _s_u_d_o_e_r_s has finished its           The cclleeaannuupp() function is called when ssuuddooeerrss has finished its
            group checks.  The plugin should free any memory it has allocated             group checks.  The plugin should free any memory it has allocated
            and close open file handles.             and close open file handles.
   
Line 1328  PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOG Line 1361  PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOG
      Version 1.0       Version 1.0
            Initial API version.             Initial API version.
   
     Version 1.1     Version 1.1 (sudo 1.8.0)
            The I/O logging plugin's ooppeenn() function was modified to take the             The I/O logging plugin's ooppeenn() function was modified to take the
            command_info list as an argument.             command_info list as an argument.
   
     Version 1.2     Version 1.2 (sudo 1.8.5)
            The Policy and I/O logging plugins' ooppeenn() functions are now passed             The Policy and I/O logging plugins' ooppeenn() functions are now passed
           a list of plugin options if any are specified in _/_e_t_c_/_s_u_d_o_._c_o_n_f.           a list of plugin parameters if any are specified in sudo.conf(4).
   
            A simple hooks API has been introduced to allow plugins to hook in             A simple hooks API has been introduced to allow plugins to hook in
            to the system's environment handling functions.             to the system's environment handling functions.
Line 1344  PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOG Line 1377  PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOG
            used to merge in environment variables stored in the PAM handle             used to merge in environment variables stored in the PAM handle
            before a command is run.             before a command is run.
   
        Version 1.3 (sudo 1.8.7)
              Support for the _e_x_e_c___b_a_c_k_g_r_o_u_n_d entry has been added to the
              command_info list.
   
              The _m_a_x___g_r_o_u_p_s and _p_l_u_g_i_n___d_i_r entries were added to the settings
              list.
   
              The vveerrssiioonn() and cclloossee() functions are now optional.  Previously,
              a missing vveerrssiioonn() or cclloossee() function would result in a crash.
              If no policy plugin cclloossee() function is defined, a default cclloossee()
              function will be provided by the ssuuddoo front end that displays a
              warning if the command could not be executed.
   
              The ssuuddoo front end now installs default signal handlers to trap
              common signals while the plugin functions are run.
   
 SSEEEE AALLSSOO  SSEEEE AALLSSOO
     sudoers(4), sudo(1m)     sudo.conf(4), sudoers(4), sudo(1m)
   
 BBUUGGSS  BBUUGGSS
      If you feel you have found a bug in ssuuddoo, please submit a bug report at       If you feel you have found a bug in ssuuddoo, please submit a bug report at
Line 1363  DDIISSCCLLAAIIMMEERR Line 1412  DDIISSCCLLAAIIMMEERR
      file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for       file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for
      complete details.       complete details.
   
Sudo 1.8.6                       July 16, 2012                      Sudo 1.8.6Sudo 1.8.7                       March 5, 2013                      Sudo 1.8.7
Removed from v.1.1.1.3  
changed lines
  Added in v.1.1.1.4

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>