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