version 1.1.1.3, 2012/10/09 09:29:52
|
version 1.1.1.4, 2013/07/22 10:46:12
|
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" "March 5, 2013" "Sudo @PACKAGE_VERSION@" "OpenBSD Programmer's Manual" |
.nh |
.nh |
.if n .ad l |
.if n .ad l |
.SH "NAME" |
.SH "NAME" |
Line 28 Starting with version 1.8,
|
Line 28 Starting with version 1.8,
|
supports a plugin API |
supports a plugin API |
for policy and session logging. |
for policy and session logging. |
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 47 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 55 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 252 itself but the
|
Line 180 itself but the
|
might. |
might. |
.RS |
.RS |
.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. |
|
.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 |
(`,\&'). |
(`,\&'). |
.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 225 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 246 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 |
Set to true if the user specified the | If the user does not specify a program on the command line, |
\fB\-P\fR | |
flag, indicating that | |
the user wishes to preserve the group vector instead of setting it | |
based on the runas user. | |
.TP 6n | |
ignore_ticket=bool | |
Set to true if the user specified the | |
\fB\-k\fR | |
flag along with a | |
command, indicating that the user wishes to ignore any cached | |
authentication credentials. | |
.TP 6n | |
noninteractive=bool | |
Set to true if the user specified the | |
\fB\-n\fR | |
flag, indicating that | |
\fBsudo\fR |
\fBsudo\fR |
should operate in non-interactive mode. | will pass the plugin the path to the user's shell and set |
The plugin may reject a command run in non-interactive mode if user | |
interaction is required. | |
.TP 6n |
.TP 6n |
login_class=string |
login_class=string |
BSD login class to use when setting resource limits and nice value, |
BSD login class to use when setting resource limits and nice value, |
Line 417 if specified by the
|
Line 257 if specified by the
|
\fB\-c\fR |
\fB\-c\fR |
flag. |
flag. |
.TP 6n |
.TP 6n |
selinux_role=string | login_shell=bool |
SELinux role to use when executing the command, if specified by | Set to true if the user specified the |
the | \fB\-i\fR |
\fB\-r\fR | flag, indicating that |
flag. | the user wishes to run a login shell. |
.TP 6n |
.TP 6n |
selinux_type=string | max_groups=int |
SELinux type to use when executing the command, if specified by | The maximum number of groups a user may belong to. |
the | This will only be present if there is a corresponding setting in |
\fB\-t\fR | sudo.conf(@mansectform@). |
flag. | |
.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. |
|
.TP 6n |
|
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 |
Line 447 If the address contains a colon
|
Line 280 If the address contains a colon
|
(`:\&'), |
(`:\&'), |
it is an IPv6 address, else it is IPv4. |
it is an IPv6 address, else it is IPv4. |
.TP 6n |
.TP 6n |
|
noninteractive=bool |
|
Set to true if the user specified the |
|
\fB\-n\fR |
|
flag, indicating that |
|
\fBsudo\fR |
|
should operate in non-interactive mode. |
|
The plugin may reject a command run in non-interactive mode if user |
|
interaction is required. |
|
.TP 6n |
|
plugin_dir=string |
|
The default plugin directory used by the |
|
\fBsudo\fR |
|
front end. |
|
This is the default directory set at compile time and may not |
|
correspond to the directory the running plugin was loaded from. |
|
It may be used by a plugin to locate support files. |
|
.TP 6n |
|
preserve_environment=bool |
|
Set to true if the user specified the |
|
\fB\-E\fR |
|
flag, indicating that |
|
the user wishes to preserve the environment. |
|
.TP 6n |
|
preserve_groups=bool |
|
Set to true if the user specified the |
|
\fB\-P\fR |
|
flag, indicating that |
|
the user wishes to preserve the group vector instead of setting it |
|
based on the runas user. |
|
.TP 6n |
progname=string |
progname=string |
The command name that sudo was run as, typically |
The command name that sudo was run as, typically |
``sudo'' |
``sudo'' |
or |
or |
``sudoedit''. |
``sudoedit''. |
.TP 6n |
.TP 6n |
|
prompt=string |
|
The prompt to use when requesting a password, if specified via |
|
the |
|
\fB\-p\fR |
|
flag. |
|
.TP 6n |
|
run_shell=bool |
|
Set to true if the user specified the |
|
\fB\-s\fR |
|
flag, indicating that |
|
the user wishes to run a shell. |
|
.TP 6n |
|
runas_group=string |
|
The group name or gid to to run the command as, if specified via |
|
the |
|
\fB\-g\fR |
|
flag. |
|
.TP 6n |
|
runas_user=string |
|
The user name or uid to to run the command as, if specified via the |
|
\fB\-u\fR |
|
flag. |
|
.TP 6n |
|
selinux_role=string |
|
SELinux role to use when executing the command, if specified by |
|
the |
|
\fB\-r\fR |
|
flag. |
|
.TP 6n |
|
selinux_type=string |
|
SELinux type to use when executing the command, if specified by |
|
the |
|
\fB\-t\fR |
|
flag. |
|
.TP 6n |
|
set_home=bool |
|
Set to true if the user specified the |
|
\fB\-H\fR |
|
flag. |
|
If true, set the |
|
\fRHOME\fR |
|
environment variable to the target user's home directory. |
|
.TP 6n |
sudoedit=bool |
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 374 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. |
Line 510 might.
|
Line 404 might.
|
.RS |
.RS |
.PD |
.PD |
.TP 6n |
.TP 6n |
|
cols=int |
|
The number of columns the user's terminal supports. |
|
If there is no terminal device available, a default value of 80 is used. |
|
.TP 6n |
|
cwd=string |
|
The user's current working directory. |
|
.TP 6n |
|
egid=gid_t |
|
The effective group ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
euid=uid_t |
|
The effective user ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
gid=gid_t |
|
The real group ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
groups=list |
|
The user's supplementary group list formatted as a string of |
|
comma-separated group IDs. |
|
.TP 6n |
|
host=string |
|
The local machine's hostname as returned by the |
|
gethostname(2) |
|
system call. |
|
.TP 6n |
|
lines=int |
|
The number of lines the user's terminal supports. |
|
If there is |
|
no terminal device available, a default value of 24 is used. |
|
.TP 6n |
|
pgid=int |
|
The ID of the process group that the running |
|
\fBsudo\fR |
|
process is a member of. |
|
Only available starting with API version 1.2 |
|
.TP 6n |
pid=int |
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 |
|
Any (non-comment) strings immediately after the plugin path are |
|
passed as arguments to the plugin. |
|
These arguments are split on a white space boundary and are passed to |
|
the plugin in the form of a |
|
\fRNULL\fR-terminated |
|
array of strings. |
|
If no arguments were |
|
specified, |
|
\fIplugin_options\fR |
|
will be the |
|
\fRNULL\fR |
|
pointer. |
|
.sp |
|
NOTE: the |
|
\fIplugin_options\fR |
|
parameter is only available starting with |
|
API version 1.2. |
|
A plugin |
|
\fBmust\fR |
|
check the API version specified |
|
by the |
|
\fBsudo\fR |
|
front end before using |
|
\fIplugin_options\fR. |
|
Failure to do so may result in a crash. |
|
.TP 6n |
ppid=int |
ppid=int |
The parent process ID of the running |
The parent process ID of the running |
\fBsudo\fR |
\fBsudo\fR |
Line 527 The session ID of the running
|
Line 487 The session ID of the running
|
\fBsudo\fR |
\fBsudo\fR |
process or 0 if |
process or 0 if |
\fBsudo\fR |
\fBsudo\fR |
is | is not part of a POSIX job control session. |
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 |
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 |
tcpgid=int |
The ID of the forground process group associated with the terminal | The ID of the foreground process group associated with the terminal |
device associcated with the | 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 |
user=string |
|
The name of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
euid=uid_t |
|
The effective user ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
uid=uid_t |
|
The real user ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
egid=gid_t |
|
The effective group ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
gid=gid_t |
|
The real group ID of the user invoking |
|
\fBsudo\fR. |
|
.TP 6n |
|
groups=list |
|
The user's supplementary group list formatted as a string of |
|
comma-separated group IDs. |
|
.TP 6n |
|
cwd=string |
|
The user's current working directory. |
|
.TP 6n |
|
tty=string |
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''. |
``\fRtty=\fR''. |
.TP 6n |
.TP 6n |
host=string | uid=uid_t |
The local machine's hostname as returned by the | The real user ID of the user invoking |
gethostname(2) | \fBsudo\fR. |
system call. | |
.TP 6n |
.TP 6n |
lines=int | user=string |
The number of lines the user's terminal supports. | The name of the user invoking |
If there is | \fBsudo\fR. |
no terminal device available, a default value of 24 is used. | |
.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. | |
.PP |
.PP |
.RE |
.RE |
.PD 0 |
.PD 0 |
Line 615 itself but the
|
Line 534 itself but the
|
\fIvalue\fR |
\fIvalue\fR |
might. |
might. |
.PD |
.PD |
.TP 6n |
|
plugin_options |
|
Any (non-comment) strings immediately after the plugin path are |
|
treated as arguments to the plugin. |
|
These arguments are split on a white space boundary and are passed to |
|
the plugin in the form of a |
|
\fRNULL\fR-terminated |
|
array of strings. |
|
If no arguments were |
|
specified, |
|
\fIplugin_options\fR |
|
will be the |
|
\fRNULL\fR |
|
pointer. |
|
.sp |
|
NOTE: the |
|
\fIplugin_options\fR |
|
parameter is only available starting with |
|
API version 1.2. |
|
A plugin |
|
\fBmust\fR |
|
check the API version specified |
|
by the |
|
\fBsudo\fR |
|
front end before using |
|
\fIplugin_options\fR. |
|
Failure to do so may result in a crash. |
|
.PP |
.PP |
.RE |
.RE |
.PD 0 |
.PD 0 |
Line 690 If the command was successfully executed, the value of
|
Line 582 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. |
|
.PP |
.RE |
.RE |
.PD 0 |
.PD 0 |
.TP 6n |
.TP 6n |
Line 862 The following values are recognized by
|
Line 768 The following values are recognized by
|
\fBsudo\fR: |
\fBsudo\fR: |
.RS |
.RS |
.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. |
.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 779 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 885 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_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 972 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 1114 is run with the
|
Line 1081 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 1158 or
|
Line 1125 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 1395 struct io_plugin {
|
Line 1362 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 1467 open
|
Line 1435 open
|
.RS |
.RS |
.nf |
.nf |
.RS 0n |
.RS 0n |
int (*open)(unsigned int version, sudo_conv_t conversation | int (*open)(unsigned int version, sudo_conv_t conversation, |
sudo_printf_t plugin_printf, char * const settings[], |
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[]); |
Line 1906 section for a description of
|
Line 1874 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 2247 user-visible.
|
Line 2262 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 2274 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 2317 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 |
Line 2331 The function arguments are as follows:
|
Line 2349 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 2368 void (*cleanup)();
|
Line 2386 void (*cleanup)();
|
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. |
Line 2444 The following revisions have been made to the Sudo Plu
|
Line 2462 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 2485 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. |
.SH "SEE ALSO" |
.SH "SEE ALSO" |
|
sudo.conf(@mansectform@), |
sudoers(@mansectform@), |
sudoers(@mansectform@), |
sudo(@mansectsu@) |
sudo(@mansectsu@) |
.SH "BUGS" |
.SH "BUGS" |