embedaddon/sudo/doc/sudo_plugin.man.in - diff

Return to sudo_plugin.man.in CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc

Diff for /embedaddon/sudo/doc/sudo_plugin.man.in between versions 1.1.1.3 and 1.1.1.6

version 1.1.1.3, 2012/10/09 09:29:52	version 1.1.1.6, 2014/06/15 16:12:54
Line 1	Line 1
.\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!	.\" DO NOT EDIT THIS FILE, IT IS NOT THE MASTER!
.\" IT IS GENERATED AUTOMATICALLY FROM sudo_plugin.mdoc.in	.\" 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	.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above	.\" purpose with or without fee is hereby granted, provided that the above
Line 16	Line 16
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.	.\" 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" "December 20, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
.nh	.nh
.if n .ad l	.if n .ad l
.SH "NAME"	.SH "NAME"
Line 27 Starting with version 1.8,	Line 27 Starting with version 1.8,
\fBsudo\fR	\fBsudo\fR
supports a plugin API	supports a plugin API
for policy and session logging.	for policy and session logging.
	Plugins may be compiled as dynamic shared objects (the default on
	systems that support them) or compiled statically into the
	\fBsudo\fR
	binary itself.
By default, the	By default, the
\fIsudoers\fR	\fBsudoers\fR
policy plugin and an associated I/O logging plugin are used.	policy plugin and an associated I/O logging plugin are used.
Via the plugin API,	Via the plugin API,
\fBsudo\fR	\fBsudo\fR
can be configured to use alternate policy and/or I/O logging plugins	can be configured to use alternate policy and/or I/O logging plugins
provided by third parties.	provided by third parties.
The plugins to be used are specified via the	The plugins to be used are specified in the
\fI@sysconfdir@/sudo.conf\fR	sudo.conf(@mansectform@)
file.	file.
.PP	.PP
The API is versioned with a major and minor number.	The API is versioned with a major and minor number.
Line 47 major version matches.	Line 51 major version matches.
The plugin API is defined by the	The plugin API is defined by the
\fRsudo_plugin.h\fR	\fRsudo_plugin.h\fR
header file.	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"	.SS "Policy plugin API"
A policy plugin must declare and populate a	A policy plugin must declare and populate a
\fRpolicy_plugin\fR	\fRpolicy_plugin\fR
Line 127 This structure contains pointers to the functions that	Line 59 This structure contains pointers to the functions that
\fBsudo\fR	\fBsudo\fR
policy checks.	policy checks.
The name of the symbol should be specified in	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	along with a path to the plugin so that
\fBsudo\fR	\fBsudo\fR
can load it.	can load it.
Line 179 to determine the API version the plugin was	Line 111 to determine the API version the plugin was
built against.	built against.
.TP 6n	.TP 6n
open	open
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*open)(unsigned int version, sudo_conv_t conversation,	int (*open)(unsigned int version, sudo_conv_t conversation,
sudo_printf_t plugin_printf, char * const settings[],	sudo_printf_t plugin_printf, char * const settings[],
char * const user_info[], char * const user_env[],	char * const user_info[], char * const user_env[],
char * const plugin_options[]);	char * const plugin_options[]);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
Returns 1 on success, 0 on failure, \-1 if a general error occurred,	Returns 1 on success, 0 on failure, \-1 if a general error occurred,
or \-2 if there was a usage error.	or \-2 if there was a usage error.
Line 228 settings	Line 160 settings
A vector of user-supplied	A vector of user-supplied
\fBsudo\fR	\fBsudo\fR
settings in the form of	settings in the form of
``name=value''	\(lqname=value\(rq
strings.	strings.
The vector is terminated by a	The vector is terminated by a
\fRNULL\fR	\fRNULL\fR
Line 243 When parsing	Line 175 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
itself but the	itself but the
\fIvalue\fR	\fIvalue\fR
might.	might.
.RS	.PP
	.RS 6n
	.PD 0
.TP 6n	.TP 6n
	bsdauth_type=string
	Authentication type, if specified by the
	\fB\-a\fR
	flag, to use on
	systems where BSD authentication is supported.
	.PD
	.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	debug_flags=string
A comma-separated list of debug flags that correspond to	A comma-separated list of debug flags that correspond to
\fBsudo\fR's	\fBsudo\fR's
\fRDebug\fR	\fRDebug\fR
entry in	entry in
\fI@sysconfdir@/sudo.conf\fR,	sudo.conf(@mansectform@),
if there is one.	if there is one.
The flags are passed to the plugin as they appear in	The flags are passed to the plugin as they appear in
\fI@sysconfdir@/sudo.conf\fR.	sudo.conf(@mansectform@).
The syntax used by	The syntax used by
\fBsudo\fR	\fBsudo\fR
and the	and the
\fIsudoers\fR	\fBsudoers\fR
plugin is	plugin is
\fIsubsystem\fR@\fIpriority\fR	\fIsubsystem\fR@\fIpriority\fR
but the plugin is free to use a different	but the plugin is free to use a different
format so long as it does not include a comma	format so long as it does not include a comma
(`,\&').	(\(oq,\&\(cq).
.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	There is not currently a way to specify a set of debug flags specific
to the plugin--the flags are shared by	to the plugin--the flags are shared by
\fBsudo\fR	\fBsudo\fR
Line 326 debug_level=number	Line 232 debug_level=number
This setting has been deprecated in favor of	This setting has been deprecated in favor of
\fIdebug_flags\fR.	\fIdebug_flags\fR.
.TP 6n	.TP 6n
runas_user=string	ignore_ticket=bool
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	Set to true if the user specified the
\fB\-H\fR	\fB\-k\fR
flag.	flag along with a
If true, set the	command, indicating that the user wishes to ignore any cached
\fRHOME\fR	authentication credentials.
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
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
\fIimplied_shell\fR	\fIimplied_shell\fR
to true.	to true.
This allows	This allows
Line 388 function, which will cause	Line 253 function, which will cause
to print a usage message and	to print a usage message and
exit.	exit.
.TP 6n	.TP 6n
preserve_groups=bool	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
	.TP 6n
	login_class=string
	BSD login class to use when setting resource limits and nice value,
	if specified by the
	\fB\-c\fR
	flag.
	.TP 6n
	login_shell=bool
Set to true if the user specified the	Set to true if the user specified the
\fB\-P\fR	\fB\-i\fR
flag, indicating that	flag, indicating that
the user wishes to preserve the group vector instead of setting it	the user wishes to run a login shell.
based on the runas user.
.TP 6n	.TP 6n
ignore_ticket=bool	max_groups=int
Set to true if the user specified the	The maximum number of groups a user may belong to.
\fB\-k\fR	This will only be present if there is a corresponding setting in
flag along with a	sudo.conf(@mansectform@).
command, indicating that the user wishes to ignore any cached
authentication credentials.
.TP 6n	.TP 6n
	network_addrs=list
	A space-separated list of IP network addresses and netmasks in the
	form
	\(lqaddr/netmask\(rq,
	e.g.\&
	\(lq192.168.1.2/255.255.255.0\(rq.
	The address and netmask pairs may be either IPv4 or IPv6, depending on
	what the operating system supports.
	If the address contains a colon
	(\(oq:\&\(cq),
	it is an IPv6 address, else it is IPv4.
	.TP 6n
noninteractive=bool	noninteractive=bool
Set to true if the user specified the	Set to true if the user specified the
\fB\-n\fR	\fB\-n\fR
Line 411 should operate in non-interactive mode.	Line 296 should operate in non-interactive mode.
The plugin may reject a command run in non-interactive mode if user	The plugin may reject a command run in non-interactive mode if user
interaction is required.	interaction is required.
.TP 6n	.TP 6n
login_class=string	plugin_dir=string
BSD login class to use when setting resource limits and nice value,	The default plugin directory used by the
if specified by the	\fBsudo\fR
\fB\-c\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
	\(lqsudo\(rq
	or
	\(lqsudoedit\(rq.
	.TP 6n
	prompt=string
	The prompt to use when requesting a password, if specified via
	the
	\fB\-p\fR
flag.	flag.
.TP 6n	.TP 6n
	remote_host=string
	The name of the remote host to run the command on, if specified via
	the
	\fB\-h\fR
	option.
	Support for running the command on a remote host is meant to be implemented
	via a helper program that is executed in place of the user-specified command.
	The
	\fBsudo\fR
	front end is only capable of executing commands on the local host.
	Only available starting with API version 1.4.
	.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 run the command as, if specified via
	the
	\fB\-g\fR
	flag.
	.TP 6n
	runas_user=string
	The user name or uid to run the command as, if specified via the
	\fB\-u\fR
	flag.
	.TP 6n
selinux_role=string	selinux_role=string
SELinux role to use when executing the command, if specified by	SELinux role to use when executing the command, if specified by
the	the
Line 429 the	Line 369 the
\fB\-t\fR	\fB\-t\fR
flag.	flag.
.TP 6n	.TP 6n
bsdauth_type=string	set_home=bool
Authentication type, if specified by the	Set to true if the user specified the
\fB\-a\fR	\fB\-H\fR
flag, to use on	flag.
systems where BSD authentication is supported.	If true, set the
	\fRHOME\fR
	environment variable to the target user's home directory.
.TP 6n	.TP 6n
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.
.TP 6n
progname=string
The command name that sudo was run as, typically
``sudo''
or
``sudoedit''.
.TP 6n
sudoedit=bool	sudoedit=bool
Set to true when the	Set to true when the
\fB\-e\fR	\fB\-e\fR
Line 468 if the plugin does not support	Line 392 if the plugin does not support
For more information, see the	For more information, see the
\fIcheck_policy\fR	\fIcheck_policy\fR
section.	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	.PP
Additional settings may be added in the future so the plugin should	Additional settings may be added in the future so the plugin should
silently ignore settings that it does not recognize.	silently ignore settings that it does not recognize.
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
user_info	user_info
A vector of information about the user running the command in the form of	A vector of information about the user running the command in the form of
``name=value''	\(lqname=value\(rq
strings.	strings.
The vector is terminated by a	The vector is terminated by a
\fRNULL\fR	\fRNULL\fR
Line 500 When parsing	Line 410 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
itself but the	itself but the
\fIvalue\fR	\fIvalue\fR
might.	might.
.RS	.PP
	.RS 6n
	.PD 0
	.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.
.PD	.PD
.TP 6n	.TP 6n
pid=int	cwd=string
The process ID of the running	The user's current working directory.
\fBsudo\fR
process.
Only available starting with API version 1.2
.TP 6n	.TP 6n
ppid=int	egid=gid_t
The parent process ID of the running	The effective group ID of the user invoking
\fBsudo\fR
process.
Only available starting with API version 1.2
.TP 6n
sid=int
The session ID of the running
\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.
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
\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.	\fBsudo\fR.
.TP 6n	.TP 6n
euid=uid_t	euid=uid_t
The effective user ID of the user invoking	The effective user ID of the user invoking
\fBsudo\fR.	\fBsudo\fR.
.TP 6n	.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	gid=gid_t
The real group ID of the user invoking	The real group ID of the user invoking
\fBsudo\fR.	\fBsudo\fR.
Line 570 groups=list	Line 445 groups=list
The user's supplementary group list formatted as a string of	The user's supplementary group list formatted as a string of
comma-separated group IDs.	comma-separated group IDs.
.TP 6n	.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	host=string
The local machine's hostname as returned by the	The local machine's hostname as returned by the
gethostname(2)	gethostname(2)
Line 589 The number of lines the user's terminal supports.	Line 455 The number of lines the user's terminal supports.
If there is	If there is
no terminal device available, a default value of 24 is used.	no terminal device available, a default value of 24 is used.
.TP 6n	.TP 6n
cols=int	pgid=int
The number of columns the user's terminal supports.	The ID of the process group that the running
If there is no terminal device available, a default value of 80 is used.	\fBsudo\fR
.PP	process is a member of.
.RE	Only available starting with API version 1.2.
.PD 0
.TP 6n	.TP 6n
user_env	pid=int
The user's environment in the form of a	The process ID of the running
\fRNULL\fR-terminated vector of	\fBsudo\fR
``name=value''	process.
strings.	Only available starting with API version 1.2.
.sp
When parsing
\fIuser_env\fR,
the plugin should split on the
\fBfirst\fR
equal sign
(`=')
since the
\fIname\fR
field will never include one
itself but the
\fIvalue\fR
might.
.PD
.TP 6n	.TP 6n
plugin_options	plugin_options
Any (non-comment) strings immediately after the plugin path are	Any (non-comment) strings immediately after the plugin path are
treated as arguments to the plugin.	passed as arguments to the plugin.
These arguments are split on a white space boundary and are passed to	These arguments are split on a white space boundary and are passed to
the plugin in the form of a	the plugin in the form of a
\fRNULL\fR-terminated	\fRNULL\fR-terminated
Line 642 by the	Line 493 by the
front end before using	front end before using
\fIplugin_options\fR.	\fIplugin_options\fR.
Failure to do so may result in a crash.	Failure to do so may result in a crash.
	.TP 6n
	ppid=int
	The parent process ID of the running
	\fBsudo\fR
	process.
	Only available starting with API version 1.2.
	.TP 6n
	sid=int
	The session ID of the running
	\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
	tcpgid=int
	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
	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
	\(lq\fRtty=\fR\(rq.
	.TP 6n
	uid=uid_t
	The real user ID of the user invoking
	\fBsudo\fR.
	.TP 6n
	user=string
	The name of the user invoking
	\fBsudo\fR.
	.PD 0
.PP	.PP
.RE	.RE
	.PD
	.TP 6n
	user_env
	The user's environment in the form of a
	\fRNULL\fR-terminated vector of
	\(lqname=value\(rq
	strings.
	.sp
	When parsing
	\fIuser_env\fR,
	the plugin should split on the
	\fBfirst\fR
	equal sign
	(\(oq=\(cq)
	since the
	\fIname\fR
	field will never include one
	itself but the
	\fIvalue\fR
	might.
.PD 0	.PD 0
	.PP
	.RE
	.PD
.TP 6n	.TP 6n
close	close
.br	.br
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*close)(int exit_status, int error);	void (*close)(int exit_status, int error);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBclose\fR()	\fBclose\fR()
Line 662 function is called when the command being run by	Line 573 function is called when the command being run by
finishes.	finishes.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
exit_status	exit_status
The command's exit status, as returned by the	The command's exit status, as returned by the
Line 690 If the command was successfully executed, the value of	Line 600 If the command was successfully executed, the value of
\fRerror\fR	\fRerror\fR
is 0.	is 0.
.PP	.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.
.RE	.RE
.PD 0
.TP 6n	.TP 6n
show_version	show_version
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*show_version)(int verbose);	int (*show_version)(int verbose);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBshow_version\fR()	\fBshow_version\fR()
Line 716 or	Line 638 or
function using	function using
\fRSUDO_CONV_INFO_MSG\fR.	\fRSUDO_CONV_INFO_MSG\fR.
If the user requests detailed version information, the verbose flag will be set.	If the user requests detailed version information, the verbose flag will be set.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
check_policy	check_policy
.RS
.nf	.nf
.RS 0n	.RS 6n
int (check_policy)(int argc, char const argv[]	int (check_policy)(int argc, char const argv[]
char env_add[], char *command_info[],	char env_add[], char *command_info[],
char argv_out[], char user_env_out[]);	char argv_out[], char user_env_out[]);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBcheck_policy\fR()	\fBcheck_policy\fR()
Line 771 into	Line 690 into
\fIargv_out\fR,	\fIargv_out\fR,
separated from the	separated from the
editor and its arguments by a	editor and its arguments by a
``\fR--\fR''	\(lq\fR--\fR\(rq
element.	element.
The	The
``\fR--\fR''	\(lq\fR--\fR\(rq
will	will
be removed by	be removed by
\fBsudo\fR	\fBsudo\fR
Line 805 function with	Line 724 function with
to present additional error information to the user.	to present additional error information to the user.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
argc	argc
The number of elements in	The number of elements in
Line 828 Additional environment variables specified by the user	Line 746 Additional environment variables specified by the user
line in the form of a	line in the form of a
\fRNULL\fR-terminated	\fRNULL\fR-terminated
vector of	vector of
``name=value''	\(lqname=value\(rq
strings.	strings.
The plugin may reject the command if one or more variables	The plugin may reject the command if one or more variables
are not allowed to be set, or it may silently ignore such variables.	are not allowed to be set, or it may silently ignore such variables.
Line 838 When parsing	Line 756 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
Line 848 might.	Line 766 might.
.TP 6n	.TP 6n
command_info	command_info
Information about the command being run in the form of	Information about the command being run in the form of
``name=value''	\(lqname=value\(rq
strings.	strings.
These values are used by	These values are used by
\fBsudo\fR	\fBsudo\fR
Line 860 which must be terminated with a	Line 778 which must be terminated with a
pointer.	pointer.
The following values are recognized by	The following values are recognized by
\fBsudo\fR:	\fBsudo\fR:
.RS	.PP
	.RS 6n
	.PD 0
.TP 6n	.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	chroot=string
The root directory to use when running the command.	The root directory to use when running the command.
	.PD
.TP 6n	.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	closefrom=number
If specified,	If specified,
\fBsudo\fR	\fBsudo\fR
Line 953 of	Line 794 of
\fInumber\fR	\fInumber\fR
or higher.	or higher.
.TP 6n	.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	iolog_compress=bool
Set to true if the I/O logging plugins, if any, should compress the	Set to true if the I/O logging plugins, if any, should compress the
log data.	log data.
Line 992 terminal output.	Line 900 terminal output.
This only includes output to the screen, not output to a pipe or file.	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.	This is a hint to the I/O logging plugin which may choose to ignore it.
.TP 6n	.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_fds=list
	A comma-separated list of file descriptors that should be
	preserved, regardless of the value of the
	\fIclosefrom\fR
	setting.
	Only available starting with API version 1.5.
	.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	use_pty=bool
Allocate a pseudo-tty to run the command in, regardless of whether	Allocate a pseudo-tty to run the command in, regardless of whether
or not I/O logging is in use.	or not I/O logging is in use.
Line 1000 By default,	Line 994 By default,
will only run	will only run
the command in a pty when an I/O log plugin is loaded.	the command in a pty when an I/O log plugin is loaded.
.TP 6n	.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	utmp_user=string
User name to use when constructing a new utmp (or utmpx) entry when	User name to use when constructing a new utmp (or utmpx) entry when
\fIset_utmp\fR	\fIset_utmp\fR
Line 1017 will base the new entry on	Line 1006 will base the new entry on
the invoking user's existing entry.	the invoking user's existing entry.
.PP	.PP
Unsupported values will be ignored.	Unsupported values will be ignored.
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
argv_out	argv_out
The	The
Line 1028 argument vector to pass to the	Line 1015 argument vector to pass to the
execve(2)	execve(2)
system call when executing the command.	system call when executing the command.
The plugin is responsible for allocating and populating the vector.	The plugin is responsible for allocating and populating the vector.
.PD
.TP 6n	.TP 6n
user_env_out	user_env_out
The	The
\fRNULL\fR-terminated	\fRNULL\fR-terminated
environment vector to use when executing the command.	environment vector to use when executing the command.
The plugin is responsible for allocating and populating the vector.	The plugin is responsible for allocating and populating the vector.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
list	list
.RS
.nf	.nf
.RS 0n	.RS 6n
int (list)(int verbose, const char list_user,	int (list)(int verbose, const char list_user,
int argc, char * const argv[]);	int argc, char * const argv[]);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
List available privileges for the invoking user.	List available privileges for the invoking user.
Returns 1 on success, 0 on failure and \-1 on error.	Returns 1 on success, 0 on failure and \-1 on error.
Line 1065 or	Line 1052 or
\fBplugin_printf\fR()	\fBplugin_printf\fR()
function using	function using
\fRSUDO_CONV_INFO_MSG\fR,	\fRSUDO_CONV_INFO_MSG\fR,
.PD
.TP 6n	.TP 6n
verbose	verbose
Flag indicating whether to list in verbose mode or not.	Flag indicating whether to list in verbose mode or not.
Line 1094 execve(2)	Line 1080 execve(2)
system call.	system call.
If the command is permitted by the policy, the fully-qualified path	If the command is permitted by the policy, the fully-qualified path
to the command should be displayed along with any command line arguments.	to the command should be displayed along with any command line arguments.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
validate	validate
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*validate)(void);	int (*validate)(void);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBvalidate\fR()	\fBvalidate\fR()
Line 1114 is run with the	Line 1101 is run with the
\fB\-v\fR	\fB\-v\fR
flag.	flag.
For policy plugins such as	For policy plugins such as
\fIsudoers\fR	\fBsudoers\fR
that cache	that cache
authentication credentials, this function will validate and cache	authentication credentials, this function will validate and cache
the credentials.	the credentials.
Line 1134 function with	Line 1121 function with
\fRSUDO_CONF_ERROR_MSG\fR	\fRSUDO_CONF_ERROR_MSG\fR
to present additional	to present additional
error information to the user.	error information to the user.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
invalidate	invalidate
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*invalidate)(int remove);	void (*invalidate)(int remove);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBinvalidate\fR()	\fBinvalidate\fR()
Line 1158 or	Line 1142 or
\fB\-K\fR	\fB\-K\fR
flag.	flag.
For policy plugins such as	For policy plugins such as
\fIsudoers\fR	\fBsudoers\fR
that	that
cache authentication credentials, this function will invalidate the	cache authentication credentials, this function will invalidate the
credentials.	credentials.
Line 1172 The	Line 1156 The
function should be	function should be
\fRNULL\fR	\fRNULL\fR
if the plugin does not support credential caching.	if the plugin does not support credential caching.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
init_session	init_session
.RS
.nf	.nf
.RS 0n	.RS 6n
int (init_session)(struct passwd pwd, char **user_envp[);	int (init_session)(struct passwd pwd, char **user_envp[);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBinit_session\fR()	\fBinit_session\fR()
Line 1216 argument points to the environment the command will	Line 1197 argument points to the environment the command will
run in, in the form of a	run in, in the form of a
\fRNULL\fR-terminated	\fRNULL\fR-terminated
vector of	vector of
``name=value''	\(lqname=value\(rq
strings.	strings.
This is the same string passed back to the front end via	This is the same string passed back to the front end via
the Policy Plugin's	the Policy Plugin's
Line 1252 function with	Line 1233 function with
\fRSUDO_CONF_ERROR_MSG\fR	\fRSUDO_CONF_ERROR_MSG\fR
to present additional	to present additional
error information to the user.	error information to the user.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
register_hooks	register_hooks
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*register_hooks)(int version,	void (*register_hooks)(int version,
int (register_hook)(struct sudo_hook hook));	int (register_hook)(struct sudo_hook hook));
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBregister_hooks\fR()	\fBregister_hooks\fR()
Line 1307 front end doesn't support API	Line 1285 front end doesn't support API
version 1.2 or higher,	version 1.2 or higher,
\fRregister_hooks\fR	\fRregister_hooks\fR
will not be called.	will not be called.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
deregister_hooks	deregister_hooks
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*deregister_hooks)(int version,	void (*deregister_hooks)(int version,
int (deregister_hook)(struct sudo_hook hook));	int (deregister_hook)(struct sudo_hook hook));
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBderegister_hooks\fR()	\fBderegister_hooks\fR()
Line 1364 version 1.2 or higher,	Line 1339 version 1.2 or higher,
\fRderegister_hooks\fR	\fRderegister_hooks\fR
will not be called.	will not be called.
.RE	.RE
.PD
.PP	.PP
\fIPolicy Plugin Version Macros\fR	\fIPolicy Plugin Version Macros\fR
.nf	.nf
Line 1395 struct io_plugin {	Line 1369 struct io_plugin {
#define SUDO_IO_PLUGIN 2	#define SUDO_IO_PLUGIN 2
unsigned int type; /* always SUDO_IO_PLUGIN */	unsigned int type; /* always SUDO_IO_PLUGIN */
unsigned int version; /* always SUDO_API_VERSION */	unsigned int version; /* always SUDO_API_VERSION */
int (*open)(unsigned int version, sudo_conv_t conversation	int (*open)(unsigned int version, sudo_conv_t conversation,
sudo_printf_t plugin_printf, char * const settings[],	sudo_printf_t plugin_printf, char * const settings[],
char * const user_info[], int argc, char * const argv[],	char * const user_info[], char * const command_info[],
char * const user_env[], char * const plugin_options[]);	int argc, char * const argv[], char * const user_env[],
	char * const plugin_options[]);
void (close)(int exit_status, int error); / wait status or error */	void (close)(int exit_status, int error); / wait status or error */
int (*show_version)(int verbose);	int (*show_version)(int verbose);
int (log_ttyin)(const char buf, unsigned int len);	int (log_ttyin)(const char buf, unsigned int len);
Line 1464 to determine the API version the plugin was	Line 1439 to determine the API version the plugin was
built against.	built against.
.TP 6n	.TP 6n
open	open
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*open)(unsigned int version, sudo_conv_t conversation	int (*open)(unsigned int version, sudo_conv_t conversation,
sudo_printf_t plugin_printf, char * const settings[],	sudo_printf_t plugin_printf, char * const settings[],
char * const user_info[], int argc, char * const argv[],	char * const user_info[], int argc, char * const argv[],
char * const user_env[], char * const plugin_options[]);	char * const user_env[], char * const plugin_options[]);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBopen\fR()	\fBopen\fR()
Line 1542 settings	Line 1517 settings
A vector of user-supplied	A vector of user-supplied
\fBsudo\fR	\fBsudo\fR
settings in the form of	settings in the form of
``name=value''	\(lqname=value\(rq
strings.	strings.
The vector is terminated by a	The vector is terminated by a
\fRNULL\fR	\fRNULL\fR
Line 1557 When parsing	Line 1532 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
Line 1571 section for a list of all possible settings.	Line 1546 section for a list of all possible settings.
.TP 6n	.TP 6n
user_info	user_info
A vector of information about the user running the command in the form of	A vector of information about the user running the command in the form of
``name=value''	\(lqname=value\(rq
strings.	strings.
The vector is terminated by a	The vector is terminated by a
\fRNULL\fR	\fRNULL\fR
Line 1582 When parsing	Line 1557 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
Line 1613 user_env	Line 1588 user_env
The user's environment in the form of a	The user's environment in the form of a
\fRNULL\fR-terminated	\fRNULL\fR-terminated
vector of	vector of
``name=value''	\(lqname=value\(rq
strings.	strings.
.sp	.sp
When parsing	When parsing
Line 1621 When parsing	Line 1596 When parsing
the plugin should split on the	the plugin should split on the
\fBfirst\fR	\fBfirst\fR
equal sign	equal sign
(`=')	(\(oq=\(cq)
since the	since the
\fIname\fR	\fIname\fR
field will never include one	field will never include one
Line 1654 by the	Line 1629 by the
front end before using	front end before using
\fIplugin_options\fR.	\fIplugin_options\fR.
Failure to do so may result in a crash.	Failure to do so may result in a crash.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
close	close
.br	.br
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*close)(int exit_status, int error);	void (*close)(int exit_status, int error);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBclose\fR()	\fBclose\fR()
Line 1674 function is called when the command being run by	Line 1650 function is called when the command being run by
finishes.	finishes.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
exit_status	exit_status
The command's exit status, as returned by the	The command's exit status, as returned by the
Line 1696 system call.	Line 1671 system call.
If the command was successfully executed, the value of	If the command was successfully executed, the value of
\fRerror\fR	\fRerror\fR
is 0.	is 0.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
show_version	show_version
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*show_version)(int verbose);	int (*show_version)(int verbose);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBshow_version\fR()	\fBshow_version\fR()
Line 1723 or	Line 1699 or
function using	function using
\fRSUDO_CONV_INFO_MSG\fR.	\fRSUDO_CONV_INFO_MSG\fR.
If the user requests detailed version information, the verbose flag will be set.	If the user requests detailed version information, the verbose flag will be set.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
log_ttyin	log_ttyin
.RS
.nf	.nf
.RS 0n	.RS 6n
int (log_ttyin)(const char buf, unsigned int len);	int (log_ttyin)(const char buf, unsigned int len);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBlog_ttyin\fR()	\fBlog_ttyin\fR()
Line 1746 Returns 1 if the data should be passed to the command,	Line 1719 Returns 1 if the data should be passed to the command,
is rejected (which will terminate the command) or \-1 if an error occurred.	is rejected (which will terminate the command) or \-1 if an error occurred.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
buf	buf
The buffer containing user input.	The buffer containing user input.
Line 1755 len	Line 1727 len
The length of	The length of
\fIbuf\fR	\fIbuf\fR
in bytes.	in bytes.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
log_ttyout	log_ttyout
.RS
.nf	.nf
.RS 0n	.RS 6n
int (log_ttyout)(const char buf, unsigned int len);	int (log_ttyout)(const char buf, unsigned int len);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBlog_ttyout\fR()	\fBlog_ttyout\fR()
Line 1777 Returns 1 if the data should be passed to the user, 0	Line 1750 Returns 1 if the data should be passed to the user, 0
(which will terminate the command) or \-1 if an error occurred.	(which will terminate the command) or \-1 if an error occurred.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
buf	buf
The buffer containing command output.	The buffer containing command output.
Line 1786 len	Line 1758 len
The length of	The length of
\fIbuf\fR	\fIbuf\fR
in bytes.	in bytes.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
log_stdin	log_stdin
.RS
.nf	.nf
.RS 0n	.RS 6n
int (log_stdin)(const char buf, unsigned int len);	int (log_stdin)(const char buf, unsigned int len);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBlog_stdin\fR()	\fBlog_stdin\fR()
Line 1810 Returns 1 if the data should be passed to the command,	Line 1783 Returns 1 if the data should be passed to the command,
rejected (which will terminate the command) or \-1 if an error occurred.	rejected (which will terminate the command) or \-1 if an error occurred.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
buf	buf
The buffer containing user input.	The buffer containing user input.
Line 1819 len	Line 1791 len
The length of	The length of
\fIbuf\fR	\fIbuf\fR
in bytes.	in bytes.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
log_stdout	log_stdout
.RS
.nf	.nf
.RS 0n	.RS 6n
int (log_stdout)(const char buf, unsigned int len);	int (log_stdout)(const char buf, unsigned int len);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBlog_stdout\fR()	\fBlog_stdout\fR()
Line 1843 Returns 1 if the data should be passed to the user, 0	Line 1816 Returns 1 if the data should be passed to the user, 0
rejected (which will terminate the command) or \-1 if an error occurred.	rejected (which will terminate the command) or \-1 if an error occurred.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
buf	buf
The buffer containing command output.	The buffer containing command output.
Line 1852 len	Line 1824 len
The length of	The length of
\fIbuf\fR	\fIbuf\fR
in bytes.	in bytes.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
log_stderr	log_stderr
.RS
.nf	.nf
.RS 0n	.RS 6n
int (log_stderr)(const char buf, unsigned int len);	int (log_stderr)(const char buf, unsigned int len);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBlog_stderr\fR()	\fBlog_stderr\fR()
Line 1876 Returns 1 if the data should be passed to the user, 0	Line 1849 Returns 1 if the data should be passed to the user, 0
rejected (which will terminate the command) or \-1 if an error occurred.	rejected (which will terminate the command) or \-1 if an error occurred.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
buf	buf
The buffer containing command output.	The buffer containing command output.
Line 1885 len	Line 1857 len
The length of	The length of
\fIbuf\fR	\fIbuf\fR
in bytes.	in bytes.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
register_hooks	register_hooks
See the	See the
\fIPolicy plugin API\fR	\fIPolicy plugin API\fR
section for a description of	section for a description of
\fRregister_hooks\fR.	\fRregister_hooks\fR.
.PD
.TP 6n	.TP 6n
deregister_hooks	deregister_hooks
See the	See the
Line 1906 section for a description of	Line 1878 section for a description of
.PP	.PP
Same as for the	Same as for the
\fIPolicy plugin API\fR.	\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"	.SS "Hook function API"
Beginning with plugin API version 1.2, it is possible to install	Beginning with plugin API version 1.2, it is possible to install
hooks for certain functions called by the	hooks for certain functions called by the
Line 1954 hook_type	Line 1973 hook_type
The	The
\fRhook_type\fR	\fRhook_type\fR
field may be one of the following supported hook types:	field may be one of the following supported hook types:
.RS	.PP
	.RS 6n
	.PD 0
.TP 6n	.TP 6n
\fRSUDO_HOOK_SETENV\fR	\fRSUDO_HOOK_SETENV\fR
The C library	The C library
Line 1965 The	Line 1986 The
\fRhook_fn\fR	\fRhook_fn\fR
field should	field should
be a function that matches the following typedef:	be a function that matches the following typedef:
.RS
.nf	.nf
.sp	.sp
.RS 0n	.RS 6n
typedef int (sudo_hook_fn_setenv_t)(const char name,	typedef int (sudo_hook_fn_setenv_t)(const char name,
const char value, int overwrite, void closure);	const char value, int overwrite, void closure);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
If the registered hook does not match the typedef the results are	If the registered hook does not match the typedef the results are
unspecified.	unspecified.
.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
\fRSUDO_HOOK_UNSETENV\fR	\fRSUDO_HOOK_UNSETENV\fR
The C library	The C library
Line 1989 The	Line 2009 The
\fRhook_fn\fR	\fRhook_fn\fR
field should	field should
be a function that matches the following typedef:	be a function that matches the following typedef:
.RS
.nf	.nf
.sp	.sp
.RS 0n	.RS 6n
typedef int (sudo_hook_fn_unsetenv_t)(const char name,	typedef int (sudo_hook_fn_unsetenv_t)(const char name,
void *closure);	void *closure);
.RE	.RE
.fi	.fi
.PD
.PP
.RE
.PD 0
.TP 6n	.TP 6n
\fRSUDO_HOOK_GETENV\fR	\fRSUDO_HOOK_GETENV\fR
The C library	The C library
Line 2011 The	Line 2026 The
\fRhook_fn\fR	\fRhook_fn\fR
field should	field should
be a function that matches the following typedef:	be a function that matches the following typedef:
.RS
.nf	.nf
.sp	.sp
.RS 0n	.RS 6n
typedef int (sudo_hook_fn_getenv_t)(const char name,	typedef int (sudo_hook_fn_getenv_t)(const char name,
char *value, void closure);	char *value, void closure);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
If the registered hook does not match the typedef the results are	If the registered hook does not match the typedef the results are
unspecified.	unspecified.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
\fRSUDO_HOOK_PUTENV\fR	\fRSUDO_HOOK_PUTENV\fR
The C library	The C library
Line 2036 The	Line 2048 The
\fRhook_fn\fR	\fRhook_fn\fR
field should	field should
be a function that matches the following typedef:	be a function that matches the following typedef:
.RS
.nf	.nf
.sp	.sp
.RS 0n	.RS 6n
typedef int (sudo_hook_fn_putenv_t)(char string,	typedef int (sudo_hook_fn_putenv_t)(char string,
void *closure);	void *closure);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
If the registered hook does not match the typedef the results are	If the registered hook does not match the typedef the results are
unspecified.	unspecified.
.RE	.RE
.PD	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
hook_fn	hook_fn
sudo_hook_fn_t hook_fn;	sudo_hook_fn_t hook_fn;
Line 2072 is passed as the last function parameter.	Line 2084 is passed as the last function parameter.
This can be used to pass arbitrary data to the plugin's hook implementation.	This can be used to pass arbitrary data to the plugin's hook implementation.
.sp	.sp
The function return value may be one of the following:	The function return value may be one of the following:
.RS	.PP
.PD	.RS 6n
	.PD 0
.TP 6n	.TP 6n
\fRSUDO_HOOK_RET_ERROR\fR	\fRSUDO_HOOK_RET_ERROR\fR
The hook function encountered an error.	The hook function encountered an error.
	.PD
.TP 6n	.TP 6n
\fRSUDO_HOOK_RET_NEXT\fR	\fRSUDO_HOOK_RET_NEXT\fR
The hook completed without error, go on to the next hook (including	The hook completed without error, go on to the next hook (including
Line 2096 hook that operates on a private copy of	Line 2110 hook that operates on a private copy of
the environment but leaves	the environment but leaves
\fRenviron\fR	\fRenviron\fR
unchanged.	unchanged.
	.PD 0
	.PP
.RE	.RE
	.PD
.PP	.PP
Note that it is very easy to create an infinite loop when hooking	Note that it is very easy to create an infinite loop when hooking
C library functions.	C library functions.
Line 2147 return SUDO_HOOK_RET_STOP;	Line 2164 return SUDO_HOOK_RET_STOP;
} while(0)	} while(0)
.RE	.RE
.fi	.fi
	.SS "Remote command execution"
	The
	\fBsudo\fR
	front end does not have native support for running remote commands.
	However, starting with
	\fBsudo\fR
	1.8.8, the
	\fB\-h\fR
	option may be used to specify a remote host that is passed
	to the policy plugin.
	A plugin may also accept a
	\fIrunas_user\fR
	in the form of
	\(lquser@hostname\(rq
	which will work with older versions of
	\fBsudo\fR.
	It is anticipated that remote commands will be supported by executing a
	\(lqhelper\(rq
	program.
	The policy plugin should setup the execution environment such that the
	\fBsudo\fR
	front end will run the helper which, in turn, will connect to the
	remote host and run the command.
	.PP
	For example, the policy plugin could utilize
	\fBssh\fR
	to perform remote command execution.
	The helper program would be responsible for running
	\fBssh\fR
	with the proper options to use a private key or certificate
	that the remote host will accept and run a program
	on the remote host that would setup the execution environment
	accordingly.
	.PP
	Note that remote
	\fBsudoedit\fR
	functionality must be handled by the policy plugin, not
	\fBsudo\fR
	itself as the front end has no knowledge that a remote command is
	being executed.
	This may be addressed in a future revision of the plugin API.
.SS "Conversation API"	.SS "Conversation API"
If the plugin needs to interact with the user, it may do so via the	If the plugin needs to interact with the user, it may do so via the
\fBconversation\fR()	\fBconversation\fR()
Line 2178 struct sudo_conv_message {	Line 2236 struct sudo_conv_message {
const char *msg;	const char *msg;
};	};

	#define SUDO_CONV_REPL_MAX 255

struct sudo_conv_reply {	struct sudo_conv_reply {
char *reply;	char *reply;
};	};
Line 2212 and	Line 2272 and
\fRstruct sudo_conv_reply\fR	\fRstruct sudo_conv_reply\fR
for	for
each message in the conversation.	each message in the conversation.
The plugin is responsible for freeing the reply buffer filled in to the	The plugin is responsible for freeing the reply buffer located in each
\fRstruct sudo_conv_reply\fR,	\fRstruct sudo_conv_reply\fR,
if any.	if it is not
	\fRNULL\fR.
	\fRSUDO_CONV_REPL_MAX\fR
	represents the maximum length of the reply buffer (not including
	the trailing NUL character).
	In practical terms, this is the longest password
	\fBsudo\fR
	will support.
	It is also useful as a maximum value for the
	\fBmemset_s\fR()
	function when clearing passwords filled in by the conversation function.
.PP	.PP
The	The
\fBprintf\fR()-style	\fBprintf\fR()-style
Line 2247 user-visible.	Line 2317 user-visible.
Instead, they are logged to the file specified in the	Instead, they are logged to the file specified in the
\fRDebug\fR	\fRDebug\fR
statement (if any) in the	statement (if any) in the
\fI@sysconfdir@/sudo.conf\fR	sudo.conf(@mansectform@).
.PP
file.	file.
This allows a plugin to log debugging information and is intended	This allows a plugin to log debugging information and is intended
to be used in conjunction with the	to be used in conjunction with the
Line 2260 See the sample plugin for an example of the	Line 2329 See the sample plugin for an example of the
function usage.	function usage.
.SS "Sudoers group plugin API"	.SS "Sudoers group plugin API"
The	The
\fIsudoers\fR	\fBsudoers\fR
module supports a plugin interface to allow non-Unix	plugin supports its own plugin interface to allow non-Unix
group lookups.	group lookups.
This can be used to query a group source other than the standard Unix	This can be used to query a group source other than the standard Unix
group database.	group database.
A sample group plugin is bundled with	Two sample group plugins are bundled with
\fBsudo\fR	\fBsudo\fR,
that implements file-based lookups.	\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.	Third party group plugins include a QAS AD plugin available from Quest Software.
.PP	.PP
A group plugin must declare and populate a	A group plugin must declare and populate a
Line 2299 The	Line 2372 The
field should be set to GROUP_API_VERSION.	field should be set to GROUP_API_VERSION.
.sp	.sp
This allows	This allows
\fIsudoers\fR	\fBsudoers\fR
to determine the API version the group plugin	to determine the API version the group plugin
was built against.	was built against.
.TP 6n	.TP 6n
init	init
.RS
.nf	.nf
.RS 0n	.RS 6n
int (*init)(int version, sudo_printf_t plugin_printf,	int (*init)(int version, sudo_printf_t plugin_printf,
char *const argv[]);	char *const argv[]);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBinit\fR()	\fBinit\fR()
Line 2331 The function arguments are as follows:	Line 2404 The function arguments are as follows:
.TP 6n	.TP 6n
version	version
The version passed in by	The version passed in by
\fIsudoers\fR	\fBsudoers\fR
allows the plugin to determine the	allows the plugin to determine the
major and minor version number of the group plugin API supported by	major and minor version number of the group plugin API supported by
\fIsudoers\fR.	\fBsudoers\fR.
.TP 6n	.TP 6n
plugin_printf	plugin_printf
A pointer to a	A pointer to a
Line 2353 If no arguments were given,	Line 2426 If no arguments were given,
\fIargv\fR	\fIargv\fR
will be	will be
\fRNULL\fR.	\fRNULL\fR.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
cleanup	cleanup
.RS
.nf	.nf
.RS 0n	.RS 6n
void (*cleanup)();	void (*cleanup)();
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBcleanup\fR()	\fBcleanup\fR()
function is called when	function is called when
\fIsudoers\fR	\fBsudoers\fR
has finished its	has finished its
group checks.	group checks.
The plugin should free any memory it has allocated and close open file handles.	The plugin should free any memory it has allocated and close open file handles.
.PD
.PP
.RE	.RE
.PD 0
.TP 6n	.TP 6n
query	query
.br	.br
.RS
.nf	.nf
.RS 0n	.RS 6n
int (query)(const char user, const char *group,	int (query)(const char user, const char *group,
const struct passwd *pwd);	const struct passwd *pwd);
.RE	.RE
.fi	.fi
	.RS 6n
.sp	.sp
The	The
\fBquery\fR()	\fBquery\fR()
Line 2395 is a member of	Line 2466 is a member of
\fIgroup\fR.	\fIgroup\fR.
.sp	.sp
The function arguments are as follows:	The function arguments are as follows:
.PD
.TP 6n	.TP 6n
user	user
The name of the user being looked up in the external group database.	The name of the user being looked up in the external group database.
Line 2415 present in the password database,	Line 2485 present in the password database,
\fIpwd\fR	\fIpwd\fR
will be	will be
\fRNULL\fR.	\fRNULL\fR.
	.PD 0
	.PP
.RE	.RE
	.PD
.PP	.PP
\fIGroup API Version Macros\fR	\fIGroup API Version Macros\fR
.nf	.nf
Line 2444 The following revisions have been made to the Sudo Plu	Line 2517 The following revisions have been made to the Sudo Plu
Version 1.0	Version 1.0
Initial API version.	Initial API version.
.TP 6n	.TP 6n
Version 1.1	Version 1.1 (sudo 1.8.0)
The I/O logging plugin's	The I/O logging plugin's
\fBopen\fR()	\fBopen\fR()
function was modified to take the	function was modified to take the
\fRcommand_info\fR	\fRcommand_info\fR
list as an argument.	list as an argument.
.TP 6n	.TP 6n
Version 1.2	Version 1.2 (sudo 1.8.5)
The Policy and I/O logging plugins'	The Policy and I/O logging plugins'
\fBopen\fR()	\fBopen\fR()
functions are now passed	functions are now passed
a list of plugin options if any are specified in	a list of plugin parameters if any are specified in
\fI@sysconfdir@/sudo.conf\fR.	sudo.conf(@mansectform@).
.sp	.sp
A simple hooks API has been introduced to allow plugins to hook in to the	A simple hooks API has been introduced to allow plugins to hook in to the
system's environment handling functions.	system's environment handling functions.
Line 2467 Policy plugin function is now passed a pointer	Line 2540 Policy plugin function is now passed a pointer
to the user environment which can be updated as needed.	to the user environment which can be updated as needed.
This can be used to merge in environment variables stored in the PAM	This can be used to merge in environment variables stored in the PAM
handle before a command is run.	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.
	.TP 6n
	Version 1.4 (sudo 1.8.8)
	The
	\fIremote_host\fR
	entry was added to the
	\fRsettings\fR
	list.
	.TP 6n
	Version 1.5 (sudo 1.8.9)
	The
	entry was added to the
	\fRcommand_info\fR
	list.
.SH "SEE ALSO"	.SH "SEE ALSO"
	sudo.conf(@mansectform@),
sudoers(@mansectform@),	sudoers(@mansectform@),
sudo(@mansectsu@)	sudo(@mansectsu@)
.SH "BUGS"	.SH "BUGS"
Line 2481 search the archives.	Line 2607 search the archives.
.SH "DISCLAIMER"	.SH "DISCLAIMER"
\fBsudo\fR	\fBsudo\fR
is provided	is provided
``AS IS''	\(lqAS IS\(rq
and any express or implied warranties, including, but not limited	and any express or implied warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a	to, the implied warranties of merchantability and fitness for a
particular purpose are disclaimed.	particular purpose are disclaimed.

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

Removed from v.1.1.1.3
changed lines
	Added in v.1.1.1.6