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

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