[BACK]Return to sudo_plugin.man.in CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sudo / doc

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

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 theThe plugins to be used are specified in the
\fI@sysconfdir@/sudo.conf\fRsudo.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\fRsudo.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=stringignore_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 thecommand, indicating that the user wishes to ignore any cached
\fRHOME\fRauthentication 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=boolimplied_shell=bool
Set to true if the user specified theIf 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=stringlogin_shell=bool
SELinux role to use when executing the command, if specified bySet to true if the user specified the
the\fB\-i\fR
\fB\-r\fRflag, indicating that
flag.the user wishes to run a login shell.
 .TP 6n  .TP 6n
selinux_type=stringmax_groups=int
SELinux type to use when executing the command, if specified byThe maximum number of groups a user may belong to.
theThis will only be present if there is a corresponding setting in
\fB\-t\fRsudo.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
isis 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 terminalThe ID of the foreground process group associated with the terminal
device associcated with thedevice 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=stringuid=uid_t
The local machine's hostname as returned by theThe real user ID of the user invoking
gethostname(2)\fBsudo\fR.
system call. 
 .TP 6n  .TP 6n
lines=intuser=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 conversationint (*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\fRsudo.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-Unixplugin 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 withTwo 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.1Version 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.2Version 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 ina 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"
Removed from v.1.1.1.3  
changed lines
  Added in v.1.1.1.4

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