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.
21 sudoers.ldap - sudo LDAP configuration
25 In addition to the standard I<sudoers> file, B<sudo> may be configured
26 via LAP. This can be especially useful for synchronizing I<sudoers>
27 in a large, distributed environment.
29 Using LDAP for I<sudoers> has several benefits:
35 B<sudo> no longer needs to read I<sudoers> in its entirety. When
36 LDAP is used, there are only two or three LDAP queries per invocation.
37 This makes it especially fast and particularly usable in LDAP
42 B<sudo> no longer exits if there is a typo in I<sudoers>.
43 It is not possible to load LDAP data into the server that does
44 not conform to the sudoers schema, so proper syntax is guaranteed.
45 It is still possible to have typos in a user or host name, but
46 this will not prevent B<sudo> from running.
50 It is possible to specify per-entry options that override the global
51 default options. F<@sysconfdir@/sudoers> only supports default options and
52 limited options associated with user/host/commands/aliases. The
53 syntax is complicated and can be difficult for users to understand.
54 Placing the options directly in the entry is more natural.
58 The B<visudo> program is no longer needed. B<visudo> provides
59 locking and syntax checking of the F<@sysconfdir@/sudoers> file.
60 Since LDAP updates are atomic, locking is no longer necessary.
61 Because syntax is checked when the data is inserted into LDAP, there
62 is no need for a specialized tool to check syntax.
66 Another major difference between LDAP and file-based I<sudoers>
67 is that in LDAP, B<sudo>-specific Aliases are not supported.
69 For the most part, there is really no need for B<sudo>-specific
70 Aliases. Unix groups or user netgroups can be used in place of
71 User_Aliases and RunasAliases. Host netgroups can be used in place
72 of HostAliases. Since Unix groups and netgroups can also be stored
73 in LDAP there is no real need for B<sudo>-specific aliases.
75 Cmnd_Aliases are not really required either since it is possible
76 to have multiple users listed in a sudoRole. Instead of defining
77 a Cmnd_Alias that is referenced by multiple users, one can create
78 a sudoRole that contains the commands and assign multiple users
81 =head2 SUDOers LDAP container
83 The I<sudoers> configuration is contained in the C<ou=SUDOers> LDAP
86 Sudo first looks for the C<cn=default> entry in the SUDOers container.
87 If found, the multi-valued C<sudoOption> attribute is parsed in the
88 same manner as a global C<Defaults> line in F<@sysconfdir@/sudoers>. In
89 the following example, the C<SSH_AUTH_SOCK> variable will be preserved
90 in the environment for all users.
92 dn: cn=defaults,ou=SUDOers,dc=example,dc=com
96 description: Default sudoOption's go here
97 sudoOption: env_keep+=SSH_AUTH_SOCK
99 The equivalent of a sudoer in LDAP is a C<sudoRole>. It consists of
100 the following components:
106 A user name, uid (prefixed with C<'#'>), Unix group (prefixed with
107 a C<'%'>) or user netgroup (prefixed with a C<'+'>).
111 A host name, IP address, IP network, or host netgroup (prefixed
113 The special value C<ALL> will match any host.
117 A Unix command with optional command line arguments, potentially
118 including globbing characters (aka wild cards).
119 The special value C<ALL> will match any command.
120 If a command is prefixed with an exclamation point C<'!'>, the
121 user will be prohibited from running that command.
125 Identical in function to the global options described above, but
126 specific to the C<sudoRole> in which it resides.
128 =item B<sudoRunAsUser>
130 A user name or uid (prefixed with C<'#'>) that commands may be run
131 as or a Unix group (prefixed with a C<'%'>) or user netgroup (prefixed
132 with a C<'+'>) that contains a list of users that commands may be
134 The special value C<ALL> will match any user.
136 =item B<sudoRunAsGroup>
138 A Unix group or gid (prefixed with C<'#'>) that commands may be run as.
139 The special value C<ALL> will match any group.
143 Each component listed above should contain a single value, but there
144 may be multiple instances of each component type. A sudoRole must
145 contain at least one C<sudoUser>, C<sudoHost> and C<sudoCommand>.
147 The following example allows users in group wheel to run any command
148 on any host via B<sudo>:
150 dn: cn=%wheel,ou=SUDOers,dc=example,dc=com
152 objectClass: sudoRole
158 =head2 Anatomy of LDAP sudoers lookup
160 When looking up a sudoer using LDAP there are only two or three
161 LDAP queries per invocation. The first query is to parse the global
162 options. The second is to match against the user's name and the
163 groups that the user belongs to. (The special ALL tag is matched
164 in this query too.) If no match is returned for the user's name
165 and groups, a third query returns all entries containing user
166 netgroups and checks to see if the user belongs to any of them.
168 =head2 Differences between LDAP and non-LDAP sudoers
170 There are some subtle differences in the way sudoers is handled
171 once in LDAP. Probably the biggest is that according to the RFC,
172 LDAP ordering is arbitrary and you cannot expect that Attributes
173 and Entries are returned in any specific order. If there are
174 conflicting command rules on an entry, the negative takes precedence.
175 This is called paranoid behavior (not necessarily the most specific
181 # Allow all commands except shell
182 johnny ALL=(root) ALL,!/bin/sh
183 # Always allows all commands because ALL is matched last
184 puddles ALL=(root) !/bin/sh,ALL
186 # LDAP equivalent of johnny
187 # Allows all commands except shell
188 dn: cn=role1,ou=Sudoers,dc=my-domain,dc=com
189 objectClass: sudoRole
195 sudoCommand: !/bin/sh
197 # LDAP equivalent of puddles
198 # Notice that even though ALL comes last, it still behaves like
199 # role1 since the LDAP code assumes the more paranoid configuration
200 dn: cn=role2,ou=Sudoers,dc=my-domain,dc=com
201 objectClass: sudoRole
206 sudoCommand: !/bin/sh
209 Another difference is that negations on the Host, User or Runas are
210 currently ignorred. For example, the following attributes do not
211 behave the way one might expect.
213 # does not match all but joe
214 # rather, does not match anyone
217 # does not match all but joe
218 # rather, matches everyone including Joe
222 # does not match all but web01
223 # rather, matches all hosts including web01
227 =head2 Sudoers Schema
229 In order to use B<sudo>'s LDAP support, the B<sudo> schema must be
230 installed on your LDAP server. In addition, be sure to index the
231 'sudoUser' attribute.
233 Three versions of the schema: one for OpenLDAP servers (F<schema.OpenLDAP>),
234 one for Netscape-derived servers (F<schema.iPlanet>), and one for
235 Microsoft Active Directory (F<schema.ActiveDirectory>) may
236 be found in the B<sudo> distribution.
238 The schema for B<sudo> in OpenLDAP form is included in the L<EXAMPLES>
241 =head2 Configuring ldap.conf
243 Sudo reads the F<@ldap_conf@> file for LDAP-specific configuration.
244 Typically, this file is shared amongst different LDAP-aware clients.
245 As such, most of the settings are not B<sudo>-specific. Note that
246 B<sudo> parses F<@ldap_conf@> itself and may support options
247 that differ from those described in the L<ldap.conf(5)> manual.
249 Also note that on systems using the OpenLDAP libraries, default
250 values specified in F</etc/openldap/ldap.conf> or the user's
251 F<.ldaprc> files are not used.
253 Only those options explicitly listed in F<@ldap_conf@> that are
254 supported by B<sudo> are honored. Configuration options are listed
255 below in upper case but are parsed in a case-independent manner.
259 =item B<URI> ldap[s]://[hostname[:port]] ...
261 Specifies a whitespace-delimited list of one or more URIs describing
262 the LDAP server(s) to connect to. The I<protocol> may be either B<ldap>
263 or B<ldaps>, the latter being for servers that support TLS (SSL)
264 encryption. If no I<port> is specified, the default is port 389 for
265 C<ldap://> or port 636 for C<ldaps://>. If no I<hostname> is specified,
266 B<sudo> will connect to B<localhost>. Only systems using the OpenSSL
267 libraries support the mixing of C<ldap://> and C<ldaps://> URIs.
268 The Netscape-derived libraries used on most commercial versions of
269 Unix are only capable of supporting one or the other.
271 =item B<HOST> name[:port] ...
273 If no B<URI> is specified, the B<HOST> parameter specifies a
274 whitespace-delimited list of LDAP servers to connect to. Each host
275 may include an optional I<port> separated by a colon (':'). The
276 B<HOST> parameter is deprecated in favor of the B<URI> specification
277 and is included for backwards compatibility.
279 =item B<PORT> port_number
281 If no B<URI> is specified, the B<PORT> parameter specifies the
282 default port to connect to on the LDAP server if a B<HOST> parameter
283 does not specify the port itself. If no B<PORT> parameter is used,
284 the default is port 389 for LDAP and port 636 for LDAP over TLS
285 (SSL). The B<PORT> parameter is deprecated in favor of the B<URI>
286 specification and is included for backwards compatibility.
288 =item B<BIND_TIMELIMIT> seconds
290 The B<BIND_TIMELIMIT> parameter specifies the amount of time, in seconds,
291 to wait while trying to connect to an LDAP server. If multiple B<URI>s or
292 B<HOST>s are specified, this is the amount of time to wait before trying
293 the next one in the list.
295 =item B<TIMELIMIT> seconds
297 The B<TIMELIMIT> parameter specifies the amount of time, in seconds,
298 to wait for a response to an LDAP query.
300 =item B<SUDOERS_BASE> base
302 The base DN to use when performing B<sudo> LDAP queries. Typically
303 this is of the form C<ou=SUDOers,dc=example,dc=com> for the domain
306 =item B<SUDOERS_DEBUG> debug_level
308 This sets the debug level for B<sudo> LDAP queries. Debugging
309 information is printed to the standard error. A value of 1 results
310 in a moderate amount of debugging information. A value of 2 shows
311 the results of the matches themselves. This parameter should not
312 be set in a production environment as the extra information is
313 likely to confuse users.
317 The B<BINDDN> parameter specifies the identity, in the form of a
318 Distinguished Name (DN), to use when performing LDAP operations.
319 If not specified, LDAP operations are performed with an anonymous
320 identity. By default, most LDAP servers will allow anonymous access.
322 =item B<BINDPW> secret
324 The B<BINDPW> parameter specifies the password to use when performing
325 LDAP operations. This is typically used in conjunction with the
328 =item B<ROOTBINDDN> DN
330 The B<ROOTBINDDN> parameter specifies the identity, in the form of
331 a Distinguished Name (DN), to use when performing privileged LDAP
332 operations, such as I<sudoers> queries. The password corresponding
333 to the identity should be stored in F<@ldap_secret@>.
334 If not specified, the B<BINDDN> identity is used (if any).
336 =item B<LDAP_VERSION> number
338 The version of the LDAP protocol to use when connecting to the server.
339 The default value is protocol version 3.
341 =item B<SSL> on/true/yes/off/false/no
343 If the B<SSL> parameter is set to C<on>, C<true> or C<yes>, TLS
344 (SSL) encryption is always used when communicating with the LDAP
345 server. Typically, this involves connecting to the server on port
348 =item B<SSL> start_tls
350 If the B<SSL> parameter is set to C<start_tls>, the LDAP server
351 connection is initiated normally and TLS encryption is begun before
352 the bind credentials are sent. This has the advantage of not
353 requiring a dedicated port for encrypted communications. This
354 parameter is only supported by LDAP servers that honor the C<start_tls>
355 extension, such as the OpenLDAP server.
357 =item B<TLS_CHECKPEER> on/true/yes/off/false/no
359 If enabled, B<TLS_CHECKPEER> will cause the LDAP server's TLS
360 certificated to be verified. If the server's TLS certificate cannot
361 be verified (usually because it is signed by an unknown certificate
362 authority), B<sudo> will be unable to connect to it. If B<TLS_CHECKPEER>
363 is disabled, no check is made.
365 =item B<TLS_CACERTFILE> file name
367 The path to a certificate authority bundle which contains the certificates
368 for all the Certificate Authorities the client knows to be valid,
369 e.g. F</etc/ssl/ca-bundle.pem>.
370 This option is only supported by the OpenLDAP libraries.
372 =item B<TLS_CACERTDIR> directory
374 Similar to B<TLS_CACERTFILE> but instead of a file, it is a
375 directory containing individual Certificate Authority certificates,
376 e.g. F</etc/ssl/certs>.
377 The directory specified by B<TLS_CACERTDIR> is checked after
379 This option is only supported by the OpenLDAP libraries.
381 =item B<TLS_CERT> file name
383 The path to a file containing the client certificate which can
384 be used to authenticate the client to the LDAP server.
385 The certificate type depends on the LDAP libraries used.
388 C<tls_cert /etc/ssl/client_cert.pem>
391 C<tls_cert /var/ldap/cert7.db>
393 When using Netscape-derived libraries, this file may also contain
394 Certificate Authority certificates.
396 =item B<TLS_KEY> file name
398 The path to a file containing the private key which matches the
399 certificate specified by B<TLS_CERT>. The private key must not be
400 password-protected. The key type depends on the LDAP libraries
404 C<tls_key /etc/ssl/client_key.pem>
407 C<tls_key /var/ldap/key3.db>
409 =item B<TLS_RANDFILE> file name
411 The B<TLS_RANDFILE> parameter specifies the path to an entropy
412 source for systems that lack a random device. It is generally used
413 in conjunction with I<prngd> or I<egd>.
414 This option is only supported by the OpenLDAP libraries.
416 =item B<TLS_CIPHERS> cipher list
418 The B<TLS_CIPHERS> parameter allows the administer to restrict
419 which encryption algorithms may be used for TLS (SSL) connections.
420 See the OpenSSL manual for a list of valid ciphers.
421 This option is only supported by the OpenLDAP libraries.
423 =item B<USE_SASL> on/true/yes/off/false/no
425 Enable B<USE_SASL> for LDAP servers that support SASL authentication.
427 =item B<SASL_AUTH_ID> identity
429 The SASL user name to use when connecting to the LDAP server.
430 By default, B<sudo> will use an anonymous connection.
432 =item B<ROOTUSE_SASL> on/true/yes/off/false/no
434 Enable B<ROOTUSE_SASL> to enable SASL authentication when connecting
435 to an LDAP server from a privileged process, such as B<sudo>.
437 =item B<ROOTSASL_AUTH_ID> identity
439 The SASL user name to use when B<ROOTUSE_SASL> is enabled.
441 =item B<SASL_SECPROPS> none/properties
443 SASL security properties or I<none> for no properties. See the
444 SASL programmer's manual for details.
446 =item B<KRB5_CCNAME> file name
448 The path to the Kerberos 5 credential cache to use when authenticating
449 with the remote server.
453 See the C<ldap.conf> entry in the L<EXAMPLES> section.
455 =head2 Configuring nsswitch.conf
457 Unless it is disabled at build time, B<sudo> consults the Name
458 Service Switch file, F<@nsswitch_conf@>, to specify the I<sudoers>
459 search order. Sudo looks for a line beginning with C<sudoers>: and
460 uses this to determine the search order. Note that B<sudo> does
461 not stop searching after the first match and later matches take
462 precedence over earlier ones.
464 The following sources are recognized:
466 files read sudoers from F<@sysconfdir@/sudoers>
467 ldap read sudoers from LDAP
469 In addition, the entry C<[NOTFOUND=return]> will short-circuit the
470 search if the user was not found in the preceding source.
472 To consult LDAP first followed by the local sudoers file (if it
477 The local I<sudoers> file can be ignored completely by using:
481 If the F<@nsswitch_conf@> file is not present or there is no
482 sudoers line, the following default is assumed:
486 Note that F<@nsswitch_conf@> is supported even when the underlying
487 operating system does not use an nsswitch.conf file.
489 =head2 Configuring netsvc.conf
491 On AIX systems, the F<@netsvc_conf@> file is consulted instead of
492 F<@nsswitch_conf@>. B<sudo> simply treats I<netsvc.conf> as a
493 variant of I<nsswitch.conf>; information in the previous section
494 unrelated to the file format itself still applies.
496 To consult LDAP first followed by the local sudoers file (if it
499 sudoers = ldap, files
501 The local I<sudoers> file can be ignored completely by using:
505 To treat LDAP as authoratative and only use the local sudoers file
506 if the user is not present in LDAP, use:
508 sudoers = ldap = auth, files
510 Note that in the above example, the C<auth> qualfier only affects
511 user lookups; both LDAP and I<sudoers> will be queried for C<Defaults>
514 If the F<@netsvc_conf@> file is not present or there is no
515 sudoers line, the following default is assumed:
525 LDAP configuration file
527 =item F<@nsswitch_conf@>
529 determines sudoers source order
531 =item F<@netsvc_conf@>
533 determines sudoers source order on AIX
539 =head2 Example ldap.conf
541 # Either specify one or more URIs or one or more host:port pairs.
542 # If neither is specified sudo will default to localhost, port 389.
545 #host ldapserver1 ldapserver2:390
547 # Default port if host is specified without one, defaults to 389.
550 # URI will override the host and port settings.
551 uri ldap://ldapserver
552 #uri ldaps://secureldapserver
553 #uri ldaps://secureldapserver ldap://ldapserver
555 # The amount of time, in seconds, to wait while trying to connect to
559 # The amount of time, in seconds, to wait while performing an LDAP query.
562 # must be set or sudo will ignore LDAP
563 sudoers_base ou=SUDOers,dc=example,dc=com
565 # verbose sudoers matching from ldap
568 # optional proxy credentials
569 #binddn <who to search as>
571 #rootbinddn <who to search as, uses /etc/ldap.secret for bindpw>
573 # LDAP protocol version, defaults to 3
576 # Define if you want to use an encrypted LDAP connection.
577 # Typically, you must also set the port to 636 (ldaps).
580 # Define if you want to use port 389 and switch to
581 # encryption before the bind credentials are sent.
582 # Only supported by LDAP servers that support the start_tls
583 # extension such as OpenLDAP.
586 # Additional TLS options follow that allow tweaking of the
587 # SSL/TLS connection.
589 #tls_checkpeer yes # verify server SSL certificate
590 #tls_checkpeer no # ignore server SSL certificate
592 # If you enable tls_checkpeer, specify either tls_cacertfile
593 # or tls_cacertdir. Only supported when using OpenLDAP.
595 #tls_cacertfile /etc/certs/trusted_signers.pem
596 #tls_cacertdir /etc/certs
598 # For systems that don't have /dev/random
599 # use this along with PRNGD or EGD.pl to seed the
600 # random number pool to generate cryptographic session keys.
601 # Only supported when using OpenLDAP.
603 #tls_randfile /etc/egd-pool
605 # You may restrict which ciphers are used. Consult your SSL
606 # documentation for which options go here.
607 # Only supported when using OpenLDAP.
609 #tls_ciphers <cipher-list>
611 # Sudo can provide a client certificate when communicating to
614 # * Enable both lines at the same time.
615 # * Do not password protect the key file.
616 # * Ensure the keyfile is only readable by root.
619 #tls_cert /etc/certs/client_cert.pem
620 #tls_key /etc/certs/client_key.pem
622 # For SunONE or iPlanet LDAP, tls_cert and tls_key may specify either
623 # a directory, in which case the files in the directory must have the
624 # default names (e.g. cert8.db and key4.db), or the path to the cert
625 # and key files themselves. However, a bug in version 5.0 of the LDAP
626 # SDK will prevent specific file names from working. For this reason
627 # it is suggested that tls_cert and tls_key be set to a directory,
630 # The certificate database specified by tls_cert may contain CA certs
631 # and/or the client's cert. If the client's cert is included, tls_key
632 # should be specified as well.
633 # For backward compatibility, "sslpath" may be used in place of tls_cert.
637 # If using SASL authentication for LDAP (OpenSSL)
639 # sasl_auth_id <SASL username>
641 # rootsasl_auth_id <SASL username for root access>
643 # krb5_ccname /etc/.ldapcache
645 =head2 Sudo schema for OpenLDAP
647 The following schema is in OpenLDAP format. Simply copy it to the
648 schema directory (e.g. F</etc/openldap/schema>), add the proper
649 C<include> line in C<slapd.conf> and restart B<slapd>.
651 attributetype ( 1.3.6.1.4.1.15953.9.1.1
653 DESC 'User(s) who may run sudo'
654 EQUALITY caseExactIA5Match
655 SUBSTR caseExactIA5SubstringsMatch
656 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
658 attributetype ( 1.3.6.1.4.1.15953.9.1.2
660 DESC 'Host(s) who may run sudo'
661 EQUALITY caseExactIA5Match
662 SUBSTR caseExactIA5SubstringsMatch
663 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
665 attributetype ( 1.3.6.1.4.1.15953.9.1.3
667 DESC 'Command(s) to be executed by sudo'
668 EQUALITY caseExactIA5Match
669 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
671 attributetype ( 1.3.6.1.4.1.15953.9.1.4
673 DESC 'User(s) impersonated by sudo'
674 EQUALITY caseExactIA5Match
675 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
677 attributetype ( 1.3.6.1.4.1.15953.9.1.5
679 DESC 'Options(s) followed by sudo'
680 EQUALITY caseExactIA5Match
681 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
683 attributetype ( 1.3.6.1.4.1.15953.9.1.6
685 DESC 'User(s) impersonated by sudo'
686 EQUALITY caseExactIA5Match
687 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
689 attributetype ( 1.3.6.1.4.1.15953.9.1.7
690 NAME 'sudoRunAsGroup'
691 DESC 'Group(s) impersonated by sudo'
692 EQUALITY caseExactIA5Match
693 SYNTAX 1.3.6.1.4.1.1466.115.121.1.26 )
695 objectclass ( 1.3.6.1.4.1.15953.9.2.1 NAME 'sudoRole' SUP top STRUCTURAL
696 DESC 'Sudoer Entries'
698 MAY ( sudoUser $ sudoHost $ sudoCommand $ sudoRunAs $ sudoRunAsUser $
699 sudoRunAsGroup $ sudoOption $ description )
704 L<ldap.conf(5)>, L<sudoers(5)>
708 The way that I<sudoers> is parsed differs between Note that there
709 are differences in the way that LDAP-based I<sudoers> is parsed
710 compared to file-based I<sudoers>. See the L<Differences between
711 LDAP and non-LDAP sudoers> section for more information.
715 If you feel you have found a bug in B<sudo>, please submit a bug report
716 at http://www.sudo.ws/sudo/bugs/
720 Limited free support is available via the sudo-users mailing list,
721 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
726 B<sudo> is provided ``AS IS'' and any express or implied warranties,
727 including, but not limited to, the implied warranties of merchantability
728 and fitness for a particular purpose are disclaimed. See the LICENSE
729 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
730 for complete details.