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