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.4 and 1.1.1.6

version 1.1.1.4, 2013/07/22 10:46:12	version 1.1.1.6, 2014/06/15 16:12:54
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" "March 5, 2013" "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
\fBsudoers\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.
Line 107 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 156 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 171 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	bsdauth_type=string
Authentication type, if specified by the	Authentication type, if specified by the
\fB\-a\fR	\fB\-a\fR
flag, to use on	flag, to use on
systems where BSD authentication is supported.	systems where BSD authentication is supported.
	.PD
.TP 6n	.TP 6n
closefrom=number	closefrom=number
If specified, the user has requested via the	If specified, the user has requested via the
Line 215 plugin is	Line 222 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).
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 271 sudo.conf(@mansectform@).	Line 278 sudo.conf(@mansectform@).
network_addrs=list	network_addrs=list
A space-separated list of IP network addresses and netmasks in the	A space-separated list of IP network addresses and netmasks in the
form	form
``addr/netmask'',	\(lqaddr/netmask\(rq,
e.g.\&	e.g.\&
``192.168.1.2/255.255.255.0''.	\(lq192.168.1.2/255.255.255.0\(rq.
The address and netmask pairs may be either IPv4 or IPv6, depending on	The address and netmask pairs may be either IPv4 or IPv6, depending on
what the operating system supports.	what the operating system supports.
If the address contains a colon	If the address contains a colon
(`:\&'),	(\(oq:\&\(cq),
it is an IPv6 address, else it is IPv4.	it is an IPv6 address, else it is IPv4.
.TP 6n	.TP 6n
noninteractive=bool	noninteractive=bool
Line 312 based on the runas user.	Line 319 based on the runas user.
.TP 6n	.TP 6n
progname=string	progname=string
The command name that sudo was run as, typically	The command name that sudo was run as, typically
``sudo''	\(lqsudo\(rq
or	or
``sudoedit''.	\(lqsudoedit\(rq.
.TP 6n	.TP 6n
prompt=string	prompt=string
The prompt to use when requesting a password, if specified via	The prompt to use when requesting a password, if specified via
Line 322 the	Line 329 the
\fB\-p\fR	\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	run_shell=bool
Set to true if the user specified the	Set to true if the user specified the
\fB\-s\fR	\fB\-s\fR
flag, indicating that	flag, indicating that the user wishes to run a shell.
the user wishes to run a shell.
.TP 6n	.TP 6n
runas_group=string	runas_group=string
The group name or gid to to run the command as, if specified via	The group name or gid to run the command as, if specified via
the	the
\fB\-g\fR	\fB\-g\fR
flag.	flag.
.TP 6n	.TP 6n
runas_user=string	runas_user=string
The user name or uid to to run the command as, if specified via the	The user name or uid to run the command as, if specified via the
\fB\-u\fR	\fB\-u\fR
flag.	flag.
.TP 6n	.TP 6n
Line 377 section.	Line 395 section.
.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 394 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
.PD	.RS 6n
	.PD 0
.TP 6n	.TP 6n
cols=int	cols=int
The number of columns the user's terminal supports.	The number of columns the user's terminal supports.
If there is no terminal device available, a default value of 80 is used.	If there is no terminal device available, a default value of 80 is used.
	.PD
.TP 6n	.TP 6n
cwd=string	cwd=string
The user's current working directory.	The user's current working directory.
Line 441 pgid=int	Line 459 pgid=int
The ID of the process group that the running	The ID of the process group that the running
\fBsudo\fR	\fBsudo\fR
process is a member of.	process is a member of.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.TP 6n	.TP 6n
pid=int	pid=int
The process ID of the running	The process ID of the running
\fBsudo\fR	\fBsudo\fR
process.	process.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.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
Line 480 ppid=int	Line 498 ppid=int
The parent process ID of the running	The parent process ID of the running
\fBsudo\fR	\fBsudo\fR
process.	process.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.TP 6n	.TP 6n
sid=int	sid=int
The session ID of the running	The session ID of the running
Line 488 The session ID of the running	Line 506 The session ID of the running
process or 0 if	process or 0 if
\fBsudo\fR	\fBsudo\fR
is not part of a POSIX job control session.	is not part of a POSIX job control session.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.TP 6n	.TP 6n
tcpgid=int	tcpgid=int
The ID of the foreground process group associated with the terminal	The ID of the foreground process group associated with the terminal
Line 496 device associated with the	Line 514 device associated with the
\fBsudo\fR	\fBsudo\fR
process or \-1 if there is no	process or \-1 if there is no
terminal present.	terminal present.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.TP 6n	.TP 6n
tty=string	tty=string
The path to the user's terminal device.	The path to the user's terminal device.
If the user has no terminal device associated with the session,	If the user has no terminal device associated with the session,
the value will be empty, as in	the value will be empty, as in
``\fRtty=\fR''.	\(lq\fRtty=\fR\(rq.
.TP 6n	.TP 6n
uid=uid_t	uid=uid_t
The real user ID of the user invoking	The real user ID of the user invoking
Line 511 The real user ID of the user invoking	Line 529 The real user ID of the user invoking
user=string	user=string
The name of the user invoking	The name of the user invoking
\fBsudo\fR.	\fBsudo\fR.
	.PD 0
.PP	.PP
.RE	.RE
.PD 0	.PD
.TP 6n	.TP 6n
user_env	user_env
The user's environment in the form of a	The user's environment in the form of a
\fRNULL\fR-terminated vector of	\fRNULL\fR-terminated vector of
``name=value''	\(lqname=value\(rq
strings.	strings.
.sp	.sp
When parsing	When parsing
Line 526 When parsing	Line 545 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.
.PD	.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 554 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 595 list, the	Line 613 list, the
\fBsudo\fR	\fBsudo\fR
front end may execute the command directly instead of running	front end may execute the command directly instead of running
it as a child process.	it as a child process.
.PP
.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 622 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 677 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 711 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 734 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 744 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 754 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 766 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
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
closefrom=number	closefrom=number
If specified,	If specified,
Line 899 on BSD systems.	Line 914 on BSD systems.
noexec=bool	noexec=bool
If set, prevent the command from executing other programs.	If set, prevent the command from executing other programs.
.TP 6n	.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	preserve_groups=bool
If set,	If set,
\fBsudo\fR	\fBsudo\fR
Line 984 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 995 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 1032 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 1061 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 1101 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 1139 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 1183 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 1219 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 1274 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 1331 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 1432 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 1510 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 1525 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 1539 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 1550 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 1581 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 1589 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 1622 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 1642 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 1664 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 1691 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 1714 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 1723 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 1745 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 1754 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 1778 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 1787 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 1811 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 1820 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 1844 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 1853 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 1969 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 1980 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 2004 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 2026 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 2051 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 2087 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 2111 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 2162 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 2193 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 2227 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 2322 to determine the API version the group plugin	Line 2377 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 2371 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()
Line 2390 function is called when	Line 2446 function is called when
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 2413 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 2433 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 2524 The	Line 2579 The
\fBsudo\fR	\fBsudo\fR
front end now installs default signal handlers to trap common signals	front end now installs default signal handlers to trap common signals
while the plugin functions are run.	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@),	sudo.conf(@mansectform@),
sudoers(@mansectform@),	sudoers(@mansectform@),
Line 2539 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.4
changed lines
	Added in v.1.1.1.6