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

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