1 Copyright (c) 2003-2009
2 Todd C. Miller <Todd.Miller@courtesan.com>
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.
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.
17 $Sudo: sudoers.ldap.pod,v 1.14 2009/05/29 13:43:12 millert Exp $
22 sudoers.ldap - sudo LDAP configuration
26 In addition to the standard I<sudoers> file, B<sudo> may be configured
27 via LAP. This can be especially useful for synchronizing I<sudoers>
28 in a large, distributed environment.
30 Using LDAP for I<sudoers> has several benefits:
36 B<sudo> no longer needs to read I<sudoers> in its entirety. When
37 LDAP is used, there are only two or three LDAP queries per invocation.
38 This makes it especially fast and particularly usable in LDAP
43 B<sudo> no longer exits if there is a typo in I<sudoers>.
44 It is not possible to load LDAP data into the server that does
45 not conform to the sudoers schema, so proper syntax is guaranteed.
46 It is still possible to have typos in a user or host name, but
47 this will not prevent B<sudo> from running.
51 It is possible to specify per-entry options that override the global
52 default options. F<@sysconfdir@/sudoers> only supports default options and
53 limited options associated with user/host/commands/aliases. The
54 syntax is complicated and can be difficult for users to understand.
55 Placing the options directly in the entry is more natural.
59 The B<visudo> program is no longer needed. B<visudo> provides
60 locking and syntax checking of the F<@sysconfdir@/sudoers> file.
61 Since LDAP updates are atomic, locking is no longer necessary.
62 Because syntax is checked when the data is inserted into LDAP, there
63 is no need for a specialized tool to check syntax.
67 Another major difference between LDAP and file-based I<sudoers>
68 is that in LDAP, B<sudo>-specific Aliases are not supported.
70 For the most part, there is really no need for B<sudo>-specific
71 Aliases. Unix groups or user netgroups can be used in place of
72 User_Aliases and RunasAliases. Host netgroups can be used in place
73 of HostAliases. Since Unix groups and netgroups can also be stored
74 in LDAP there is no real need for B<sudo>-specific aliases.
76 Cmnd_Aliases are not really required either since it is possible
77 to have multiple users listed in a sudoRole. Instead of defining
78 a Cmnd_Alias that is referenced by multiple users, one can create
79 a sudoRole that contains the commands and assign multiple users
82 =head2 SUDOers LDAP container
84 The I<sudoers> configuration is contained in the C<ou=SUDOers> LDAP
87 Sudo first looks for the C<cn=default> entry in the SUDOers container.
88 If found, the multi-valued C<sudoOption> attribute is parsed in the
89 same manner as a global C<Defaults> line in F<@sysconfdir@/sudoers>. In
90 the following example, the C<SSH_AUTH_SOCK> variable will be preserved
91 in the environment for all users.
93 dn: cn=defaults,ou=SUDOers,dc=example,dc=com
97 description: Default sudoOption's go here
98 sudoOption: env_keep+=SSH_AUTH_SOCK
100 The equivalent of a sudoer in LDAP is a C<sudoRole>. It consists of
101 the following components:
107 A user name, uid (prefixed with C<'#'>), Unix group (prefixed with
108 a C<'%'>) or user netgroup (prefixed with a C<'+'>).
112 A host name, IP address, IP network, or host netgroup (prefixed
114 The special value C<ALL> will match any host.
118 A Unix command with optional command line arguments, potentially
119 including globbing characters (aka wild cards).
120 The special value C<ALL> will match any command.
121 If a command is prefixed with an exclamation point C<'!'>, the
122 user will be prohibited from running that command.
126 Identical in function to the global options described above, but
127 specific to the C<sudoRole> in which it resides.
129 =item B<sudoRunAsUser>
131 A user name or uid (prefixed with C<'#'>) that commands may be run
132 as or a Unix group (prefixed with a C<'%'>) or user netgroup (prefixed
133 with a C<'+'>) that contains a list of users that commands may be
135 The special value C<ALL> will match any user.
137 =item B<sudoRunAsGroup>
139 A Unix group or gid (prefixed with C<'#'>) that commands may be run as.
140 The special value C<ALL> will match any group.
144 Each component listed above should contain a single value, but there
145 may be multiple instances of each component type. A sudoRole must
146 contain at least one C<sudoUser>, C<sudoHost> and C<sudoCommand>.
148 The following example allows users in group wheel to run any command
149 on any host via B<sudo>:
151 dn: cn=%wheel,ou=SUDOers,dc=example,dc=com
153 objectClass: sudoRole
159 =head2 Anatomy of LDAP sudoers lookup
161 When looking up a sudoer using LDAP there are only two or three
162 LDAP queries per invocation. The first query is to parse the global
163 options. The second is to match against the user's name and the
164 groups that the user belongs to. (The special ALL tag is matched
165 in this query too.) If no match is returned for the user's name
166 and groups, a third query returns all entries containing user
167 netgroups and checks to see if the user belongs to any of them.
169 =head2 Differences between LDAP and non-LDAP sudoers
171 There are some subtle differences in the way sudoers is handled
172 once in LDAP. Probably the biggest is that according to the RFC,
173 LDAP ordering is arbitrary and you cannot expect that Attributes
174 and Entries are returned in any specific order. If there are
175 conflicting command rules on an entry, the negative takes precedence.
176 This is called paranoid behavior (not necessarily the most specific
182 # Allow all commands except shell
183 johnny ALL=(root) ALL,!/bin/sh
184 # Always allows all commands because ALL is matched last
185 puddles ALL=(root) !/bin/sh,ALL
187 # LDAP equivalent of johnny
188 # Allows all commands except shell
189 dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com
190 objectClass: sudoRole
196 sudoCommand: !/bin/sh
198 # LDAP equivalent of puddles
199 # Notice that even though ALL comes last, it still behaves like
200 # role1 since the LDAP code assumes the more paranoid configuration
201 dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com
202 objectClass: sudoRole
207 sudoCommand: !/bin/sh
210 Another difference is that negations on the Host, User or Runas are
211 currently ignorred. For example, the following attributes do not
212 behave the way one might expect.
214 # does not match all but joe
215 # rather, does not match anyone
218 # does not match all but joe
219 # rather, matches everyone including Joe
223 # does not match all but web01
224 # rather, matches all hosts including web01
228 =head2 Sudoers Schema
230 In order to use B<sudo>'s LDAP support, the B<sudo> schema must be
231 installed on your LDAP server. In addition, be sure to index the
232 'sudoUser' attribute.
234 Three versions of the schema: one for OpenLDAP servers (F<schema.OpenLDAP>),
235 one for Netscape-derived servers (F<schema.iPlanet>), and one for
236 Microsoft Active Directory (F<schema.ActiveDirectory>) may
237 be found in the B<sudo> distribution.
239 The schema for B<sudo> in OpenLDAP form is included in the L<EXAMPLES>
242 =head2 Configuring ldap.conf
244 Sudo reads the F<@ldap_conf@> file for LDAP-specific configuration.
245 Typically, this file is shared amongst different LDAP-aware clients.
246 As such, most of the settings are not B<sudo>-specific. Note that
247 B<sudo> parses F<@ldap_conf@> itself and may support options
248 that differ from those described in the L<ldap.conf(5)> manual.
250 Also note that on systems using the OpenLDAP libraries, default
251 values specified in F</etc/openldap/ldap.conf> or the user's
252 F<.ldaprc> files are not used.
254 Only those options explicitly listed in F<@ldap_conf@> that are
255 supported by B<sudo> are honored. Configuration options are listed
256 below in upper case but are parsed in a case-independent manner.
260 =item B<URI> ldap[s]://[hostname[:port]] ...
262 Specifies a whitespace-delimited list of one or more URIs describing
263 the LDAP server(s) to connect to. The I<protocol> may be either B<ldap>
264 or B<ldaps>, the latter being for servers that support TLS (SSL)
265 encryption. If no I<port> is specified, the default is port 389 for
266 C<ldap://> or port 636 for C<ldaps://>. If no I<hostname> is specified,
267 B<sudo> will connect to B<localhost>. Only systems using the OpenSSL
268 libraries support the mixing of C<ldap://> and C<ldaps://> URIs.
269 The Netscape-derived libraries used on most commercial versions of
270 Unix are only capable of supporting one or the other.
272 =item B<HOST> name[:port] ...
274 If no B<URI> is specified, the B<HOST> parameter specifies a
275 whitespace-delimited list of LDAP servers to connect to. Each host
276 may include an optional I<port> separated by a colon (':'). The
277 B<HOST> parameter is deprecated in favor of the B<URI> specification
278 and is included for backwards compatibility.
280 =item B<PORT> port_number
282 If no B<URI> is specified, the B<PORT> parameter specifies the
283 default port to connect to on the LDAP server if a B<HOST> parameter
284 does not specify the port itself. If no B<PORT> parameter is used,
285 the default is port 389 for LDAP and port 636 for LDAP over TLS
286 (SSL). The B<PORT> parameter is deprecated in favor of the B<URI>
287 specification and is included for backwards compatibility.
289 =item B<BIND_TIMELIMIT> seconds
291 The B<BIND_TIMELIMIT> parameter specifies the amount of time, in seconds,
292 to wait while trying to connect to an LDAP server. If multiple B<URI>s or
293 B<HOST>s are specified, this is the amount of time to wait before trying
294 the next one in the list.
296 =item B<TIMELIMIT> seconds
298 The B<TIMELIMIT> parameter specifies the amount of time, in seconds,
299 to wait for a response to an LDAP query.
301 =item B<SUDOERS_BASE> base
303 The base DN to use when performing B<sudo> LDAP queries. Typically
304 this is of the form C<ou=SUDOers,dc=example,dc=com> for the domain
307 =item B<SUDOERS_DEBUG> debug_level
309 This sets the debug level for B<sudo> LDAP queries. Debugging
310 information is printed to the standard error. A value of 1 results
311 in a moderate amount of debugging information. A value of 2 shows
312 the results of the matches themselves. This parameter should not
313 be set in a production environment as the extra information is
314 likely to confuse users.
318 The B<BINDDN> parameter specifies the identity, in the form of a
319 Distinguished Name (DN), to use when performing LDAP operations.
320 If not specified, LDAP operations are performed with an anonymous
321 identity. By default, most LDAP servers will allow anonymous access.
323 =item B<BINDPW> secret
325 The B<BINDPW> parameter specifies the password to use when performing
326 LDAP operations. This is typically used in conjunction with the
329 =item B<ROOTBINDDN> DN
331 The B<ROOTBINDDN> parameter specifies the identity, in the form of
332 a Distinguished Name (DN), to use when performing privileged LDAP
333 operations, such as I<sudoers> queries. The password corresponding
334 to the identity should be stored in F<@ldap_secret@>.
335 If not specified, the B<BINDDN> identity is used (if any).
337 =item B<LDAP_VERSION> number
339 The version of the LDAP protocol to use when connecting to the server.
340 The default value is protocol version 3.
342 =item B<SSL> on/true/yes/off/false/no
344 If the B<SSL> parameter is set to C<on>, C<true> or C<yes>, TLS
345 (SSL) encryption is always used when communicating with the LDAP
346 server. Typically, this involves connecting to the server on port
349 =item B<SSL> start_tls
351 If the B<SSL> parameter is set to C<start_tls>, the LDAP server
352 connection is initiated normally and TLS encryption is begun before
353 the bind credentials are sent. This has the advantage of not
354 requiring a dedicated port for encrypted communications. This
355 parameter is only supported by LDAP servers that honor the C<start_tls>
356 extension, such as the OpenLDAP server.
358 =item B<TLS_CHECKPEER> on/true/yes/off/false/no
360 If enabled, B<TLS_CHECKPEER> will cause the LDAP server's TLS
361 certificated to be verified. If the server's TLS certificate cannot
362 be verified (usually because it is signed by an unknown certificate
363 authority), B<sudo> will be unable to connect to it. If B<TLS_CHECKPEER>
364 is disabled, no check is made.
366 =item B<TLS_CACERTFILE> file name
368 The path to a certificate authority bundle which contains the certificates
369 for all the Certificate Authorities the client knows to be valid,
370 e.g. F</etc/ssl/ca-bundle.pem>.
371 This option is only supported by the OpenLDAP libraries.
373 =item B<TLS_CACERTDIR> directory
375 Similar to B<TLS_CACERTFILE> but instead of a file, it is a
376 directory containing individual Certificate Authority certificates,
377 e.g. F</etc/ssl/certs>.
378 The directory specified by B<TLS_CACERTDIR> is checked after
380 This option is only supported by the OpenLDAP libraries.
382 =item B<TLS_CERT> file name
384 The path to a file containing the client certificate which can
385 be used to authenticate the client to the LDAP server.
386 The certificate type depends on the LDAP libraries used.
389 C<tls_cert /etc/ssl/client_cert.pem>
392 C<tls_cert /var/ldap/cert7.db>
394 When using Netscape-derived libraries, this file may also contain
395 Certificate Authority certificates.
397 =item B<TLS_KEY> file name
399 The path to a file containing the private key which matches the
400 certificate specified by B<TLS_CERT>. The private key must not be
401 password-protected. The key type depends on the LDAP libraries
405 C<tls_key /etc/ssl/client_key.pem>
408 C<tls_key /var/ldap/key3.db>
410 =item B<TLS_RANDFILE> file name
412 The B<TLS_RANDFILE> parameter specifies the path to an entropy
413 source for systems that lack a random device. It is generally used
414 in conjunction with I<prngd> or I<egd>.
415 This option is only supported by the OpenLDAP libraries.
417 =item B<TLS_CIPHERS> cipher list
419 The B<TLS_CIPHERS> parameter allows the administer to restrict
420 which encryption algorithms may be used for TLS (SSL) connections.
421 See the OpenSSL manual for a list of valid ciphers.
422 This option is only supported by the OpenLDAP libraries.
424 =item B<USE_SASL> on/true/yes/off/false/no
426 Enable B<USE_SASL> for LDAP servers that support SASL authentication.
428 =item B<SASL_AUTH_ID> identity
430 The SASL user name to use when connecting to the LDAP server.
431 By default, B<sudo> will use an anonymous connection.
433 =item B<ROOTUSE_SASL> on/true/yes/off/false/no
435 Enable B<ROOTUSE_SASL> to enable SASL authentication when connecting
436 to an LDAP server from a privileged process, such as B<sudo>.
438 =item B<ROOTSASL_AUTH_ID> identity
440 The SASL user name to use when B<ROOTUSE_SASL> is enabled.
442 =item B<SASL_SECPROPS> none/properties
444 SASL security properties or I<none> for no properties. See the
445 SASL programmer's manual for details.
447 =item B<KRB5_CCNAME> file name
449 The path to the Kerberos 5 credential cache to use when authenticating
450 with the remote server.
454 See the C<ldap.conf> entry in the L<EXAMPLES> section.
456 =head2 Configuring nsswitch.conf
458 Unless it is disabled at build time, B<sudo> consults the Name
459 Service Switch file, F<@nsswitch_conf@>, to specify the I<sudoers>
460 search order. Sudo looks for a line beginning with C<sudoers>: and
461 uses this to determine the search order. Note that B<sudo> does
462 not stop searching after the first match and later matches take
463 precedence over earlier ones.
465 The following sources are recognized:
467 files read sudoers from F<@sysconfdir@/sudoers>
468 ldap read sudoers from LDAP
470 In addition, the entry C<[NOTFOUND=return]> will short-circuit the
471 search if the user was not found in the preceding source.
473 To consult LDAP first followed by the local sudoers file (if it
478 The local I<sudoers> file can be ignored completely by using:
482 If the F<@nsswitch_conf@> file is not present or there is no
483 sudoers line, the following default is assumed:
487 Note that F<@nsswitch_conf@> is supported even when the underlying
488 operating system does not use an nsswitch.conf file.
490 =head2 Configuring netsvc.conf
492 On AIX systems, the F<@netsvc_conf@> file is consulted instead of
493 F<@nsswitch_conf@>. B<sudo> simply treats I<netsvc.conf> as a
494 variant of I<nsswitch.conf>; information in the previous section
495 unrelated to the file format itself still applies.
497 To consult LDAP first followed by the local sudoers file (if it
500 sudoers = ldap, files
502 The local I<sudoers> file can be ignored completely by using:
506 To treat LDAP as authoratative and only use the local sudoers file
507 if the user is not present in LDAP, use:
509 sudoers = ldap = auth, files
511 Note that in the above example, the C<auth> qualfier only affects
512 user lookups; both LDAP and I<sudoers> will be queried for C<Defaults>
515 If the F<@netsvc_conf@> file is not present or there is no
516 sudoers line, the following default is assumed:
526 LDAP configuration file
528 =item F<@nsswitch_conf@>
530 determines sudoers source order
532 =item F<@netsvc_conf@>
534 determines sudoers source order on AIX
540 =head2 Example ldap.conf
542 # Either specify one or more URIs or one or more host:port pairs.
543 # If neither is specified sudo will default to localhost, port 389.
546 #host ldapserver1 ldapserver2:390
548 # Default port if host is specified without one, defaults to 389.
551 # URI will override the host and port settings.
552 uri ldap://ldapserver
553 #uri ldaps://secureldapserver
554 #uri ldaps://secureldapserver ldap://ldapserver
556 # The amount of time, in seconds, to wait while trying to connect to
560 # The amount of time, in seconds, to wait while performing an LDAP query.
563 # must be set or sudo will ignore LDAP
564 sudoers_base ou=SUDOers,dc=example,dc=com
566 # verbose sudoers matching from ldap
569 # optional proxy credentials
570 #binddn <who to search as>
572 #rootbinddn <who to search as, uses /etc/ldap.secret for bindpw>
574 # LDAP protocol version, defaults to 3
577 # Define if you want to use an encrypted LDAP connection.
578 # Typically, you must also set the port to 636 (ldaps).
581 # Define if you want to use port 389 and switch to
582 # encryption before the bind credentials are sent.
583 # Only supported by LDAP servers that support the start_tls
584 # extension such as OpenLDAP.
587 # Additional TLS options follow that allow tweaking of the
588 # SSL/TLS connection.
590 #tls_checkpeer yes # verify server SSL certificate
591 #tls_checkpeer no # ignore server SSL certificate
593 # If you enable tls_checkpeer, specify either tls_cacertfile
594 # or tls_cacertdir. Only supported when using OpenLDAP.
596 #tls_cacertfile /etc/certs/trusted_signers.pem
597 #tls_cacertdir /etc/certs
599 # For systems that don't have /dev/random
600 # use this along with PRNGD or EGD.pl to seed the
601 # random number pool to generate cryptographic session keys.
602 # Only supported when using OpenLDAP.
604 #tls_randfile /etc/egd-pool
606 # You may restrict which ciphers are used. Consult your SSL
607 # documentation for which options go here.
608 # Only supported when using OpenLDAP.
610 #tls_ciphers <cipher-list>
612 # Sudo can provide a client certificate when communicating to
615 # * Enable both lines at the same time.
616 # * Do not password protect the key file.
617 # * Ensure the keyfile is only readable by root.
620 #tls_cert /etc/certs/client_cert.pem
621 #tls_key /etc/certs/client_key.pem
623 # For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either
624 # a directory, in which case the files in the directory must have the
625 # default names (e.g. cert8.db and key4.db), or the path to the cert
626 # and key files themselves. However, a bug in version 5.0 of the LDAP
627 # SDK will prevent specific file names from working. For this reason
628 # it is suggested that tls_cert and tls_key be set to a directory,
631 # The certificate database specified by tls_cert may contain CA certs
632 # and/or the client's cert. If the client's cert is included, tls_key
633 # should be specified as well.
634 # For backward compatibility, "sslpath" may be used in place of tls_cert.
638 # If using SASL authentication for LDAP (OpenSSL)
640 # sasl_auth_id <SASL username>
642 # rootsasl_auth_id <SASL username for root access>
644 # krb5_ccname /etc/.ldapcache
646 =head2 Sudo schema for OpenLDAP
648 The following schema is in OpenLDAP format. Simply copy it to the
649 schema directory (e.g. F</etc/openldap/schema>), add the proper
650 C<include> line in C<slapd.conf> and restart B<slapd>.
652 attributetype ( 1.3.6.1.4.1.15953.9.1.1
654 DESC 'User(s) who may run sudo'
655 EQUALITY caseExactIA5Match
656 SUBSTR caseExactIA5SubstringsMatch
657 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
659 attributetype ( 1.3.6.1.4.1.15953.9.1.2
661 DESC 'Host(s) who may run sudo'
662 EQUALITY caseExactIA5Match
663 SUBSTR caseExactIA5SubstringsMatch
664 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
666 attributetype ( 1.3.6.1.4.1.15953.9.1.3
668 DESC 'Command(s) to be executed by sudo'
669 EQUALITY caseExactIA5Match
670 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
672 attributetype ( 1.3.6.1.4.1.15953.9.1.4
674 DESC 'User(s) impersonated by sudo'
675 EQUALITY caseExactIA5Match
676 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
678 attributetype ( 1.3.6.1.4.1.15953.9.1.5
680 DESC 'Options(s) followed by sudo'
681 EQUALITY caseExactIA5Match
682 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
684 attributetype ( 1.3.6.1.4.1.15953.9.1.6
686 DESC 'User(s) impersonated by sudo'
687 EQUALITY caseExactIA5Match
688 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
690 attributetype ( 1.3.6.1.4.1.15953.9.1.7
691 NAME 'sudoRunAsGroup'
692 DESC 'Group(s) impersonated by sudo'
693 EQUALITY caseExactIA5Match
694 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
696 objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL
697 DESC 'Sudoer Entries'
699 MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $
700 sudoRunAsGroup $ sudoOption $ description )
705 L<ldap.conf(5)>, L<sudoers(5)>
709 The way that I<sudoers> is parsed differs between Note that there
710 are differences in the way that LDAP-based I<sudoers> is parsed
711 compared to file-based I<sudoers>. See the L<Differences between
712 LDAP and non-LDAP sudoers> section for more information.
716 If you feel you have found a bug in B<sudo>, please submit a bug report
717 at http://www.sudo.ws/sudo/bugs/
721 Limited free support is available via the sudo-users mailing list,
722 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
727 B<sudo> is provided ``AS IS'' and any express or implied warranties,
728 including, but not limited to, the implied warranties of merchantability
729 and fitness for a particular purpose are disclaimed. See the LICENSE
730 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
731 for complete details.