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

Return to sudo_plugin.mdoc.in CVS log

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

Diff for /embedaddon/sudo/doc/sudo_plugin.mdoc.in between versions 1.1.1.2 and 1.1.1.4

version 1.1.1.2, 2013/07/22 10:46:12	version 1.1.1.4, 2014/06/15 16:12:54
Line 14	Line 14
.\" 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.
.\"	.\"
.Dd March 5, 2013	.Dd December 20, 2013
.Dt SUDO_PLUGIN @mansectform@	.Dt SUDO_PLUGIN @mansectform@
.Os Sudo @PACKAGE_VERSION@	.Os Sudo @PACKAGE_VERSION@
.Sh NAME	.Sh NAME
Line 25 Starting with version 1.8,	Line 25 Starting with version 1.8,
.Nm sudo	.Nm sudo
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
	.Nm sudo
	binary itself.
By default, the	By default, the
.Nm sudoers	.Nm sudoers
policy plugin and an associated I/O logging plugin are used.	policy plugin and an associated I/O logging plugin are used.
Line 135 function that can be used by the plugin to interact wi	Line 139 function that can be used by the plugin to interact wi
Returns 0 on success and \-1 on failure.	Returns 0 on success and \-1 on failure.
.It plugin_printf	.It plugin_printf
A pointer to a	A pointer to a
.Fn printf Ns No -style	.Fn printf Ns -style
function that may be used to display informational or error messages	function that may be used to display informational or error messages
(see below).	(see below).
Returns the number of characters printed on success and \-1 on failure.	Returns the number of characters printed on success and \-1 on failure.
Line 184 The plugin may optionally pass this, or another value,	Line 188 The plugin may optionally pass this, or another value,
list.	list.
.It debug_flags=string	.It debug_flags=string
A comma-separated list of debug flags that correspond to	A comma-separated list of debug flags that correspond to
.Nm sudo Ns No 's	.Nm sudo Ns 's
.Li Debug	.Li Debug
entry in	entry in
.Xr sudo.conf @mansectform@ ,	.Xr sudo.conf @mansectform@ ,
Line 196 The syntax used by	Line 200 The syntax used by
and the	and the
.Nm sudoers	.Nm sudoers
plugin is	plugin is
.Em subsystem Ns No @ Ns Em priority	.Em subsystem Ns @ Ns Em priority
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
.Pq Ql ,\& .	.Pq Ql ,\& .
Line 292 The prompt to use when requesting a password, if speci	Line 296 The prompt to use when requesting a password, if speci
the	the
.Fl p	.Fl p
flag.	flag.
	.It remote_host=string
	The name of the remote host to run the command on, if specified via
	the
	.Fl h
	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
	.Nm sudo
	front end is only capable of executing commands on the local host.
	Only available starting with API version 1.4.
.It run_shell=bool	.It run_shell=bool
Set to true if the user specified the	Set to true if the user specified the
.Fl s	.Fl s
flag, indicating that	flag, indicating that the user wishes to run a shell.
the user wishes to run a shell.
.It runas_group=string	.It 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
.Fl g	.Fl g
flag.	flag.
.It runas_user=string	.It 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
.Fl u	.Fl u
flag.	flag.
.It selinux_role=string	.It selinux_role=string
Line 392 no terminal device available, a default value of 24 is	Line 406 no terminal device available, a default value of 24 is
The ID of the process group that the running	The ID of the process group that the running
.Nm sudo	.Nm sudo
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.
.It pid=int	.It pid=int
The process ID of the running	The process ID of the running
.Nm sudo	.Nm sudo
process.	process.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.It plugin_options	.It plugin_options
Any (non-comment) strings immediately after the plugin path are	Any (non-comment) strings immediately after the plugin path are
passed 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
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
array of strings.	array of strings.
If no arguments were	If no arguments were
specified,	specified,
Line 428 Failure to do so may result in a crash.	Line 442 Failure to do so may result in a crash.
The parent process ID of the running	The parent process ID of the running
.Nm sudo	.Nm sudo
process.	process.
Only available starting with API version 1.2	Only available starting with API version 1.2.
.It sid=int	.It sid=int
The session ID of the running	The session ID of the running
.Nm sudo	.Nm sudo
process or 0 if	process or 0 if
.Nm sudo	.Nm sudo
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.
.It tcpgid=int	.It tcpgid=int
The ID of the foreground process group associated with the terminal	The ID of the foreground process group associated with the terminal
device associated with the	device associated with the
.Nm sudo	.Nm sudo
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.
.It tty=string	.It 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,
Line 457 The name of the user invoking	Line 471 The name of the user invoking
.El	.El
.It user_env	.It user_env
The user's environment in the form of a	The user's environment in the form of a
.Dv NULL Ns No -terminated vector of	.Dv NULL Ns -terminated vector of
.Dq name=value	.Dq name=value
strings.	strings.
.Pp	.Pp
Line 644 pointer.	Line 658 pointer.
.It env_add	.It env_add
Additional environment variables specified by the user on the command	Additional environment variables specified by the user on the command
line in the form of a	line in the form of a
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
vector of	vector of
.Dq name=value	.Dq name=value
strings.	strings.
Line 794 The nice value, if specified, overrides the priority a	Line 808 The nice value, if specified, overrides the priority a
on BSD systems.	on BSD systems.
.It noexec=bool	.It noexec=bool
If set, prevent the command from executing other programs.	If set, prevent the command from executing other programs.
	.It preserve_fds=list
	A comma-separated list of file descriptors that should be
	preserved, regardless of the value of the
	.Em closefrom
	setting.
	Only available starting with API version 1.5.
.It preserve_groups=bool	.It preserve_groups=bool
If set,	If set,
.Nm sudo	.Nm sudo
Line 869 the invoking user's existing entry.	Line 889 the invoking user's existing entry.
Unsupported values will be ignored.	Unsupported values will be ignored.
.It argv_out	.It argv_out
The	The
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
argument vector to pass to the	argument vector to pass to the
.Xr execve 2	.Xr 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.
.It user_env_out	.It user_env_out
The	The
.Dv NULL Ns No -terminated	.Dv NULL Ns -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.
.El	.El
Line 1026 The	Line 1046 The
.Em user_env	.Em user_env
argument points to the environment the command will	argument points to the environment the command will
run in, in the form of a	run in, in the form of a
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
vector of	vector of
.Dq name=value	.Dq name=value
strings.	strings.
Line 1310 The	Line 1330 The
function returns 0 on success and \-1 on failure.	function returns 0 on success and \-1 on failure.
.It plugin_printf	.It plugin_printf
A pointer to a	A pointer to a
.Fn printf Ns No -style	.Fn printf Ns -style
function that may be used by the	function that may be used by the
.Fn show_version	.Fn show_version
function to display version information (see	function to display version information (see
Line 1390 wishes to run in the same form as what would be passed	Line 1410 wishes to run in the same form as what would be passed
system call.	system call.
.It user_env	.It user_env
The user's environment in the form of a	The user's environment in the form of a
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
vector of	vector of
.Dq name=value	.Dq name=value
strings.	strings.
Line 1412 Any (non-comment) strings immediately after the plugin	Line 1432 Any (non-comment) strings immediately after the plugin
treated as arguments to the plugin.	treated 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
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
array of strings.	array of strings.
If no arguments were specified,	If no arguments were specified,
.Em plugin_options	.Em plugin_options
Line 1854 return SUDO_HOOK_RET_STOP;	Line 1874 return SUDO_HOOK_RET_STOP;
(vp) = ((vp) & 0xffff0000) \| (n); \e	(vp) = ((vp) & 0xffff0000) \| (n); \e
} while(0)	} while(0)
.Ed	.Ed
	.Ss Remote command execution
	The
	.Nm sudo
	front end does not have native support for running remote commands.
	However, starting with
	.Nm sudo
	1.8.8, the
	.Fl h
	option may be used to specify a remote host that is passed
	to the policy plugin.
	A plugin may also accept a
	.Em runas_user
	in the form of
	.Dq user@hostname
	which will work with older versions of
	.Nm sudo .
	It is anticipated that remote commands will be supported by executing a
	.Dq helper
	program.
	The policy plugin should setup the execution environment such that the
	.Nm sudo
	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
	.Nm ssh
	to perform remote command execution.
	The helper program would be responsible for running
	.Nm ssh
	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
	.Nm sudoedit
	functionality must be handled by the policy plugin, not
	.Nm sudo
	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
.Fn conversation	.Fn conversation
Line 1865 The caller must include a trailing newline in	Line 1926 The caller must include a trailing newline in
if one is to be printed.	if one is to be printed.
.Pp	.Pp
A	A
.Fn printf Ns No -style	.Fn printf Ns -style
function is also available that can be used to display informational	function is also available that can be used to display informational
or error messages to the user, which is usually more convenient for	or error messages to the user, which is usually more convenient for
simple messages where no use input is required.	simple messages where no use input is required.
Line 1883 struct sudo_conv_message {	Line 1944 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 1897 typedef int (*sudo_printf_t)(int msg_type, const char	Line 1960 typedef int (*sudo_printf_t)(int msg_type, const char
Pointers to the	Pointers to the
.Fn conversation	.Fn conversation
and	and
.Fn printf Ns No -style	.Fn printf Ns -style
functions are passed	functions are passed
in to the plugin's	in to the plugin's
.Fn open	.Fn open
Line 1916 and	Line 1979 and
.Li struct sudo_conv_reply	.Li struct sudo_conv_reply
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
.Li struct sudo_conv_reply ,	.Li struct sudo_conv_reply ,
if any.	if it is not
	.Dv NULL .
	.Dv SUDO_CONV_REPL_MAX
	represents the maximum length of the reply buffer (not including
	the trailing NUL character).
	In practical terms, this is the longest password
	.Nm sudo
	will support.
	It is also useful as a maximum value for the
	.Fn memset_s
	function when clearing passwords filled in by the conversation function.
.Pp	.Pp
The	The
.Fn printf Ns No -style	.Fn printf Ns -style
function uses the same underlying mechanism as the	function uses the same underlying mechanism as the
.Fn conversation	.Fn conversation
function but only supports	function but only supports
Line 2037 major and minor version number of the group plugin API	Line 2110 major and minor version number of the group plugin API
.Nm sudoers .	.Nm sudoers .
.It plugin_printf	.It plugin_printf
A pointer to a	A pointer to a
.Fn printf Ns No -style	.Fn printf Ns -style
function that may be used to display informational or error message to the user.	function that may be used to display informational or error message to the user.
Returns the number of characters printed on success and \-1 on failure.	Returns the number of characters printed on success and \-1 on failure.
.It argv	.It argv
A	A
.Dv NULL Ns No -terminated	.Dv NULL Ns -terminated
array of arguments generated from the	array of arguments generated from the
.Em group_plugin	.Em group_plugin
option in	option in
Line 2180 The	Line 2253 The
.Nm sudo	.Nm sudo
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.
	.It Version 1.4 (sudo 1.8.8)
	The
	.Em remote_host
	entry was added to the
	.Li settings
	list.
	.It Version 1.5 (sudo 1.8.9)
	The
	.em preserve_fds
	entry was added to the
	.Li command_info
	list.
.El	.El
.Sh SEE ALSO	.Sh SEE ALSO
.Xr sudo.conf @mansectform@ ,	.Xr sudo.conf @mansectform@ ,

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

Removed from v.1.1.1.2
changed lines
	Added in v.1.1.1.4