1This file explains how to build the optional LDAP functionality of SUDO to
2store /etc/sudoers information.  This feature is distinct from LDAP passwords.
3
4For general sudo LDAP configuration details, see the sudoers.ldap manual that
5comes with the sudo distribution.  A pre-formatted version of the manual may
6be found in the sudoers.ldap.cat file.
7
8The sudo binary compiled with LDAP support should be totally backward
9compatible and be syntactically and source code equivalent to its
10non LDAP-enabled build.
11
12LDAP philosophy
13===============
14As times change and servers become cheap, an enterprise can easily have 500+
15UNIX servers.  Using LDAP to synchronize Users, Groups, Hosts, Mounts, and
16others across an enterprise can greatly reduce the administrative overhead.
17
18In the past, sudo has used a single local configuration file, /etc/sudoers.
19While the same sudoers file can be shared among machines, no built-in
20mechanism exists to distribute it.  Some have attempted to workaround this
21by synchronizing changes via CVS/RSYNC/RDIST/RCP/SCP and even NFS.
22
23By using LDAP for sudoers we gain a centrally administered, globally
24available configuration source for sudo.
25
26For information on OpenLDAP, please see http://www.openldap.org/.
27
28Definitions
29===========
30Many times the word 'Directory' is used in the document to refer to the LDAP
31server, structure and contents.
32
33Many times 'options' are used in this document to refer to sudoer 'defaults'.
34They are one and the same.
35
36Build instructions
37==================
38The simplest way to build sudo with LDAP support is to include the
39'--with-ldap' option.
40
41  $ ./configure --with-ldap
42
43If your ldap libraries and headers are in a non-standard place, you will need
44to specify them at configure time.  E.g.
45
46  $ ./configure --with-ldap=/usr/local/ldapsdk
47
48Sudo is developed using OpenLDAP but Netscape-based LDAP libraries
49(such as those present in Solaris) are also known to work.
50
51Your mileage may vary.  Please let the sudo workers mailing list
52<sudo-workers@sudo.ws> know if special configuration was required
53to build an LDAP-enabled sudo so we can improve sudo.
54
55Schema Changes
56==============
57You must add the appropriate schema to your LDAP server before it
58can store sudoers content.
59
60For OpenLDAP, copy the file schema.OpenLDAP to the schema directory
61(e.g. /etc/openldap/schema).  You must then edit your slapd.conf and
62add an include line the new schema, e.g.
63
64    # Sudo LDAP schema
65    include	/etc/openldap/schema/sudo.schema
66
67In order for sudoRole LDAP queries to be efficient, the server must index
68the attribute 'sudoUser', e.g.
69
70    # Indices to maintain
71    index	sudoUser	eq
72
73After making the changes to slapd.conf, restart slapd.
74
75For Netscape-derived LDAP servers such as SunONE, iPlanet or Fedora Directory,
76copy the schema.iPlanet file to the schema directory with the name 99sudo.ldif.
77
78On Solaris, schemas are stored in /var/Sun/mps/slapd-`hostname`/config/schema/.
79For Fedora Directory Server, they are stored in /etc/dirsrv/schema/.
80
81After copying the schema file to the appropriate directory, restart
82the LDAP server.
83
84Finally, using an LDAP browser/editor, enable indexing by editing the
85client profile to provide a Service Search Descriptor (SSD) for sudoers,
86replacing example.com with your domain:
87
88    serviceSearchDescriptor: sudoers: ou=sudoers,dc=example,dc=com
89
90If using an Active Directory server, copy schema.ActiveDirectory
91to your Windows domain controller and run the following command:
92
93    ldifde -i -f schema.ActiveDirectory -c dc=X dc=example,dc=com
94
95Importing /etc/sudoers into LDAP
96================================
97Importing sudoers is a two-step process.
98
99Step 1:
100Ask your LDAP Administrator where to create the ou=SUDOers container.
101
102For instance, if using OpenLDAP:
103
104  dn: ou=SUDOers,dc=example,dc=com
105  objectClass: top
106  objectClass: organizationalUnit
107  ou: SUDOers
108
109(An example location is shown below).  Then use the provided script to convert
110your sudoers file into LDIF format.  The script will also convert any default
111options.
112
113  # SUDOERS_BASE=ou=SUDOers,dc=example,dc=com
114  # export SUDOERS_BASE
115  # ./sudoers2ldif /etc/sudoers > /tmp/sudoers.ldif
116
117Step 2:
118Import into your directory server.  The following example is for
119OpenLDAP.  If you are using another directory, provide the LDIF
120file to your LDAP Administrator.
121
122  # ldapadd -f /tmp/sudoers.ldif -h ldapserver \
123    -D cn=Manager,dc=example,dc=com -W -x
124
125Managing LDAP entries
126=====================
127Doing a one-time bulk load of your ldap entries is fine.  However what if you
128need to make minor changes on a daily basis?  It doesn't make sense to delete
129and re-add objects.  (You can, but this is tedious).
130
131I recommend using any of the following LDAP browsers to administer your SUDOers.
132  * GQ - The gentleman's LDAP client - Open Source - I use this a lot on Linux
133    and since it is Schema aware, I don't need to create a sudoRole template.
134	http://biot.com/gq/
135
136  * phpQLAdmin - Open Source - phpQLAdmin is an administration tool,
137    originally for QmailLDAP, that supports editing sudoRole objects
138    in version 2.3.2 and higher.
139	http://phpqladmin.com/
140
141  * LDAP Browser/Editor - by Jarek Gawor - I use this a lot on Windows
142    and Solaris.  It runs anywhere in a Java Virtual Machine including
143    web pages.  You have to make a template from an existing sudoRole entry.
144	http://www.iit.edu/~gawojar/ldap
145	http://www.mcs.anl.gov/~gawor/ldap
146	http://ldapmanager.com
147
148  * Apache Directory Studio - Open Source - an Eclipse-based LDAP
149    development platform.  Includes an LDAP browser, and LDIF editor,
150    a schema editor and more.
151    http://directory.apache.org/studio
152
153  There are dozens of others, some Open Source, some free, some not.
154
155Configure your /etc/ldap.conf and /etc/nsswitch.conf
156====================================================
157The /etc/ldap.conf file is meant to be shared between sudo, pam_ldap, nss_ldap
158and other ldap applications and modules.  IBM Secureway unfortunately uses
159the same file name but has a different syntax.  If you need to change where
160this file is stored, re-run configure with the --with-ldap-conf-file=PATH
161option.
162
163See the "Configuring ldap.conf" section in the sudoers.ldap manual
164for a list of supported ldap.conf parameters and an example ldap.conf
165
166Make sure you sudoers_base matches the location you specified when you
167imported the sudoers ldif data.
168
169After configuring /etc/ldap.conf, you must add a line in /etc/nsswitch.conf
170to tell sudo to look in LDAP for sudoers.  See the "Configuring nsswitch.conf"
171section in the sudoers.ldap manual for details.  Note that sudo will use
172/etc/nsswitch.conf even if the underlying operating system does not support it.
173To disable nsswitch support, run configure with the --with-nsswitch=no option.
174This will cause sudo to consult LDAP first and /etc/sudoers second, unless the
175ignore_sudoers_file flag is set in the global LDAP options.
176
177Debugging your LDAP configuration
178=================================
179Enable debugging if you believe sudo is not parsing LDAP the way you think it
180should.  Setting the 'sudoers_debug' parameter to a value of 1 shows moderate
181debugging.  A value of 2 shows the results of the matches themselves.  Make
182sure to set the value back to zero so that other users don't get confused by
183the debugging messages.
184