1 I'm using [LDAP][] ([RFC 4510][rfc4510]) to maintain a centralized
2 address book at home. Here are my setup notes, mostly following
3 Gentoo's [LDAP howto][howto].
5 Install [OpenLDAP][] with the `ldap` USE flag enabled:
9 If you get complaints about a `cyrus-sasl` ↔ `openldap` dependency
10 cycle, you should temporarily (or permanently) disable the `ldap` USE
11 flag for `cyrus-sasl`:
13 # echo 'dev-libs/cyrus-sasl -ldap' > /etc/portage/package.use/ldap
14 # -ldap" emerge -av1 cyrus-sasl
17 Generate an administrative password:
21 Re-enter new password:
22 {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
24 Configure the `slapd` LDAP server. Here is a very minimal
25 configuration, read the [OpenLDAP Admin Guide][admin] for details:
27 # emacs /etc/openldap/slapd.conf
28 # cat /etc/openldap/slapd.conf
29 include /etc/openldap/schema/core.schema
30 include /etc/openldap/schema/cosine.schema
31 include /etc/openldap/schema/inetorgperson.schema
32 pidfile /var/run/openldap/slapd.pid
33 argsfile /var/run/openldap/slapd.args
35 suffix "dc=example,dc=com"
37 rootdn "cn=Manager,dc=example,dc=com"
38 rootpw {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
39 directory /var/lib/openldap-data
42 Note that [inetorgperson][] is huge, but it's standardized. I think
43 it's better to pick a big standard right off, than to outgrow
44 something smaller and need to migrate.
46 Gentoo creates the default database directory for you, so you can ignore warnings about needing to create it yourself.
48 Configure LDAP client access. Again, read the docs for details on
49 adapting this to your particular situation:
51 # emacs /etc/openldap/ldap.conf
52 $ cat /etc/openldap/ldap.conf
53 BASE dc=example,dc=com
54 URI ldap://ldapserver.example.com
56 You can edit '/etc/conf.d/slapd' if you want command line options
57 passed to `slapd` when the service starts, but the defaults looked
62 # /etc/init.d/slapd start
64 Add it to your default runlevel:
66 # eselect rc add /etc/init.d/slapd default
70 $ ldapsearch -x -b '' -s base '(objectclass=*)'
72 Build a hierarchy in your database (this will depend on your
73 organizational structure):
75 $ emacs /tmp/people.ldif
76 $ cat /tmp/people.ldif
79 dn: dc=example, dc=com
81 objectClass: organization
85 dn: ou=people, dc=example,dc=com
86 objectClass: organizationalUnit
88 description: All people in organisation
90 dn: cn=Manager, dc=example,dc=com
91 objectClass: organizationalRole
93 description: Directory Manager
94 $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/people.ldif
100 If you currently keep your addresses in [abook][], you can export them
103 $ abook --convert --infile ~/.abook/addressbook --outformat ldif \
104 | abook-ldif-cleanup.py --basedn 'ou=people,dc=example,dc=com' > dump.ldif
106 where [[abook-ldif-cleanup.py]] does some compatibility processing
107 using the [python-ldap][] module.
109 Add the people to your LDAP database:
111 $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f dump.ldif
113 To check if that worked, you can list all the entries in your
116 $ ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'
118 Then remove the temporary files:
125 Ok, we've put lots of people into the `people` OU, but what if we want
126 to assign them to another department? We can use aliases ([RFC
127 4512][rfc4512]), the symlinks of the LDAP world. To see how this
128 works, lets create a test OU to play with:
130 $ emacs /tmp/test.ldif
133 dn: ou=test, dc=example,dc=com
134 objectClass: organizationalUnit
136 $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/test.ldif
139 Now assign one of your people to that group:
141 $ emacs /tmp/alias.ldif
142 $ cat /tmp/alias.ldif
144 dn: cn=Jane Doe, ou=test,dc=example,dc=com
146 aliasedObjectName: cn=Jane Doe, ou=people,dc=example,dc=com
147 $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/alias.ldif
150 The `extensibleObject` class allows us to add the DN field, without it
153 $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/alias.ldif
155 adding new entry "cn=Jane Doe, ou=test,dc=example,dc=com"
156 ldap_add: Object class violation (65)
157 additional info: attribute 'cn' not allowed
159 You can search for all entries (including aliases) with
161 $ ldapsearch -x -b 'ou=test, dc=example,dc=com' '(objectclass=*)'
163 dn: cn=Jane Doe,ou=test,dc=example,dc=com
165 objectClass: extensibleObject
166 aliasedObjectName:: Y249TWljaGVsIFZhbGxpw6hyZXMsb3U9cGVvcGxlLGRjPXRyZW1pbHksZGM9dXM=
169 You can control dereferencing with the `-a` option:
171 $ ldapsearch -x -a always -b 'ou=test, dc=example,dc=com' '(objectclass=*)'
173 dn: cn=Jane Doe,ou=people,dc=example,dc=com
178 Once you've played around, you can remove the `test` OU and its
181 $ ldapdelete -D "cn=Manager,dc=example,dc=com" -xW -r ou=test,dc=example,dc=com
186 There are a number of tools to make it easier to manage LDAP
187 databases. Command line junkies will probably like [shelldap][]:
189 $ shelldap --server ldapserver.example.com
195 dn: cn=Manager,dc=example,dc=com
196 objectClass: organizationalRole
205 If you use the [[Mutt]] email client (or just want a simple way to
206 query email addresses from the command line) there are a [number of
207 scripts][mutts] available. Pick whichever sounds most appealing to
208 you. I wrote up [[mutt-ldap.py]], which lets you configuration the
209 connection details via a config file (`~/.mutt-ldap.rc`) rather than
210 editing the script itself. Usage details are available in the
216 It took me a bit of work to get [SSL/TLS][] working with my
217 [[GnuTLS]]-linked OpenLDAP. First, you'll probably need to generate
218 new SSL/TLS keys (`/etc/openldap/ssl/*`) with [certtool][] (see
219 [[X.509_certificates]]). Then add the following lines to
220 `/etc/openldap/slapd.conf`:
222 TLSCipherSuite NORMAL
223 TLSCACertificateFile /etc/openldap/ssl/ca.crt
224 TLSCertificateFile /etc/openldap/ssl/ldap.crt
225 TLSCertificateKeyFile /etc/openldap/ssl/ldap.key
226 TLSVerifyClient never
228 Where `ca.crt`, `ldap.crt`, and `ldap.key` are your new CA,
229 certificate, and private key. If you want to disable unencrypted
230 connections completely, remove the `ldap://` entry from your `slapd`
231 command line by editing (on Gentoo) `/etc/conf.d/slapd` so it has
233 OPTS="-h 'ldaps:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
235 Now you should be able to restart `slapd` so it will use the new
238 Have clients running on your server use the local socket by editing
239 `/etc/openldap/ldap.conf` to set:
241 URI ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock
243 Test your server setup by running (on the server)
245 $ ldapsearch -x -b '' -s base '(objectclass=*)'
247 Copy your CA over to any client machines (I put it in
248 `/etc/openldap/ssl/ldapserver.crt`), and set them up with the
249 following two lines in `/etc/openldap/ldap.conf`:
251 URI ldaps://ldapserver.example.com
252 TLS_CACERT /etc/openldap/ssl/ldapserver.crt
254 Test your client setup by running (on the client)
256 $ ldapsearch -x -b '' -s base '(objectclass=*)'
258 You can configure `shelldap` with the following lines in
261 server: ldaps://ldapserver.example.com
263 tls_cacert: /etc/openldap/ssl/ldapserver.crt
265 You can configure `mutt-ldap.py` with the following lines in
274 There's a [good overview][schema] of schema and objectclasses by Brian
275 Jones on O'Reilly. If you want to use inetOrgPerson but also include
276 the countryName attribute, ...
278 [LDAP]: http://en.wikipedia.org/wiki/LDAP
279 [rfc4510]: http://tools.ietf.org/html/rfc4510
280 [howto]: http://www.gentoo.org/doc/en/ldap-howto.xml
281 [OpenLDAP]: http://www.openldap.org/
282 [admin]: http://www.openldap.org/doc/admin/
283 [inetorgperson]: http://www.apps.ietf.org/rfc/rfc2798.html
284 [abook]: http://abook.sourceforge.net/
285 [LDIF]: http://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format
286 [python-ldap]: http://www.python-ldap.org/
287 [rfc4512]: http://tools.ietf.org/html/rfc4512
288 [shelldap]: http://projects.martini.nu/shelldap/
289 [mutts]: http://wiki.mutt.org/?QueryCommand
290 [SSL/TLS]: http://en.wikipedia.org/wiki/Transport_Layer_Security
291 [certtool]:http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html#Invoking-certtool
292 [schema]: http://www.oreillynet.com/pub/a/sysadmin/2006/11/09/demystifying-ldap-data.html