git.gag.com Git - debian/sudo/blob - doc/sudoers.ldap.mdoc.in

   1 .\"
   2 .\" Copyright (c) 2003-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 April 25, 2013
  18 .Dt SUDOERS.LDAP @mansectsu@
  19 .Os Sudo @PACKAGE_VERSION@
  20 .Sh NAME
  21 .Nm sudoers.ldap
  22 .Nd sudo LDAP configuration
  23 .Sh DESCRIPTION
  24 In addition to the standard
  25 .Em sudoers
  26 file,
  27 .Nm sudo
  28 may be configured
  29 via LDAP.
  30 This can be especially useful for synchronizing
  31 .Em sudoers
  32 in a large, distributed environment.
  33 .Pp
  34 Using LDAP for
  35 .Em sudoers
  36 has several benefits:
  37 .Bl -bullet
  38 .It
  39 .Nm sudo
  40 no longer needs to read
  41 .Em sudoers
  42 in its entirety.
  43 When LDAP is used, there are only two or three LDAP queries per invocation.
  44 This makes it especially fast and particularly usable in LDAP environments.
  45 .It
  46 .Nm sudo
  47 no longer exits if there is a typo in
  48 .Em sudoers .
  49 It is not possible to load LDAP data into the server that does
  50 not conform to the sudoers schema, so proper syntax is guaranteed.
  51 It is still possible to have typos in a user or host name, but
  52 this will not prevent
  53 .Nm sudo
  54 from running.
  55 .It
  56 It is possible to specify per-entry options that override the global
  57 default options.
  58 .Pa @sysconfdir@/sudoers
  59 only supports default options and limited options associated with
  60 user/host/commands/aliases.
  61 The syntax is complicated and can be difficult for users to understand.
  62 Placing the options directly in the entry is more natural.
  63 .It
  64 The
  65 .Nm visudo
  66 program is no longer needed.
  67 .Nm visudo
  68 provides locking and syntax checking of the
  69 .Pa @sysconfdir@/sudoers
  70 file.
  71 Since LDAP updates are atomic, locking is no longer necessary.
  72 Because syntax is checked when the data is inserted into LDAP, there
  73 is no need for a specialized tool to check syntax.
  74 .El
  75 .Pp
  76 Another major difference between LDAP and file-based
  77 .Em sudoers
  78 is that in LDAP,
  79 .Nm sudo Ns No -specific
  80 Aliases are not supported.
  81 .Pp
  82 For the most part, there is really no need for
  83 .Nm sudo Ns No -specific
  84 Aliases.
  85 Unix groups, non-Unix groups (via the
  86 .Em group_plugin )
  87 or user netgroups can be used in place of User_Aliases and Runas_Aliases.
  88 Host netgroups can be used in place of Host_Aliases.
  89 Since groups and netgroups can also be stored in LDAP there is no real need for
  90 .Nm sudo Ns No -specific
  91 aliases.
  92 .Pp
  93 Cmnd_Aliases are not really required either since it is possible
  94 to have multiple users listed in a
  95 .Li sudoRole .
  96 Instead of defining a Cmnd_Alias that is referenced by multiple users,
  97 one can create a
  98 .Li sudoRole
  99 that contains the commands and assign multiple users to it.
 100 .Ss SUDOers LDAP container
 101 The
 102 .Em sudoers
 103 configuration is contained in the
 104 .Li ou=SUDOers
 105 LDAP container.
 106 .Pp
 107 Sudo first looks for the
 108 .Li cn=default
 109 entry in the SUDOers container.
 110 If found, the multi-valued
 111 .Li sudoOption
 112 attribute is parsed in the same manner as a global
 113 .Li Defaults
 114 line in
 115 .Pa @sysconfdir@/sudoers .
 116 In the following example, the
 117 .Ev SSH_AUTH_SOCK
 118 variable will be preserved in the environment for all users.
 119 .Bd -literal -offset 4n
 120 dn: cn=defaults,ou=SUDOers,dc=example,dc=com
 121 objectClass: top
 122 objectClass: sudoRole
 123 cn: defaults
 124 description: Default sudoOption's go here
 125 sudoOption: env_keep+=SSH_AUTH_SOCK
 126 .Ed
 127 .Pp
 128 The equivalent of a sudoer in LDAP is a
 129 .Li sudoRole .
 130 It consists of the following attributes:
 131 .Bl -tag -width 4n
 132 .It Sy sudoUser
 133 A user name, user ID (prefixed with
 134 .Ql # ) ,
 135 Unix group name or ID (prefixed with
 136 .Ql %
 137 or
 138 .Ql %#
 139 respectively), user netgroup (prefixed with
 140 .Ql + ) ,
 141 or non-Unix group name or ID (prefixed with
 142 .Ql %:
 143 or
 144 .Ql %:#
 145 respectively).
 146 Non-Unix group support is only available when an appropriate
 147 .Em group_plugin
 148 is defined in the global
 149 .Em defaults
 150 .Li sudoRole
 151 object.
 152 .It Sy sudoHost
 153 A host name, IP address, IP network, or host netgroup (prefixed with a
 154 .Ql + ) .
 155 The special value
 156 .Li ALL
 157 will match any host.
 158 .It Sy sudoCommand
 159 A fully-qualified Unix command name with optional command line arguments,
 160 potentially including globbing characters (aka wild cards).
 161 If a command name is preceded by an exclamation point,
 162 .Ql \&! ,
 163 the user will be prohibited from running that command.
 164 .Pp
 165 The built-in command
 166 .Dq Li sudoedit
 167 is used to permit a user to run
 168 .Nm sudo
 169 with the
 170 .Fl e
 171 option (or as
 172 .Nm sudoedit ) .
 173 It may take command line arguments just as a normal command does.
 174 Note that
 175 .Dq Li sudoedit
 176 is a command built into
 177 .Nm sudo
 178 itself and must be specified in without a leading path.
 179 .Pp
 180 The special value
 181 .Li ALL
 182 will match any command.
 183 .Pp
 184 If a command name is prefixed with a SHA-2 digest, it will
 185 only be allowed if the digest matches.
 186 This may be useful in situations where the user invoking
 187 .Nm sudo
 188 has write access to the command or its parent directory.
 189 The following digest formats are supported: sha224, sha256, sha384 and sha512.
 190 The digest name must be followed by a colon
 191 .Pq Ql :\&
 192 and then the actual digest, in either hex or base64 format.
 193 For example, given the following value for sudoCommand:
 194 .Bd -literal -offset 4n
 195 sha224:0GomF8mNN3wlDt1HD9XldjJ3SNgpFdbjO1+NsQ /bin/ls
 196 .Ed
 197 .Pp
 198 The user may only run
 199 .Pa /bin/ls
 200 if its sha224 digest matches the specified value.
 201 Command digests are only supported by version 1.8.7 or higher.
 202 .It Sy sudoOption
 203 Identical in function to the global options described above, but
 204 specific to the
 205 .Li sudoRole
 206 in which it resides.
 207 .It Sy sudoRunAsUser
 208 A user name or uid (prefixed with
 209 .Ql # )
 210 that commands may be run as or a Unix group (prefixed with a
 211 .Ql % )
 212 or user netgroup (prefixed with a
 213 .Ql + )
 214 that contains a list of users that commands may be run as.
 215 The special value
 216 .Li ALL
 217 will match any user.
 218 .Pp
 219 The
 220 .Li sudoRunAsUser
 221 attribute is only available in
 222 .Nm sudo
 223 versions
 224 1.7.0 and higher.
 225 Older versions of
 226 .Nm sudo
 227 use the
 228 .Li sudoRunAs
 229 attribute instead.
 230 .It Sy sudoRunAsGroup
 231 A Unix group or gid (prefixed with
 232 .Ql # )
 233 that commands may be run as.
 234 The special value
 235 .Li ALL
 236 will match any group.
 237 .Pp
 238 The
 239 .Li sudoRunAsGroup
 240 attribute is only available in
 241 .Nm sudo
 242 versions
 243 1.7.0 and higher.
 244 .It Sy sudoNotBefore
 245 A timestamp in the form
 246 .Li yyyymmddHHMMSSZ
 247 that can be used to provide a start date/time for when the
 248 .Li sudoRole
 249 will be valid.
 250 If multiple
 251 .Li sudoNotBefore
 252 entries are present, the earliest is used.
 253 Note that timestamps must be in Coordinated Universal Time (UTC),
 254 not the local timezone.
 255 The minute and seconds portions are optional, but some LDAP servers
 256 require that they be present (contrary to the RFC).
 257 .Pp
 258 The
 259 .Li sudoNotBefore
 260 attribute is only available in
 261 .Nm sudo
 262 versions 1.7.5 and higher and must be explicitly enabled via the
 263 .Sy SUDOERS_TIMED
 264 option in
 265 .Pa @ldap_conf@ .
 266 .It Sy sudoNotAfter
 267 A timestamp in the form
 268 .Li yyyymmddHHMMSSZ
 269 that indicates an expiration date/time, after which the
 270 .Li sudoRole
 271 will no longer be valid.
 272 If multiple
 273 .Li sudoNotBefore
 274 entries are present, the last one is used.
 275 Note that timestamps must be in Coordinated Universal Time (UTC),
 276 not the local timezone.
 277 The minute and seconds portions are optional, but some LDAP servers
 278 require that they be present (contrary to the RFC).
 279 .Pp
 280 The
 281 .Li sudoNotAfter
 282 attribute is only available in
 283 .Nm sudo
 284 versions
 285 1.7.5 and higher and must be explicitly enabled via the
 286 .Sy SUDOERS_TIMED
 287 option in
 288 .Pa @ldap_conf@ .
 289 .It Sy sudoOrder
 290 The
 291 .Li sudoRole
 292 entries retrieved from the LDAP directory have no inherent order.
 293 The
 294 .Li sudoOrder
 295 attribute is an integer (or floating point value for LDAP servers
 296 that support it) that is used to sort the matching entries.
 297 This allows LDAP-based sudoers entries to more closely mimic the behavior
 298 of the sudoers file, where the of the entries influences the result.
 299 If multiple entries match, the entry with the highest
 300 .Li sudoOrder
 301 attribute is chosen.
 302 This corresponds to the
 303 .Dq last match
 304 behavior of the sudoers file.
 305 If the
 306 .Li sudoOrder
 307 attribute is not present, a value of 0 is assumed.
 308 .Pp
 309 The
 310 .Li sudoOrder
 311 attribute is only available in
 312 .Nm sudo
 313 versions 1.7.5 and higher.
 314 .El
 315 .Pp
 316 Each attribute listed above should contain a single value, but there
 317 may be multiple instances of each attribute type.
 318 A
 319 .Li sudoRole
 320 must contain at least one
 321 .Li sudoUser ,
 322 .Li sudoHost
 323 and
 324 .Li sudoCommand .
 325 .Pp
 326 The following example allows users in group wheel to run any command
 327 on any host via
 328 .Nm sudo :
 329 .Bd -literal -offset 4n
 330 dn: cn=%wheel,ou=SUDOers,dc=example,dc=com
 331 objectClass: top
 332 objectClass: sudoRole
 333 cn: %wheel
 334 sudoUser: %wheel
 335 sudoHost: ALL
 336 sudoCommand: ALL
 337 .Ed
 338 .Ss Anatomy of LDAP sudoers lookup
 339 When looking up a sudoer using LDAP there are only two or three
 340 LDAP queries per invocation.
 341 The first query is to parse the global options.
 342 The second is to match against the user's name and the groups that
 343 the user belongs to.
 344 (The special
 345 .Li ALL
 346 tag is matched in this query too.)
 347 If no match is returned for the user's name and groups, a third
 348 query returns all entries containing user netgroups and checks
 349 to see if the user belongs to any of them.
 350 .Pp
 351 If timed entries are enabled with the
 352 .Sy SUDOERS_TIMED
 353 configuration directive, the LDAP queries include a sub-filter that
 354 limits retrieval to entries that satisfy the time constraints, if any.
 355 .Ss Differences between LDAP and non-LDAP sudoers
 356 There are some subtle differences in the way sudoers is handled
 357 once in LDAP.
 358 Probably the biggest is that according to the RFC, LDAP ordering
 359 is arbitrary and you cannot expect that Attributes and Entries are
 360 returned in any specific order.
 361 .Pp
 362 The order in which different entries are applied can be controlled
 363 using the
 364 .Li sudoOrder
 365 attribute, but there is no way to guarantee the order of attributes
 366 within a specific entry.
 367 If there are conflicting command rules in an entry, the negative
 368 takes precedence.
 369 This is called paranoid behavior (not necessarily the most specific
 370 match).
 371 .Pp
 372 Here is an example:
 373 .Bd -literal -offset 4n
 374 # /etc/sudoers:
 375 # Allow all commands except shell
 376 johnny  ALL=(root) ALL,!/bin/sh
 377 # Always allows all commands because ALL is matched last
 378 puddles ALL=(root) !/bin/sh,ALL
 379
 380 # LDAP equivalent of johnny
 381 # Allows all commands except shell
 382 dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com
 383 objectClass: sudoRole
 384 objectClass: top
 385 cn: role1
 386 sudoUser: johnny
 387 sudoHost: ALL
 388 sudoCommand: ALL
 389 sudoCommand: !/bin/sh
 390
 391 # LDAP equivalent of puddles
 392 # Notice that even though ALL comes last, it still behaves like
 393 # role1 since the LDAP code assumes the more paranoid configuration
 394 dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com
 395 objectClass: sudoRole
 396 objectClass: top
 397 cn: role2
 398 sudoUser: puddles
 399 sudoHost: ALL
 400 sudoCommand: !/bin/sh
 401 sudoCommand: ALL
 402 .Ed
 403 .Pp
 404 Another difference is that negations on the Host, User or Runas are
 405 currently ignored.
 406 For example, the following attributes do not behave the way one might expect.
 407 .Bd -literal -offset 4n
 408 # does not match all but joe
 409 # rather, does not match anyone
 410 sudoUser: !joe
 411
 412 # does not match all but joe
 413 # rather, matches everyone including Joe
 414 sudoUser: ALL
 415 sudoUser: !joe
 416
 417 # does not match all but web01
 418 # rather, matches all hosts including web01
 419 sudoHost: ALL
 420 sudoHost: !web01
 421 .Ed
 422 .Ss Sudoers schema
 423 In order to use
 424 .Nm sudo Ns No 's
 425 LDAP support, the
 426 .Nm sudo
 427 schema must be
 428 installed on your LDAP server.
 429 In addition, be sure to index the
 430 .Li sudoUser
 431 attribute.
 432 .Pp
 433 Three versions of the schema: one for OpenLDAP servers
 434 .Pq Pa schema.OpenLDAP ,
 435 one for Netscape-derived servers
 436 .Pq Pa schema.iPlanet ,
 437 and one for Microsoft Active Directory
 438 .Pq Pa schema.ActiveDirectory
 439 may be found in the
 440 .Nm sudo
 441 distribution.
 442 .Pp
 443 The schema for
 444 .Nm sudo
 445 in OpenLDAP form is also included in the
 446 .Sx EXAMPLES
 447 section.
 448 .Ss Configuring ldap.conf
 449 Sudo reads the
 450 .Pa @ldap_conf@
 451 file for LDAP-specific configuration.
 452 Typically, this file is shared between different LDAP-aware clients.
 453 As such, most of the settings are not
 454 .Nm sudo Ns No -specific.
 455 Note that
 456 .Nm sudo
 457 parses
 458 .Pa @ldap_conf@
 459 itself and may support options that differ from those described in the
 460 system's
 461 .Xr ldap.conf @mansectsu@
 462 manual.
 463 The path to
 464 .Pa ldap.conf
 465 may be overridden via the
 466 .Em ldap_conf
 467 plugin argument in
 468 .Xr sudo.conf @mansectform@ .
 469 .Pp
 470 Also note that on systems using the OpenLDAP libraries, default
 471 values specified in
 472 .Pa /etc/openldap/ldap.conf
 473 or the user's
 474 .Pa .ldaprc
 475 files are not used.
 476 .Pp
 477 Only those options explicitly listed in
 478 .Pa @ldap_conf@
 479 as being supported by
 480 .Nm sudo
 481 are honored.
 482 Configuration options are listed below in upper case but are parsed
 483 in a case-independent manner.
 484 .Pp
 485 Long lines can be continued with a backslash
 486 .Pq Ql \e
 487 as the last character on the line.
 488 Note that leading white space is removed from the beginning of lines
 489 even when the continuation character is used.
 490 .Bl -tag -width 4n
 491 .It Sy URI Ar ldap[s]://[hostname[:port]] ...
 492 Specifies a white space-delimited list of one or more URIs describing
 493 the LDAP server(s) to connect to.
 494 The
 495 .Em protocol
 496 may be either
 497 .Em ldap
 498 .Em ldaps ,
 499 the latter being for servers that support TLS (SSL) encryption.
 500 If no
 501 .Em port
 502 is specified, the default is port 389 for
 503 .Li ldap://
 504 or port 636 for
 505 .Li ldaps:// .
 506 If no
 507 .Em hostname
 508 is specified,
 509 .Nm sudo
 510 will connect to
 511 .Em localhost .
 512 Multiple
 513 .Sy URI
 514 lines are treated identically to a
 515 .Sy URI
 516 line containing multiple entries.
 517 Only systems using the OpenSSL libraries support the mixing of
 518 .Li ldap://
 519 and
 520 .Li ldaps://
 521 URIs.
 522 Both the Netscape-derived and Tivoli LDAP libraries used on most commercial
 523 versions of Unix are only capable of supporting one or the other.
 524 .It Sy HOST Ar name[:port] ...
 525 If no
 526 .Sy URI
 527 is specified, the
 528 .Sy HOST
 529 parameter specifies a white space-delimited list of LDAP servers to connect to.
 530 Each host may include an optional
 531 .Em port
 532 separated by a colon
 533 .Pq Ql :\& .
 534 The
 535 .Sy HOST
 536 parameter is deprecated in favor of the
 537 .Sy URI
 538 specification and is included for backwards compatibility.
 539 .It Sy PORT Ar port_number
 540 If no
 541 .Sy URI
 542 is specified, the
 543 .Sy PORT
 544 parameter specifies the default port to connect to on the LDAP server if a
 545 .Sy HOST
 546 parameter does not specify the port itself.
 547 If no
 548 .Sy PORT
 549 parameter is used, the default is port 389 for LDAP and port 636 for LDAP
 550 over TLS (SSL).
 551 The
 552 .Sy PORT
 553 parameter is deprecated in favor of the
 554 .Sy URI
 555 specification and is included for backwards compatibility.
 556 .It Sy BIND_TIMELIMIT Ar seconds
 557 The
 558 .Sy BIND_TIMELIMIT
 559 parameter specifies the amount of time, in seconds, to wait while trying
 560 to connect to an LDAP server.
 561 If multiple
 562 .Sy URI Ns No s
 563 or
 564 .Sy HOST Ns No s
 565 are specified, this is the amount of time to wait before trying
 566 the next one in the list.
 567 .It Sy NETWORK_TIMEOUT Ar seconds
 568 An alias for
 569 .Sy BIND_TIMELIMIT
 570 for OpenLDAP compatibility.
 571 .It Sy TIMELIMIT Ar seconds
 572 The
 573 .Sy TIMELIMIT
 574 parameter specifies the amount of time, in seconds, to wait for a
 575 response to an LDAP query.
 576 .It Sy TIMEOUT Ar seconds
 577 The
 578 .Sy TIMEOUT
 579 parameter specifies the amount of time, in seconds, to wait for a
 580 response from the various LDAP APIs.
 581 .It Sy SUDOERS_BASE Ar base
 582 The base DN to use when performing
 583 .Nm sudo
 584 LDAP queries.
 585 Typically this is of the form
 586 .Li ou=SUDOers,dc=example,dc=com
 587 for the domain
 588 .Li example.com .
 589 Multiple
 590 .Sy SUDOERS_BASE
 591 lines may be specified, in which case they are queried in the order specified.
 592 .It Sy SUDOERS_SEARCH_FILTER Ar ldap_filter
 593 An LDAP filter which is used to restrict the set of records returned
 594 when performing a
 595 .Nm sudo
 596 LDAP query.
 597 Typically, this is of the
 598 form
 599 .Li attribute=value
 600 or
 601 .Li (&(attribute=value)(attribute2=value2)) .
 602 .It Sy SUDOERS_TIMED Ar on/true/yes/off/false/no
 603 Whether or not to evaluate the
 604 .Li sudoNotBefore
 605 and
 606 .Li sudoNotAfter
 607 attributes that implement time-dependent sudoers entries.
 608 .It Sy SUDOERS_DEBUG Ar debug_level
 609 This sets the debug level for
 610 .Nm sudo
 611 LDAP queries.
 612 Debugging information is printed to the standard error.
 613 A value of 1 results in a moderate amount of debugging information.
 614 A value of 2 shows the results of the matches themselves.
 615 This parameter should not be set in a production environment as the
 616 extra information is likely to confuse users.
 617 .Pp
 618 The
 619 .Sy SUDOERS_DEBUG
 620 parameter is deprecated and will be removed in a future release.
 621 The same information is now logged via the
 622 .Nm sudo
 623 debugging framework using the
 624 .Dq ldap
 625 subsystem at priorities
 626 .Em diag
 627 and
 628 .Em info
 629 for
 630 .Em debug_level
 631 values 1 and 2 respectively.
 632 See the
 633 .Xr sudo.conf @mansectform@
 634 manual for details on how to configure
 635 .Nm sudo
 636 debugging.
 637 .It Sy BINDDN Ar DN
 638 The
 639 .Sy BINDDN
 640 parameter specifies the identity, in the form of a Distinguished Name (DN),
 641 to use when performing LDAP operations.
 642 If not specified, LDAP operations are performed with an anonymous identity.
 643 By default, most LDAP servers will allow anonymous access.
 644 .It Sy BINDPW Ar secret
 645 The
 646 .Sy BINDPW
 647 parameter specifies the password to use when performing LDAP operations.
 648 This is typically used in conjunction with the
 649 .Sy BINDDN
 650 parameter.
 651 .It Sy ROOTBINDDN Ar DN
 652 The
 653 .Sy ROOTBINDDN
 654 parameter specifies the identity, in the form of a Distinguished Name (DN),
 655 to use when performing privileged LDAP operations, such as
 656 .Em sudoers
 657 queries.
 658 The password corresponding to the identity should be stored in the
 659 or the path specified by the
 660 .Em ldap_secret
 661 plugin argument in
 662 .Xr sudo.conf @mansectform@ ,
 663 which defaults to
 664 .Pa @ldap_secret@ .
 665 If no
 666 .Sy ROOTBINDDN
 667 is specified, the
 668 .Sy BINDDN
 669 identity is used (if any).
 670 .It Sy LDAP_VERSION Ar number
 671 The version of the LDAP protocol to use when connecting to the server.
 672 The default value is protocol version 3.
 673 .It Sy SSL Ar on/true/yes/off/false/no
 674 If the
 675 .Sy SSL
 676 parameter is set to
 677 .Li on ,
 678 .Li true
 679 .Li or
 680 .Li yes ,
 681 TLS (SSL) encryption is always used when communicating with the LDAP server.
 682 Typically, this involves connecting to the server on port 636 (ldaps).
 683 .It Sy SSL Ar start_tls
 684 If the
 685 .Sy SSL
 686 parameter is set to
 687 .Li start_tls ,
 688 the LDAP server connection is initiated normally and TLS encryption is
 689 begun before the bind credentials are sent.
 690 This has the advantage of not requiring a dedicated port for encrypted
 691 communications.
 692 This parameter is only supported by LDAP servers that honor the
 693 .Em start_tls
 694 extension, such as the OpenLDAP and Tivoli Directory servers.
 695 .It Sy TLS_CHECKPEER Ar on/true/yes/off/false/no
 696 If enabled,
 697 .Sy TLS_CHECKPEER
 698 will cause the LDAP server's TLS certificated to be verified.
 699 If the server's TLS certificate cannot be verified (usually because it
 700 is signed by an unknown certificate authority),
 701 .Nm sudo
 702 will be unable to connect to it.
 703 If
 704 .Sy TLS_CHECKPEER
 705 is disabled, no check is made.
 706 Note that disabling the check creates an opportunity for man-in-the-middle
 707 attacks since the server's identity will not be authenticated.
 708 If possible, the CA's certificate should be installed locally so it can
 709 be verified.
 710 This option is not supported by the Tivoli Directory Server LDAP libraries.
 711 .It Sy TLS_CACERT Ar file name
 712 An alias for
 713 .Sy TLS_CACERTFILE
 714 for OpenLDAP compatibility.
 715 .It Sy TLS_CACERTFILE Ar file name
 716 The path to a certificate authority bundle which contains the certificates
 717 for all the Certificate Authorities the client knows to be valid, e.g.\&
 718 .Pa /etc/ssl/ca-bundle.pem .
 719 This option is only supported by the OpenLDAP libraries.
 720 Netscape-derived LDAP libraries use the same certificate
 721 database for CA and client certificates (see
 722 .Sy TLS_CERT ) .
 723 .It Sy TLS_CACERTDIR Ar directory
 724 Similar to
 725 .Sy TLS_CACERTFILE
 726 but instead of a file, it is a directory containing individual
 727 Certificate Authority certificates, e.g.\&
 728 .Pa /etc/ssl/certs .
 729 The directory specified by
 730 .Sy TLS_CACERTDIR
 731 is checked after
 732 .Sy TLS_CACERTFILE .
 733 This option is only supported by the OpenLDAP libraries.
 734 .It Sy TLS_CERT Ar file name
 735 The path to a file containing the client certificate which can
 736 be used to authenticate the client to the LDAP server.
 737 The certificate type depends on the LDAP libraries used.
 738 .Bl -tag -width 4n
 739 .It OpenLDAP:
 740 .Li tls_cert /etc/ssl/client_cert.pem
 741 .It Netscape-derived:
 742 .Li tls_cert /var/ldap/cert7.db
 743 .It Tivoli Directory Server:
 744 Unused, the key database specified by
 745 .Sy TLS_KEY
 746 contains both keys and certificates.
 747 .Pp
 748 When using Netscape-derived libraries, this file may also contain
 749 Certificate Authority certificates.
 750 .El
 751 .It Sy TLS_KEY Ar file name
 752 The path to a file containing the private key which matches the
 753 certificate specified by
 754 .Sy TLS_CERT .
 755 The private key must not be password-protected.
 756 The key type depends on the LDAP libraries used.
 757 .Bl -tag -width 4n
 758 .It OpenLDAP:
 759 .Li tls_key /etc/ssl/client_key.pem
 760 .It Netscape-derived:
 761 .Li tls_key /var/ldap/key3.db
 762 .It Tivoli Directory Server:
 763 .Li tls_cert /usr/ldap/ldapkey.kdb
 764 .El
 765 When using Tivoli LDAP libraries, this file may also contain
 766 Certificate Authority and client certificates and may be encrypted.
 767 .It Sy TLS_KEYPW Ar secret
 768 The
 769 .Sy TLS_KEYPW
 770 contains the password used to decrypt the key database on clients
 771 using the Tivoli Directory Server LDAP library.
 772 If no
 773 .Sy TLS_KEYPW
 774 is specified, a
 775 .Em stash file
 776 will be used if it exists.
 777 The
 778 .Em stash file
 779 must have the same path as the file specified by
 780 .Sy TLS_KEY ,
 781 but use a
 782 .Li .sth
 783 file extension instead of
 784 .Li .kdb ,
 785 e.g.\&
 786 .Li ldapkey.sth .
 787 The default
 788 .Li ldapkey.kdb
 789 that ships with Tivoli Directory Server is encrypted with the password
 790 .Li ssl_password .
 791 This option is only supported by the Tivoli LDAP libraries.
 792 .It Sy TLS_RANDFILE Ar file name
 793 The
 794 .Sy TLS_RANDFILE
 795 parameter specifies the path to an entropy source for systems that lack
 796 a random device.
 797 It is generally used in conjunction with
 798 .Em prngd
 799 or
 800 .Em egd .
 801 This option is only supported by the OpenLDAP libraries.
 802 .It Sy TLS_CIPHERS Ar cipher list
 803 The
 804 .Sy TLS_CIPHERS
 805 parameter allows the administer to restrict which encryption algorithms
 806 may be used for TLS (SSL) connections.
 807 See the OpenLDAP or Tivoli Directory Server manual for a list of valid
 808 ciphers.
 809 This option is not supported by Netscape-derived libraries.
 810 .It Sy USE_SASL Ar on/true/yes/off/false/no
 811 Enable
 812 .Sy USE_SASL
 813 for LDAP servers that support SASL authentication.
 814 .It Sy SASL_AUTH_ID Ar identity
 815 The SASL user name to use when connecting to the LDAP server.
 816 By default,
 817 .Nm sudo
 818 will use an anonymous connection.
 819 .It Sy ROOTUSE_SASL Ar on/true/yes/off/false/no
 820 Enable
 821 .Sy ROOTUSE_SASL
 822 to enable SASL authentication when connecting
 823 to an LDAP server from a privileged process, such as
 824 .Nm sudo .
 825 .It Sy ROOTSASL_AUTH_ID Ar identity
 826 The SASL user name to use when
 827 .Sy ROOTUSE_SASL
 828 is enabled.
 829 .It Sy SASL_SECPROPS Ar none/properties
 830 SASL security properties or
 831 .Em none
 832 for no properties.
 833 See the SASL programmer's manual for details.
 834 .It Sy KRB5_CCNAME Ar file name
 835 The path to the Kerberos 5 credential cache to use when authenticating
 836 with the remote server.
 837 .It Sy DEREF Ar never/searching/finding/always
 838 How alias dereferencing is to be performed when searching.
 839 See the
 840 .Xr ldap.conf @mansectsu@
 841 manual for a full description of this option.
 842 .El
 843 .Pp
 844 See the
 845 .Pa ldap.conf
 846 entry in the
 847 .Sx EXAMPLES
 848 section.
 849 .Ss Configuring nsswitch.conf
 850 Unless it is disabled at build time,
 851 .Nm sudo
 852 consults the Name Service Switch file,
 853 .Pa @nsswitch_conf@ ,
 854 to specify the
 855 .Em sudoers
 856 search order.
 857 Sudo looks for a line beginning with
 858 .Li sudoers :
 859 and uses this to determine the search order.
 860 Note that
 861 .Nm sudo
 862 does
 863 not stop searching after the first match and later matches take
 864 precedence over earlier ones.
 865 The following sources are recognized:
 866 .Pp
 867 .Bl -tag -width 8n -offset 4n -compact
 868 .It files
 869 read sudoers from
 870 .Pa @sysconfdir@/sudoers
 871 .It ldap
 872 read sudoers from LDAP
 873 .El
 874 .Pp
 875 In addition, the entry
 876 .Li [NOTFOUND=return]
 877 will short-circuit the search if the user was not found in the
 878 preceding source.
 879 .Pp
 880 To consult LDAP first followed by the local sudoers file (if it
 881 exists), use:
 882 .Bd -literal -offset 4n
 883 sudoers: ldap files
 884 .Ed
 885 .Pp
 886 The local
 887 .Em sudoers
 888 file can be ignored completely by using:
 889 .Bd -literal -offset 4n
 890 sudoers: ldap
 891 .Ed
 892 .Pp
 893 If the
 894 .Pa @nsswitch_conf@
 895 file is not present or there is no sudoers line, the following
 896 default is assumed:
 897 .Bd -literal -offset 4n
 898 sudoers: files
 899 .Ed
 900 .Pp
 901 Note that
 902 .Pa @nsswitch_conf@
 903 is supported even when the underlying operating system does not use
 904 an nsswitch.conf file, except on AIX (see below).
 905 .Ss Configuring netsvc.conf
 906 On AIX systems, the
 907 .Pa @netsvc_conf@
 908 file is consulted instead of
 909 .Pa @nsswitch_conf@ .
 910 .Nm sudo
 911 simply treats
 912 .Pa netsvc.conf
 913 as a variant of
 914 .Pa nsswitch.conf ;
 915 information in the previous section unrelated to the file format
 916 itself still applies.
 917 .Pp
 918 To consult LDAP first followed by the local sudoers file (if it
 919 exists), use:
 920 .Bd -literal -offset 4n
 921 sudoers = ldap, files
 922 .Ed
 923 .Pp
 924 The local
 925 .Em sudoers
 926 file can be ignored completely by using:
 927 .Bd -literal -offset 4n
 928 sudoers = ldap
 929 .Ed
 930 .Pp
 931 To treat LDAP as authoritative and only use the local sudoers file
 932 if the user is not present in LDAP, use:
 933 .Bd -literal -offset 4n
 934 sudoers = ldap = auth, files
 935 .Ed
 936 .Pp
 937 Note that in the above example, the
 938 .Li auth
 939 qualifier only affects user lookups; both LDAP and
 940 .Em sudoers
 941 will be queried for
 942 .Li Defaults
 943 entries.
 944 .Pp
 945 If the
 946 .Pa @netsvc_conf@
 947 file is not present or there is no sudoers line, the following
 948 default is assumed:
 949 .Bd -literal -offset 4n
 950 sudoers = files
 951 .Ed
 952 .Sh FILES
 953 .Bl -tag -width 24n
 954 .It Pa @ldap_conf@
 955 LDAP configuration file
 956 .It Pa @nsswitch_conf@
 957 determines sudoers source order
 958 .It Pa @netsvc_conf@
 959 determines sudoers source order on AIX
 960 .El
 961 .Sh EXAMPLES
 962 .Ss Example ldap.conf
 963 .Bd -literal -offset 2n
 964 # Either specify one or more URIs or one or more host:port pairs.
 965 # If neither is specified sudo will default to localhost, port 389.
 966 #
 967 #host          ldapserver
 968 #host          ldapserver1 ldapserver2:390
 969 #
 970 # Default port if host is specified without one, defaults to 389.
 971 #port          389
 972 #
 973 # URI will override the host and port settings.
 974 uri            ldap://ldapserver
 975 #uri            ldaps://secureldapserver
 976 #uri            ldaps://secureldapserver ldap://ldapserver
 977 #
 978 # The amount of time, in seconds, to wait while trying to connect to
 979 # an LDAP server.
 980 bind_timelimit 30
 981 #
 982 # The amount of time, in seconds, to wait while performing an LDAP query.
 983 timelimit 30
 984 #
 985 # Must be set or sudo will ignore LDAP; may be specified multiple times.
 986 sudoers_base   ou=SUDOers,dc=example,dc=com
 987 #
 988 # verbose sudoers matching from ldap
 989 #sudoers_debug 2
 990 #
 991 # Enable support for time-based entries in sudoers.
 992 #sudoers_timed yes
 993 #
 994 # optional proxy credentials
 995 #binddn        <who to search as>
 996 #bindpw        <password>
 997 #rootbinddn    <who to search as, uses /etc/ldap.secret for bindpw>
 998 #
 999 # LDAP protocol version, defaults to 3
1000 #ldap_version 3
1001 #
1002 # Define if you want to use an encrypted LDAP connection.
1003 # Typically, you must also set the port to 636 (ldaps).
1004 #ssl on
1005 #
1006 # Define if you want to use port 389 and switch to
1007 # encryption before the bind credentials are sent.
1008 # Only supported by LDAP servers that support the start_tls
1009 # extension such as OpenLDAP.
1010 #ssl start_tls
1011 #
1012 # Additional TLS options follow that allow tweaking of the
1013 # SSL/TLS connection.
1014 #
1015 #tls_checkpeer yes # verify server SSL certificate
1016 #tls_checkpeer no  # ignore server SSL certificate
1017 #
1018 # If you enable tls_checkpeer, specify either tls_cacertfile
1019 # or tls_cacertdir.  Only supported when using OpenLDAP.
1020 #
1021 #tls_cacertfile /etc/certs/trusted_signers.pem
1022 #tls_cacertdir  /etc/certs
1023 #
1024 # For systems that don't have /dev/random
1025 # use this along with PRNGD or EGD.pl to seed the
1026 # random number pool to generate cryptographic session keys.
1027 # Only supported when using OpenLDAP.
1028 #
1029 #tls_randfile /etc/egd-pool
1030 #
1031 # You may restrict which ciphers are used.  Consult your SSL
1032 # documentation for which options go here.
1033 # Only supported when using OpenLDAP.
1034 #
1035 #tls_ciphers <cipher-list>
1036 #
1037 # Sudo can provide a client certificate when communicating to
1038 # the LDAP server.
1039 # Tips:
1040 #   * Enable both lines at the same time.
1041 #   * Do not password protect the key file.
1042 #   * Ensure the keyfile is only readable by root.
1043 #
1044 # For OpenLDAP:
1045 #tls_cert /etc/certs/client_cert.pem
1046 #tls_key  /etc/certs/client_key.pem
1047 #
1048 # For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either
1049 # a directory, in which case the files in the directory must have the
1050 # default names (e.g. cert8.db and key4.db), or the path to the cert
1051 # and key files themselves.  However, a bug in version 5.0 of the LDAP
1052 # SDK will prevent specific file names from working.  For this reason
1053 # it is suggested that tls_cert and tls_key be set to a directory,
1054 # not a file name.
1055 #
1056 # The certificate database specified by tls_cert may contain CA certs
1057 # and/or the client's cert.  If the client's cert is included, tls_key
1058 # should be specified as well.
1059 # For backward compatibility, "sslpath" may be used in place of tls_cert.
1060 #tls_cert /var/ldap
1061 #tls_key /var/ldap
1062 #
1063 # If using SASL authentication for LDAP (OpenSSL)
1064 # use_sasl yes
1065 # sasl_auth_id <SASL user name>
1066 # rootuse_sasl yes
1067 # rootsasl_auth_id <SASL user name for root access>
1068 # sasl_secprops none
1069 # krb5_ccname /etc/.ldapcache
1070 .Ed
1071 .Ss Sudo schema for OpenLDAP
1072 The following schema, in OpenLDAP format, is included with
1073 .Nm sudo
1074 source and binary distributions as
1075 .Pa schema.OpenLDAP .
1076 Simply copy
1077 it to the schema directory (e.g.\&
1078 .Pa /etc/openldap/schema ) ,
1079 add the proper
1080 .Li include
1081 line in
1082 .Pa slapd.conf
1083 and restart
1084 .Nm slapd .
1085 .Bd -literal -offset 2n
1086 attributetype ( 1.3.6.1.4.1.15953.9.1.1
1087    NAME 'sudoUser'
1088    DESC 'User(s) who may  run sudo'
1089    EQUALITY caseExactIA5Match
1090    SUBSTR caseExactIA5SubstringsMatch
1091    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1092
1093 attributetype ( 1.3.6.1.4.1.15953.9.1.2
1094    NAME 'sudoHost'
1095    DESC 'Host(s) who may run sudo'
1096    EQUALITY caseExactIA5Match
1097    SUBSTR caseExactIA5SubstringsMatch
1098    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1099
1100 attributetype ( 1.3.6.1.4.1.15953.9.1.3
1101    NAME 'sudoCommand'
1102    DESC 'Command(s) to be executed by sudo'
1103    EQUALITY caseExactIA5Match
1104    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1105
1106 attributetype ( 1.3.6.1.4.1.15953.9.1.4
1107    NAME 'sudoRunAs'
1108    DESC 'User(s) impersonated by sudo'
1109    EQUALITY caseExactIA5Match
1110    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1111
1112 attributetype ( 1.3.6.1.4.1.15953.9.1.5
1113    NAME 'sudoOption'
1114    DESC 'Options(s) followed by sudo'
1115    EQUALITY caseExactIA5Match
1116    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1117
1118 attributetype ( 1.3.6.1.4.1.15953.9.1.6
1119    NAME 'sudoRunAsUser'
1120    DESC 'User(s) impersonated by sudo'
1121    EQUALITY caseExactIA5Match
1122    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1123
1124 attributetype ( 1.3.6.1.4.1.15953.9.1.7
1125    NAME 'sudoRunAsGroup'
1126    DESC 'Group(s) impersonated by sudo'
1127    EQUALITY caseExactIA5Match
1128    SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
1129
1130 attributetype ( 1.3.6.1.4.1.15953.9.1.8
1131    NAME 'sudoNotBefore'
1132    DESC 'Start of time interval for which the entry is valid'
1133    EQUALITY generalizedTimeMatch
1134    ORDERING generalizedTimeOrderingMatch
1135    SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 )
1136
1137 attributetype ( 1.3.6.1.4.1.15953.9.1.9
1138    NAME 'sudoNotAfter'
1139    DESC 'End of time interval for which the entry is valid'
1140    EQUALITY generalizedTimeMatch
1141    ORDERING generalizedTimeOrderingMatch
1142    SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 )
1143
1144 attributeTypes ( 1.3.6.1.4.1.15953.9.1.10
1145     NAME 'sudoOrder'
1146     DESC 'an integer to order the sudoRole entries'
1147     EQUALITY integerMatch
1148     ORDERING integerOrderingMatch
1149     SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 )
1150
1151 objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL
1152    DESC 'Sudoer Entries'
1153    MUST ( cn )
1154    MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $
1155          sudoRunAsGroup $ sudoOption $ sudoNotBefore $ sudoNotAfter $
1156          sudoOrder $ description )
1157    )
1158 .Ed
1159 .Sh SEE ALSO
1160 .Xr ldap.conf @mansectform@ ,
1161 .Xr sudo.conf @mansectform@ ,
1162 .Xr sudoers @mansectsu@
1163 .Sh CAVEATS
1164 Note that there are differences in the way that LDAP-based
1165 .Em sudoers
1166 is parsed compared to file-based
1167 .Em sudoers .
1168 See the
1169 .Sx Differences between LDAP and non-LDAP sudoers
1170 section for more information.
1171 .Sh BUGS
1172 If you feel you have found a bug in
1173 .Nm sudo ,
1174 please submit a bug report at http://www.sudo.ws/sudo/bugs/
1175 .Sh SUPPORT
1176 Limited free support is available via the sudo-users mailing list,
1177 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
1178 search the archives.
1179 .Sh DISCLAIMER
1180 .Nm sudo
1181 is provided
1182 .Dq AS IS
1183 and any express or implied warranties, including, but not limited
1184 to, the implied warranties of merchantability and fitness for a
1185 particular purpose are disclaimed.
1186 See the LICENSE file distributed with
1187 .Nm sudo
1188 or http://www.sudo.ws/sudo/license.html for complete details.