Annotation of embedaddon/sudo/doc/sudo.conf.mdoc.in, revision 1.1
1.1 ! misho 1: .\"
! 2: .\" Copyright (c) 2010-2013 Todd C. Miller <Todd.Miller@courtesan.com>
! 3: .\"
! 4: .\" Permission to use, copy, modify, and distribute this software for any
! 5: .\" purpose with or without fee is hereby granted, provided that the above
! 6: .\" copyright notice and this permission notice appear in all copies.
! 7: .\"
! 8: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 9: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 10: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 11: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 12: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 13: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 14: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 15: .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
! 16: .\"
! 17: .Dd March 14, 2013
! 18: .Dt SUDO @mansectform@
! 19: .Os Sudo @PACKAGE_VERSION@
! 20: .Sh NAME
! 21: .Nm sudo.conf
! 22: .Nd configuration for sudo front end
! 23: .Sh DESCRIPTION
! 24: The
! 25: .Nm sudo.conf
! 26: file is used to configure the
! 27: .Nm sudo
! 28: front end.
! 29: It specifies the security policy and I/O logging plugins, debug flags
! 30: as well as plugin-agnostic path names and settings.
! 31: .Pp
! 32: The
! 33: .Nm sudo.conf
! 34: file supports the following directives, described in detail below.
! 35: .Bl -tag -width 8n
! 36: .It Plugin
! 37: a security policy or I/O logging plugin
! 38: .It Path
! 39: a plugin-agnostic path
! 40: .It Set
! 41: a front end setting, such as
! 42: .Em disable_coredump
! 43: or
! 44: .Em group_source
! 45: .It Debug
! 46: debug flags to aid in debugging
! 47: .Nm sudo ,
! 48: .Nm sudoreplay ,
! 49: .Nm visudo ,
! 50: and the
! 51: .Nm sudoers
! 52: plugin.
! 53: .El
! 54: .Pp
! 55: The pound sign
! 56: .Pq Ql #
! 57: is used to indicate a comment.
! 58: Both the comment character and any text after it, up to the end of
! 59: the line, are ignored.
! 60: .Pp
! 61: Long lines can be continued with a backslash
! 62: .Pq Ql \e
! 63: as the last character on the line.
! 64: Note that leading white space is removed from the beginning of lines
! 65: even when the continuation character is used.
! 66: .Pp
! 67: Non-comment lines that don't begin with
! 68: .Li Plugin ,
! 69: .Li Path ,
! 70: .Li Debug ,
! 71: or
! 72: .Li Set
! 73: are silently ignored.
! 74: .Pp
! 75: The
! 76: .Nm sudo.conf
! 77: file is always parsed in the
! 78: .Dq Li C
! 79: locale.
! 80: .Ss Plugin configuration
! 81: .Nm sudo
! 82: supports a plugin architecture for security policies and input/output
! 83: logging.
! 84: Third parties can develop and distribute their own policy and I/O
! 85: logging plugins to work seamlessly with the
! 86: .Nm sudo
! 87: front end.
! 88: Plugins are dynamically loaded based on the contents of
! 89: .Nm sudo.conf .
! 90: .Pp
! 91: A
! 92: .Li Plugin
! 93: line consists of the
! 94: .Li Plugin
! 95: keyword, followed by the
! 96: .Em symbol_name
! 97: and the
! 98: .Em path
! 99: to the shared object containing the plugin.
! 100: The
! 101: .Em symbol_name
! 102: is the name of the
! 103: .Li struct policy_plugin
! 104: or
! 105: .Li struct io_plugin
! 106: in the plugin shared object.
! 107: The
! 108: .Em path
! 109: may be fully qualified or relative.
! 110: If not fully qualified, it is relative to the
! 111: .Pa @PLUGINDIR@
! 112: directory.
! 113: In other words:
! 114: .Bd -literal -offset indent
! 115: Plugin sudoers_policy sudoers.so
! 116: .Ed
! 117: .Pp
! 118: is equivalent to:
! 119: .Bd -literal -offset indent
! 120: Plugin sudoers_policy @PLUGINDIR@/sudoers.so
! 121: .Ed
! 122: .Pp
! 123: Starting with
! 124: .Nm sudo
! 125: 1.8.5, any additional parameters after the
! 126: .Em path
! 127: are passed as arguments to the plugin's
! 128: .Em open
! 129: function.
! 130: For example, to override the compile-time default sudoers file mode:
! 131: .Bd -literal -offset indent
! 132: Plugin sudoers_policy sudoers.so sudoers_mode=0440
! 133: .Ed
! 134: .Pp
! 135: The same shared object may contain multiple plugins, each with a
! 136: different symbol name.
! 137: The shared object file must be owned by uid 0 and only writable by its owner.
! 138: Because of ambiguities that arise from composite policies, only a single
! 139: policy plugin may be specified.
! 140: This limitation does not apply to I/O plugins.
! 141: .Pp
! 142: If no
! 143: .Nm sudo.conf
! 144: file is present, or if it contains no
! 145: .Li Plugin
! 146: lines, the
! 147: .Nm sudoers
! 148: plugin will be used as the default security policy and for I/O logging
! 149: (if enabled by the policy).
! 150: This is equivalent to the following:
! 151: .Bd -literal -offset indent
! 152: Plugin sudoers_policy sudoers.so
! 153: Plugin sudoers_io sudoers.so
! 154: .Ed
! 155: .Pp
! 156: For more information on the
! 157: .Nm sudo
! 158: plugin architecture, see the
! 159: .Xr sudo_plugin @mansectsu@
! 160: manual.
! 161: .Ss Path settings
! 162: A
! 163: .Li Path
! 164: line consists of the
! 165: .Li Path
! 166: keyword, followed by the name of the path to set and its value.
! 167: For example:
! 168: .Bd -literal -offset indent
! 169: Path noexec @noexec_file@
! 170: Path askpass /usr/X11R6/bin/ssh-askpass
! 171: .Ed
! 172: .Pp
! 173: The following plugin-agnostic paths may be set in the
! 174: .Pa @sysconfdir@/sudo.conf
! 175: file:
! 176: .Bl -tag -width 8n
! 177: .It askpass
! 178: The fully qualified path to a helper program used to read the user's
! 179: password when no terminal is available.
! 180: This may be the case when
! 181: .Nm sudo
! 182: is executed from a graphical (as opposed to text-based) application.
! 183: The program specified by
! 184: .Em askpass
! 185: should display the argument passed to it as the prompt and write
! 186: the user's password to the standard output.
! 187: The value of
! 188: .Em askpass
! 189: may be overridden by the
! 190: .Ev SUDO_ASKPASS
! 191: environment variable.
! 192: .It noexec
! 193: The fully-qualified path to a shared library containing dummy
! 194: versions of the
! 195: .Fn execv ,
! 196: .Fn execve
! 197: and
! 198: .Fn fexecve
! 199: library functions that just return an error.
! 200: This is used to implement the
! 201: .Em noexec
! 202: functionality on systems that support
! 203: .Ev LD_PRELOAD
! 204: or its equivalent.
! 205: The default value is:
! 206: .Pa @noexec_file@ .
! 207: .It sesh
! 208: The fully-qualified path to the
! 209: .Nm sesh
! 210: binary.
! 211: This setting is only used when
! 212: .Nm sudo
! 213: is built with SELinux support.
! 214: The default value is
! 215: .Pa @sesh_file@ .
! 216: .El
! 217: .Ss Other settings
! 218: The
! 219: .Nm sudo.conf
! 220: file also supports the following front end settings:
! 221: .Bl -tag -width 8n
! 222: .It disable_coredump
! 223: Core dumps of
! 224: .Nm sudo
! 225: itself are disabled by default.
! 226: To aid in debugging
! 227: .Nm sudo
! 228: crashes, you may wish to re-enable core dumps by setting
! 229: .Dq disable_coredump
! 230: to false in
! 231: .Nm sudo.conf
! 232: as follows:
! 233: .Bd -literal -offset indent
! 234: Set disable_coredump false
! 235: .Ed
! 236: .Pp
! 237: Note that most operating systems disable core dumps from setuid programs,
! 238: including
! 239: .Nm sudo .
! 240: To actually get a
! 241: .Nm sudo
! 242: core file you will likely need to enable core dumps for setuid processes.
! 243: On BSD and Linux systems this is accomplished in the
! 244: .Xr sysctl
! 245: command.
! 246: On Solaris, the
! 247: .Xr coreadm
! 248: command is used to configure core dump behavior.
! 249: .Pp
! 250: This setting is only available in
! 251: .Nm sudo
! 252: version 1.8.4 and higher.
! 253: .It group_source
! 254: .Nm sudo
! 255: passes the invoking user's group list to the policy and I/O plugins.
! 256: On most systems, there is an upper limit to the number of groups that
! 257: a user may belong to simultaneously (typically 16 for compatibility
! 258: with NFS).
! 259: On systems with the
! 260: .Xr getconf 1
! 261: utility, running:
! 262: .Dl getconf NGROUPS_MAX
! 263: will return the maximum number of groups.
! 264: .Pp
! 265: However, it is still possible to be a member of a larger number of
! 266: groups--they simply won't be included in the group list returned
! 267: by the kernel for the user.
! 268: Starting with
! 269: .Nm sudo
! 270: version 1.8.7, if the user's kernel group list has the maximum number
! 271: of entries,
! 272: .Nm sudo
! 273: will consult the group database directly to determine the group list.
! 274: This makes it possible for the security policy to perform matching by group
! 275: name even when the user is a member of more than the maximum number of groups.
! 276: .Pp
! 277: The
! 278: .Em group_source
! 279: setting allows the administrator to change this default behavior.
! 280: Supported values for
! 281: .Em group_source
! 282: are:
! 283: .Bl -tag -width 8n
! 284: .It static
! 285: Use the static group list that the kernel returns.
! 286: Retrieving the group list this way is very fast but it is subject
! 287: to an upper limit as described above.
! 288: It is
! 289: .Dq static
! 290: in that it does not reflect changes to the group database made
! 291: after the user logs in.
! 292: This was the default behavior prior to
! 293: .Nm sudo
! 294: 1.8.7.
! 295: .It dynamic
! 296: Always query the group database directly.
! 297: It is
! 298: .Dq dynamic
! 299: in that changes made to the group database after the user logs in
! 300: will be reflected in the group list.
! 301: On some systems, querying the group database for all of a user's
! 302: groups can be time consuming when querying a network-based group
! 303: database.
! 304: Most operating systems provide an efficient method of performing
! 305: such queries.
! 306: Currently,
! 307: .Nm sudo
! 308: supports efficient group queries on AIX, BSD, HP-UX, Linux and
! 309: Solaris.
! 310: .It adaptive
! 311: Only query the group database if the static group list returned
! 312: by the kernel has the maximum number of entries.
! 313: This is the default behavior in
! 314: .Nm sudo
! 315: 1.8.7 and higher.
! 316: .El
! 317: .Pp
! 318: For example, to cause
! 319: .Nm sudo
! 320: to only use the kernel's static list of groups for the user:
! 321: .Bd -literal -offset indent
! 322: Set group_source static
! 323: .Ed
! 324: .Pp
! 325: This setting is only available in
! 326: .Nm sudo
! 327: version 1.8.7 and higher.
! 328: .It max_groups
! 329: The maximum number of user groups to retrieve from the group database.
! 330: This setting is only used when querying the group database directly.
! 331: It is intended to be used on systems where it is not possible to detect
! 332: when the array to be populated with group entries is not sufficiently large.
! 333: By default,
! 334: .Nm sudo
! 335: will allocate four times the system's maximum number of groups (see above)
! 336: and retry with double that number if the group database query fails.
! 337: However, some systems just return as many entries as will fit and
! 338: do not indicate an error when there is a lack of space.
! 339: .Pp
! 340: This setting is only available in
! 341: .Nm sudo
! 342: version 1.8.7 and higher.
! 343: .El
! 344: .Ss Debug flags
! 345: .Nm sudo
! 346: versions 1.8.4 and higher support a flexible debugging framework
! 347: that can help track down what
! 348: .Nm sudo
! 349: is doing internally if there is a problem.
! 350: .Pp
! 351: A
! 352: .Li Debug
! 353: line consists of the
! 354: .Li Debug
! 355: keyword, followed by the name of the program (or plugin) to debug
! 356: .Pq Nm sudo , Nm visudo , Nm sudoreplay , Nm sudoers ,
! 357: the debug file name and a comma-separated list of debug flags. The
! 358: debug flag syntax used by
! 359: .Nm sudo
! 360: and the
! 361: .Nm sudoers
! 362: plugin is
! 363: .Em subsystem Ns No @ Ns Em priority
! 364: but a plugin is free to use a different format so long as it does
! 365: not include a comma
! 366: .Pq Ql \&, .
! 367: .Pp
! 368: For example:
! 369: .Bd -literal -offset indent
! 370: Debug sudo /var/log/sudo_debug all@warn,plugin@info
! 371: .Ed
! 372: .Pp
! 373: would log all debugging statements at the
! 374: .Em warn
! 375: level and higher in addition to those at the
! 376: .Em info
! 377: level for the plugin subsystem.
! 378: .Pp
! 379: Currently, only one
! 380: .Li Debug
! 381: entry per program is supported. The
! 382: .Nm sudo
! 383: .Li Debug
! 384: entry is shared by the
! 385: .Nm sudo
! 386: front end,
! 387: .Nm sudoedit
! 388: and the plugins. A future release may add support for per-plugin
! 389: .Li Debug
! 390: lines and/or support for multiple debugging files for a single
! 391: program.
! 392: .Pp
! 393: The priorities used by the
! 394: .Nm sudo
! 395: front end, in order of decreasing severity, are:
! 396: .Em crit , err , warn , notice , diag , info , trace
! 397: and
! 398: .Em debug .
! 399: Each priority, when specified, also includes all priorities higher
! 400: than it. For example, a priority of
! 401: .Em notice
! 402: would include debug messages logged at
! 403: .Em notice
! 404: and higher.
! 405: .Pp
! 406: The following subsystems are used by the
! 407: .Nm sudo
! 408: front-end:
! 409: .Bl -tag -width Fl
! 410: .It Em all
! 411: matches every subsystem
! 412: .It Em args
! 413: command line argument processing
! 414: .It Em conv
! 415: user conversation
! 416: .It Em edit
! 417: sudoedit
! 418: .It Em exec
! 419: command execution
! 420: .It Em main
! 421: .Nm sudo
! 422: main function
! 423: .It Em netif
! 424: network interface handling
! 425: .It Em pcomm
! 426: communication with the plugin
! 427: .It Em plugin
! 428: plugin configuration
! 429: .It Em pty
! 430: pseudo-tty related code
! 431: .It Em selinux
! 432: SELinux-specific handling
! 433: .It Em util
! 434: utility functions
! 435: .It Em utmp
! 436: utmp handling
! 437: .El
! 438: .Pp
! 439: The
! 440: .Xr sudoers @mansectform@
! 441: plugin includes support for additional subsystems.
! 442: .Sh FILES
! 443: .Bl -tag -width 24n
! 444: .It Pa @sysconfdir@/sudo.conf
! 445: .Nm sudo
! 446: front end configuration
! 447: .El
! 448: .Sh EXAMPLES
! 449: .Bd -literal
! 450: #
! 451: # Default @sysconfdir@/sudo.conf file
! 452: #
! 453: # Format:
! 454: # Plugin plugin_name plugin_path plugin_options ...
! 455: # Path askpass /path/to/askpass
! 456: # Path noexec /path/to/sudo_noexec.so
! 457: # Debug sudo /var/log/sudo_debug all@warn
! 458: # Set disable_coredump true
! 459: #
! 460: # The plugin_path is relative to @PLUGINDIR@ unless
! 461: # fully qualified.
! 462: # The plugin_name corresponds to a global symbol in the plugin
! 463: # that contains the plugin interface structure.
! 464: # The plugin_options are optional.
! 465: #
! 466: # The sudoers plugin is used by default if no Plugin lines are
! 467: # present.
! 468: Plugin sudoers_policy sudoers.so
! 469: Plugin sudoers_io sudoers.so
! 470:
! 471: #
! 472: # Sudo askpass:
! 473: #
! 474: # An askpass helper program may be specified to provide a graphical
! 475: # password prompt for "sudo -A" support. Sudo does not ship with
! 476: # its own askpass program but can use the OpenSSH askpass.
! 477: #
! 478: # Use the OpenSSH askpass
! 479: #Path askpass /usr/X11R6/bin/ssh-askpass
! 480: #
! 481: # Use the Gnome OpenSSH askpass
! 482: #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
! 483:
! 484: #
! 485: # Sudo noexec:
! 486: #
! 487: # Path to a shared library containing dummy versions of the execv(),
! 488: # execve() and fexecve() library functions that just return an error.
! 489: # This is used to implement the "noexec" functionality on systems that
! 490: # support C<LD_PRELOAD> or its equivalent.
! 491: # The compiled-in value is usually sufficient and should only be
! 492: # changed if you rename or move the sudo_noexec.so file.
! 493: #
! 494: #Path noexec @noexec_file@
! 495:
! 496: #
! 497: # Core dumps:
! 498: #
! 499: # By default, sudo disables core dumps while it is executing
! 500: # (they are re-enabled for the command that is run).
! 501: # To aid in debugging sudo problems, you may wish to enable core
! 502: # dumps by setting "disable_coredump" to false.
! 503: #
! 504: #Set disable_coredump false
! 505:
! 506: #
! 507: # User groups:
! 508: #
! 509: # Sudo passes the user's group list to the policy plugin.
! 510: # If the user is a member of the maximum number of groups (usually 16),
! 511: # sudo will query the group database directly to be sure to include
! 512: # the full list of groups.
! 513: #
! 514: # On some systems, this can be expensive so the behavior is configurable.
! 515: # The "group_source" setting has three possible values:
! 516: # static - use the user's list of groups returned by the kernel.
! 517: # dynamic - query the group database to find the list of groups.
! 518: # adaptive - if user is in less than the maximum number of groups.
! 519: # use the kernel list, else query the group database.
! 520: #
! 521: #Set group_source static
! 522: .Ed
! 523: .Sh SEE ALSO
! 524: .Xr sudoers @mansectform@ ,
! 525: .Xr sudo @mansectsu@ ,
! 526: .Xr sudo_plugin @mansectsu@
! 527: .Sh HISTORY
! 528: See the HISTORY file in the
! 529: .Nm sudo
! 530: distribution (http://www.sudo.ws/sudo/history.html) for a brief
! 531: history of sudo.
! 532: .Sh AUTHORS
! 533: Many people have worked on
! 534: .Nm sudo
! 535: over the years; this version consists of code written primarily by:
! 536: .Bd -ragged -offset indent
! 537: Todd C. Miller
! 538: .Ed
! 539: .Pp
! 540: See the CONTRIBUTORS file in the
! 541: .Nm sudo
! 542: distribution (http://www.sudo.ws/sudo/contributors.html) for an
! 543: exhaustive list of people who have contributed to
! 544: .Nm sudo .
! 545: .Sh BUGS
! 546: If you feel you have found a bug in
! 547: .Nm sudo ,
! 548: please submit a bug report at http://www.sudo.ws/sudo/bugs/
! 549: .Sh SUPPORT
! 550: Limited free support is available via the sudo-users mailing list,
! 551: see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
! 552: search the archives.
! 553: .Sh DISCLAIMER
! 554: .Nm sudo
! 555: is provided
! 556: .Dq AS IS
! 557: and any express or implied warranties, including, but not limited
! 558: to, the implied warranties of merchantability and fitness for a
! 559: particular purpose are disclaimed.
! 560: See the LICENSE file distributed with
! 561: .Nm sudo
! 562: or http://www.sudo.ws/sudo/license.html for complete details.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>