--- /dev/null
+SUDO_PLUGIN(1m) MAINTENANCE COMMANDS SUDO_PLUGIN(1m)
+
+
+
+N\bNA\bAM\bME\bE
+ sudo_plugin - Sudo Plugin API
+
+D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
+ Starting with version 1.8, s\bsu\bud\bdo\bo supports a plugin API for policy and
+ session logging. By default, the _\bs_\bu_\bd_\bo_\be_\br_\bs policy plugin and an
+ associated I/O logging plugin are used. Via the plugin API, s\bsu\bud\bdo\bo can
+ be configured to use alternate policy and/or I/O logging plugins
+ provided by third parties. The plugins to be used are specified via
+ the _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf file.
+
+ The API is versioned with a major and minor number. The minor version
+ number is incremented when additions are made. The major number is
+ incremented when incompatible changes are made. A plugin should be
+ check the version passed to it and make sure that the major version
+ matches.
+
+ The plugin API is defined by the sudo_plugin.h header file.
+
+ T\bTh\bhe\be s\bsu\bud\bdo\bo.\b.c\bco\bon\bnf\bf F\bFi\bil\ble\be
+ The _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf file contains plugin configuration directives.
+ Currently, the only supported keyword is the Plugin directive, which
+ causes a plugin plugin to be loaded.
+
+ A Plugin line consists of the Plugin keyword, followed by the
+ _\bs_\by_\bm_\bb_\bo_\bl_\b__\bn_\ba_\bm_\be and the _\bp_\ba_\bt_\bh to the shared object containing the plugin.
+ The _\bs_\by_\bm_\bb_\bo_\bl_\b__\bn_\ba_\bm_\be is the name of the struct policy_plugin or struct
+ io_plugin in the plugin shared object. The _\bp_\ba_\bt_\bh may be fully qualified
+ or relative. If not fully qualified it is relative to the
+ _\b/_\bu_\bs_\br_\b/_\bl_\bo_\bc_\ba_\bl_\b/_\bl_\bi_\bb_\be_\bx_\be_\bc directory. Any additional parameters after the _\bp_\ba_\bt_\bh
+ are passed as options to the plugin's _\bo_\bp_\be_\bn 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
+
+ P\bPo\bol\bli\bic\bcy\by P\bPl\blu\bug\bgi\bin\bn A\bAP\bPI\bI
+ A policy plugin must declare and populate a policy_plugin struct in the
+ global scope. This structure contains pointers to the functions that
+ implement the s\bsu\bud\bdo\bo policy checks. The name of the symbol should be
+ specified in _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf along with a path to the plugin so that
+ s\bsu\bud\bdo\bo can load it.
+
+ struct policy_plugin {
+ #define SUDO_POLICY_PLUGIN 1
+ unsigned int type; /* always SUDO_POLICY_PLUGIN */
+ unsigned int version; /* always SUDO_API_VERSION */
+ int (*open)(unsigned int version, sudo_conv_t conversation,
+ sudo_printf_t plugin_printf, char * const settings[],
+ char * const user_info[], char * const user_env[],
+ char * const plugin_options[]);
+ void (*close)(int exit_status, int error);
+ int (*show_version)(int verbose);
+ int (*check_policy)(int argc, char * const argv[],
+ char *env_add[], char **command_info[],
+ char **argv_out[], char **user_env_out[]);
+ int (*list)(int argc, char * const argv[], int verbose,
+ const char *list_user);
+ int (*validate)(void);
+ void (*invalidate)(int remove);
+ int (*init_session)(struct passwd *pwd, char **user_env[]);
+ void (*register_hooks)(int version,
+ int (*register_hook)(struct sudo_hook *hook));
+ void (*deregister_hooks)(int version,
+ int (*deregister_hook)(struct sudo_hook *hook));
+ };
+
+ The policy_plugin struct has the following fields:
+
+ type
+ The type field should always be set to SUDO_POLICY_PLUGIN.
+
+ version
+ The version field should be set to SUDO_API_VERSION.
+
+ This allows s\bsu\bud\bdo\bo to determine the API version the plugin was built
+ against.
+
+ open
+ int (*open)(unsigned int version, sudo_conv_t conversation,
+ sudo_printf_t plugin_printf, char * const settings[],
+ char * const user_info[], char * const user_env[],
+ char * const plugin_options[]);
+
+ Returns 1 on success, 0 on failure, -1 if a general error occurred,
+ or -2 if there was a usage error. In the latter case, s\bsu\bud\bdo\bo will
+ print a usage message before it exits. If an error occurs, the
+ plugin may optionally call the conversation or plugin_printf
+ function with SUDO_CONF_ERROR_MSG to present additional error
+ information to the user.
+
+ The function arguments are as follows:
+
+ version
+ The version passed in by s\bsu\bud\bdo\bo allows the plugin to determine
+ the major and minor version number of the plugin API supported
+ by s\bsu\bud\bdo\bo.
+
+ conversation
+ A pointer to the conversation function that can be used by the
+ plugin to interact with the user (see below). Returns 0 on
+ success and -1 on failure.
+
+ plugin_printf
+ A pointer to a printf-style function that may be used to
+ display informational or error messages (see below). Returns
+ the number of characters printed on success and -1 on failure.
+
+ settings
+ A vector of user-supplied s\bsu\bud\bdo\bo settings in the form of
+ "name=value" strings. The vector is terminated by a NULL
+ pointer. These settings correspond to flags the user specified
+ when running s\bsu\bud\bdo\bo. As such, they will only be present when the
+ corresponding flag has been specified on the command line.
+
+ When parsing _\bs_\be_\bt_\bt_\bi_\bn_\bg_\bs, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be might.
+
+ debug_flags=string
+ A comma-separated list of debug flags that correspond to
+ s\bsu\bud\bdo\bo's Debug entry in _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf, if there is one. The
+ flags are passed to the plugin as they appear in
+ _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf. The syntax used by s\bsu\bud\bdo\bo and the _\bs_\bu_\bd_\bo_\be_\br_\bs
+ 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 use
+ a different format so long as it does not include a command
+ ,.
+
+ For reference, the priorities supported by the s\bsu\bud\bdo\bo front
+ end and _\bs_\bu_\bd_\bo_\be_\br_\bs are: _\bc_\br_\bi_\bt, _\be_\br_\br, _\bw_\ba_\br_\bn, _\bn_\bo_\bt_\bi_\bc_\be, _\bd_\bi_\ba_\bg, _\bi_\bn_\bf_\bo,
+ _\bt_\br_\ba_\bc_\be and _\bd_\be_\bb_\bu_\bg.
+
+ The following subsystems are defined: _\bm_\ba_\bi_\bn, _\bm_\be_\bm_\bo_\br_\by, _\ba_\br_\bg_\bs,
+ _\be_\bx_\be_\bc, _\bp_\bt_\by, _\bu_\bt_\bm_\bp, _\bc_\bo_\bn_\bv, _\bp_\bc_\bo_\bm_\bm, _\bu_\bt_\bi_\bl, _\bl_\bi_\bs_\bt, _\bn_\be_\bt_\bi_\bf, _\ba_\bu_\bd_\bi_\bt,
+ _\be_\bd_\bi_\bt, _\bs_\be_\bl_\bi_\bn_\bu_\bx, _\bl_\bd_\ba_\bp, _\bm_\ba_\bt_\bc_\bh, _\bp_\ba_\br_\bs_\be_\br, _\ba_\bl_\bi_\ba_\bs, _\bd_\be_\bf_\ba_\bu_\bl_\bt_\bs, _\ba_\bu_\bt_\bh,
+ _\be_\bn_\bv, _\bl_\bo_\bg_\bg_\bi_\bn_\bg, _\bn_\bs_\bs, _\br_\bb_\bt_\br_\be_\be, _\bp_\be_\br_\bm_\bs, _\bp_\bl_\bu_\bg_\bi_\bn. The subsystem
+ _\ba_\bl_\bl 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 s\bsu\bud\bdo\bo
+ and the plugin.
+
+ debug_level=number
+ This setting has been deprecated in favor of _\bd_\be_\bb_\bu_\bg_\b__\bf_\bl_\ba_\bg_\bs.
+
+ runas_user=string
+ The user name or uid to to run the command as, if specified
+ via the -u flag.
+
+ runas_group=string
+ The group name or gid to to run the command as, if
+ specified via the -g flag.
+
+ prompt=string
+ The prompt to use when requesting a password, if specified
+ via the -p flag.
+
+ set_home=bool
+ Set to true if the user specified the -H flag. If true,
+ set the HOME environment variable to the target user's home
+ directory.
+
+ preserve_environment=bool
+ Set to true if the user specified the -E flag, indicating
+ that the user wishes to preserve the environment.
+
+ run_shell=bool
+ Set to true if the user specified the -s flag, indicating
+ that the user wishes to run a shell.
+
+ login_shell=bool
+ Set to true if the user specified the -i 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,
+ s\bsu\bud\bdo\bo will pass the plugin the path to the user's shell and
+ set _\bi_\bm_\bp_\bl_\bi_\be_\bd_\b__\bs_\bh_\be_\bl_\bl to true. This allows s\bsu\bud\bdo\bo with no
+ arguments to be used similarly to _\bs_\bu(1). If the plugin
+ does not to support this usage, it may return a value of -2
+ from the check_policy function, which will cause s\bsu\bud\bdo\bo to
+ print a usage message and exit.
+
+ preserve_groups=bool
+ Set to true if the user specified the -P flag, indicating
+ that the user wishes to preserve the group vector instead
+ of setting it based on the runas user.
+
+ ignore_ticket=bool
+ Set to true if the user specified the -k flag along with a
+ command, indicating that the user wishes to ignore any
+ cached authentication credentials.
+
+ noninteractive=bool
+ Set to true if the user specified the -n flag, indicating
+ that s\bsu\bud\bdo\bo should operate in non-interactive mode. The
+ plugin may reject a command run in non-interactive mode if
+ user interaction is required.
+
+ login_class=string
+ BSD login class to use when setting resource limits and
+ nice value, if specified by the -c flag.
+
+ selinux_role=string
+ SELinux role to use when executing the command, if
+ specified by the -r flag.
+
+ selinux_type=string
+ SELinux type to use when executing the command, if
+ specified by the -t flag.
+
+ bsdauth_type=string
+ Authentication type, if specified by the -a flag, to use on
+ systems where BSD authentication is supported.
+
+ 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
+ Set to true when the -e flag is is specified or if invoked
+ as s\bsu\bud\bdo\boe\bed\bdi\bit\bt. The plugin shall substitute an editor into
+ _\ba_\br_\bg_\bv in the _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by function or return -2 with a usage
+ error if the plugin does not support _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt. For more
+ information, see the _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by section.
+
+ closefrom=number
+ If specified, the user has requested via the -C flag that
+ s\bsu\bud\bdo\bo close all files descriptors with a value of _\bn_\bu_\bm_\bb_\be_\br or
+ higher. The plugin may optionally pass this, or another
+ value, back in the _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bi_\bn_\bf_\bo list.
+
+ Additional settings may be added in the future so the plugin
+ should silently ignore settings that it does not recognize.
+
+ user_info
+ A vector of information about the user running the command in
+ the form of "name=value" strings. The vector is terminated by
+ a NULL pointer.
+
+ When parsing _\bu_\bs_\be_\br_\b__\bi_\bn_\bf_\bo, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be might.
+
+ pid=int
+ The process ID of the running s\bsu\bud\bdo\bo process. Only available
+ starting with API version 1.2
+
+ ppid=int
+ The parent process ID of the running s\bsu\bud\bdo\bo process. Only
+ available starting with API version 1.2
+
+ sid=int
+ The session ID of the running s\bsu\bud\bdo\bo process or 0 if s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\bo 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 s\bsu\bud\bdo\bo.
+
+ euid=uid_t
+ The effective user ID of the user invoking s\bsu\bud\bdo\bo.
+
+ uid=uid_t
+ The real user ID of the user invoking s\bsu\bud\bdo\bo.
+
+ egid=gid_t
+ The effective group ID of the user invoking s\bsu\bud\bdo\bo.
+
+ gid=gid_t
+ The real group ID of the user invoking s\bsu\bud\bdo\bo.
+
+ groups=list
+ The user's supplementary group list formatted as a 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
+ The local machine's hostname as returned by the
+ gethostname() system call.
+
+ lines=int
+ The number of lines the user's terminal supports. If there
+ is no terminal device available, a default value of 24 is
+ used.
+
+ cols=int
+ The number of columns the user's terminal supports. If
+ there is no terminal device available, a default value of
+ 80 is used.
+
+ user_env
+ The user's environment in the form of a NULL-terminated vector
+ of "name=value" strings.
+
+ When parsing _\bu_\bs_\be_\br_\b__\be_\bn_\bv, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be 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, _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs will be the NULL pointer.
+
+ NOTE: the _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs parameter is only available starting
+ with API version 1.2. A plugin m\bmu\bus\bst\bt check the API version
+ 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.
+ Failure to do so may result in a crash.
+
+ close
+ void (*close)(int exit_status, int error);
+
+ The close function is called when the command being run by s\bsu\bud\bdo\bo
+ finishes.
+
+ The function arguments are as follows:
+
+ exit_status
+ The command's exit status, as returned by the _\bw_\ba_\bi_\bt(2) system
+ call. The value of exit_status is undefined if error is non-
+ zero.
+
+ error
+ If the command could not be executed, this is set to the value
+ of errno set by the _\be_\bx_\be_\bc_\bv_\be(2) system call. The plugin is
+ responsible for displaying error information via the
+ conversation or plugin_printf function. If the command was
+ successfully executed, the value of error is 0.
+
+ show_version
+ int (*show_version)(int verbose);
+
+ The show_version function is called by s\bsu\bud\bdo\bo when the user specifies
+ the -V option. The plugin may display its version information to
+ the user via the conversation or plugin_printf function using
+ SUDO_CONV_INFO_MSG. If the user requests detailed version
+ information, the verbose flag will be set.
+
+ check_policy
+ int (*check_policy)(int argc, char * const argv[]
+ char *env_add[], char **command_info[],
+ char **argv_out[], char **user_env_out[]);
+
+ The _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by function is called by s\bsu\bud\bdo\bo to determine whether
+ the user is allowed to run the specified commands.
+
+ 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
+ the _\bo_\bp_\be_\bn function, the user has requested _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode. _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt
+ is a mechanism for editing one or more files where an editor is run
+ with the user's credentials instead of with elevated privileges.
+ s\bsu\bud\bdo\bo achieves this by creating user-writable temporary copies of
+ the files to be edited and then overwriting the originals with the
+ temporary copies after editing is complete. If the plugin supports
+ s\bsu\bud\bdo\boe\bed\bdi\bit\bt, it should choose the editor to be used, potentially from
+ a variable in the user's environment, such as EDITOR, and include
+ it in _\ba_\br_\bg_\bv_\b__\bo_\bu_\bt (note that environment variables may include command
+ line flags). The files to be edited should be copied from _\ba_\br_\bg_\bv
+ into _\ba_\br_\bg_\bv_\b__\bo_\bu_\bt, separated from the editor and its arguments by a
+ "--" element. The "--" will be removed by s\bsu\bud\bdo\bo before the editor
+ is executed. The plugin should also set _\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.
+
+ The _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by function returns 1 if the command is allowed, 0 if
+ not allowed, -1 for a general error, or -2 for a usage error or if
+ s\bsu\bud\bdo\boe\bed\bdi\bit\bt was specified but is unsupported by the plugin. In the
+ latter case, s\bsu\bud\bdo\bo will print a usage message before it exits. If
+ an error occurs, the plugin may optionally call the conversation or
+ plugin_printf function with SUDO_CONF_ERROR_MSG to present
+ additional error information to the user.
+
+ The function arguments are as follows:
+
+ argc
+ The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
+ pointer.
+
+ argv
+ The argument vector describing the command the user wishes to
+ run, in the same form as what would be passed to the _\be_\bx_\be_\bc_\bv_\be_\b(_\b)
+ system call. The vector is terminated by a NULL pointer.
+
+ env_add
+ Additional environment variables specified by the user on the
+ command line in the form of a NULL-terminated vector of
+ "name=value" strings. The plugin may reject the command if one
+ or more variables are not allowed to be set, or it may silently
+ ignore such variables.
+
+ When parsing _\be_\bn_\bv_\b__\ba_\bd_\bd, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be might.
+
+ command_info
+ Information about the command being run in the form of
+ "name=value" strings. These values are used by s\bsu\bud\bdo\bo to set the
+ execution environment when running a command. The plugin is
+ responsible for creating and populating the vector, which must
+ be terminated with a NULL pointer. The following values are
+ recognized by s\bsu\bud\bdo\bo:
+
+ command=string
+ 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 _\br_\bu_\bn_\ba_\bs_\b__\bu_\bi_\bd 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 _\br_\bu_\bn_\ba_\bs_\b__\bg_\bi_\bd 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
+ _\bp_\br_\be_\bs_\be_\br_\bv_\be_\b__\bg_\br_\bo_\bu_\bp_\bs 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, s\bsu\bud\bdo\bo will preserve the user's group vector instead
+ of initializing the group vector based on runas_user.
+
+ cwd=string
+ The current working directory to change to when executing
+ the command.
+
+ noexec=bool
+ If set, prevent the command from executing other programs.
+
+ chroot=string
+ The root directory to use when running the command.
+
+ nice=int
+ Nice value (priority) to use when executing the command.
+ The nice value, if specified, overrides the priority
+ associated with the _\bl_\bo_\bg_\bi_\bn_\b__\bc_\bl_\ba_\bs_\bs 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 _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode. The plugin may enable
+ _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt mode even if s\bsu\bud\bdo\bo was not invoked as s\bsu\bud\bdo\boe\bed\bdi\bit\bt.
+ This allows the plugin to perform command substitution and
+ transparently enable _\bs_\bu_\bd_\bo_\be_\bd_\bi_\bt when the user attempts to run
+ an editor.
+
+ closefrom=number
+ If specified, s\bsu\bud\bdo\bo will close all files descriptors with a
+ value of _\bn_\bu_\bm_\bb_\be_\br or higher.
+
+ iolog_compress=bool
+ Set to true if the I/O logging plugins, if any, should
+ compress the log data. This is a hint to the I/O logging
+ plugin which may choose to ignore it.
+
+ iolog_path=string
+ Fully qualified path to the file or directory in which I/O
+ log is to be stored. This is a hint to the I/O logging
+ plugin which may choose to ignore it. If no I/O logging
+ plugin is loaded, this setting has no effect.
+
+ iolog_stdin=bool
+ Set to true if the I/O logging plugins, if any, should log
+ the standard input if it is not connected to a terminal
+ device. This is a hint to the I/O logging plugin which may
+ choose to ignore it.
+
+ iolog_stdout=bool
+ Set to true if the I/O logging plugins, if any, should log
+ the standard output if it is not connected to a terminal
+ device. This is a hint to the I/O logging plugin which may
+ choose to ignore it.
+
+ iolog_stderr=bool
+ Set to true if the I/O logging plugins, if any, should log
+ the standard error if it is not connected to a terminal
+ device. This is a hint to the I/O logging plugin which may
+ choose to ignore it.
+
+ iolog_ttyin=bool
+ Set to true if the I/O logging plugins, if any, should log
+ all terminal input. This only includes input typed by the
+ user and not from a pipe or redirected from a file. This
+ is a hint to the I/O logging plugin which may choose to
+ ignore it.
+
+ iolog_ttyout=bool
+ Set to true if the I/O logging plugins, if any, should log
+ all terminal output. This only includes output to the
+ screen, not output to a pipe or file. This is a hint to
+ the I/O logging plugin which may choose to ignore it.
+
+ 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, s\bsu\bud\bdo\bo
+ will only run the command in a pty when an I/O log plugin
+ is loaded.
+
+ set_utmp=bool
+ Create a utmp (or utmpx) entry when a pseudo-tty is
+ allocated. By default, the new entry will be a copy of the
+ user's existing utmp entry (if any), with the tty, time,
+ type and pid fields updated.
+
+ utmp_user=string
+ User name to use when constructing a new utmp (or utmpx)
+ entry when _\bs_\be_\bt_\b__\bu_\bt_\bm_\bp is enabled. This option can be used to
+ set the user field in the utmp entry to the user the
+ command runs as rather than the invoking user. If not set,
+ s\bsu\bud\bdo\bo will base the new entry on the invoking user's
+ existing entry.
+
+ Unsupported values will be ignored.
+
+ argv_out
+ The NULL-terminated argument vector to pass to the _\be_\bx_\be_\bc_\bv_\be_\b(_\b)
+ system call when executing the command. The plugin is
+ responsible for allocating and populating the vector.
+
+ user_env_out
+ The NULL-terminated environment vector to use when executing
+ the command. The plugin is responsible for allocating and
+ populating the vector.
+
+ list
+ int (*list)(int verbose, const char *list_user,
+ int argc, char * const argv[]);
+
+ List available privileges for the invoking user. Returns 1 on
+ success, 0 on failure and -1 on error. On error, the plugin may
+ optionally call the conversation or plugin_printf function with
+ SUDO_CONF_ERROR_MSG to present additional error information to the
+ user.
+
+ Privileges should be output via the conversation or plugin_printf
+ function using SUDO_CONV_INFO_MSG.
+
+ verbose
+ Flag indicating whether to list in verbose mode or not.
+
+ list_user
+ The name of a different user to list privileges for if the
+ policy allows it. If NULL, the plugin should list the
+ privileges of the invoking user.
+
+ argc
+ The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
+ pointer.
+
+ argv
+ If non-NULL, an argument vector describing a command the user
+ wishes to check against the policy in the same form as what
+ would be passed to the _\be_\bx_\be_\bc_\bv_\be_\b(_\b) system call. If the command is
+ permitted by the policy, the fully-qualified path to the
+ command should be displayed along with any command line
+ arguments.
+
+ validate
+ int (*validate)(void);
+
+ The validate function is called when s\bsu\bud\bdo\bo is run with the -v flag.
+ For policy plugins such as _\bs_\bu_\bd_\bo_\be_\br_\bs that cache authentication
+ credentials, this function will validate and cache the credentials.
+
+ The validate function should be NULL if the plugin does not support
+ credential caching.
+
+ Returns 1 on success, 0 on failure and -1 on error. On error, the
+ plugin may optionally call the conversation or plugin_printf
+ function with SUDO_CONF_ERROR_MSG to present additional error
+ information to the user.
+
+ invalidate
+ void (*invalidate)(int remove);
+
+ The invalidate function is called when s\bsu\bud\bdo\bo is called with the -k
+ or -K flag. For policy plugins such as _\bs_\bu_\bd_\bo_\be_\br_\bs that cache
+ authentication credentials, this function will invalidate the
+ credentials. If the _\br_\be_\bm_\bo_\bv_\be flag is set, the plugin may remove the
+ credentials instead of simply invalidating them.
+
+ The invalidate function should be NULL if the plugin does not
+ support credential caching.
+
+ init_session
+ int (*init_session)(struct passwd *pwd, char **user_envp[);
+
+ The init_session function is called before s\bsu\bud\bdo\bo sets up the
+ execution environment for the command. It is run in the parent
+ s\bsu\bud\bdo\bo process and before any uid or gid changes. This can be used
+ to perform session setup that is not supported by _\bc_\bo_\bm_\bm_\ba_\bn_\bd_\b__\bi_\bn_\bf_\bo,
+ such as opening the PAM session. The close function can be used to
+ tear down the session that was opened by init_session.
+
+ The _\bp_\bw_\bd argument points to a passwd struct for the user the command
+ will be run as if the uid the command will run as was found in the
+ password database, otherwise it will be NULL.
+
+ The _\bu_\bs_\be_\br_\b__\be_\bn_\bv argument points to the environment the command will
+ run in, in the form of a NULL-terminated vector of "name=value"
+ strings. This is the same string passed back to the front end via
+ the Policy Plugin's _\bu_\bs_\be_\br_\b__\be_\bn_\bv_\b__\bo_\bu_\bt parameter. If the init_session
+ function needs to modify the user environment, it should update the
+ pointer stored in _\bu_\bs_\be_\br_\b__\be_\bn_\bv. The expected use case is to merge the
+ contents of the PAM environment (if any) with the contents of
+ _\bu_\bs_\be_\br_\b__\be_\bn_\bv. NOTE: the _\bu_\bs_\be_\br_\b__\be_\bn_\bv parameter is only available starting
+ with API version 1.2. A plugin m\bmu\bus\bst\bt check the API version
+ specified by the s\bsu\bud\bdo\bo front end before using _\bu_\bs_\be_\br_\b__\be_\bn_\bv. Failure to
+ do so may result in a crash.
+
+ Returns 1 on success, 0 on failure and -1 on error. On error, the
+ plugin may optionally call the conversation or plugin_printf
+ function with SUDO_CONF_ERROR_MSG to present additional error
+ information to the user.
+
+ register_hooks
+ void (*register_hooks)(int version,
+ int (*register_hook)(struct sudo_hook *hook));
+
+ The register_hooks function is called by the sudo front end to
+ register any hooks the plugin needs. If the plugin does not
+ support hooks, register_hooks should be set to the NULL pointer.
+
+ The _\bv_\be_\br_\bs_\bi_\bo_\bn argument describes the version of the hooks API
+ supported by the s\bsu\bud\bdo\bo front end.
+
+ The register_hook function should be used to register any supported
+ hooks the plugin needs. It returns 0 on success, 1 if the hook
+ type is not supported and -1 if the major version in struct hook
+ does not match the front end's major hook API version.
+
+ See the "Hook Function API" section below for more information
+ about hooks.
+
+ NOTE: the register_hooks function is only available starting with
+ API version 1.2. If the s\bsu\bud\bdo\bo front end doesn't support API version
+ 1.2 or higher, register_hooks will not be called.
+
+ deregister_hooks
+ void (*deregister_hooks)(int version,
+ int (*deregister_hook)(struct sudo_hook *hook));
+
+ The deregister_hooks function is called by the sudo front end to
+ deregister any hooks the plugin has registered. If the plugin does
+ not support hooks, deregister_hooks should be set to the NULL
+ pointer.
+
+ The _\bv_\be_\br_\bs_\bi_\bo_\bn argument describes the version of the hooks API
+ supported by the s\bsu\bud\bdo\bo front end.
+
+ The deregister_hook function should be used to deregister any hooks
+ that were put in place by the register_hook function. If the
+ plugin tries to deregister a hook that the front end does not
+ support, deregister_hook will return an error.
+
+ See the "Hook Function API" section below for more information
+ about hooks.
+
+ NOTE: the deregister_hooks function is only available starting with
+ API version 1.2. If the s\bsu\bud\bdo\bo front end doesn't support API version
+ 1.2 or higher, deregister_hooks will not be called.
+
+ _\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
+
+ /* Plugin API version major/minor. */
+ #define SUDO_API_VERSION_MAJOR 1
+ #define SUDO_API_VERSION_MINOR 2
+ #define SUDO_API_MKVERSION(x, y) ((x << 16) | y)
+ #define SUDO_API_VERSION SUDO_API_MKVERSION(SUDO_API_VERSION_MAJOR,\
+ SUDO_API_VERSION_MINOR)
+
+ /* Getters and setters for API version */
+ #define SUDO_API_VERSION_GET_MAJOR(v) ((v) >> 16)
+ #define SUDO_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
+ #define SUDO_API_VERSION_SET_MAJOR(vp, n) do { \
+ *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
+ } while(0)
+ #define SUDO_VERSION_SET_MINOR(vp, n) do { \
+ *(vp) = (*(vp) & 0xffff0000) | (n); \
+ } while(0)
+
+ I\bI/\b/O\bO P\bPl\blu\bug\bgi\bin\bn A\bAP\bPI\bI
+ struct io_plugin {
+ #define SUDO_IO_PLUGIN 2
+ unsigned int type; /* always SUDO_IO_PLUGIN */
+ unsigned int version; /* always SUDO_API_VERSION */
+ int (*open)(unsigned int version, sudo_conv_t conversation
+ sudo_printf_t plugin_printf, char * const settings[],
+ char * const user_info[], int argc, char * const argv[],
+ char * const user_env[], char * const plugin_options[]);
+ void (*close)(int exit_status, int error); /* wait status or error */
+ int (*show_version)(int verbose);
+ int (*log_ttyin)(const char *buf, unsigned int len);
+ int (*log_ttyout)(const char *buf, unsigned int len);
+ int (*log_stdin)(const char *buf, unsigned int len);
+ int (*log_stdout)(const char *buf, unsigned int len);
+ int (*log_stderr)(const char *buf, unsigned int len);
+ void (*register_hooks)(int version,
+ int (*register_hook)(struct sudo_hook *hook));
+ void (*deregister_hooks)(int version,
+ int (*deregister_hook)(struct sudo_hook *hook));
+ };
+
+ When an I/O plugin is loaded, s\bsu\bud\bdo\bo runs the command in a pseudo-tty.
+ This makes it possible to log the input and output from the user's
+ session. If any of the standard input, standard output or standard
+ error do not correspond to a tty, s\bsu\bud\bdo\bo will open a pipe to capture the
+ I/O for logging before passing it on.
+
+ The log_ttyin function receives the raw user input from the terminal
+ device (note that this will include input even when echo is disabled,
+ such as when a password is read). The log_ttyout function receives
+ output from the pseudo-tty that is suitable for replaying the user's
+ session at a later time. The log_stdin, log_stdout and log_stderr
+ functions are only called if the standard input, standard output or
+ standard error respectively correspond to something other than a tty.
+
+ Any of the logging functions may be set to the NULL pointer if no
+ logging is to be performed. If the open function returns 0, no I/O
+ will be sent to the plugin.
+
+ The io_plugin struct has the following fields:
+
+ type
+ The type field should always be set to SUDO_IO_PLUGIN
+
+ version
+ The version field should be set to SUDO_API_VERSION.
+
+ This allows s\bsu\bud\bdo\bo to determine the API version the plugin was built
+ against.
+
+ open
+ int (*open)(unsigned int version, sudo_conv_t conversation
+ sudo_printf_t plugin_printf, char * const settings[],
+ char * const user_info[], int argc, char * const argv[],
+ char * const user_env[], char * const plugin_options[]);
+
+ The _\bo_\bp_\be_\bn function is run before the _\bl_\bo_\bg_\b__\bi_\bn_\bp_\bu_\bt, _\bl_\bo_\bg_\b__\bo_\bu_\bt_\bp_\bu_\bt or
+ _\bs_\bh_\bo_\bw_\b__\bv_\be_\br_\bs_\bi_\bo_\bn functions are called. It is only called if the
+ version is being requested or the _\bc_\bh_\be_\bc_\bk_\b__\bp_\bo_\bl_\bi_\bc_\by function has
+ returned successfully. It returns 1 on success, 0 on failure, -1
+ if a general error occurred, or -2 if there was a usage error. In
+ the latter case, s\bsu\bud\bdo\bo will print a usage message before it exits.
+ If an error occurs, the plugin may optionally call the conversation
+ or plugin_printf function with SUDO_CONF_ERROR_MSG to present
+ additional error information to the user.
+
+ The function arguments are as follows:
+
+ version
+ The version passed in by s\bsu\bud\bdo\bo allows the plugin to determine
+ the major and minor version number of the plugin API supported
+ by s\bsu\bud\bdo\bo.
+
+ conversation
+ A pointer to the conversation function that may be used by the
+ _\bs_\bh_\bo_\bw_\b__\bv_\be_\br_\bs_\bi_\bo_\bn function to display version information (see
+ show_version below). The conversation function may also be
+ used to display additional error message to the user. The
+ conversation function returns 0 on success and -1 on failure.
+
+ plugin_printf
+ A pointer to a printf-style function that may be used by the
+ _\bs_\bh_\bo_\bw_\b__\bv_\be_\br_\bs_\bi_\bo_\bn function to display version information (see
+ show_version below). The plugin_printf function may also be
+ used to display additional error message to the user. The
+ plugin_printf function returns number of characters printed on
+ success and -1 on failure.
+
+ settings
+ A vector of user-supplied s\bsu\bud\bdo\bo settings in the form of
+ "name=value" strings. The vector is terminated by a NULL
+ pointer. These settings correspond to flags the user specified
+ when running s\bsu\bud\bdo\bo. As such, they will only be present when the
+ corresponding flag has been specified on the command line.
+
+ When parsing _\bs_\be_\bt_\bt_\bi_\bn_\bg_\bs, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be might.
+
+ See the "Policy Plugin API" section for a list of all possible
+ settings.
+
+ user_info
+ A vector of information about the user running the command in
+ the form of "name=value" strings. The vector is terminated by
+ a NULL pointer.
+
+ When parsing _\bu_\bs_\be_\br_\b__\bi_\bn_\bf_\bo, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be might.
+
+ See the "Policy Plugin API" section for a list of all possible
+ strings.
+
+ argc
+ The number of elements in _\ba_\br_\bg_\bv, not counting the final NULL
+ pointer.
+
+ argv
+ If non-NULL, an argument vector describing a command the user
+ wishes to run in the same form as what would be passed to the
+ _\be_\bx_\be_\bc_\bv_\be_\b(_\b) system call.
+
+ user_env
+ The user's environment in the form of a NULL-terminated vector
+ of "name=value" strings.
+
+ When parsing _\bu_\bs_\be_\br_\b__\be_\bn_\bv, the plugin should split on the f\bfi\bir\brs\bst\bt
+ equal sign ('=') since the _\bn_\ba_\bm_\be field will never include one
+ itself but the _\bv_\ba_\bl_\bu_\be 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, _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs will be the NULL pointer.
+
+ NOTE: the _\bp_\bl_\bu_\bg_\bi_\bn_\b__\bo_\bp_\bt_\bi_\bo_\bn_\bs parameter is only available starting
+ with API version 1.2. A plugin m\bmu\bus\bst\bt check the API version
+ 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.
+ Failure to do so may result in a crash.
+
+ close
+ void (*close)(int exit_status, int error);
+
+ The close function is called when the command being run by s\bsu\bud\bdo\bo
+ finishes.
+
+ The function arguments are as follows:
+
+ exit_status
+ The command's exit status, as returned by the _\bw_\ba_\bi_\bt(2) system
+ call. The value of exit_status is undefined if error is non-
+ zero.
+
+ error
+ If the command could not be executed, this is set to the value
+ of errno set by the _\be_\bx_\be_\bc_\bv_\be(2) system call. If the command was
+ successfully executed, the value of error is 0.
+
+ show_version
+ int (*show_version)(int verbose);
+
+ The show_version function is called by s\bsu\bud\bdo\bo when the user specifies
+ the -V option. The plugin may display its version information to
+ the user via the conversation or plugin_printf function using
+ SUDO_CONV_INFO_MSG. If the user requests detailed version
+ information, the verbose flag will be set.
+
+ log_ttyin
+ int (*log_ttyin)(const char *buf, unsigned int len);
+
+ The _\bl_\bo_\bg_\b__\bt_\bt_\by_\bi_\bn function is called whenever data can be read from the
+ user but before it is passed to the running command. This allows
+ the plugin to reject data if it chooses to (for instance if the
+ input contains banned content). Returns 1 if the data should be
+ passed to the command, 0 if the data is rejected (which will
+ terminate the command) or -1 if an error occurred.
+
+ The function arguments are as follows:
+
+ buf The buffer containing user input.
+
+ len The length of _\bb_\bu_\bf in bytes.
+
+ log_ttyout
+ int (*log_ttyout)(const char *buf, unsigned int len);
+
+ The _\bl_\bo_\bg_\b__\bt_\bt_\by_\bo_\bu_\bt function is called whenever data can be read from
+ the command but before it is written to the user's terminal. This
+ allows the plugin to reject data if it chooses to (for instance if
+ the output contains banned content). Returns 1 if the data should
+ be passed to the user, 0 if the data is rejected (which will
+ terminate the command) or -1 if an error occurred.
+
+ The function arguments are as follows:
+
+ buf The buffer containing command output.
+
+ len The length of _\bb_\bu_\bf in bytes.
+
+ log_stdin
+ int (*log_stdin)(const char *buf, unsigned int len);
+
+ The _\bl_\bo_\bg_\b__\bs_\bt_\bd_\bi_\bn function is only used if the standard input does not
+ correspond to a tty device. It is called whenever data can be read
+ from the standard input but before it is passed to the running
+ command. This allows the plugin to reject data if it chooses to
+ (for instance if the input contains banned content). Returns 1 if
+ the data should be passed to the command, 0 if the data is rejected
+ (which will terminate the command) or -1 if an error occurred.
+
+ The function arguments are as follows:
+
+ buf The buffer containing user input.
+
+ len The length of _\bb_\bu_\bf in bytes.
+
+ log_stdout
+ int (*log_stdout)(const char *buf, unsigned int len);
+
+ The _\bl_\bo_\bg_\b__\bs_\bt_\bd_\bo_\bu_\bt function is only used if the standard output does
+ not correspond to a tty device. It is called whenever data can be
+ read from the command but before it is written to the standard
+ output. This allows the plugin to reject data if it chooses to
+ (for instance if the output contains banned content). Returns 1 if
+ the data should be passed to the user, 0 if the data is rejected
+ (which will terminate the command) or -1 if an error occurred.
+
+ The function arguments are as follows:
+
+ buf The buffer containing command output.
+
+ len The length of _\bb_\bu_\bf in bytes.
+
+ log_stderr
+ int (*log_stderr)(const char *buf, unsigned int len);
+
+ The _\bl_\bo_\bg_\b__\bs_\bt_\bd_\be_\br_\br function is only used if the standard error does not
+ correspond to a tty device. It is called whenever data can be read
+ from the command but before it is written to the standard error.
+ This allows the plugin to reject data if it chooses to (for
+ instance if the output contains banned content). Returns 1 if the
+ data should be passed to the user, 0 if the data is rejected (which
+ will terminate the command) or -1 if an error occurred.
+
+ The function arguments are as follows:
+
+ buf The buffer containing command output.
+
+ len The length of _\bb_\bu_\bf in bytes.
+
+ register_hooks
+ See the "Policy Plugin API" section for a description of
+ register_hooks.
+
+ deregister_hooks
+ See the "Policy Plugin API" section for a description of
+ deregister_hooks.
+
+ _\bI_\b/_\bO _\bP_\bl_\bu_\bg_\bi_\bn _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
+
+ Same as for the "Policy Plugin API".
+
+ H\bHo\boo\bok\bk F\bFu\bun\bnc\bct\bti\bio\bon\bn A\bAP\bPI\bI
+ Beginning with plugin API version 1.2, it is possible to install hooks
+ for certain functions called by the s\bsu\bud\bdo\bo front end.
+
+ Currently, the only supported hooks relate to the handling of
+ environment variables. Hooks can be used to intercept attempts to get,
+ set, or remove environment variables so that these changes can be
+ reflected in the version of the environment that is used to execute a
+ command. A future version of the API will support hooking internal
+ s\bsu\bud\bdo\bo front end functions as well.
+
+ _\bH_\bo_\bo_\bk _\bs_\bt_\br_\bu_\bc_\bt_\bu_\br_\be
+
+ Hooks in s\bsu\bud\bdo\bo are described by the following structure:
+
+ typedef int (*sudo_hook_fn_t)();
+
+ struct sudo_hook {
+ int hook_version;
+ int hook_type;
+ sudo_hook_fn_t hook_fn;
+ void *closure;
+ };
+
+ The sudo_hook structure has the following fields:
+
+ hook_version
+ The hook_version field should be set to SUDO_HOOK_VERSION.
+
+ hook_type
+ The hook_type field may be one of the following supported hook
+ types:
+
+ SUDO_HOOK_SETENV
+ The C library setenv() function. Any registered hooks will run
+ before the C library implementation. The hook_fn field should
+ be a function that matches the following typedef:
+
+ typedef int (*sudo_hook_fn_setenv_t)(const char *name,
+ const char *value, int overwrite, void *closure);
+
+ If the registered hook does not match the typedef the results
+ are unspecified.
+
+ SUDO_HOOK_UNSETENV
+ The C library unsetenv() function. Any registered hooks will
+ run before the C library implementation. The hook_fn field
+ should be a function that matches the following typedef:
+
+ typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
+ void *closure);
+
+ SUDO_HOOK_GETENV
+ The C library getenv() function. Any registered hooks will run
+ before the C library implementation. The hook_fn field should
+ be a function that matches the following typedef:
+
+ typedef int (*sudo_hook_fn_getenv_t)(const char *name,
+ char **value, void *closure);
+
+ If the registered hook does not match the typedef the results
+ are unspecified.
+
+ SUDO_HOOK_PUTENV
+ The C library putenv() function. Any registered hooks will run
+ before the C library implementation. The hook_fn field should
+ be a function that matches the following typedef:
+
+ typedef int (*sudo_hook_fn_putenv_t)(char *string,
+ void *closure);
+
+ If the registered hook does not match the typedef the results
+ are unspecified.
+
+ hook_fn
+ sudo_hook_fn_t hook_fn;
+
+ The hook_fn field should be set to the plugin's hook
+ implementation. The actual function arguments will vary depending
+ on the hook_type (see hook_type above). In all cases, the closure
+ field of struct sudo_hook is passed as the last function parameter.
+ This can be used to pass arbitrary data to the plugin's hook
+ implementation.
+
+ The function return value may be one of the following:
+
+ SUDO_HOOK_RET_ERROR
+ The hook function encountered an error.
+
+ SUDO_HOOK_RET_NEXT
+ The hook completed without error, go on to the next hook
+ (including the native implementation if applicable). For
+ example, a getenv hook might return SUDO_HOOK_RET_NEXT if the
+ specified variable was not found in the private copy of the
+ environment.
+
+ SUDO_HOOK_RET_STOP
+ The hook completed without error, stop processing hooks for
+ this invocation. This can be used to replace the native
+ implementation. For example, a setenv hook that operates on a
+ private copy of the environment but leaves environ unchanged.
+
+ Note that it is very easy to create an infinite loop when hooking C
+ library functions. For example, a getenv hook that calls the snprintf
+ function may create a loop if the snprintf implementation calls getenv
+ to check the locale. To prevent this, you may wish to use a static
+ variable in the hook function to guard against nested calls. E.g.
+
+ static int in_progress = 0; /* avoid recursion */
+ if (in_progress)
+ return SUDO_HOOK_RET_NEXT;
+ in_progress = 1;
+ ...
+ in_progress = 0;
+ return SUDO_HOOK_RET_STOP;
+
+ _\bH_\bo_\bo_\bk _\bA_\bP_\bI _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
+
+ /* Hook API version major/minor */
+ #define SUDO_HOOK_VERSION_MAJOR 1
+ #define SUDO_HOOK_VERSION_MINOR 0
+ #define SUDO_HOOK_MKVERSION(x, y) ((x << 16) | y)
+ #define SUDO_HOOK_VERSION SUDO_HOOK_MKVERSION(SUDO_HOOK_VERSION_MAJOR,\
+ SUDO_HOOK_VERSION_MINOR)
+
+ /* Getters and setters for hook API version */
+ #define SUDO_HOOK_VERSION_GET_MAJOR(v) ((v) >> 16)
+ #define SUDO_HOOK_VERSION_GET_MINOR(v) ((v) & 0xffff)
+ #define SUDO_HOOK_VERSION_SET_MAJOR(vp, n) do { \
+ *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
+ } while(0)
+ #define SUDO_HOOK_VERSION_SET_MINOR(vp, n) do { \
+ *(vp) = (*(vp) & 0xffff0000) | (n); \
+ } while(0)
+
+ C\bCo\bon\bnv\bve\ber\brs\bsa\bat\bti\bio\bon\bn A\bAP\bPI\bI
+ If the plugin needs to interact with the user, it may do so via the
+ conversation function. A plugin should not attempt to read directly
+ from the standard input or the user's tty (neither of which are
+ guaranteed to exist). The caller must include a trailing newline in
+ msg if one is to be printed.
+
+ A printf-style function is also available that can be used to display
+ informational or error messages to the user, which is usually more
+ convenient for simple messages where no use input is required.
+
+ struct sudo_conv_message {
+ #define SUDO_CONV_PROMPT_ECHO_OFF 0x0001 /* do not echo user input */
+ #define SUDO_CONV_PROMPT_ECHO_ON 0x0002 /* echo user input */
+ #define SUDO_CONV_ERROR_MSG 0x0003 /* error message */
+ #define SUDO_CONV_INFO_MSG 0x0004 /* informational message */
+ #define SUDO_CONV_PROMPT_MASK 0x0005 /* mask user input */
+ #define SUDO_CONV_DEBUG_MSG 0x0006 /* debugging message */
+ #define SUDO_CONV_PROMPT_ECHO_OK 0x1000 /* flag: allow echo if no tty */
+ int msg_type;
+ int timeout;
+ const char *msg;
+ };
+
+ struct sudo_conv_reply {
+ char *reply;
+ };
+
+ typedef int (*sudo_conv_t)(int num_msgs,
+ const struct sudo_conv_message msgs[],
+ struct sudo_conv_reply replies[]);
+
+ typedef int (*sudo_printf_t)(int msg_type, const char *fmt, ...);
+
+ Pointers to the conversation and printf-style functions are passed in
+ to the plugin's open function when the plugin is initialized.
+
+ To use the conversation function, the plugin must pass an array of
+ sudo_conv_message and sudo_conv_reply structures. There must be a
+ struct sudo_conv_message and struct sudo_conv_reply for each message in
+ the conversation. The plugin is responsible for freeing the reply
+ buffer filled in to the struct sudo_conv_reply, if any.
+
+ The printf-style function uses the same underlying mechanism as the
+ conversation function but only supports SUDO_CONV_INFO_MSG,
+ SUDO_CONV_ERROR_MSG and SUDO_CONV_DEBUG_MSG for the _\bm_\bs_\bg_\b__\bt_\by_\bp_\be parameter.
+ It can be more convenient than using the conversation function if no
+ user reply is needed and supports standard _\bp_\br_\bi_\bn_\bt_\bf_\b(_\b) escape sequences.
+
+ Unlike, SUDO_CONV_INFO_MSG and SUDO_CONV_ERROR_MSG, messages sent with
+ the <SUDO_CONV_DEBUG_MSG> _\bm_\bs_\bg_\b__\bt_\by_\bp_\be are not directly user-visible.
+ Instead, they are logged to the file specified in the Debug statement
+ (if any) in the _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf file. This allows a plugin to log
+ debugging information and is intended to be used in conjunction with
+ the _\bd_\be_\bb_\bu_\bg_\b__\bf_\bl_\ba_\bg_\bs setting.
+
+ See the sample plugin for an example of the conversation function
+ usage.
+
+ 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
+ The _\bs_\bu_\bd_\bo_\be_\br_\bs module supports a plugin interface to allow non-Unix 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
+ s\bsu\bud\bdo\bo that implements file-based lookups. Third 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 the global scope. This structure contains pointers to the functions
+ that implement plugin initialization, cleanup and group lookup.
+
+ struct sudoers_group_plugin {
+ unsigned int version;
+ int (*init)(int version, sudo_printf_t sudo_printf,
+ char *const argv[]);
+ void (*cleanup)(void);
+ int (*query)(const char *user, const char *group,
+ const struct passwd *pwd);
+ };
+
+ The sudoers_group_plugin struct has the following fields:
+
+ version
+ The version field should be set to GROUP_API_VERSION.
+
+ This allows _\bs_\bu_\bd_\bo_\be_\br_\bs to determine the API version the group plugin
+ was built against.
+
+ init
+ int (*init)(int version, sudo_printf_t plugin_printf,
+ char *const argv[]);
+
+ The _\bi_\bn_\bi_\bt function is called after _\bs_\bu_\bd_\bo_\be_\br_\bs has been parsed but
+ before any policy checks. It returns 1 on success, 0 on failure
+ (or if the plugin is not configured), and -1 if a error occurred.
+ If an error occurs, the plugin may call the plugin_printf function
+ with SUDO_CONF_ERROR_MSG to present additional error information to
+ the user.
+
+ The function arguments are as follows:
+
+ version
+ The version passed in by _\bs_\bu_\bd_\bo_\be_\br_\bs allows the plugin to determine
+ the major and minor version number of the group plugin API
+ supported by _\bs_\bu_\bd_\bo_\be_\br_\bs.
+
+ plugin_printf
+ A pointer to a printf-style function that may be used to
+ display informational or error message to the user. Returns
+ the number of characters printed on success and -1 on failure.
+
+ argv
+ A NULL-terminated array of arguments generated from the
+ _\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,
+ _\ba_\br_\bg_\bv will be NULL.
+
+ cleanup
+ void (*cleanup)();
+
+ The _\bc_\bl_\be_\ba_\bn_\bu_\bp function is called when _\bs_\bu_\bd_\bo_\be_\br_\bs has finished its group
+ checks. The plugin should free any memory it has allocated and
+ close open file handles.
+
+ query
+ int (*query)(const char *user, const char *group,
+ const struct passwd *pwd);
+
+ The _\bq_\bu_\be_\br_\by function is used to ask the group plugin whether _\bu_\bs_\be_\br is
+ a member of _\bg_\br_\bo_\bu_\bp.
+
+ The function arguments are as follows:
+
+ user
+ The name of the user being looked up in the external group
+ database.
+
+ group
+ The name of the group being queried.
+
+ pwd The password database entry for _\bu_\bs_\be_\br, if any. If _\bu_\bs_\be_\br is not
+ present in the password database, _\bp_\bw_\bd will be NULL.
+
+ _\bG_\br_\bo_\bu_\bp _\bA_\bP_\bI _\bV_\be_\br_\bs_\bi_\bo_\bn _\bM_\ba_\bc_\br_\bo_\bs
+
+ /* Sudoers group plugin version major/minor */
+ #define GROUP_API_VERSION_MAJOR 1
+ #define GROUP_API_VERSION_MINOR 0
+ #define GROUP_API_VERSION ((GROUP_API_VERSION_MAJOR << 16) | \
+ GROUP_API_VERSION_MINOR)
+
+ /* Getters and setters for group version */
+ #define GROUP_API_VERSION_GET_MAJOR(v) ((v) >> 16)
+ #define GROUP_API_VERSION_GET_MINOR(v) ((v) & 0xffff)
+ #define GROUP_API_VERSION_SET_MAJOR(vp, n) do { \
+ *(vp) = (*(vp) & 0x0000ffff) | ((n) << 16); \
+ } while(0)
+ #define GROUP_API_VERSION_SET_MINOR(vp, n) do { \
+ *(vp) = (*(vp) & 0xffff0000) | (n); \
+ } while(0)
+
+P\bPL\bLU\bUG\bGI\bIN\bN A\bAP\bPI\bI C\bCH\bHA\bAN\bNG\bGE\bEL\bLO\bOG\bG
+ The following revisions have been made to the Sudo Plugin API.
+
+ Version 1.0
+ Initial API version.
+
+ Version 1.1
+ The I/O logging plugin's open function was modified to take the
+ command_info list as an argument.
+
+ Version 1.2
+ The Policy and I/O logging plugins' open functions are now passed a
+ list of plugin options if any are specified in _\b/_\be_\bt_\bc_\b/_\bs_\bu_\bd_\bo_\b._\bc_\bo_\bn_\bf.
+
+ A simple hooks API has been introduced to allow plugins to hook in
+ to the system's environment handling functions.
+
+ The init_session Policy plugin function is now passed a pointer to
+ the user environment which can be updated as needed. This can be
+ used to merge in environment variables stored in the PAM handle
+ before a command is run.
+
+S\bSE\bEE\bE A\bAL\bLS\bSO\bO
+ _\bs_\bu_\bd_\bo_\be_\br_\bs(4), _\bs_\bu_\bd_\bo(1m)
+
+B\bBU\bUG\bGS\bS
+ If you feel you have found a bug in s\bsu\bud\bdo\bo, please submit a bug report at
+ http://www.sudo.ws/sudo/bugs/
+
+S\bSU\bUP\bPP\bPO\bOR\bRT\bT
+ Limited free support is available via the sudo-workers mailing list,
+ see http://www.sudo.ws/mailman/listinfo/sudo-workers to subscribe or
+ search the archives.
+
+D\bDI\bIS\bSC\bCL\bLA\bAI\bIM\bME\bER\bR
+ s\bsu\bud\bdo\bo is provided ``AS IS'' and any express or implied warranties,
+ including, but not limited to, the implied warranties of
+ merchantability and fitness for a particular purpose are disclaimed.
+ See the LICENSE file distributed with s\bsu\bud\bdo\bo or
+ http://www.sudo.ws/sudo/license.html for complete details.
+
+
+
+1.8.5 April 23, 2012 SUDO_PLUGIN(1m)
projects / debian / sudo / blobdiff