The prompt to use when requesting a password, if
specified via the -\b-p\bp flag.
+ remote_host=string
+ The name of the remote host to run the command on, if
+ specified via the -\b-h\bh 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 s\bsu\bud\bdo\bo front end is only capable
+ of executing commands on the local host. Only
+ available starting with API version 1.4.
+
run_shell=bool
Set to true if the user specified the -\b-s\bs flag,
indicating that the user wishes to run a shell.
runas_group=string
- The group name or gid to to run the command as, if
+ The group name or gid to run the command as, if
specified via the -\b-g\bg flag.
runas_user=string
- The user name or uid to to run the command as, if
+ The user name or uid to run the command as, if
specified via the -\b-u\bu flag.
selinux_role=string
pgid=int
The ID of the process group that the running s\bsu\bud\bdo\bo
process is a member of. Only available starting with
- API version 1.2
+ API version 1.2.
pid=int
The process ID of the running s\bsu\bud\bdo\bo process. Only
- available starting with API version 1.2
+ available starting with API version 1.2.
plugin_options
Any (non-comment) strings immediately after the plugin
ppid=int
The parent process ID of the running s\bsu\bud\bdo\bo process.
- Only available starting with API version 1.2
+ Only available starting with API version 1.2.
sid=int
The session ID of the running s\bsu\bud\bdo\bo process or 0 if s\bsu\bud\bdo\bo
is not part of a POSIX job control session. Only
- available starting with API version 1.2
+ available starting with API version 1.2.
tcpgid=int
The ID of the foreground process group associated with
the terminal device associated with the s\bsu\bud\bdo\bo process or
-1 if there is no terminal present. Only available
- starting with API version 1.2
+ starting with API version 1.2.
tty=string
The path to the user's terminal device. If the user
The s\bsu\bud\bdo\bo front end now installs default signal handlers to trap
common signals while the plugin functions are run.
+ Version 1.4 (sudo 1.8.8)
+ The _\br_\be_\bm_\bo_\bt_\be_\b__\bh_\bo_\bs_\bt entry was added to the settings list.
+
S\bSE\bEE\bE A\bAL\bLS\bSO\bO
sudo.conf(4), sudoers(4), sudo(1m)
file distributed with s\bsu\bud\bdo\bo or http://www.sudo.ws/sudo/license.html for
complete details.
-Sudo 1.8.7 March 5, 2013 Sudo 1.8.7
+Sudo 1.8.8 July 16, 2013 Sudo 1.8.8
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" 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" "July 16, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual"
.nh
.if n .ad l
.SH "NAME"
built against.
.TP 6n
open
-.RS
.nf
-.RS 0n
+.RS 6n
int (*open)(unsigned int version, sudo_conv_t conversation,
sudo_printf_t plugin_printf, char * const settings[],
char * const user_info[], char * const user_env[],
char * const plugin_options[]);
.RE
.fi
+.RS 6n
.sp
Returns 1 on success, 0 on failure, \-1 if a general error occurred,
or \-2 if there was a usage error.
A vector of user-supplied
\fBsudo\fR
settings in the form of
-``name=value''
+\(lqname=value\(rq
strings.
The vector is terminated by a
\fRNULL\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.
-.RS
+.PP
+.RS 6n
+.PD 0
.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
\fIsubsystem\fR@\fIpriority\fR
but the plugin is free to use a different
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
to the plugin--the flags are shared by
\fBsudo\fR
network_addrs=list
A space-separated list of IP network addresses and netmasks in the
form
-``addr/netmask'',
+\(lqaddr/netmask\(rq,
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
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
.TP 6n
progname=string
The command name that sudo was run as, typically
-``sudo''
+\(lqsudo\(rq
or
-``sudoedit''.
+\(lqsudoedit\(rq.
.TP 6n
prompt=string
The prompt to use when requesting a password, if specified via
\fB\-p\fR
flag.
.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.
+flag, indicating that the user wishes to run a shell.
.TP 6n
runas_group=string
-The group name or gid to to run the command as, if specified via
+The 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 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
flag.
.TP 6n
.PP
Additional settings may be added in the future so the plugin should
silently ignore settings that it does not recognize.
-.PP
.RE
-.PD 0
.TP 6n
user_info
A vector of information about the user running the command in the form of
-``name=value''
+\(lqname=value\(rq
strings.
The vector is terminated by a
\fRNULL\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.
-.RS
-.PD
+.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
.TP 6n
cwd=string
The user's current working directory.
The ID of the process group that the running
\fBsudo\fR
process is a member of.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
.TP 6n
pid=int
The process ID of the running
\fBsudo\fR
process.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
.TP 6n
plugin_options
Any (non-comment) strings immediately after the plugin path are
The parent process ID of the running
\fBsudo\fR
process.
-Only available starting with API version 1.2
+Only available starting with API version 1.2.
.TP 6n
sid=int
The session ID of the running
process or 0 if
\fBsudo\fR
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
tcpgid=int
The ID of the foreground process group associated with the terminal
\fBsudo\fR
process or \-1 if there is no
terminal present.
-Only available starting with API version 1.2
+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
-``\fRtty=\fR''.
+\(lq\fRtty=\fR\(rq.
.TP 6n
uid=uid_t
The real user ID of the user invoking
user=string
The name of the user invoking
\fBsudo\fR.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
user_env
The user's environment in the form of a
\fRNULL\fR-terminated vector of
-``name=value''
+\(lqname=value\(rq
strings.
.sp
When parsing
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
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
close
.br
-.RS
.nf
-.RS 0n
+.RS 6n
void (*close)(int exit_status, int error);
.RE
.fi
+.RS 6n
.sp
The
\fBclose\fR()
finishes.
.sp
The function arguments are as follows:
-.PD
.TP 6n
exit_status
The command's exit status, as returned by the
\fBsudo\fR
front end may execute the command directly instead of running
it as a child process.
-.PP
.RE
-.PD 0
.TP 6n
show_version
-.RS
.nf
-.RS 0n
+.RS 6n
int (*show_version)(int verbose);
.RE
.fi
+.RS 6n
.sp
The
\fBshow_version\fR()
function using
\fRSUDO_CONV_INFO_MSG\fR.
If the user requests detailed version information, the verbose flag will be set.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
check_policy
-.RS
.nf
-.RS 0n
+.RS 6n
int (*check_policy)(int argc, char * const argv[]
char *env_add[], char **command_info[],
char **argv_out[], char **user_env_out[]);
.RE
.fi
+.RS 6n
.sp
The
\fBcheck_policy\fR()
\fIargv_out\fR,
separated from the
editor and its arguments by a
-``\fR--\fR''
+\(lq\fR--\fR\(rq
element.
The
-``\fR--\fR''
+\(lq\fR--\fR\(rq
will
be removed by
\fBsudo\fR
to present additional error information to the user.
.sp
The function arguments are as follows:
-.PD
.TP 6n
argc
The number of elements in
line in the form of a
\fRNULL\fR-terminated
vector of
-``name=value''
+\(lqname=value\(rq
strings.
The plugin may reject the command if one or more variables
are not allowed to be set, or it may silently ignore such variables.
the plugin should split on the
\fBfirst\fR
equal sign
-(`=')
+(\(oq=\(cq)
since the
\fIname\fR
field will never include one
.TP 6n
command_info
Information about the command being run in the form of
-``name=value''
+\(lqname=value\(rq
strings.
These values are used by
\fBsudo\fR
pointer.
The following values are recognized by
\fBsudo\fR:
-.RS
+.PP
+.RS 6n
+.PD 0
.TP 6n
chroot=string
The root directory to use when running the command.
+.PD
.TP 6n
closefrom=number
If specified,
the invoking user's existing entry.
.PP
Unsupported values will be ignored.
-.PP
.RE
-.PD 0
.TP 6n
argv_out
The
execve(2)
system call when executing the command.
The plugin is responsible for allocating and populating the vector.
-.PD
.TP 6n
user_env_out
The
\fRNULL\fR-terminated
environment vector to use when executing the command.
The plugin is responsible for allocating and populating the vector.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
list
-.RS
.nf
-.RS 0n
+.RS 6n
int (*list)(int verbose, const char *list_user,
int argc, char * const argv[]);
.RE
.fi
+.RS 6n
.sp
List available privileges for the invoking user.
Returns 1 on success, 0 on failure and \-1 on error.
\fBplugin_printf\fR()
function using
\fRSUDO_CONV_INFO_MSG\fR,
-.PD
.TP 6n
verbose
Flag indicating whether to list in verbose mode or not.
system call.
If the command is permitted by the policy, the fully-qualified path
to the command should be displayed along with any command line arguments.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
validate
-.RS
.nf
-.RS 0n
+.RS 6n
int (*validate)(void);
.RE
.fi
+.RS 6n
.sp
The
\fBvalidate\fR()
\fRSUDO_CONF_ERROR_MSG\fR
to present additional
error information to the user.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
invalidate
-.RS
.nf
-.RS 0n
+.RS 6n
void (*invalidate)(int remove);
.RE
.fi
+.RS 6n
.sp
The
\fBinvalidate\fR()
function should be
\fRNULL\fR
if the plugin does not support credential caching.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
init_session
-.RS
.nf
-.RS 0n
+.RS 6n
int (*init_session)(struct passwd *pwd, char **user_envp[);
.RE
.fi
+.RS 6n
.sp
The
\fBinit_session\fR()
run in, in the form of a
\fRNULL\fR-terminated
vector of
-``name=value''
+\(lqname=value\(rq
strings.
This is the same string passed back to the front end via
the Policy Plugin's
\fRSUDO_CONF_ERROR_MSG\fR
to present additional
error information to the user.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
register_hooks
-.RS
.nf
-.RS 0n
+.RS 6n
void (*register_hooks)(int version,
int (*register_hook)(struct sudo_hook *hook));
.RE
.fi
+.RS 6n
.sp
The
\fBregister_hooks\fR()
version 1.2 or higher,
\fRregister_hooks\fR
will not be called.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
deregister_hooks
-.RS
.nf
-.RS 0n
+.RS 6n
void (*deregister_hooks)(int version,
int (*deregister_hook)(struct sudo_hook *hook));
.RE
.fi
+.RS 6n
.sp
The
\fBderegister_hooks\fR()
\fRderegister_hooks\fR
will not be called.
.RE
-.PD
.PP
\fIPolicy Plugin Version Macros\fR
.nf
built against.
.TP 6n
open
-.RS
.nf
-.RS 0n
+.RS 6n
int (*open)(unsigned int version, sudo_conv_t conversation,
sudo_printf_t plugin_printf, char * const settings[],
char * const user_info[], int argc, char * const argv[],
char * const user_env[], char * const plugin_options[]);
.RE
.fi
+.RS 6n
.sp
The
\fBopen\fR()
A vector of user-supplied
\fBsudo\fR
settings in the form of
-``name=value''
+\(lqname=value\(rq
strings.
The vector is terminated by a
\fRNULL\fR
the plugin should split on the
\fBfirst\fR
equal sign
-(`=')
+(\(oq=\(cq)
since the
\fIname\fR
field will never include one
.TP 6n
user_info
A vector of information about the user running the command in the form of
-``name=value''
+\(lqname=value\(rq
strings.
The vector is terminated by a
\fRNULL\fR
the plugin should split on the
\fBfirst\fR
equal sign
-(`=')
+(\(oq=\(cq)
since the
\fIname\fR
field will never include one
The user's environment in the form of a
\fRNULL\fR-terminated
vector of
-``name=value''
+\(lqname=value\(rq
strings.
.sp
When parsing
the plugin should split on the
\fBfirst\fR
equal sign
-(`=')
+(\(oq=\(cq)
since the
\fIname\fR
field will never include one
front end before using
\fIplugin_options\fR.
Failure to do so may result in a crash.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
close
.br
-.RS
.nf
-.RS 0n
+.RS 6n
void (*close)(int exit_status, int error);
.RE
.fi
+.RS 6n
.sp
The
\fBclose\fR()
finishes.
.sp
The function arguments are as follows:
-.PD
.TP 6n
exit_status
The command's exit status, as returned by the
If the command was successfully executed, the value of
\fRerror\fR
is 0.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
show_version
-.RS
.nf
-.RS 0n
+.RS 6n
int (*show_version)(int verbose);
.RE
.fi
+.RS 6n
.sp
The
\fBshow_version\fR()
function using
\fRSUDO_CONV_INFO_MSG\fR.
If the user requests detailed version information, the verbose flag will be set.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
log_ttyin
-.RS
.nf
-.RS 0n
+.RS 6n
int (*log_ttyin)(const char *buf, unsigned int len);
.RE
.fi
+.RS 6n
.sp
The
\fBlog_ttyin\fR()
is rejected (which will terminate the command) or \-1 if an error occurred.
.sp
The function arguments are as follows:
-.PD
.TP 6n
buf
The buffer containing user input.
The length of
\fIbuf\fR
in bytes.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
log_ttyout
-.RS
.nf
-.RS 0n
+.RS 6n
int (*log_ttyout)(const char *buf, unsigned int len);
.RE
.fi
+.RS 6n
.sp
The
\fBlog_ttyout\fR()
(which will terminate the command) or \-1 if an error occurred.
.sp
The function arguments are as follows:
-.PD
.TP 6n
buf
The buffer containing command output.
The length of
\fIbuf\fR
in bytes.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
log_stdin
-.RS
.nf
-.RS 0n
+.RS 6n
int (*log_stdin)(const char *buf, unsigned int len);
.RE
.fi
+.RS 6n
.sp
The
\fBlog_stdin\fR()
rejected (which will terminate the command) or \-1 if an error occurred.
.sp
The function arguments are as follows:
-.PD
.TP 6n
buf
The buffer containing user input.
The length of
\fIbuf\fR
in bytes.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
log_stdout
-.RS
.nf
-.RS 0n
+.RS 6n
int (*log_stdout)(const char *buf, unsigned int len);
.RE
.fi
+.RS 6n
.sp
The
\fBlog_stdout\fR()
rejected (which will terminate the command) or \-1 if an error occurred.
.sp
The function arguments are as follows:
-.PD
.TP 6n
buf
The buffer containing command output.
The length of
\fIbuf\fR
in bytes.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
log_stderr
-.RS
.nf
-.RS 0n
+.RS 6n
int (*log_stderr)(const char *buf, unsigned int len);
.RE
.fi
+.RS 6n
.sp
The
\fBlog_stderr\fR()
rejected (which will terminate the command) or \-1 if an error occurred.
.sp
The function arguments are as follows:
-.PD
.TP 6n
buf
The buffer containing command output.
The length of
\fIbuf\fR
in bytes.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
register_hooks
See the
\fIPolicy plugin API\fR
section for a description of
\fRregister_hooks\fR.
-.PD
.TP 6n
deregister_hooks
See the
The
\fRhook_type\fR
field may be one of the following supported hook types:
-.RS
+.PP
+.RS 6n
+.PD 0
.TP 6n
\fRSUDO_HOOK_SETENV\fR
The C library
\fRhook_fn\fR
field should
be a function that matches the following typedef:
-.RS
.nf
.sp
-.RS 0n
+.RS 6n
typedef int (*sudo_hook_fn_setenv_t)(const char *name,
const char *value, int overwrite, void *closure);
.RE
.fi
+.RS 6n
.sp
If the registered hook does not match the typedef the results are
unspecified.
-.PP
.RE
-.PD 0
+.PD
.TP 6n
\fRSUDO_HOOK_UNSETENV\fR
The C library
\fRhook_fn\fR
field should
be a function that matches the following typedef:
-.RS
.nf
.sp
-.RS 0n
+.RS 6n
typedef int (*sudo_hook_fn_unsetenv_t)(const char *name,
void *closure);
.RE
.fi
-.PD
-.PP
-.RE
-.PD 0
.TP 6n
\fRSUDO_HOOK_GETENV\fR
The C library
\fRhook_fn\fR
field should
be a function that matches the following typedef:
-.RS
.nf
.sp
-.RS 0n
+.RS 6n
typedef int (*sudo_hook_fn_getenv_t)(const char *name,
char **value, void *closure);
.RE
.fi
+.RS 6n
.sp
If the registered hook does not match the typedef the results are
unspecified.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
\fRSUDO_HOOK_PUTENV\fR
The C library
\fRhook_fn\fR
field should
be a function that matches the following typedef:
-.RS
.nf
.sp
-.RS 0n
+.RS 6n
typedef int (*sudo_hook_fn_putenv_t)(char *string,
void *closure);
.RE
.fi
+.RS 6n
.sp
If the registered hook does not match the typedef the results are
unspecified.
.RE
-.PD
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
hook_fn
sudo_hook_fn_t hook_fn;
This can be used to pass arbitrary data to the plugin's hook implementation.
.sp
The function return value may be one of the following:
-.RS
-.PD
+.PP
+.RS 6n
+.PD 0
.TP 6n
\fRSUDO_HOOK_RET_ERROR\fR
The hook function encountered an error.
+.PD
.TP 6n
\fRSUDO_HOOK_RET_NEXT\fR
The hook completed without error, go on to the next hook (including
the environment but leaves
\fRenviron\fR
unchanged.
+.PD 0
+.PP
.RE
+.PD
.PP
Note that it is very easy to create an infinite loop when hooking
C library functions.
was built against.
.TP 6n
init
-.RS
.nf
-.RS 0n
+.RS 6n
int (*init)(int version, sudo_printf_t plugin_printf,
char *const argv[]);
.RE
.fi
+.RS 6n
.sp
The
\fBinit\fR()
\fIargv\fR
will be
\fRNULL\fR.
+.PD 0
.PP
.RE
-.PD 0
+.PD
.TP 6n
cleanup
-.RS
.nf
-.RS 0n
+.RS 6n
void (*cleanup)();
.RE
.fi
+.RS 6n
.sp
The
\fBcleanup\fR()
has finished its
group checks.
The plugin should free any memory it has allocated and close open file handles.
-.PD
-.PP
.RE
-.PD 0
.TP 6n
query
.br
-.RS
.nf
-.RS 0n
+.RS 6n
int (*query)(const char *user, const char *group,
const struct passwd *pwd);
.RE
.fi
+.RS 6n
.sp
The
\fBquery\fR()
\fIgroup\fR.
.sp
The function arguments are as follows:
-.PD
.TP 6n
user
The name of the user being looked up in the external group database.
\fIpwd\fR
will be
\fRNULL\fR.
+.PD 0
+.PP
.RE
+.PD
.PP
\fIGroup API Version Macros\fR
.nf
\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.
.SH "SEE ALSO"
sudo.conf(@mansectform@),
sudoers(@mansectform@),
.SH "DISCLAIMER"
\fBsudo\fR
is provided
-``AS IS''
+\(lqAS IS\(rq
and any express or implied warranties, including, but not limited
to, the implied warranties of merchantability and fitness for a
particular purpose are disclaimed.
projects / sudo / commitdiff