X-Git-Url: https://git.gag.com/?a=blobdiff_plain;f=doc%2Fsudo_plugin.cat;h=193da0e8b46cdc0b551f80504159451aa3b2c20b;hb=e8db7f6eea9b35527ddd4532affabd18a30549b5;hp=11e9dd733dfc1634526425f629453e6bf5ab9f40;hpb=98b9fd63cd28a3636a7cd24641b8f497eaadcd50;p=debian%2Fsudo diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index 11e9dd7..193da0e 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -5,11 +5,10 @@ NNAAMMEE DDEESSCCRRIIPPTTIIOONN 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 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 - file. + parties. The plugins to be used are specified in the sudo.conf(4) 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 @@ -18,50 +17,11 @@ DDEESSCCRRIIPPTTIIOONN 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 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 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. struct policy_plugin { @@ -141,92 +101,109 @@ DDEESSCCRRIIPPTTIIOONN equal sign (`=') since the _n_a_m_e field will never include one 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 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 - one. The flags are passed to the plugin as they appear - in _/_e_t_c_/_s_u_d_o_._c_o_n_f. The syntax used by ssuuddoo and the - _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 - free to use a different format so long as it does not - include a comma (`,'). - - 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. + to ssuuddoo's Debug entry in sudo.conf(4), if there is one. + The flags are passed to the plugin as they appear in + sudo.conf(4). The syntax used by ssuuddoo and the ssuuddooeerrss + 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 + use a different format so long as it does not include a + 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. debug_level=number This setting has been deprecated in favor of _d_e_b_u_g___f_l_a_g_s. - runas_user=string - The user name or uid to to run the command as, if - specified via the --uu flag. + ignore_ticket=bool + Set to true if the user specified the --kk flag along + 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 - The group name or gid to to run the command as, if - specified via the --gg flag. + 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 - prompt=string - The prompt to use when requesting a password, if - specified via the --pp flag. + login_class=string + BSD login class to use when setting resource limits and + nice value, if specified by the --cc flag. - set_home=bool - Set to true if the user specified the --HH flag. If - true, set the HOME environment variable to the target - user's home directory. + login_shell=bool + Set to true if the user specified the --ii flag, + indicating that the user wishes to run a login shell. + + 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 Set to true if the user specified the --EE flag, indicating that the user wishes to preserve the 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 Set to true if the user specified the --PP 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 --kk flag along - with a command, indicating that the user wishes to - ignore any cached authentication credentials. + progname=string + The command name that sudo was run as, typically + ``sudo'' or ``sudoedit''. - 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. + prompt=string + The prompt to use when requesting a password, if + specified via the --pp flag. - login_class=string - BSD login class to use when setting resource limits and - nice value, if specified by the --cc flag. + run_shell=bool + Set to true if the user specified the --ss 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 to use when executing the command, if @@ -236,21 +213,10 @@ DDEESSCCRRIIPPTTIIOONN SELinux type to use when executing the command, if specified by the --tt flag. - bsdauth_type=string - Authentication type, if specified by the --aa 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''. + set_home=bool + Set to true if the user specified the --HH flag. If + true, set the HOME environment variable to the target + user's home directory. sudoedit=bool Set to true when the --ee flag is is specified or if @@ -260,12 +226,6 @@ DDEESSCCRRIIPPTTIIOONN 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. - 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 should silently ignore settings that it does not recognize. @@ -278,42 +238,20 @@ DDEESSCCRRIIPPTTIIOONN equal sign (`=') since the _n_a_m_e field will never include one itself but the _v_a_l_u_e might. - pid=int - The process ID of the running ssuuddoo process. Only - available starting with API version 1.2 - - 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 - - pgid=int - The ID of the process group that the running ssuuddoo - process belongs to. Only available starting with API - version 1.2 + 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. - 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 + cwd=string + The user's current working directory. - user=string - The name of the user invoking ssuuddoo. + egid=gid_t + The effective group ID of the user invoking ssuuddoo. euid=uid_t 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 The real group ID of the user invoking ssuuddoo. @@ -321,14 +259,6 @@ DDEESSCCRRIIPPTTIIOONN 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(2) system call. @@ -338,10 +268,54 @@ DDEESSCCRRIIPPTTIIOONN 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. + pgid=int + The ID of the process group that the running ssuuddoo + process is a member of. Only available starting with + 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 The user's environment in the form of a NULL-terminated @@ -351,19 +325,6 @@ DDEESSCCRRIIPPTTIIOONN equal sign (`=') since the _n_a_m_e field will never include one 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 void (*close)(int exit_status, int error); @@ -384,6 +345,11 @@ DDEESSCCRRIIPPTTIIOONN ccoonnvveerrssaattiioonn() or pplluuggiinn__pprriinnttff() function. If the command 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 int (*show_version)(int verbose); @@ -454,79 +420,62 @@ DDEESSCCRRIIPPTTIIOONN must be terminated with a NULL pointer. The following values are recognized by ssuuddoo: - 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 _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. + chroot=string + The root directory to use when running the command. - 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. + closefrom=number + If specified, ssuuddoo will close all files descriptors + with a value of _n_u_m_b_e_r or higher. - preserve_groups=bool - If set, ssuuddoo will preserve the user's group vector - instead of initializing the group vector based on - runas_user. + command=string + Fully qualified path to the command to be executed. 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 _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. + exec_background=bool + By default, ssuuddoo runs a command as the foreground + 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. + + For this to work seamlessly, the operating system must + 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. + + This setting has no effect unless I/O logging is + enabled or _u_s_e___p_t_y is enabled. iolog_compress=bool Set to true if the I/O logging plugins, if any, should @@ -572,11 +521,50 @@ DDEESSCCRRIIPPTTIIOONN 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, - ssuuddoo will only run the command in a pty when an I/O log - plugin is loaded. + 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. + + 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 Create a utmp (or utmpx) entry when a pseudo-tty is @@ -584,6 +572,27 @@ DDEESSCCRRIIPPTTIIOONN the user's existing utmp entry (if any), with the tty, 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 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 @@ -639,7 +648,7 @@ DDEESSCCRRIIPPTTIIOONN int (*validate)(void); 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. The vvaalliiddaattee() function should be NULL if the plugin does not @@ -654,7 +663,7 @@ DDEESSCCRRIIPPTTIIOONN void (*invalidate)(int remove); 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 credentials. If the _r_e_m_o_v_e flag is set, the plugin may remove the credentials instead of simply invalidating them. @@ -764,10 +773,11 @@ DDEESSCCRRIIPPTTIIOONN #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 + 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[]); + char * const user_info[], char * const command_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); @@ -810,7 +820,7 @@ DDEESSCCRRIIPPTTIIOONN against. 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[], char * const user_info[], int argc, char * const argv[], char * const user_env[], char * const plugin_options[]); @@ -1025,6 +1035,29 @@ DDEESSCCRRIIPPTTIIOONN 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 Beginning with plugin API version 1.2, it is possible to install hooks for certain functions called by the ssuuddoo front end. @@ -1215,20 +1248,20 @@ DDEESSCCRRIIPPTTIIOONN 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. 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 - - 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. + 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. See the sample plugin for an example of the ccoonnvveerrssaattiioonn() function usage. SSuuddooeerrss ggrroouupp pplluuggiinn AAPPII - The _s_u_d_o_e_r_s 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 ssuuddoo - that implements file-based lookups. Third party group plugins include a - QAS AD plugin available from Quest Software. + The ssuuddooeerrss plugin supports its own plugin interface to allow non-Unix + group lookups. This can be used to query a group source other than the + standard Unix group database. Two sample group plugins are bundled with + 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 + 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 @@ -1248,7 +1281,7 @@ DDEESSCCRRIIPPTTIIOONN 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. init @@ -1265,9 +1298,9 @@ DDEESSCCRRIIPPTTIIOONN The function arguments are as follows: 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 - plugin API supported by _s_u_d_o_e_r_s. + plugin API supported by ssuuddooeerrss. plugin_printf A pointer to a pprriinnttff()-style function that may be used to @@ -1282,7 +1315,7 @@ DDEESSCCRRIIPPTTIIOONN 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 and close open file handles. @@ -1328,13 +1361,13 @@ PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG Version 1.0 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 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 - 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 to the system's environment handling functions. @@ -1344,8 +1377,24 @@ PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG used to merge in environment variables stored in the PAM handle 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 - sudoers(4), sudo(1m) + sudo.conf(4), sudoers(4), sudo(1m) BBUUGGSS If you feel you have found a bug in ssuuddoo, please submit a bug report at @@ -1363,4 +1412,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or http://www.sudo.ws/sudo/license.html for complete details. -Sudo 1.8.6 July 16, 2012 Sudo 1.8.6 +Sudo 1.8.7 March 5, 2013 Sudo 1.8.7