manual/sudo/original/man5/sudo.conf.5

   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-2016 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.CONF" "5" "June 15, 2016" "Sudo 1.8.17" "File Formats 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 (\(oq#\(cq)
  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 (\(oq\e\(cq)
  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 \(Lq\fRC\fR\(Rq
  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 dynamic shared object that contains 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 symbol contained in the plugin.
 111 The
 112 \fIpath\fR
 113 may be fully qualified or relative.
 114 If not fully qualified, it is relative to the directory
 115 specified by the
 116 \fIplugin_dir\fR
 117 \fRPath\fR
 118 setting, which defaults to
 119 \fI/usr/local/libexec/sudo\fR.
 120 In other words:
 121 .nf
 122 .sp
 123 .RS 6n
 124 Plugin sudoers_policy sudoers.so
 125 .RE
 126 .fi
 127 .PP
 128 is equivalent to:
 129 .nf
 130 .sp
 131 .RS 6n
 132 Plugin sudoers_policy /usr/local/libexec/sudo/sudoers.so
 133 .RE
 134 .fi
 135 .PP
 136 If the plugin was compiled statically into the
 137 \fBsudo\fR
 138 binary instead of being installed as a dynamic shared object, the
 139 \fIpath\fR
 140 should be specified without a leading directory,
 141 as it does not actually exist in the file system.
 142 For example:
 143 .nf
 144 .sp
 145 .RS 6n
 146 Plugin sudoers_policy sudoers.so
 147 .RE
 148 .fi
 149 .PP
 150 Starting with
 151 \fBsudo\fR
 152 1.8.5, any additional parameters after the
 153 \fIpath\fR
 154 are passed as arguments to the plugin's
 155 \fIopen\fR
 156 function.
 157 For example, to override the compile-time default sudoers file mode:
 158 .nf
 159 .sp
 160 .RS 6n
 161 Plugin sudoers_policy sudoers.so sudoers_mode=0440
 162 .RE
 163 .fi
 164 .PP
 165 See the
 166 sudoers(5)
 167 manual for a list of supported arguments.
 168 .PP
 169 The same dynamic shared object may contain multiple plugins,
 170 each with a different symbol name.
 171 The file must be owned by uid 0 and only writable by its owner.
 172 Because of ambiguities that arise from composite policies, only a single
 173 policy plugin may be specified.
 174 This limitation does not apply to I/O plugins.
 175 .PP
 176 If no
 177 \fBsudo.conf\fR
 178 file is present, or if it contains no
 179 \fRPlugin\fR
 180 lines, the
 181 \fBsudoers\fR
 182 plugin will be used as the default security policy and for I/O logging
 183 (if enabled by the policy).
 184 This is equivalent to the following:
 185 .nf
 186 .sp
 187 .RS 6n
 188 Plugin sudoers_policy sudoers.so
 189 Plugin sudoers_io sudoers.so
 190 .RE
 191 .fi
 192 .PP
 193 For more information on the
 194 \fBsudo\fR
 195 plugin architecture, see the
 196 sudo_plugin(8)
 197 manual.
 198 .SS "Path settings"
 199 A
 200 \fRPath\fR
 201 line consists of the
 202 \fRPath\fR
 203 keyword, followed by the name of the path to set and its value.
 204 For example:
 205 .nf
 206 .sp
 207 .RS 6n
 208 Path noexec /usr/local/libexec/sudo/sudo_noexec.so
 209 Path askpass /usr/X11R6/bin/ssh-askpass
 210 .RE
 211 .fi
 212 .PP
 213 If no path name is specified, features relying on the specified
 214 setting will be disabled.
 215 Disabling
 216 \fRPath\fR
 217 settings is only supported in
 218 \fBsudo\fR
 219 version 1.8.16 and higher.
 220 .PP
 221 The following plugin-agnostic paths may be set in the
 222 \fI/etc/sudo.conf\fR
 223 file:
 224 .TP 10n
 225 askpass
 226 The fully qualified path to a helper program used to read the user's
 227 password when no terminal is available.
 228 This may be the case when
 229 \fBsudo\fR
 230 is executed from a graphical (as opposed to text-based) application.
 231 The program specified by
 232 \fIaskpass\fR
 233 should display the argument passed to it as the prompt and write
 234 the user's password to the standard output.
 235 The value of
 236 \fIaskpass\fR
 237 may be overridden by the
 238 \fRSUDO_ASKPASS\fR
 239 environment variable.
 240 .TP 10n
 241 noexec
 242 The fully-qualified path to a shared library containing dummy
 243 versions of the
 244 \fBexecl\fR(),
 245 \fBexecle\fR(),
 246 \fBexeclp\fR(),
 247 \fBexect\fR(),
 248 \fBexecv\fR(),
 249 \fBexecve\fR(),
 250 \fBexecvP\fR(),
 251 \fBexecvp\fR(),
 252 \fBexecvpe\fR(),
 253 \fBfexecve\fR(),
 254 \fBpopen\fR(),
 255 \fBposix_spawn\fR(),
 256 \fBposix_spawnp\fR(),
 257 and
 258 \fBsystem\fR()
 259 library functions that just return an error.
 260 This is used to implement the
 261 \fInoexec\fR
 262 functionality on systems that support
 263 \fRLD_PRELOAD\fR
 264 or its equivalent.
 265 The default value is:
 266 \fI/usr/local/libexec/sudo/sudo_noexec.so\fR.
 267 .TP 10n
 268 plugin_dir
 269 The default directory to use when searching for plugins
 270 that are specified without a fully qualified path name.
 271 The default value is
 272 \fI/usr/local/libexec/sudo\fR.
 273 .TP 10n
 274 sesh
 275 The fully-qualified path to the
 276 \fBsesh\fR
 277 binary.
 278 This setting is only used when
 279 \fBsudo\fR
 280 is built with SELinux support.
 281 The default value is
 282 \fI/usr/local/libexec/sudo/sesh\fR.
 283 .SS "Other settings"
 284 The
 285 \fBsudo.conf\fR
 286 file also supports the following front end settings:
 287 .TP 10n
 288 disable_coredump
 289 Core dumps of
 290 \fBsudo\fR
 291 itself are disabled by default to prevent the disclosure of potentially
 292 sensitive information.
 293 To aid in debugging
 294 \fBsudo\fR
 295 crashes, you may wish to re-enable core dumps by setting
 296 \(Lqdisable_coredump\(Rq
 297 to false in
 298 \fBsudo.conf\fR
 299 as follows:
 300 .nf
 301 .sp
 302 .RS 16n
 303 Set disable_coredump false
 304 .RE
 305 .fi
 306 .RS 10n
 307 .sp
 308 All modern operating systems place restrictions on core dumps
 309 from setuid processes like
 310 \fBsudo\fR
 311 so this option can be enabled without compromising security.
 312 To actually get a
 313 \fBsudo\fR
 314 core file you will likely need to enable core dumps for setuid processes.
 315 On BSD and Linux systems this is accomplished in the
 316 sysctl
 317 command.
 318 On Solaris, the
 319 coreadm
 320 command is used to configure core dump behavior.
 321 .sp
 322 This setting is only available in
 323 \fBsudo\fR
 324 version 1.8.4 and higher.
 325 .RE
 326 .TP 10n
 327 group_source
 328 \fBsudo\fR
 329 passes the invoking user's group list to the policy and I/O plugins.
 330 On most systems, there is an upper limit to the number of groups that
 331 a user may belong to simultaneously (typically 16 for compatibility
 332 with NFS).
 333 On systems with the
 334 getconf(1)
 335 utility, running:
 336 .RS 16n
 337 getconf NGROUPS_MAX
 338 .RE
 339 .RS 10n
 340 will return the maximum number of groups.
 341 .sp
 342 However, it is still possible to be a member of a larger number of
 343 groups--they simply won't be included in the group list returned
 344 by the kernel for the user.
 345 Starting with
 346 \fBsudo\fR
 347 version 1.8.7, if the user's kernel group list has the maximum number
 348 of entries,
 349 \fBsudo\fR
 350 will consult the group database directly to determine the group list.
 351 This makes it possible for the security policy to perform matching by group
 352 name even when the user is a member of more than the maximum number of groups.
 353 .sp
 354 The
 355 \fIgroup_source\fR
 356 setting allows the administrator to change this default behavior.
 357 Supported values for
 358 \fIgroup_source\fR
 359 are:
 360 .TP 10n
 361 static
 362 Use the static group list that the kernel returns.
 363 Retrieving the group list this way is very fast but it is subject
 364 to an upper limit as described above.
 365 It is
 366 \(Lqstatic\(Rq
 367 in that it does not reflect changes to the group database made
 368 after the user logs in.
 369 This was the default behavior prior to
 370 \fBsudo\fR
 371 1.8.7.
 372 .TP 10n
 373 dynamic
 374 Always query the group database directly.
 375 It is
 376 \(Lqdynamic\(Rq
 377 in that changes made to the group database after the user logs in
 378 will be reflected in the group list.
 379 On some systems, querying the group database for all of a user's
 380 groups can be time consuming when querying a network-based group
 381 database.
 382 Most operating systems provide an efficient method of performing
 383 such queries.
 384 Currently,
 385 \fBsudo\fR
 386 supports efficient group queries on AIX, BSD, HP-UX, Linux and
 387 Solaris.
 388 .TP 10n
 389 adaptive
 390 Only query the group database if the static group list returned
 391 by the kernel has the maximum number of entries.
 392 This is the default behavior in
 393 \fBsudo\fR
 394 1.8.7 and higher.
 395 .PP
 396 For example, to cause
 397 \fBsudo\fR
 398 to only use the kernel's static list of groups for the user:
 399 .nf
 400 .sp
 401 .RS 16n
 402 Set group_source static
 403 .RE
 404 .fi
 405 .sp
 406 This setting is only available in
 407 \fBsudo\fR
 408 version 1.8.7 and higher.
 409 .RE
 410 .TP 10n
 411 max_groups
 412 The maximum number of user groups to retrieve from the group database.
 413 Values less than one will be ignored.
 414 This setting is only used when querying the group database directly.
 415 It is intended to be used on systems where it is not possible to detect
 416 when the array to be populated with group entries is not sufficiently large.
 417 By default,
 418 \fBsudo\fR
 419 will allocate four times the system's maximum number of groups (see above)
 420 and retry with double that number if the group database query fails.
 421 However, some systems just return as many entries as will fit and
 422 do not indicate an error when there is a lack of space.
 423 .sp
 424 This setting is only available in
 425 \fBsudo\fR
 426 version 1.8.7 and higher.
 427 .TP 10n
 428 probe_interfaces
 429 By default,
 430 \fBsudo\fR
 431 will probe the system's network interfaces and pass the IP address
 432 of each enabled interface to the policy plugin.  This makes it
 433 possible for the plugin to match rules based on the IP address
 434 without having to query DNS.  On Linux systems with a large number
 435 of virtual interfaces, this may take a non-negligible amount of time.
 436 If IP-based matching is not required, network interface probing
 437 can be disabled as follows:
 438 .nf
 439 .sp
 440 .RS 16n
 441 Set probe_interfaces false
 442 .RE
 443 .fi
 444 .RS 10n
 445 .sp
 446 This setting is only available in
 447 \fBsudo\fR
 448 version 1.8.10 and higher.
 449 .RE
 450 .SS "Debug flags"
 451 \fBsudo\fR
 452 versions 1.8.4 and higher support a flexible debugging framework
 453 that can help track down what
 454 \fBsudo\fR
 455 is doing internally if there is a problem.
 456 .PP
 457 A
 458 \fRDebug\fR
 459 line consists of the
 460 \fRDebug\fR
 461 keyword, followed by the name of the program (or plugin) to debug
 462 (\fBsudo\fR, \fBvisudo\fR, \fBsudoreplay\fR, \fBsudoers\fR),
 463 the debug file name and a comma-separated list of debug flags.  The
 464 debug flag syntax used by
 465 \fBsudo\fR
 466 and the
 467 \fBsudoers\fR
 468 plugin is
 469 \fIsubsystem\fR@\fIpriority\fR
 470 but a plugin is free to use a different format so long as it does
 471 not include a comma
 472 (\(oq\&,\(cq).
 473 .PP
 474 For example:
 475 .nf
 476 .sp
 477 .RS 6n
 478 Debug sudo /var/log/sudo_debug all@warn,plugin@info
 479 .RE
 480 .fi
 481 .PP
 482 would log all debugging statements at the
 483 \fIwarn\fR
 484 level and higher in addition to those at the
 485 \fIinfo\fR
 486 level for the plugin subsystem.
 487 .PP
 488 As of
 489 \fBsudo\fR
 490 1.8.12, multiple
 491 \fRDebug\fR
 492 entries may be specified per program.
 493 Older versions of
 494 \fBsudo\fR
 495 only support a single
 496 \fRDebug\fR
 497 entry per program.
 498 Plugin-specific
 499 \fRDebug\fR
 500 entries are also supported starting with
 501 \fBsudo\fR
 502 1.8.12 and are matched by either the base name of the plugin that was loaded
 503 (for example
 504 \fRsudoers.so\fR)
 505 or by the plugin's fully-qualified path name.
 506 Previously, the
 507 \fBsudoers\fR
 508 plugin shared the same
 509 \fRDebug\fR
 510 entry as the
 511 \fBsudo\fR
 512 front end and could not be configured separately.
 513 .PP
 514 The following priorities are supported, in order of decreasing severity:
 515 \fIcrit\fR, \fIerr\fR, \fIwarn\fR, \fInotice\fR, \fIdiag\fR, \fIinfo\fR, \fItrace\fR
 516 and
 517 \fIdebug\fR.
 518 Each priority, when specified, also includes all priorities higher
 519 than it.  For example, a priority of
 520 \fInotice\fR
 521 would include debug messages logged at
 522 \fInotice\fR
 523 and higher.
 524 .PP
 525 The priorities
 526 \fItrace\fR
 527 and
 528 \fIdebug\fR
 529 also include function call tracing which logs when a function is
 530 entered and when it returns.
 531 For example, the following trace is for the get_user_groups()
 532 function located in src/sudo.c:
 533 .nf
 534 .sp
 535 .RS 6n
 536 sudo[123] -> get_user_groups @ src/sudo.c:385
 537 sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5
 538 .RE
 539 .fi
 540 .PP
 541 When the function is entered, indicated by a right arrow
 542 \(oq->\(cq,
 543 the program, process ID, function, source file and line number
 544 are logged.
 545 When the function returns, indicated by a left arrow
 546 \(oq<-\(cq,
 547 the same information is logged along with the return value.
 548 In this case, the return value is a string.
 549 .PP
 550 The following subsystems are used by the
 551 \fBsudo\fR
 552 front-end:
 553 .TP 12n
 554 \fIall\fR
 555 matches every subsystem
 556 .TP 12n
 557 \fIargs\fR
 558 command line argument processing
 559 .TP 12n
 560 \fIconv\fR
 561 user conversation
 562 .TP 12n
 563 \fIedit\fR
 564 sudoedit
 565 .TP 12n
 566 \fIevent\fR
 567 event subsystem
 568 .TP 12n
 569 \fIexec\fR
 570 command execution
 571 .TP 12n
 572 \fImain\fR
 573 \fBsudo\fR
 574 main function
 575 .TP 12n
 576 \fInetif\fR
 577 network interface handling
 578 .TP 12n
 579 \fIpcomm\fR
 580 communication with the plugin
 581 .TP 12n
 582 \fIplugin\fR
 583 plugin configuration
 584 .TP 12n
 585 \fIpty\fR
 586 pseudo-tty related code
 587 .TP 12n
 588 \fIselinux\fR
 589 SELinux-specific handling
 590 .TP 12n
 591 \fIutil\fR
 592 utility functions
 593 .TP 12n
 594 \fIutmp\fR
 595 utmp handling
 596 .PP
 597 The
 598 sudoers(5)
 599 plugin includes support for additional subsystems.
 600 .SH "FILES"
 601 .TP 26n
 602 \fI/etc/sudo.conf\fR
 603 \fBsudo\fR
 604 front end configuration
 605 .SH "EXAMPLES"
 606 .nf
 607 .RS 0n
 608 #
 609 # Default /etc/sudo.conf file
 610 #
 611 # Format:
 612 #   Plugin plugin_name plugin_path plugin_options ...
 613 #   Path askpass /path/to/askpass
 614 #   Path noexec /path/to/sudo_noexec.so
 615 #   Debug sudo /var/log/sudo_debug all@warn
 616 #   Set disable_coredump true
 617 #
 618 # The plugin_path is relative to /usr/local/libexec/sudo unless
 619 #   fully qualified.
 620 # The plugin_name corresponds to a global symbol in the plugin
 621 #   that contains the plugin interface structure.
 622 # The plugin_options are optional.
 623 #
 624 # The sudoers plugin is used by default if no Plugin lines are
 625 # present.
 626 Plugin sudoers_policy sudoers.so
 627 Plugin sudoers_io sudoers.so
 628
 629 #
 630 # Sudo askpass:
 631 #
 632 # An askpass helper program may be specified to provide a graphical
 633 # password prompt for "sudo -A" support.  Sudo does not ship with
 634 # its own askpass program but can use the OpenSSH askpass.
 635 #
 636 # Use the OpenSSH askpass
 637 #Path askpass /usr/X11R6/bin/ssh-askpass
 638 #
 639 # Use the Gnome OpenSSH askpass
 640 #Path askpass /usr/libexec/openssh/gnome-ssh-askpass
 641
 642 #
 643 # Sudo noexec:
 644 #
 645 # Path to a shared library containing dummy versions of the execv(),
 646 # execve() and fexecve() library functions that just return an error.
 647 # This is used to implement the "noexec" functionality on systems that
 648 # support C<LD_PRELOAD> or its equivalent.
 649 # The compiled-in value is usually sufficient and should only be
 650 # changed if you rename or move the sudo_noexec.so file.
 651 #
 652 #Path noexec /usr/local/libexec/sudo/sudo_noexec.so
 653
 654 #
 655 # Core dumps:
 656 #
 657 # By default, sudo disables core dumps while it is executing
 658 # (they are re-enabled for the command that is run).
 659 # To aid in debugging sudo problems, you may wish to enable core
 660 # dumps by setting "disable_coredump" to false.
 661 #
 662 #Set disable_coredump false
 663
 664 #
 665 # User groups:
 666 #
 667 # Sudo passes the user's group list to the policy plugin.
 668 # If the user is a member of the maximum number of groups (usually 16),
 669 # sudo will query the group database directly to be sure to include
 670 # the full list of groups.
 671 #
 672 # On some systems, this can be expensive so the behavior is configurable.
 673 # The "group_source" setting has three possible values:
 674 #   static   - use the user's list of groups returned by the kernel.
 675 #   dynamic  - query the group database to find the list of groups.
 676 #   adaptive - if user is in less than the maximum number of groups.
 677 #              use the kernel list, else query the group database.
 678 #
 679 #Set group_source static
 680 .RE
 681 .fi
 682 .SH "SEE ALSO"
 683 sudoers(5),
 684 sudo(8),
 685 sudo_plugin(8)
 686 .SH "HISTORY"
 687 See the HISTORY file in the
 688 \fBsudo\fR
 689 distribution (https://www.sudo.ws/history.html) for a brief
 690 history of sudo.
 691 .SH "AUTHORS"
 692 Many people have worked on
 693 \fBsudo\fR
 694 over the years; this version consists of code written primarily by:
 695 .sp
 696 .RS 6n
 697 Todd C. Miller
 698 .RE
 699 .PP
 700 See the CONTRIBUTORS file in the
 701 \fBsudo\fR
 702 distribution (https://www.sudo.ws/contributors.html) for an
 703 exhaustive list of people who have contributed to
 704 \fBsudo\fR.
 705 .SH "BUGS"
 706 If you feel you have found a bug in
 707 \fBsudo\fR,
 708 please submit a bug report at https://bugzilla.sudo.ws/
 709 .SH "SUPPORT"
 710 Limited free support is available via the sudo-users mailing list,
 711 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 712 search the archives.
 713 .SH "DISCLAIMER"
 714 \fBsudo\fR
 715 is provided
 716 \(LqAS IS\(Rq
 717 and any express or implied warranties, including, but not limited
 718 to, the implied warranties of merchantability and fitness for a
 719 particular purpose are disclaimed.
 720 See the LICENSE file distributed with
 721 \fBsudo\fR
 722 or https://www.sudo.ws/license.html for complete details.