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

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

version 1.1.1.1, 2012/10/09 09:29:52 version 1.1.1.4, 2014/06/15 16:12:54
Line 1 Line 1
 .\"  .\"
.\" 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 14 Line 14
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.  .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"  .\"
.Dd July 16, 2012.Dd December 20, 2013
 .Dt SUDO_PLUGIN @mansectform@  .Dt SUDO_PLUGIN @mansectform@
 .Os Sudo @PACKAGE_VERSION@  .Os Sudo @PACKAGE_VERSION@
 .Sh NAME  .Sh NAME
Line 25  Starting with version 1.8, Line 25  Starting with version 1.8,
 .Nm sudo  .Nm sudo
 supports a plugin API  supports a plugin API
 for policy and session logging.  for policy and session logging.
   Plugins may be compiled as dynamic shared objects (the default on
   systems that support them) or compiled statically into the
   .Nm sudo
   binary itself.
 By default, the  By default, the
.Em sudoers.Nm sudoers
 policy plugin and an associated I/O logging plugin are used.  policy plugin and an associated I/O logging plugin are used.
 Via the plugin API,  Via the plugin API,
 .Nm sudo  .Nm sudo
 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
.Pa @sysconfdir@/sudo.conf.Xr 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 45  major version matches. Line 49  major version matches.
 The plugin API is defined by the  The plugin API is defined by the
 .Li sudo_plugin.h  .Li sudo_plugin.h
 header file.  header file.
 .Ss The sudo.conf file  
 The  
 .Pa @sysconfdir@/sudo.conf  
 file contains plugin configuration directives.  
 The primary keyword is the  
 .Li Plugin  
 directive, which causes a plugin to be loaded.  
 .Pp  
 A  
 .Li Plugin  
 line consists of the  
 .Li Plugin  
 keyword, followed by the  
 .Em symbol_name  
 and the  
 .Em path  
 to the shared object containing the plugin.  
 The  
 .Em symbol_name  
 is the name of the  
 .Li struct policy_plugin  
 or  
 .Li struct io_plugin  
 in the plugin shared object.  
 The  
 .Em path  
 may be fully qualified or relative.  
 If not fully qualified it is relative to the  
 .Pa @prefix@/libexec  
 directory.  
 Any additional parameters after the  
 .Em path  
 are passed as options to the plugin's  
 .Fn open  
 function.  
 Lines that don't begin with  
 .Li Plugin ,  
 .Li Path ,  
 .Li Debug  
 or  
 .Li Set  
 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.  
 .Bd -literal  
 #  
 # 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  
 .Ed  
 .Ss Policy plugin API  .Ss Policy plugin API
 A policy plugin must declare and populate a  A policy plugin must declare and populate a
 .Li policy_plugin  .Li policy_plugin
Line 122  This structure contains pointers to the functions that Line 57  This structure contains pointers to the functions that
 .Nm sudo  .Nm sudo
 policy checks.  policy checks.
 The name of the symbol should be specified in  The name of the symbol should be specified in
.Pa @sysconfdir@/sudo.conf.Xr sudo.conf @mansectform@
 along with a path to the plugin so that  along with a path to the plugin so that
 .Nm sudo  .Nm sudo
 can load it.  can load it.
Line 204  function that can be used by the plugin to interact wi Line 139  function that can be used by the plugin to interact wi
 Returns 0 on success and \-1 on failure.  Returns 0 on success and \-1 on failure.
 .It plugin_printf  .It plugin_printf
 A pointer to a  A pointer to a
.Fn printf Ns No -style.Fn printf Ns -style
 function that may be used to display informational or error messages  function that may be used to display informational or error messages
 (see below).  (see below).
 Returns the number of characters printed on success and \-1 on failure.  Returns the number of characters printed on success and \-1 on failure.
Line 235  itself but the Line 170  itself but the
 .Em value  .Em value
 might.  might.
 .Bl -tag -width 4n  .Bl -tag -width 4n
   .It bsdauth_type=string
   Authentication type, if specified by the
   .Fl a
   flag, to use on
   systems where BSD authentication is supported.
   .It closefrom=number
   If specified, the user has requested via the
   .Fl C
   flag that
   .Nm sudo
   close all files descriptors with a value of
   .Em number
   or higher.
   The plugin may optionally pass this, or another value, back in the
   .Em command_info
   list.
 .It debug_flags=string  .It debug_flags=string
 A comma-separated list of debug flags that correspond to  A comma-separated list of debug flags that correspond to
.Nm sudo Ns No 's.Nm sudo Ns 's
 .Li Debug  .Li Debug
 entry in  entry in
.Pa @sysconfdir@/sudo.conf ,.Xr 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
.Pa @sysconfdir@/sudo.conf ..Xr sudo.conf @mansectform@ .
 The syntax used by  The syntax used by
 .Nm sudo  .Nm sudo
 and the  and the
.Em sudoers.Nm sudoers
 plugin is  plugin is
.Em subsystem Ns No @ Ns Em priority.Em subsystem Ns @ Ns Em priority
 but the plugin is free to use a different  but the plugin is free to use a different
 format so long as it does not include a comma  format so long as it does not include a comma
 .Pq Ql ,\& .  .Pq Ql ,\& .
 .Pp  
 For reference, the priorities supported by the  
 .Nm sudo  
 front end and  
 .Em sudoers  
 are:  
 .Em crit ,  
 .Em err ,  
 .Em warn ,  
 .Em notice ,  
 .Em diag ,  
 .Em info ,  
 .Em trace  
 and  
 .Em debug .  
 .Pp  
 The following subsystems are defined:  
 .Em main ,  
 .Em memory ,  
 .Em args ,  
 .Em exec ,  
 .Em pty ,  
 .Em utmp ,  
 .Em conv ,  
 .Em pcomm ,  
 .Em util ,  
 .Em list ,  
 .Em netif ,  
 .Em audit ,  
 .Em edit ,  
 .Em selinux ,  
 .Em ldap ,  
 .Em match ,  
 .Em parser ,  
 .Em alias ,  
 .Em defaults ,  
 .Em auth ,  
 .Em env ,  
 .Em logging ,  
 .Em nss ,  
 .Em rbtree ,  
 .Em perms ,  
 .Em plugin .  
 The subsystem  
 .Em all  
 includes every subsystem.  
 .Pp  
 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
 .Nm sudo  .Nm sudo
Line 307  and the plugin. Line 211  and the plugin.
 .It debug_level=number  .It debug_level=number
 This setting has been deprecated in favor of  This setting has been deprecated in favor of
 .Em debug_flags .  .Em debug_flags .
.It runas_user=string.It ignore_ticket=bool
The user name or uid to to run the command as, if specified via the 
.Fl u 
flag. 
.It runas_group=string 
The group name or gid to to run the command as, if specified via 
the 
.Fl g 
flag. 
.It prompt=string 
The prompt to use when requesting a password, if specified via 
the 
.Fl p 
flag. 
.It set_home=bool 
 Set to true if the user specified the  Set to true if the user specified the
.Fl H.Fl k
flag.flag along with a
If true, set thecommand, indicating that the user wishes to ignore any cached
.Li HOMEauthentication credentials.
environment variable to the target user's home directory. 
.It preserve_environment=bool 
Set to true if the user specified the 
.Fl E 
flag, indicating that 
the user wishes to preserve the environment. 
.It run_shell=bool 
Set to true if the user specified the 
.Fl s 
flag, indicating that 
the user wishes to run a shell. 
.It login_shell=bool 
Set to true if the user specified the 
.Fl i 
flag, indicating that 
the user wishes to run a login shell. 
.It implied_shell=bool 
If the user does not specify a program on the command line, 
.Nm sudo 
will pass the plugin the path to the user's shell and set 
 .Em implied_shell  .Em implied_shell
 to true.  to true.
 This allows  This allows
Line 361  function, which will cause Line 231  function, which will cause
 .Nm sudo  .Nm sudo
 to print a usage message and  to print a usage message and
 exit.  exit.
.It preserve_groups=bool.It implied_shell=bool
Set to true if the user specified theIf the user does not specify a program on the command line,
.Fl P 
flag, indicating that 
the user wishes to preserve the group vector instead of setting it 
based on the runas user. 
.It ignore_ticket=bool 
Set to true if the user specified the 
.Fl k 
flag along with a 
command, indicating that the user wishes to ignore any cached 
authentication credentials. 
.It noninteractive=bool 
Set to true if the user specified the 
.Fl n 
flag, indicating that 
 .Nm sudo  .Nm sudo
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. 
 .It login_class=string  .It 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,
 if specified by the  if specified by the
 .Fl c  .Fl c
 flag.  flag.
.It selinux_role=string.It login_shell=bool
SELinux role to use when executing the command, if specified bySet to true if the user specified the
the.Fl i
.Fl rflag, indicating that
flag.the user wishes to run a login shell.
.It selinux_type=string.It max_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
.Fl t.Xr sudo.conf @mansectform@ .
flag. 
.It bsdauth_type=string 
Authentication type, if specified by the 
.Fl a 
flag, to use on 
systems where BSD authentication is supported. 
 .It network_addrs=list  .It 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 412  what the operating system supports. Line 260  what the operating system supports.
 If the address contains a colon  If the address contains a colon
 .Pq Ql :\& ,  .Pq Ql :\& ,
 it is an IPv6 address, else it is IPv4.  it is an IPv6 address, else it is IPv4.
   .It noninteractive=bool
   Set to true if the user specified the
   .Fl n
   flag, indicating that
   .Nm sudo
   should operate in non-interactive mode.
   The plugin may reject a command run in non-interactive mode if user
   interaction is required.
   .It plugin_dir=string
   The default plugin directory used by the
   .Nm sudo
   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.
   .It preserve_environment=bool
   Set to true if the user specified the
   .Fl E
   flag, indicating that
   the user wishes to preserve the environment.
   .It preserve_groups=bool
   Set to true if the user specified the
   .Fl P
   flag, indicating that
   the user wishes to preserve the group vector instead of setting it
   based on the runas user.
 .It progname=string  .It progname=string
 The command name that sudo was run as, typically  The command name that sudo was run as, typically
 .Dq sudo  .Dq sudo
 or  or
 .Dq sudoedit .  .Dq sudoedit .
   .It prompt=string
   The prompt to use when requesting a password, if specified via
   the
   .Fl p
   flag.
   .It remote_host=string
   The name of the remote host to run the command on, if specified via
   the
   .Fl h
   option.
   Support for running the command on a remote host is meant to be implemented
   via a helper program that is executed in place of the user-specified command.
   The
   .Nm sudo
   front end is only capable of executing commands on the local host.
   Only available starting with API version 1.4.
   .It run_shell=bool
   Set to true if the user specified the
   .Fl s
   flag, indicating that the user wishes to run a shell.
   .It runas_group=string
   The group name or gid to run the command as, if specified via
   the
   .Fl g
   flag.
   .It runas_user=string
   The user name or uid to run the command as, if specified via the
   .Fl u
   flag.
   .It selinux_role=string
   SELinux role to use when executing the command, if specified by
   the
   .Fl r
   flag.
   .It selinux_type=string
   SELinux type to use when executing the command, if specified by
   the
   .Fl t
   flag.
   .It set_home=bool
   Set to true if the user specified the
   .Fl H
   flag.
   If true, set the
   .Li HOME
   environment variable to the target user's home directory.
 .It sudoedit=bool  .It sudoedit=bool
 Set to true when the  Set to true when the
 .Fl e  .Fl e
Line 432  if the plugin does not support Line 352  if the plugin does not support
 For more information, see the  For more information, see the
 .Em check_policy  .Em check_policy
 section.  section.
 .It closefrom=number  
 If specified, the user has requested via the  
 .Fl C  
 flag that  
 .Nm sudo  
 close all files descriptors with a value of  
 .Em number  
 or higher.  
 The plugin may optionally pass this, or another value, back in the  
 .Em command_info  
 list.  
 .El  .El
 .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
Line 468  itself but the Line 377  itself but the
 .Em value  .Em value
 might.  might.
 .Bl -tag -width 4n  .Bl -tag -width 4n
.It pid=int.It cols=int
The process ID of the runningThe number of columns the user's terminal supports.
.Nm sudoIf there is no terminal device available, a default value of 80 is used.
process..It cwd=string
Only available starting with API version 1.2The user's current working directory.
.It ppid=int.It egid=gid_t
The parent process ID of the runningThe effective group ID of the user invoking
.Nm sudo 
process. 
Only available starting with API version 1.2 
.It sid=int 
The session ID of the running 
.Nm sudo 
process or 0 if 
.Nm sudo 
is 
not part of a POSIX job control session. 
Only available starting with API version 1.2 
.It pgid=int 
The ID of the process group that the running 
.Nm sudo 
process belongs 
to. 
Only available starting with API version 1.2 
.It tcpgid=int 
The ID of the forground process group associated with the terminal 
device associcated with the 
.Nm sudo 
process or \-1 if there is no 
terminal present. 
Only available starting with API version 1.2 
.It user=string 
The name of the user invoking 
 .Nm sudo .  .Nm sudo .
 .It euid=uid_t  .It euid=uid_t
 The effective user ID of the user invoking  The effective user ID of the user invoking
 .Nm sudo .  .Nm sudo .
 .It uid=uid_t  
 The real user ID of the user invoking  
 .Nm sudo .  
 .It egid=gid_t  
 The effective group ID of the user invoking  
 .Nm sudo .  
 .It gid=gid_t  .It gid=gid_t
 The real group ID of the user invoking  The real group ID of the user invoking
 .Nm sudo .  .Nm sudo .
 .It groups=list  .It groups=list
 The user's supplementary group list formatted as a string of  The user's supplementary group list formatted as a string of
 comma-separated group IDs.  comma-separated group IDs.
 .It cwd=string  
 The user's current working directory.  
 .It 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  
 .Dq Li tty= .  
 .It host=string  .It host=string
 The local machine's hostname as returned by the  The local machine's hostname as returned by the
 .Xr gethostname 2  .Xr gethostname 2
Line 532  system call. Line 402  system call.
 The number of lines the user's terminal supports.  The number of lines the user's terminal supports.
 If there is  If there is
 no terminal device available, a default value of 24 is used.  no terminal device available, a default value of 24 is used.
.It cols=int.It pgid=int
The number of columns the user's terminal supports.The ID of the process group that the running
If there is no terminal device available, a default value of 80 is used..Nm sudo
.Elprocess is a member of.
.It user_envOnly available starting with API version 1.2.
The user's environment in the form of a.It pid=int
.Dv NULL Ns No -terminated vector ofThe process ID of the running
.Dq name=value.Nm sudo
strings.process.
.PpOnly available starting with API version 1.2.
When parsing 
.Em user_env , 
the plugin should split on the 
.Sy first 
equal sign 
.Pq Ql = 
since the 
.Em name 
field will never include one 
itself but the 
.Em value 
might. 
 .It plugin_options  .It plugin_options
 Any (non-comment) strings immediately after the plugin path are  Any (non-comment) strings immediately after the plugin path are
treated as arguments to the plugin.passed as arguments to the plugin.
 These arguments are split on a white space boundary and are passed to  These arguments are split on a white space boundary and are passed to
 the plugin in the form of a  the plugin in the form of a
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 array of strings.  array of strings.
 If no arguments were  If no arguments were
 specified,  specified,
Line 580  by the Line 438  by the
 front end before using  front end before using
 .Em plugin_options .  .Em plugin_options .
 Failure to do so may result in a crash.  Failure to do so may result in a crash.
   .It ppid=int
   The parent process ID of the running
   .Nm sudo
   process.
   Only available starting with API version 1.2.
   .It sid=int
   The session ID of the running
   .Nm sudo
   process or 0 if
   .Nm sudo
   is not part of a POSIX job control session.
   Only available starting with API version 1.2.
   .It tcpgid=int
   The ID of the foreground process group associated with the terminal
   device associated with the
   .Nm sudo
   process or \-1 if there is no
   terminal present.
   Only available starting with API version 1.2.
   .It 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
   .Dq Li tty= .
   .It uid=uid_t
   The real user ID of the user invoking
   .Nm sudo .
   .It user=string
   The name of the user invoking
   .Nm sudo .
 .El  .El
   .It user_env
   The user's environment in the form of a
   .Dv NULL Ns -terminated vector of
   .Dq name=value
   strings.
   .Pp
   When parsing
   .Em user_env ,
   the plugin should split on the
   .Sy first
   equal sign
   .Pq Ql =
   since the
   .Em name
   field will never include one
   itself but the
   .Em value
   might.
   .El
 .It close  .It close
 .Bd -literal -compact  .Bd -literal -compact
 void (*close)(int exit_status, int error);  void (*close)(int exit_status, int error);
Line 618  If the command was successfully executed, the value of Line 525  If the command was successfully executed, the value of
 .Li error  .Li error
 is 0.  is 0.
 .El  .El
   .Pp
   If no
   .Fn close
   function is defined, no I/O logging plugins are loaded,
   and neither the
   .Em timeout
   not
   .Em use_pty
   options are set in the
   .Li command_info
   list, the
   .Nm sudo
   front end may execute the command directly instead of running
   it as a child process.
 .It show_version  .It show_version
 .Bd -literal -compact  .Bd -literal -compact
 int (*show_version)(int verbose);  int (*show_version)(int verbose);
Line 737  pointer. Line 658  pointer.
 .It env_add  .It env_add
 Additional environment variables specified by the user on the command  Additional environment variables specified by the user on the command
 line in the form of a  line in the form of a
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 vector of  vector of
 .Dq name=value  .Dq name=value
 strings.  strings.
Line 771  pointer. Line 692  pointer.
 The following values are recognized by  The following values are recognized by
 .Nm sudo :  .Nm sudo :
 .Bl -tag -width 4n  .Bl -tag -width 4n
 .It command=string  
 Fully qualified path to the command to be executed.  
 .It runas_uid=uid  
 User ID to run the command as.  
 .It runas_euid=uid  
 Effective user ID to run the command as.  
 If not specified, the value of  
 .Em runas_uid  
 is used.  
 .It runas_gid=gid  
 Group ID to run the command as.  
 .It runas_egid=gid  
 Effective group ID to run the command as.  
 If not specified, the value of  
 .Em runas_gid  
 is used.  
 .It runas_groups=list  
 The supplementary group vector to use for the command in the form  
 of a comma-separated list of group IDs.  
 If  
 .Em preserve_groups  
 is set, this option is ignored.  
 .It 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.  
 .It preserve_groups=bool  
 If set,  
 .Nm sudo  
 will preserve the user's group vector instead of  
 initializing the group vector based on  
 .Li runas_user .  
 .It cwd=string  
 The current working directory to change to when executing the command.  
 .It noexec=bool  
 If set, prevent the command from executing other programs.  
 .It chroot=string  .It chroot=string
 The root directory to use when running the command.  The root directory to use when running the command.
 .It nice=int  
 Nice value (priority) to use when executing the command.  
 The nice value, if specified, overrides the priority associated with the  
 .Em login_class  
 on BSD systems.  
 .It umask=octal  
 The file creation mask to use when executing the command.  
 .It selinux_role=string  
 SELinux role to use when executing the command.  
 .It selinux_type=string  
 SELinux type to use when executing the command.  
 .It timeout=int  
 Command timeout.  
 If non-zero then when the timeout expires the command will be killed.  
 .It sudoedit=bool  
 Set to true when in  
 .Em sudoedit  
 mode.  
 The plugin may enable  
 .Em sudoedit  
 mode even if  
 .Nm sudo  
 was not invoked as  
 .Nm sudoedit .  
 This allows the plugin to perform command substitution and transparently  
 enable  
 .Em sudoedit  
 when the user attempts to run an editor.  
 .It closefrom=number  .It closefrom=number
 If specified,  If specified,
 .Nm sudo  .Nm sudo
Line 844  will close all files descriptors with a value Line 701  will close all files descriptors with a value
 of  of
 .Em number  .Em number
 or higher.  or higher.
   .It command=string
   Fully qualified path to the command to be executed.
   .It cwd=string
   The current working directory to change to when executing the command.
   .It exec_background=bool
   By default,
   .Nm sudo
   runs a command as the foreground process as long as
   .Nm sudo
   itself is running in the foreground.
   When
   .Em exec_background
   is enabled and the command is being run in a pty (due to I/O logging
   or the
   .Em use_pty
   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
   .Dv SIGTTIN
   signal (or
   .Dv SIGTTOU
   in the case of terminal settings).
   If this happens when
   .Nm sudo
   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
   .Nm sudo
   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
   .Em sudo
   behavior or when the command is not being run in a pty.
   .Pp
   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
   .Fn tcgetattr
   and
   .Fn tcsetattr
   system calls (this is a bug in Mac OS X).
   Furthermore, because this behavior depends on the command stopping with the
   .Dv SIGTTIN
   or
   .Dv SIGTTOU
   signals, programs that catch these signals and suspend themselves
   with a different signal (usually
   .Dv SIGTOP )
   will not be automatically foregrounded.
   Some versions of the linux
   .Xr su 1
   command behave this way.
   Because of this, a plugin should not set
   .Em exec_background
   unless it is explicitly enabled by the administrator and there should
   be a way to enabled or disable it on a per-command basis.
   .Pp
   This setting has no effect unless I/O logging is enabled or
   .Em use_pty
   is enabled.
 .It iolog_compress=bool  .It 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 876  Set to true if the I/O logging plugins, if any, should Line 797  Set to true if the I/O logging plugins, if any, should
 terminal output.  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.
   .It 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.
   .It nice=int
   Nice value (priority) to use when executing the command.
   The nice value, if specified, overrides the priority associated with the
   .Em login_class
   on BSD systems.
   .It noexec=bool
   If set, prevent the command from executing other programs.
   .It preserve_fds=list
   A comma-separated list of file descriptors that should be
   preserved, regardless of the value of the
   .Em closefrom
   setting.
   Only available starting with API version 1.5.
   .It preserve_groups=bool
   If set,
   .Nm sudo
   will preserve the user's group vector instead of
   initializing the group vector based on
   .Li runas_user .
   .It runas_egid=gid
   Effective group ID to run the command as.
   If not specified, the value of
   .Em runas_gid
   is used.
   .It runas_euid=uid
   Effective user ID to run the command as.
   If not specified, the value of
   .Em runas_uid
   is used.
   .It runas_gid=gid
   Group ID to run the command as.
   .It runas_groups=list
   The supplementary group vector to use for the command in the form
   of a comma-separated list of group IDs.
   If
   .Em preserve_groups
   is set, this option is ignored.
   .It runas_uid=uid
   User ID to run the command as.
   .It selinux_role=string
   SELinux role to use when executing the command.
   .It selinux_type=string
   SELinux type to use when executing the command.
   .It 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.
   .It sudoedit=bool
   Set to true when in
   .Em sudoedit
   mode.
   The plugin may enable
   .Em sudoedit
   mode even if
   .Nm sudo
   was not invoked as
   .Nm sudoedit .
   This allows the plugin to perform command substitution and transparently
   enable
   .Em sudoedit
   when the user attempts to run an editor.
   .It timeout=int
   Command timeout.
   If non-zero then when the timeout expires the command will be killed.
   .It umask=octal
   The file creation mask to use when executing the command.
 .It use_pty=bool  .It 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 883  By default, Line 874  By default,
 .Nm sudo  .Nm sudo
 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.
 .It 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.  
 .It utmp_user=string  .It 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
 .Em set_utmp  .Em set_utmp
Line 902  the invoking user's existing entry. Line 889  the invoking user's existing entry.
 Unsupported values will be ignored.  Unsupported values will be ignored.
 .It argv_out  .It argv_out
 The  The
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 argument vector to pass to the  argument vector to pass to the
 .Xr execve 2  .Xr execve 2
 system call when executing the command.  system call when executing the command.
 The plugin is responsible for allocating and populating the vector.  The plugin is responsible for allocating and populating the vector.
 .It user_env_out  .It user_env_out
 The  The
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 environment vector to use when executing the command.  environment vector to use when executing the command.
 The plugin is responsible for allocating and populating the vector.  The plugin is responsible for allocating and populating the vector.
 .El  .El
Line 975  is run with the Line 962  is run with the
 .Fl v  .Fl v
 flag.  flag.
 For policy plugins such as  For policy plugins such as
.Em sudoers.Nm sudoers
 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 1011  or Line 998  or
 .Fl K  .Fl K
 flag.  flag.
 For policy plugins such as  For policy plugins such as
.Em sudoers.Nm sudoers
 that  that
 cache authentication credentials, this function will invalidate the  cache authentication credentials, this function will invalidate the
 credentials.  credentials.
Line 1059  The Line 1046  The
 .Em user_env  .Em user_env
 argument points to the environment the command will  argument points to the environment the command will
 run in, in the form of a  run in, in the form of a
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 vector of  vector of
 .Dq name=value  .Dq name=value
 strings.  strings.
Line 1219  struct io_plugin { Line 1206  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 1286  to determine the API version the plugin was Line 1274  to determine the API version the plugin was
 built against.  built against.
 .It open  .It open
 .Bd -literal -compact  .Bd -literal -compact
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 1342  The Line 1330  The
 function returns 0 on success and \-1 on failure.  function returns 0 on success and \-1 on failure.
 .It plugin_printf  .It plugin_printf
 A pointer to a  A pointer to a
.Fn printf Ns No -style.Fn printf Ns -style
 function that may be used by the  function that may be used by the
 .Fn show_version  .Fn show_version
 function to display version information (see  function to display version information (see
Line 1422  wishes to run in the same form as what would be passed Line 1410  wishes to run in the same form as what would be passed
 system call.  system call.
 .It user_env  .It user_env
 The user's environment in the form of a  The user's environment in the form of a
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 vector of  vector of
 .Dq name=value  .Dq name=value
 strings.  strings.
Line 1444  Any (non-comment) strings immediately after the plugin Line 1432  Any (non-comment) strings immediately after the plugin
 treated as arguments to the plugin.  treated as arguments to the plugin.
 These arguments are split on a white space boundary and are passed to  These arguments are split on a white space boundary and are passed to
 the plugin in the form of a  the plugin in the form of a
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 array of strings.  array of strings.
 If no arguments were specified,  If no arguments were specified,
 .Em plugin_options  .Em plugin_options
Line 1654  section for a description of Line 1642  section for a description of
 .Pp  .Pp
 Same as for the  Same as for the
 .Sx Policy plugin API .  .Sx Policy plugin API .
   .Ss Signal handlers
   The
   .Nm sudo
   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:
   .Pp
   .Bl -bullet -compact
   .It
   .Dv SIGALRM
   .It
   .Dv SIGHUP
   .It
   .Dv SIGINT
   .It
   .Dv SIGQUIT
   .It
   .Dv SIGTERM
   .It
   .Dv SIGTSTP
   .It
   .Dv SIGUSR1
   .It
   .Dv SIGUSR2
   .El
   .Pp
   If a fatal signal is received before the command is executed,
   .Nm sudo
   will call the plugin's
   .Fn close
   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
   .Fn close
   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 1846  return SUDO_HOOK_RET_STOP; Line 1874  return SUDO_HOOK_RET_STOP;
     *(vp) = (*(vp) & 0xffff0000) | (n); \e      *(vp) = (*(vp) & 0xffff0000) | (n); \e
 } while(0)  } while(0)
 .Ed  .Ed
   .Ss Remote command execution
   The
   .Nm sudo
   front end does not have native support for running remote commands.
   However, starting with
   .Nm sudo
   1.8.8, the
   .Fl h
   option may be used to specify a remote host that is passed
   to the policy plugin.
   A plugin may also accept a
   .Em runas_user
   in the form of
   .Dq user@hostname
   which will work with older versions of
   .Nm sudo .
   It is anticipated that remote commands will be supported by executing a
   .Dq helper
   program.
   The policy plugin should setup the execution environment such that the
   .Nm sudo
   front end will run the helper which, in turn, will connect to the
   remote host and run the command.
   .Pp
   For example, the policy plugin could utilize
   .Nm ssh
   to perform remote command execution.
   The helper program would be responsible for running
   .Nm ssh
   with the proper options to use a private key or certificate
   that the remote host will accept and run a program
   on the remote host that would setup the execution environment
   accordingly.
   .Pp
   Note that remote
   .Nm sudoedit
   functionality must be handled by the policy plugin, not
   .Nm sudo
   itself as the front end has no knowledge that a remote command is
   being executed.
   This may be addressed in a future revision of the plugin API.
 .Ss Conversation API  .Ss Conversation API
 If the plugin needs to interact with the user, it may do so via the  If the plugin needs to interact with the user, it may do so via the
 .Fn conversation  .Fn conversation
Line 1857  The caller must include a trailing newline in Line 1926  The caller must include a trailing newline in
 if one is to be printed.  if one is to be printed.
 .Pp  .Pp
 A  A
.Fn printf Ns No -style.Fn printf Ns -style
 function is also available that can be used to display informational  function is also available that can be used to display informational
 or error messages to the user, which is usually more convenient for  or error messages to the user, which is usually more convenient for
 simple messages where no use input is required.  simple messages where no use input is required.
Line 1875  struct sudo_conv_message { Line 1944  struct sudo_conv_message {
     const char *msg;      const char *msg;
 };  };
   
   #define SUDO_CONV_REPL_MAX      255
   
 struct sudo_conv_reply {  struct sudo_conv_reply {
     char *reply;      char *reply;
 };  };
Line 1889  typedef int (*sudo_printf_t)(int msg_type, const char  Line 1960  typedef int (*sudo_printf_t)(int msg_type, const char 
 Pointers to the  Pointers to the
 .Fn conversation  .Fn conversation
 and  and
.Fn printf Ns No -style.Fn printf Ns -style
 functions are passed  functions are passed
 in to the plugin's  in to the plugin's
 .Fn open  .Fn open
Line 1908  and Line 1979  and
 .Li struct sudo_conv_reply  .Li struct sudo_conv_reply
 for  for
 each message in the conversation.  each message in the conversation.
The plugin is responsible for freeing the reply buffer filled in to theThe plugin is responsible for freeing the reply buffer located in each
 .Li struct sudo_conv_reply ,  .Li struct sudo_conv_reply ,
if any.if it is not
 .Dv NULL .
 .Dv SUDO_CONV_REPL_MAX
 represents the maximum length of the reply buffer (not including
 the trailing NUL character).
 In practical terms, this is the longest password
 .Nm sudo
 will support.
 It is also useful as a maximum value for the
 .Fn memset_s
 function when clearing passwords filled in by the conversation function.
 .Pp  .Pp
 The  The
.Fn printf Ns No -style.Fn printf Ns -style
 function uses the same underlying mechanism as the  function uses the same underlying mechanism as the
 .Fn conversation  .Fn conversation
 function but only supports  function but only supports
Line 1943  user-visible. Line 2024  user-visible.
 Instead, they are logged to the file specified in the  Instead, they are logged to the file specified in the
 .Li Debug  .Li Debug
 statement (if any) in the  statement (if any) in the
.Pa @sysconfdir@/sudo.conf.Xr 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 1956  See the sample plugin for an example of the Line 2036  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
.Em sudoers.Nm sudoers
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
.Nm sudo.Nm sudo ,
that implements file-based lookups..Em group_file
 and
 .Em system_group ,
 are detailed in
 .Xr 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 1992  The Line 2076  The
 field should be set to GROUP_API_VERSION.  field should be set to GROUP_API_VERSION.
 .Pp  .Pp
 This allows  This allows
.Em sudoers.Nm sudoers
 to determine the API version the group plugin  to determine the API version the group plugin
 was built against.  was built against.
 .It init  .It init
Line 2020  The function arguments are as follows: Line 2104  The function arguments are as follows:
 .Bl -tag -width 4n  .Bl -tag -width 4n
 .It version  .It version
 The version passed in by  The version passed in by
.Em sudoers.Nm sudoers
 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
.Em sudoers ..Nm sudoers .
 .It plugin_printf  .It plugin_printf
 A pointer to a  A pointer to a
.Fn printf Ns No -style.Fn printf Ns -style
 function that may be used to display informational or error message to the user.  function that may be used to display informational or error message to the user.
 Returns the number of characters printed on success and \-1 on failure.  Returns the number of characters printed on success and \-1 on failure.
 .It argv  .It argv
 A  A
.Dv NULL Ns No -terminated.Dv NULL Ns -terminated
 array of arguments generated from the  array of arguments generated from the
 .Em group_plugin  .Em group_plugin
 option in  option in
Line 2049  void (*cleanup)(); Line 2133  void (*cleanup)();
 The  The
 .Fn cleanup  .Fn cleanup
 function is called when  function is called when
.Em sudoers.Nm sudoers
 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 2109  The following revisions have been made to the Sudo Plu Line 2193  The following revisions have been made to the Sudo Plu
 .Bl -tag -width 4n  .Bl -tag -width 4n
 .It Version 1.0  .It Version 1.0
 Initial API version.  Initial API version.
.It Version 1.1.It Version 1.1 (sudo 1.8.0)
 The I/O logging plugin's  The I/O logging plugin's
 .Fn open  .Fn open
 function was modified to take the  function was modified to take the
 .Li command_info  .Li command_info
 list as an argument.  list as an argument.
.It Version 1.2.It Version 1.2 (sudo 1.8.5)
 The Policy and I/O logging plugins'  The Policy and I/O logging plugins'
 .Fn open  .Fn open
 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
.Pa @sysconfdir@/sudo.conf ..Xr sudo.conf @mansectform@ .
 .Pp  .Pp
 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 2131  Policy plugin function is now passed a pointer Line 2215  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.
   .It Version 1.3 (sudo 1.8.7)
   Support for the
   .Em exec_background
   entry has been added to the
   .Li command_info
   list.
   .Pp
   The
   .Em max_groups
   and
   .Em plugin_dir
   entries were added to the
   .Li settings
   list.
   .Pp
   The
   .Fn version
   and
   .Fn close
   functions are now optional.
   Previously, a missing
   .Fn version
   or
   .Fn close
   function would result in a crash.
   If no policy plugin
   .Fn close
   function is defined, a default
   .Fn close
   function will be provided by the
   .Nm sudo
   front end that displays a warning if the command could not be
   executed.
   .Pp
   The
   .Nm sudo
   front end now installs default signal handlers to trap common signals
   while the plugin functions are run.
   .It Version 1.4 (sudo 1.8.8)
   The
   .Em remote_host
   entry was added to the
   .Li settings
   list.
   .It Version 1.5 (sudo 1.8.9)
   The
   .em preserve_fds
   entry was added to the
   .Li command_info
   list.
 .El  .El
 .Sh SEE ALSO  .Sh SEE ALSO
   .Xr sudo.conf @mansectform@ ,
 .Xr sudoers @mansectform@ ,  .Xr sudoers @mansectform@ ,
 .Xr sudo @mansectsu@  .Xr sudo @mansectsu@
 .Sh BUGS  .Sh BUGS
Removed from v.1.1.1.1  
changed lines
  Added in v.1.1.1.4

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