.\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
.\" IT IS GENERATED AUTOMATICALLY FROM sudo_plugin.mdoc.in
.\"
-.\" Copyright (c) 2009-2012 Todd C. Miller <Todd.Miller@courtesan.com>
+.\" Copyright (c) 2009-2013 Todd C. Miller <Todd.Miller@courtesan.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.TH "SUDO_PLUGIN" "5" "July 16, 2012" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
+.TH "SUDO_PLUGIN" "5" "March 5, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
.nh
.if n .ad l
.SH "NAME"
supports a plugin API
for policy and session logging.
By default, the
-\fIsudoers\fR
+\fBsudoers\fR
policy plugin and an associated I/O logging plugin are used.
Via the plugin API,
\fBsudo\fR
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
-\fI@sysconfdir@/sudo.conf\fR
+The plugins to be used are specified in the
+sudo.conf(@mansectform@)
file.
.PP
The API is versioned with a major and minor number.
The plugin API is defined by the
\fRsudo_plugin.h\fR
header file.
-.SS "The sudo.conf file"
-The
-\fI@sysconfdir@/sudo.conf\fR
-file contains plugin configuration directives.
-The primary keyword is the
-\fRPlugin\fR
-directive, which causes a plugin to be loaded.
-.PP
-A
-\fRPlugin\fR
-line consists of the
-\fRPlugin\fR
-keyword, followed by the
-\fIsymbol_name\fR
-and the
-\fIpath\fR
-to the shared object containing the plugin.
-The
-\fIsymbol_name\fR
-is the name of the
-\fRstruct policy_plugin\fR
-or
-\fRstruct io_plugin\fR
-in the plugin shared object.
-The
-\fIpath\fR
-may be fully qualified or relative.
-If not fully qualified it is relative to the
-\fI@prefix@/libexec\fR
-directory.
-Any additional parameters after the
-\fIpath\fR
-are passed as options to the plugin's
-\fBopen\fR()
-function.
-Lines that don't begin with
-\fRPlugin\fR,
-\fRPath\fR,
-\fRDebug\fR
-or
-\fRSet\fR
-are silently ignored.
-.PP
-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.
-.nf
-.sp
-.RS 0n
-#
-# Default @sysconfdir@/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 @prefix@/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
-.RE
-.fi
.SS "Policy plugin API"
A policy plugin must declare and populate a
\fRpolicy_plugin\fR
\fBsudo\fR
policy checks.
The name of the symbol should be specified in
-\fI@sysconfdir@/sudo.conf\fR
+sudo.conf(@mansectform@)
along with a path to the plugin so that
\fBsudo\fR
can load it.
might.
.RS
.TP 6n
+bsdauth_type=string
+Authentication type, if specified by the
+\fB\-a\fR
+flag, to use on
+systems where BSD authentication is supported.
+.TP 6n
+closefrom=number
+If specified, the user has requested via the
+\fB\-C\fR
+flag that
+\fBsudo\fR
+close all files descriptors with a value of
+\fInumber\fR
+or higher.
+The plugin may optionally pass this, or another value, back in the
+\fIcommand_info\fR
+list.
+.TP 6n
debug_flags=string
A comma-separated list of debug flags that correspond to
\fBsudo\fR's
\fRDebug\fR
entry in
-\fI@sysconfdir@/sudo.conf\fR,
+sudo.conf(@mansectform@),
if there is one.
The flags are passed to the plugin as they appear in
-\fI@sysconfdir@/sudo.conf\fR.
+sudo.conf(@mansectform@).
The syntax used by
\fBsudo\fR
and the
-\fIsudoers\fR
+\fBsudoers\fR
plugin is
\fIsubsystem\fR@\fIpriority\fR
but the plugin is free to use a different
format so long as it does not include a comma
(`,\&').
-.sp
-For reference, the priorities supported by the
-\fBsudo\fR
-front end and
-\fIsudoers\fR
-are:
-\fIcrit\fR,
-\fIerr\fR,
-\fIwarn\fR,
-\fInotice\fR,
-\fIdiag\fR,
-\fIinfo\fR,
-\fItrace\fR
-and
-\fIdebug\fR.
-.sp
-The following subsystems are defined:
-\fImain\fR,
-\fImemory\fR,
-\fIargs\fR,
-\fIexec\fR,
-\fIpty\fR,
-\fIutmp\fR,
-\fIconv\fR,
-\fIpcomm\fR,
-\fIutil\fR,
-\fIlist\fR,
-\fInetif\fR,
-\fIaudit\fR,
-\fIedit\fR,
-\fIselinux\fR,
-\fIldap\fR,
-\fImatch\fR,
-\fIparser\fR,
-\fIalias\fR,
-\fIdefaults\fR,
-\fIauth\fR,
-\fIenv\fR,
-\fIlogging\fR,
-\fInss\fR,
-\fIrbtree\fR,
-\fIperms\fR,
-\fIplugin\fR.
-The subsystem
-\fIall\fR
-includes every subsystem.
-.sp
There is not currently a way to specify a set of debug flags specific
to the plugin--the flags are shared by
\fBsudo\fR
This setting has been deprecated in favor of
\fIdebug_flags\fR.
.TP 6n
-runas_user=string
-The user name or uid to to run the command as, if specified via the
-\fB\-u\fR
-flag.
-.TP 6n
-runas_group=string
-The group name or gid to to run the command as, if specified via
-the
-\fB\-g\fR
-flag.
-.TP 6n
-prompt=string
-The prompt to use when requesting a password, if specified via
-the
-\fB\-p\fR
-flag.
-.TP 6n
-set_home=bool
-Set to true if the user specified the
-\fB\-H\fR
-flag.
-If true, set the
-\fRHOME\fR
-environment variable to the target user's home directory.
-.TP 6n
-preserve_environment=bool
-Set to true if the user specified the
-\fB\-E\fR
-flag, indicating that
-the user wishes to preserve the environment.
-.TP 6n
-run_shell=bool
-Set to true if the user specified the
-\fB\-s\fR
-flag, indicating that
-the user wishes to run a shell.
-.TP 6n
-login_shell=bool
+ignore_ticket=bool
Set to true if the user specified the
-\fB\-i\fR
-flag, indicating that
-the user wishes to run a login shell.
-.TP 6n
-implied_shell=bool
-If the user does not specify a program on the command line,
-\fBsudo\fR
-will pass the plugin the path to the user's shell and set
+\fB\-k\fR
+flag along with a
+command, indicating that the user wishes to ignore any cached
+authentication credentials.
\fIimplied_shell\fR
to true.
This allows
to print a usage message and
exit.
.TP 6n
-preserve_groups=bool
-Set to true if the user specified the
-\fB\-P\fR
-flag, indicating that
-the user wishes to preserve the group vector instead of setting it
-based on the runas user.
-.TP 6n
-ignore_ticket=bool
-Set to true if the user specified the
-\fB\-k\fR
-flag along with a
-command, indicating that the user wishes to ignore any cached
-authentication credentials.
-.TP 6n
-noninteractive=bool
-Set to true if the user specified the
-\fB\-n\fR
-flag, indicating that
+implied_shell=bool
+If the user does not specify a program on the command line,
\fBsudo\fR
-should operate in non-interactive mode.
-The plugin may reject a command run in non-interactive mode if user
-interaction is required.
+will pass the plugin the path to the user's shell and set
.TP 6n
login_class=string
BSD login class to use when setting resource limits and nice value,
\fB\-c\fR
flag.
.TP 6n
-selinux_role=string
-SELinux role to use when executing the command, if specified by
-the
-\fB\-r\fR
-flag.
-.TP 6n
-selinux_type=string
-SELinux type to use when executing the command, if specified by
-the
-\fB\-t\fR
-flag.
+login_shell=bool
+Set to true if the user specified the
+\fB\-i\fR
+flag, indicating that
+the user wishes to run a login shell.
.TP 6n
-bsdauth_type=string
-Authentication type, if specified by the
-\fB\-a\fR
-flag, to use on
-systems where BSD authentication is supported.
+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(@mansectform@).
.TP 6n
network_addrs=list
A space-separated list of IP network addresses and netmasks in the
(`:\&'),
it is an IPv6 address, else it is IPv4.
.TP 6n
+noninteractive=bool
+Set to true if the user specified the
+\fB\-n\fR
+flag, indicating that
+\fBsudo\fR
+should operate in non-interactive mode.
+The plugin may reject a command run in non-interactive mode if user
+interaction is required.
+.TP 6n
+plugin_dir=string
+The default plugin directory used by the
+\fBsudo\fR
+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.
+.TP 6n
+preserve_environment=bool
+Set to true if the user specified the
+\fB\-E\fR
+flag, indicating that
+the user wishes to preserve the environment.
+.TP 6n
+preserve_groups=bool
+Set to true if the user specified the
+\fB\-P\fR
+flag, indicating that
+the user wishes to preserve the group vector instead of setting it
+based on the runas user.
+.TP 6n
progname=string
The command name that sudo was run as, typically
``sudo''
or
``sudoedit''.
.TP 6n
+prompt=string
+The prompt to use when requesting a password, if specified via
+the
+\fB\-p\fR
+flag.
+.TP 6n
+run_shell=bool
+Set to true if the user specified the
+\fB\-s\fR
+flag, indicating that
+the user wishes to run a shell.
+.TP 6n
+runas_group=string
+The group name or gid to to run the command as, if specified via
+the
+\fB\-g\fR
+flag.
+.TP 6n
+runas_user=string
+The user name or uid to to run the command as, if specified via the
+\fB\-u\fR
+flag.
+.TP 6n
+selinux_role=string
+SELinux role to use when executing the command, if specified by
+the
+\fB\-r\fR
+flag.
+.TP 6n
+selinux_type=string
+SELinux type to use when executing the command, if specified by
+the
+\fB\-t\fR
+flag.
+.TP 6n
+set_home=bool
+Set to true if the user specified the
+\fB\-H\fR
+flag.
+If true, set the
+\fRHOME\fR
+environment variable to the target user's home directory.
+.TP 6n
sudoedit=bool
Set to true when the
\fB\-e\fR
For more information, see the
\fIcheck_policy\fR
section.
-.TP 6n
-closefrom=number
-If specified, the user has requested via the
-\fB\-C\fR
-flag that
-\fBsudo\fR
-close all files descriptors with a value of
-\fInumber\fR
-or higher.
-The plugin may optionally pass this, or another value, back in the
-\fIcommand_info\fR
-list.
.PP
Additional settings may be added in the future so the plugin should
silently ignore settings that it does not recognize.
.RS
.PD
.TP 6n
+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.
+.TP 6n
+cwd=string
+The user's current working directory.
+.TP 6n
+egid=gid_t
+The effective group ID of the user invoking
+\fBsudo\fR.
+.TP 6n
+euid=uid_t
+The effective user ID of the user invoking
+\fBsudo\fR.
+.TP 6n
+gid=gid_t
+The real group ID of the user invoking
+\fBsudo\fR.
+.TP 6n
+groups=list
+The user's supplementary group list formatted as a string of
+comma-separated group IDs.
+.TP 6n
+host=string
+The local machine's hostname as returned by the
+gethostname(2)
+system call.
+.TP 6n
+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.
+.TP 6n
+pgid=int
+The ID of the process group that the running
+\fBsudo\fR
+process is a member of.
+Only available starting with API version 1.2
+.TP 6n
pid=int
The process ID of the running
\fBsudo\fR
process.
Only available starting with API version 1.2
.TP 6n
+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
+\fRNULL\fR-terminated
+array of strings.
+If no arguments were
+specified,
+\fIplugin_options\fR
+will be the
+\fRNULL\fR
+pointer.
+.sp
+NOTE: the
+\fIplugin_options\fR
+parameter is only available starting with
+API version 1.2.
+A plugin
+\fBmust\fR
+check the API version specified
+by the
+\fBsudo\fR
+front end before using
+\fIplugin_options\fR.
+Failure to do so may result in a crash.
+.TP 6n
ppid=int
The parent process ID of the running
\fBsudo\fR
\fBsudo\fR
process or 0 if
\fBsudo\fR
-is
-not part of a POSIX job control session.
-Only available starting with API version 1.2
-.TP 6n
-pgid=int
-The ID of the process group that the running
-\fBsudo\fR
-process belongs
-to.
+is not part of a POSIX job control session.
Only available starting with API version 1.2
.TP 6n
tcpgid=int
-The ID of the forground process group associated with the terminal
-device associcated with the
+The ID of the foreground process group associated with the terminal
+device associated with the
\fBsudo\fR
process or \-1 if there is no
terminal present.
Only available starting with API version 1.2
.TP 6n
-user=string
-The name of the user invoking
-\fBsudo\fR.
-.TP 6n
-euid=uid_t
-The effective user ID of the user invoking
-\fBsudo\fR.
-.TP 6n
-uid=uid_t
-The real user ID of the user invoking
-\fBsudo\fR.
-.TP 6n
-egid=gid_t
-The effective group ID of the user invoking
-\fBsudo\fR.
-.TP 6n
-gid=gid_t
-The real group ID of the user invoking
-\fBsudo\fR.
-.TP 6n
-groups=list
-The user's supplementary group list formatted as a string of
-comma-separated group IDs.
-.TP 6n
-cwd=string
-The user's current working directory.
-.TP 6n
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
``\fRtty=\fR''.
.TP 6n
-host=string
-The local machine's hostname as returned by the
-gethostname(2)
-system call.
-.TP 6n
-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.
+uid=uid_t
+The real user ID of the user invoking
+\fBsudo\fR.
.TP 6n
-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=string
+The name of the user invoking
+\fBsudo\fR.
.PP
.RE
.PD 0
\fIvalue\fR
might.
.PD
-.TP 6n
-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
-\fRNULL\fR-terminated
-array of strings.
-If no arguments were
-specified,
-\fIplugin_options\fR
-will be the
-\fRNULL\fR
-pointer.
-.sp
-NOTE: the
-\fIplugin_options\fR
-parameter is only available starting with
-API version 1.2.
-A plugin
-\fBmust\fR
-check the API version specified
-by the
-\fBsudo\fR
-front end before using
-\fIplugin_options\fR.
-Failure to do so may result in a crash.
.PP
.RE
.PD 0
\fRerror\fR
is 0.
.PP
+If no
+\fBclose\fR()
+function is defined, no I/O logging plugins are loaded,
+and neither the
+\fItimeout\fR
+not
+\fIuse_pty\fR
+options are set in the
+\fRcommand_info\fR
+list, the
+\fBsudo\fR
+front end may execute the command directly instead of running
+it as a child process.
+.PP
.RE
.PD 0
.TP 6n
\fBsudo\fR:
.RS
.TP 6n
-command=string
-Fully qualified path to the command to be executed.
-.TP 6n
-runas_uid=uid
-User ID to run the command as.
-.TP 6n
-runas_euid=uid
-Effective user ID to run the command as.
-If not specified, the value of
-\fIrunas_uid\fR
-is used.
-.TP 6n
-runas_gid=gid
-Group ID to run the command as.
-.TP 6n
-runas_egid=gid
-Effective group ID to run the command as.
-If not specified, the value of
-\fIrunas_gid\fR
-is used.
-.TP 6n
-runas_groups=list
-The supplementary group vector to use for the command in the form
-of a comma-separated list of group IDs.
-If
-\fIpreserve_groups\fR
-is set, this option is ignored.
-.TP 6n
-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.
-.TP 6n
-preserve_groups=bool
-If set,
-\fBsudo\fR
-will preserve the user's group vector instead of
-initializing the group vector based on
-\fRrunas_user\fR.
-.TP 6n
-cwd=string
-The current working directory to change to when executing the command.
-.TP 6n
-noexec=bool
-If set, prevent the command from executing other programs.
-.TP 6n
chroot=string
The root directory to use when running the command.
.TP 6n
-nice=int
-Nice value (priority) to use when executing the command.
-The nice value, if specified, overrides the priority associated with the
-\fIlogin_class\fR
-on BSD systems.
-.TP 6n
-umask=octal
-The file creation mask to use when executing the command.
-.TP 6n
-selinux_role=string
-SELinux role to use when executing the command.
-.TP 6n
-selinux_type=string
-SELinux type to use when executing the command.
-.TP 6n
-timeout=int
-Command timeout.
-If non-zero then when the timeout expires the command will be killed.
-.TP 6n
-sudoedit=bool
-Set to true when in
-\fIsudoedit\fR
-mode.
-The plugin may enable
-\fIsudoedit\fR
-mode even if
-\fBsudo\fR
-was not invoked as
-\fBsudoedit\fR.
-This allows the plugin to perform command substitution and transparently
-enable
-\fIsudoedit\fR
-when the user attempts to run an editor.
-.TP 6n
closefrom=number
If specified,
\fBsudo\fR
\fInumber\fR
or higher.
.TP 6n
+command=string
+Fully qualified path to the command to be executed.
+.TP 6n
+cwd=string
+The current working directory to change to when executing the command.
+.TP 6n
+exec_background=bool
+By default,
+\fBsudo\fR
+runs a command as the foreground process as long as
+\fBsudo\fR
+itself is running in the foreground.
+When
+\fIexec_background\fR
+is enabled and the command is being run in a pty (due to I/O logging
+or the
+\fIuse_pty\fR
+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
+\fRSIGTTIN\fR
+signal (or
+\fRSIGTTOU\fR
+in the case of terminal settings).
+If this happens when
+\fBsudo\fR
+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
+\fBsudo\fR
+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
+\fIsudo\fR
+behavior or when the command is not being run in a pty.
+.sp
+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
+\fBtcgetattr\fR()
+and
+\fBtcsetattr\fR()
+system calls (this is a bug in Mac OS X).
+Furthermore, because this behavior depends on the command stopping with the
+\fRSIGTTIN\fR
+or
+\fRSIGTTOU\fR
+signals, programs that catch these signals and suspend themselves
+with a different signal (usually
+\fRSIGTOP\fR)
+will not be automatically foregrounded.
+Some versions of the linux
+su(1)
+command behave this way.
+Because of this, a plugin should not set
+\fIexec_background\fR
+unless it is explicitly enabled by the administrator and there should
+be a way to enabled or disable it on a per-command basis.
+.sp
+This setting has no effect unless I/O logging is enabled or
+\fIuse_pty\fR
+is enabled.
+.TP 6n
iolog_compress=bool
Set to true if the I/O logging plugins, if any, should compress the
log data.
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.
.TP 6n
+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.
+.TP 6n
+nice=int
+Nice value (priority) to use when executing the command.
+The nice value, if specified, overrides the priority associated with the
+\fIlogin_class\fR
+on BSD systems.
+.TP 6n
+noexec=bool
+If set, prevent the command from executing other programs.
+.TP 6n
+preserve_groups=bool
+If set,
+\fBsudo\fR
+will preserve the user's group vector instead of
+initializing the group vector based on
+\fRrunas_user\fR.
+.TP 6n
+runas_egid=gid
+Effective group ID to run the command as.
+If not specified, the value of
+\fIrunas_gid\fR
+is used.
+.TP 6n
+runas_euid=uid
+Effective user ID to run the command as.
+If not specified, the value of
+\fIrunas_uid\fR
+is used.
+.TP 6n
+runas_gid=gid
+Group ID to run the command as.
+.TP 6n
+runas_groups=list
+The supplementary group vector to use for the command in the form
+of a comma-separated list of group IDs.
+If
+\fIpreserve_groups\fR
+is set, this option is ignored.
+.TP 6n
+runas_uid=uid
+User ID to run the command as.
+.TP 6n
+selinux_role=string
+SELinux role to use when executing the command.
+.TP 6n
+selinux_type=string
+SELinux type to use when executing the command.
+.TP 6n
+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.
+.TP 6n
+sudoedit=bool
+Set to true when in
+\fIsudoedit\fR
+mode.
+The plugin may enable
+\fIsudoedit\fR
+mode even if
+\fBsudo\fR
+was not invoked as
+\fBsudoedit\fR.
+This allows the plugin to perform command substitution and transparently
+enable
+\fIsudoedit\fR
+when the user attempts to run an editor.
+.TP 6n
+timeout=int
+Command timeout.
+If non-zero then when the timeout expires the command will be killed.
+.TP 6n
+umask=octal
+The file creation mask to use when executing the command.
+.TP 6n
use_pty=bool
Allocate a pseudo-tty to run the command in, regardless of whether
or not I/O logging is in use.
will only run
the command in a pty when an I/O log plugin is loaded.
.TP 6n
-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.
-.TP 6n
utmp_user=string
User name to use when constructing a new utmp (or utmpx) entry when
\fIset_utmp\fR
\fB\-v\fR
flag.
For policy plugins such as
-\fIsudoers\fR
+\fBsudoers\fR
that cache
authentication credentials, this function will validate and cache
the credentials.
\fB\-K\fR
flag.
For policy plugins such as
-\fIsudoers\fR
+\fBsudoers\fR
that
cache authentication credentials, this function will invalidate the
credentials.
#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);
.RS
.nf
.RS 0n
-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[]);
.PP
Same as for the
\fIPolicy plugin API\fR.
+.SS "Signal handlers"
+The
+\fBsudo\fR
+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:
+.TP 4n
+\fBo\fR
+\fRSIGALRM\fR
+.PD 0
+.TP 4n
+\fBo\fR
+\fRSIGHUP\fR
+.TP 4n
+\fBo\fR
+\fRSIGINT\fR
+.TP 4n
+\fBo\fR
+\fRSIGQUIT\fR
+.TP 4n
+\fBo\fR
+\fRSIGTERM\fR
+.TP 4n
+\fBo\fR
+\fRSIGTSTP\fR
+.TP 4n
+\fBo\fR
+\fRSIGUSR1\fR
+.TP 4n
+\fBo\fR
+\fRSIGUSR2\fR
+.PD
+.PP
+If a fatal signal is received before the command is executed,
+\fBsudo\fR
+will call the plugin's
+\fBclose\fR()
+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
+\fBclose\fR()
+function.
+.PP
+A plugin may temporarily install its own signal handlers but must
+restore the original handler before the plugin function returns.
.SS "Hook function API"
Beginning with plugin API version 1.2, it is possible to install
hooks for certain functions called by the
Instead, they are logged to the file specified in the
\fRDebug\fR
statement (if any) in the
-\fI@sysconfdir@/sudo.conf\fR
-.PP
+sudo.conf(@mansectform@).
file.
This allows a plugin to log debugging information and is intended
to be used in conjunction with the
function usage.
.SS "Sudoers group plugin API"
The
-\fIsudoers\fR
-module supports a plugin interface to allow non-Unix
+\fBsudoers\fR
+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.
-A sample group plugin is bundled with
-\fBsudo\fR
-that implements file-based lookups.
+Two sample group plugins are bundled with
+\fBsudo\fR,
+\fIgroup_file\fR
+and
+\fIsystem_group\fR,
+are detailed in
+sudoers(@mansectform@).
Third party group plugins include a QAS AD plugin available from Quest Software.
.PP
A group plugin must declare and populate a
field should be set to GROUP_API_VERSION.
.sp
This allows
-\fIsudoers\fR
+\fBsudoers\fR
to determine the API version the group plugin
was built against.
.TP 6n
.TP 6n
version
The version passed in by
-\fIsudoers\fR
+\fBsudoers\fR
allows the plugin to determine the
major and minor version number of the group plugin API supported by
-\fIsudoers\fR.
+\fBsudoers\fR.
.TP 6n
plugin_printf
A pointer to a
The
\fBcleanup\fR()
function is called when
-\fIsudoers\fR
+\fBsudoers\fR
has finished its
group checks.
The plugin should free any memory it has allocated and close open file handles.
Version 1.0
Initial API version.
.TP 6n
-Version 1.1
+Version 1.1 (sudo 1.8.0)
The I/O logging plugin's
\fBopen\fR()
function was modified to take the
\fRcommand_info\fR
list as an argument.
.TP 6n
-Version 1.2
+Version 1.2 (sudo 1.8.5)
The Policy and I/O logging plugins'
\fBopen\fR()
functions are now passed
-a list of plugin options if any are specified in
-\fI@sysconfdir@/sudo.conf\fR.
+a list of plugin parameters if any are specified in
+sudo.conf(@mansectform@).
.sp
A simple hooks API has been introduced to allow plugins to hook in to the
system's environment handling functions.
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.
+.TP 6n
+Version 1.3 (sudo 1.8.7)
+Support for the
+\fIexec_background\fR
+entry has been added to the
+\fRcommand_info\fR
+list.
+.sp
+The
+\fImax_groups\fR
+and
+\fIplugin_dir\fR
+entries were added to the
+\fRsettings\fR
+list.
+.sp
+The
+\fBversion\fR()
+and
+\fBclose\fR()
+functions are now optional.
+Previously, a missing
+\fBversion\fR()
+or
+\fBclose\fR()
+function would result in a crash.
+If no policy plugin
+\fBclose\fR()
+function is defined, a default
+\fBclose\fR()
+function will be provided by the
+\fBsudo\fR
+front end that displays a warning if the command could not be
+executed.
+.sp
+The
+\fBsudo\fR
+front end now installs default signal handlers to trap common signals
+while the plugin functions are run.
.SH "SEE ALSO"
+sudo.conf(@mansectform@),
sudoers(@mansectform@),
sudo(@mansectsu@)
.SH "BUGS"
projects / debian / sudo / blobdiff