diff options
Diffstat (limited to 'doc/sudo.conf.mdoc.in')
| -rw-r--r-- | doc/sudo.conf.mdoc.in | 687 |
1 files changed, 687 insertions, 0 deletions
diff --git a/doc/sudo.conf.mdoc.in b/doc/sudo.conf.mdoc.in new file mode 100644 index 0000000..4823a0b --- /dev/null +++ b/doc/sudo.conf.mdoc.in @@ -0,0 +1,687 @@ +.\" +.\" Copyright (c) 2010-2018 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd October 7, 2018 +.Dt SUDO.CONF @mansectform@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudo.conf +.Nd configuration for sudo front end +.Sh DESCRIPTION +The +.Nm sudo.conf +file is used to configure the +.Nm sudo +front end. +It specifies the security policy and I/O logging plugins, debug flags +as well as plugin-agnostic path names and settings. +.Pp +The +.Nm +file supports the following directives, described in detail below. +.Bl -tag -width 8n +.It Plugin +a security policy or I/O logging plugin +.It Path +a plugin-agnostic path +.It Set +a front end setting, such as +.Em disable_coredump +or +.Em group_source +.It Debug +debug flags to aid in debugging +.Nm sudo , +.Nm sudoreplay , +.Nm visudo , +and the +.Nm sudoers +plugin. +.El +.Pp +The pound sign +.Pq Ql # +is used to indicate a comment. +Both the comment character and any text after it, up to the end of +the line, are ignored. +.Pp +Long lines can be continued with a backslash +.Pq Ql \e +as the last character on the line. +Note that leading white space is removed from the beginning of lines +even when the continuation character is used. +.Pp +Non-comment lines that don't begin with +.Li Plugin , +.Li Path , +.Li Debug , +or +.Li Set +are silently ignored. +.Pp +The +.Nm +file is always parsed in the +.Dq Li C +locale. +.Ss Plugin configuration +.Nm sudo +supports a plugin architecture for security policies and input/output +logging. +Third parties can develop and distribute their own policy and I/O +logging plugins to work seamlessly with the +.Nm sudo +front end. +Plugins are dynamically loaded based on the contents of +.Nm . +.Pp +A +.Li Plugin +line consists of the +.Li Plugin +keyword, followed by the +.Em symbol_name +and the +.Em path +to the dynamic shared object that contains the plugin. +The +.Em symbol_name +is the name of the +.Li struct policy_plugin +or +.Li struct io_plugin +symbol contained in the plugin. +The +.Em path +may be fully qualified or relative. +If not fully qualified, it is relative to the directory +specified by the +.Em plugin_dir +.Li Path +setting, which defaults to +.Pa @PLUGINDIR@ . +In other words: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +.Ed +.Pp +is equivalent to: +.Bd -literal -offset indent +Plugin sudoers_policy @PLUGINDIR@/sudoers.so +.Ed +.Pp +If the plugin was compiled statically into the +.Nm sudo +binary instead of being installed as a dynamic shared object, the +.Em path +should be specified without a leading directory, +as it does not actually exist in the file system. +For example: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +.Ed +.Pp +Starting with +.Nm sudo +1.8.5, any additional parameters after the +.Em path +are passed as arguments to the plugin's +.Em open +function. +For example, to override the compile-time default sudoers file mode: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so sudoers_mode=0440 +.Ed +.Pp +See the +.Xr sudoers @mansectform@ +manual for a list of supported arguments. +.Pp +The same dynamic shared object may contain multiple plugins, +each with a different symbol name. +The 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. +.Pp +If no +.Nm +file is present, or if it contains no +.Li Plugin +lines, the +.Nm sudoers +plugin will be used as the default security policy and for I/O logging +(if enabled by the policy). +This is equivalent to the following: +.Bd -literal -offset indent +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so +.Ed +.Pp +For more information on the +.Nm sudo +plugin architecture, see the +.Xr sudo_plugin @mansectform@ +manual. +.Ss Path settings +A +.Li Path +line consists of the +.Li Path +keyword, followed by the name of the path to set and its value. +For example: +.Bd -literal -offset indent +Path noexec @noexec_file@ +Path askpass /usr/X11R6/bin/ssh-askpass +.Ed +.Pp +If no path name is specified, features relying on the specified +setting will be disabled. +Disabling +.Li Path +settings is only supported in +.Nm sudo +version 1.8.16 and higher. +.Pp +The following plugin-agnostic paths may be set in the +.Pa @sysconfdir@/sudo.conf +file: +.Bl -tag -width 8n +.It askpass +The fully qualified path to a helper program used to read the user's +password when no terminal is available. +This may be the case when +.Nm sudo +is executed from a graphical (as opposed to text-based) application. +The program specified by +.Em askpass +should display the argument passed to it as the prompt and write +the user's password to the standard output. +The value of +.Em askpass +may be overridden by the +.Ev SUDO_ASKPASS +environment variable. +.It devsearch +An ordered, colon-separated search path of directories to look in for +device nodes. +This is used when mapping the process's tty device number to a device name +on systems that do not provide such a mechanism. +Sudo will +.Em not +recurse into sub-directories. +If terminal devices may be located in a sub-directory of +.Pa /dev , +that path must be explicitly listed in +.Em devsearch . +The default value is: +.Li /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev +.Pp +This option is ignored on systems that support either the +.Fn devname +or +.Fn _ttyname_dev +functions, for example +.Bx , +macOS and Solaris. +.It noexec +The fully-qualified path to a shared library containing wrappers +for the +.Fn execl , +.Fn execle , +.Fn execlp , +.Fn exect , +.Fn execv , +.Fn execve , +.Fn execvP , +.Fn execvp , +.Fn execvpe , +.Fn fexecve , +.Fn popen , +.Fn posix_spawn , +.Fn posix_spawnp , +.Fn system , +and +.Fn wordexp +library functions that prevent the execution of further commands. +This is used to implement the +.Em noexec +functionality on systems that support +.Ev LD_PRELOAD +or its equivalent. +The default value is: +.Pa @noexec_file@ . +.It plugin_dir +The default directory to use when searching for plugins +that are specified without a fully qualified path name. +The default value is +.Pa @PLUGINDIR@ . +.It sesh +The fully-qualified path to the +.Nm sesh +binary. +This setting is only used when +.Nm sudo +is built with SELinux support. +The default value is +.Pa @sesh_file@ . +.El +.Ss Other settings +The +.Nm +file also supports the following front end settings: +.Bl -tag -width 8n +.It disable_coredump +Core dumps of +.Nm sudo +itself are disabled by default to prevent the disclosure of potentially +sensitive information. +To aid in debugging +.Nm sudo +crashes, you may wish to re-enable core dumps by setting +.Dq disable_coredump +to false in +.Nm +as follows: +.Bd -literal -offset indent +Set disable_coredump false +.Ed +.Pp +All modern operating systems place restrictions on core dumps +from setuid processes like +.Nm sudo +so this option can be enabled without compromising security. +To actually get a +.Nm sudo +core file you will likely need to enable core dumps for setuid processes. +On +.Bx +and Linux systems this is accomplished in the +.Xr sysctl 8 +command. +On Solaris, the +.Xr coreadm 1m +command is used to configure core dump behavior. +.Pp +This setting is only available in +.Nm sudo +version 1.8.4 and higher. +.It group_source +.Nm sudo +passes the invoking user's group list to the policy and I/O plugins. +On most systems, there is an upper limit to the number of groups that +a user may belong to simultaneously (typically 16 for compatibility +with NFS). +On systems with the +.Xr getconf 1 +utility, running: +.Dl getconf NGROUPS_MAX +will return the maximum number of groups. +.Pp +However, it is still possible to be a member of a larger number of +groups--they simply won't be included in the group list returned +by the kernel for the user. +Starting with +.Nm sudo +version 1.8.7, if the user's kernel group list has the maximum number +of entries, +.Nm sudo +will consult the group database directly to determine the group list. +This makes it possible for the security policy to perform matching by group +name even when the user is a member of more than the maximum number of groups. +.Pp +The +.Em group_source +setting allows the administrator to change this default behavior. +Supported values for +.Em group_source +are: +.Bl -tag -width 8n +.It static +Use the static group list that the kernel returns. +Retrieving the group list this way is very fast but it is subject +to an upper limit as described above. +It is +.Dq static +in that it does not reflect changes to the group database made +after the user logs in. +This was the default behavior prior to +.Nm sudo +1.8.7. +.It dynamic +Always query the group database directly. +It is +.Dq dynamic +in that changes made to the group database after the user logs in +will be reflected in the group list. +On some systems, querying the group database for all of a user's +groups can be time consuming when querying a network-based group +database. +Most operating systems provide an efficient method of performing +such queries. +Currently, +.Nm sudo +supports efficient group queries on AIX, +.Bx , +HP-UX, Linux and Solaris. +.It adaptive +Only query the group database if the static group list returned +by the kernel has the maximum number of entries. +This is the default behavior in +.Nm sudo +1.8.7 and higher. +.El +.Pp +For example, to cause +.Nm sudo +to only use the kernel's static list of groups for the user: +.Bd -literal -offset indent +Set group_source static +.Ed +.Pp +This setting is only available in +.Nm sudo +version 1.8.7 and higher. +.It max_groups +The maximum number of user groups to retrieve from the group database. +Values less than one will be ignored. +This setting is only used when querying the group database directly. +It is intended to be used on systems where it is not possible to detect +when the array to be populated with group entries is not sufficiently large. +By default, +.Nm sudo +will allocate four times the system's maximum number of groups (see above) +and retry with double that number if the group database query fails. +.Pp +This setting is only available in +.Nm sudo +version 1.8.7 and higher. +It should not be required in +.Nm sudo +versions 1.8.24 and higher and may be removed in a later release. +.It probe_interfaces +By default, +.Nm sudo +will probe the system's network interfaces and pass the IP address +of each enabled interface to the policy plugin. +This makes it possible for the plugin to match rules based on the IP address +without having to query DNS. +On Linux systems with a large number of virtual interfaces, this may +take a non-negligible amount of time. +If IP-based matching is not required, network interface probing +can be disabled as follows: +.Bd -literal -offset indent +Set probe_interfaces false +.Ed +.Pp +This setting is only available in +.Nm sudo +version 1.8.10 and higher. +.El +.Ss Debug flags +.Nm sudo +versions 1.8.4 and higher support a flexible debugging framework +that can help track down what +.Nm sudo +is doing internally if there is a problem. +.Pp +A +.Li Debug +line consists of the +.Li Debug +keyword, followed by the name of the program (or plugin) to debug +.Pq Nm sudo , Nm visudo , Nm sudoreplay , Nm sudoers , +the debug file name and a comma-separated list of debug flags. +The debug flag syntax used by +.Nm sudo +and the +.Nm sudoers +plugin is +.Em subsystem Ns @ Ns Em priority +but a plugin is free to use a different format so long as it does +not include a comma +.Pq Ql \&, . +.Pp +For example: +.Bd -literal -offset indent +Debug sudo /var/log/sudo_debug all@warn,plugin@info +.Ed +.Pp +would log all debugging statements at the +.Em warn +level and higher in addition to those at the +.Em info +level for the plugin subsystem. +.Pp +As of +.Nm sudo +1.8.12, multiple +.Li Debug +entries may be specified per program. +Older versions of +.Nm sudo +only support a single +.Li Debug +entry per program. +Plugin-specific +.Li Debug +entries are also supported starting with +.Nm sudo +1.8.12 and are matched by either the base name of the plugin that was loaded +(for example +.Li sudoers.so ) +or by the plugin's fully-qualified path name. +Previously, the +.Nm sudoers +plugin shared the same +.Li Debug +entry as the +.Nm sudo +front end and could not be configured separately. +.Pp +The following priorities are supported, in order of decreasing severity: +.Em crit , err , warn , notice , diag , info , trace +and +.Em debug . +Each priority, when specified, also includes all priorities higher +than it. +For example, a priority of +.Em notice +would include debug messages logged at +.Em notice +and higher. +.Pp +The priorities +.Em trace +and +.Em debug +also include function call tracing which logs when a function is +entered and when it returns. +For example, the following trace is for the +.Fn get_user_groups +function located in src/sudo.c: +.Bd -literal -offset indent +sudo[123] -> get_user_groups @ src/sudo.c:385 +sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5 +.Ed +.Pp +When the function is entered, indicated by a right arrow +.Ql -> , +the program, process ID, function, source file and line number +are logged. +When the function returns, indicated by a left arrow +.Ql <- , +the same information is logged along with the return value. +In this case, the return value is a string. +.Pp +The following subsystems are used by the +.Nm sudo +front-end: +.Bl -tag -width Fl +.It Em all +matches every subsystem +.It Em args +command line argument processing +.It Em conv +user conversation +.It Em edit +sudoedit +.It Em event +event subsystem +.It Em exec +command execution +.It Em main +.Nm sudo +main function +.It Em netif +network interface handling +.It Em pcomm +communication with the plugin +.It Em plugin +plugin configuration +.It Em pty +pseudo-tty related code +.It Em selinux +SELinux-specific handling +.It Em util +utility functions +.It Em utmp +utmp handling +.El +.Pp +The +.Xr sudoers @mansectform@ +plugin includes support for additional subsystems. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +.Nm sudo +front end configuration +.El +.Sh EXAMPLES +.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 @PLUGINDIR@ 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. +# +# The sudoers plugin is used by default if no Plugin lines are +# present. +Plugin sudoers_policy sudoers.so +Plugin sudoers_io sudoers.so + +# +# Sudo askpass: +# +# An askpass helper program may be specified to provide a graphical +# password prompt for "sudo -A" support. Sudo does not ship with +# its own askpass program but can use the OpenSSH askpass. +# +# Use the OpenSSH askpass +#Path askpass /usr/X11R6/bin/ssh-askpass +# +# Use the Gnome OpenSSH askpass +#Path askpass /usr/libexec/openssh/gnome-ssh-askpass + +# +# Sudo noexec: +# +# Path to a shared library containing dummy versions of the execv(), +# execve() and fexecve() library functions that just return an error. +# This is used to implement the "noexec" functionality on systems that +# support C<LD_PRELOAD> or its equivalent. +# The compiled-in value is usually sufficient and should only be +# changed if you rename or move the sudo_noexec.so file. +# +#Path noexec @noexec_file@ + +# +# Core dumps: +# +# By default, sudo disables core dumps while it is executing +# (they are re-enabled for the command that is run). +# To aid in debugging sudo problems, you may wish to enable core +# dumps by setting "disable_coredump" to false. +# +#Set disable_coredump false + +# +# User groups: +# +# Sudo passes the user's group list to the policy plugin. +# If the user is a member of the maximum number of groups (usually 16), +# sudo will query the group database directly to be sure to include +# the full list of groups. +# +# On some systems, this can be expensive so the behavior is configurable. +# The "group_source" setting has three possible values: +# static - use the user's list of groups returned by the kernel. +# dynamic - query the group database to find the list of groups. +# adaptive - if user is in less than the maximum number of groups. +# use the kernel list, else query the group database. +# +#Set group_source static +.Ed +.Sh SEE ALSO +.Xr sudo_plugin @mansectform@ , +.Xr sudoers @mansectform@ , +.Xr sudo @mansectsu@ +.Sh HISTORY +See the HISTORY file in the +.Nm sudo +distribution (https://www.sudo.ws/history.html) for a brief +history of sudo. +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS file in the +.Nm sudo +distribution (https://www.sudo.ws/contributors.html) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you feel you have found a bug in +.Nm sudo , +please submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm sudo +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE file distributed with +.Nm sudo +or https://www.sudo.ws/license.html for complete details. |