posts/LDAP.mdwn

   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].
   4
   5 Install [OpenLDAP][] with the `ldap` USE flag enabled:
   6
   7     # emerge -av openldap
   8
   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`:
  12
  13     # echo 'dev-libs/cyrus-sasl -ldap' > /etc/portage/package.use/ldap
  14     # -ldap" emerge -av1 cyrus-sasl
  15     # emerge -av openldap
  16
  17 Generate an administrative password:
  18
  19     $ slappasswd
  20     New password:
  21     Re-enter new password:
  22     {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
  23
  24 Configure the `slapd` LDAP server.  Here is a very minimal
  25 configuration, read the [OpenLDAP Admin Guide][admin] for details:
  26
  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
  34     database        hdb
  35     suffix          "dc=example,dc=com"
  36     checkpoint      32      30
  37     rootdn          "cn=Manager,dc=example,dc=com"
  38     rootpw          {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
  39     directory       /var/lib/openldap-data
  40     index   objectClass     eq
  41
  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.
  45
  46 Gentoo creates the default database directory for you, so you can
  47 ignore warnings about needing to create it yourself.
  48
  49 Configure LDAP client access.  Again, read the docs for details on
  50 adapting this to your particular situation:
  51
  52     # emacs /etc/openldap/ldap.conf
  53     $ cat /etc/openldap/ldap.conf
  54     BASE    dc=example,dc=com
  55     URI     ldap://ldapserver.example.com
  56
  57 You can edit '/etc/conf.d/slapd' if you want command line options
  58 passed to `slapd` when the service starts, but the defaults looked
  59 fine to me.
  60
  61 Start `slapd`:
  62
  63     # /etc/init.d/slapd start
  64
  65 Add it to your default runlevel:
  66
  67     # eselect rc add /etc/init.d/slapd default
  68
  69 Test the server with
  70
  71     $ ldapsearch -x -b '' -s base '(objectclass=*)'
  72
  73 Build a hierarchy in your database (this will depend on your
  74 organizational structure):
  75
  76     $ emacs /tmp/people.ldif
  77     $ cat /tmp/people.ldif
  78     version: 1
  79
  80     dn: dc=example, dc=com
  81     objectClass: dcObject
  82     objectClass: organization
  83     o: Example, Inc.
  84     dc: example
  85
  86     dn: ou=people, dc=example,dc=com
  87     objectClass: organizationalUnit
  88     ou: people
  89     description: All people in organisation
  90
  91     dn: cn=Manager, dc=example,dc=com
  92     objectClass: organizationalRole
  93     cn: Manager
  94     description: Directory Manager
  95     $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/people.ldif
  96     $ rm /tmp/people.ldif
  97
  98 abook
  99 -----
 100
 101 If you currently keep your addresses in [abook][], you can export them
 102 to [LDIF][] with:
 103
 104     $ abook --convert --infile ~/.abook/addressbook --outformat ldif \
 105       | abook-ldif-cleanup.py --basedn 'ou=people,dc=example,dc=com' > dump.ldif
 106
 107 where [[abook-ldif-cleanup.py]] does some compatibility processing
 108 using the [python-ldap][] module.
 109
 110 Add the people to your LDAP database:
 111
 112     $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f dump.ldif
 113
 114 To check if that worked, you can list all the entries in your
 115 database:
 116
 117     $ ldapsearch -x -b 'dc=example,dc=com' '(objectclass=*)'
 118
 119 Then remove the temporary files:
 120
 121     $ rm -rf dump.ldif
 122
 123 Aliases
 124 -------
 125
 126 Ok, we've put lots of people into the `people` OU, but what if we want
 127 to assign them to another department?  We can use aliases ([RFC
 128 4512][rfc4512]), the symlinks of the LDAP world.  To see how this
 129 works, lets create a test OU to play with:
 130
 131     $ emacs /tmp/test.ldif
 132     $ cat /tmp/test.ldif
 133     version: 1
 134     dn: ou=test, dc=example,dc=com
 135     objectClass: organizationalUnit
 136     ou: testing
 137     $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/test.ldif
 138     $ rm /tmp/test.ldif
 139
 140 Now assign one of your people to that group:
 141
 142     $ emacs /tmp/alias.ldif
 143     $ cat /tmp/alias.ldif
 144     version: 1
 145     dn: cn=Jane Doe, ou=test,dc=example,dc=com
 146     objectClass: alias
 147     aliasedObjectName: cn=Jane Doe, ou=people,dc=example,dc=com
 148     $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/alias.ldif
 149     $ rm /tmp/alias.ldif
 150
 151 The `extensibleObject` class allows us to add the DN field, without it
 152 you get:
 153
 154     $ ldapadd -D "cn=Manager,dc=example,dc=com" -xW -f /tmp/alias.ldif
 155     Enter LDAP Password:
 156     adding new entry "cn=Jane Doe, ou=test,dc=example,dc=com"
 157     ldap_add: Object class violation (65)
 158             additional info: attribute 'cn' not allowed
 159
 160 You can search for all entries (including aliases) with
 161
 162     $ ldapsearch -x -b 'ou=test, dc=example,dc=com' '(objectclass=*)'
 163     ...
 164     dn: cn=Jane Doe,ou=test,dc=example,dc=com
 165     objectClass: alias
 166     objectClass: extensibleObject
 167     aliasedObjectName:: Y249TWljaGVsIFZhbGxpw6hyZXMsb3U9cGVvcGxlLGRjPXRyZW1pbHksZGM9dXM=
 168     ...
 169
 170 You can control dereferencing with the `-a` option:
 171
 172     $ ldapsearch -x -a always -b 'ou=test, dc=example,dc=com' '(objectclass=*)'
 173     ...
 174     dn: cn=Jane Doe,ou=people,dc=example,dc=com
 175     cn: Jane Doe
 176     sn: Doe
 177     ...
 178
 179 Once you've played around, you can remove the `test` OU and its
 180 descendants:
 181
 182     $ ldapdelete -D "cn=Manager,dc=example,dc=com" -xW -r ou=test,dc=example,dc=com
 183
 184 shelldap
 185 --------
 186
 187 There are a number of tools to make it easier to manage LDAP
 188 databases.  Command line junkies will probably like [shelldap][]:
 189
 190     $ shelldap --server ldapserver.example.com
 191     ~ > ls
 192     cn=Manager
 193     ou=people
 194     ~ > cat cn=Manager
 195
 196     dn: cn=Manager,dc=example,dc=com
 197     objectClass: organizationalRole
 198     cn: Manager
 199
 200     ~ > cd ou=people
 201     ou=people,~ > ls
 202
 203 Mutt
 204 ----
 205
 206 If you use the [[Mutt]] email client (or just want a simple way to
 207 query email addresses from the command line) there are a [number of
 208 scripts][mutts] available.  Pick whichever sounds most appealing to
 209 you.  I wrote up [[mutt-ldap.py]], which lets you configuration the
 210 connection details via a config file (`~/.mutt-ldap.rc`) rather than
 211 editing the script itself.  Usage details are available in the
 212 docstring.
 213
 214 Apple Address Book
 215 ------------------
 216
 217 You can configure Apple's [Address Book][aab] to search an LDAP
 218 directory.  See [[Humanizing_OS_X]] for details.
 219
 220 SSL/TLS
 221 -------
 222
 223 It took me a bit of work to get [SSL/TLS][] working with my
 224 [[GnuTLS]]-linked OpenLDAP.  First, you'll probably need to generate
 225 new SSL/TLS keys (`/etc/openldap/ssl/*`) with [certtool][] (see
 226 [[X.509_certificates]]).  Then add the following lines to
 227 `/etc/openldap/slapd.conf`:
 228
 229     TLSCipherSuite NORMAL
 230     TLSCACertificateFile /etc/openldap/ssl/ca.crt
 231     TLSCertificateFile /etc/openldap/ssl/ldap.crt
 232     TLSCertificateKeyFile /etc/openldap/ssl/ldap.key
 233     TLSVerifyClient never
 234
 235 Where `ca.crt`, `ldap.crt`, and `ldap.key` are your new CA,
 236 certificate, and private key.  If you want to disable unencrypted
 237 connections completely, remove the `ldap://` entry from your `slapd`
 238 command line by editing (on Gentoo) `/etc/conf.d/slapd` so it has
 239
 240     OPTS="-h 'ldaps:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
 241
 242 Now you should be able to restart `slapd` so it will use the new
 243 configuration.
 244
 245 Have clients running on your server use the local socket by editing
 246 `/etc/openldap/ldap.conf` to set:
 247
 248     URI     ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock
 249
 250 Test your server setup by running (on the server)
 251
 252     $ ldapsearch -x -b '' -s base '(objectclass=*)'
 253
 254 Copy your CA over to any client machines (I put it in
 255 `/etc/openldap/ssl/ldapserver.crt`), and set them up with the
 256 following two lines in `/etc/openldap/ldap.conf`:
 257
 258     URI         ldaps://ldapserver.example.com
 259     TLS_CACERT  /etc/openldap/ssl/ldapserver.crt
 260
 261 Test your client setup by running (on the client)
 262
 263     $ ldapsearch -x -b '' -s base '(objectclass=*)'
 264
 265 You can configure `shelldap` with the following lines in
 266 `~/.shelldap.rc`:
 267
 268     server: ldaps://ldapserver.example.com
 269     tls: yes
 270     tls_cacert: /etc/openldap/ssl/ldapserver.crt
 271
 272 You can configure `mutt-ldap.py` with the following lines in
 273 `~/.mutt-ldap.rc`:
 274
 275     port = 636
 276     ssl = yes
 277
 278 Debian-based systems
 279 --------------------
 280
 281 I wanted to mirror my home LDAP info on my public Ubuntu server.
 282 Here's a quick rundown of the Ubuntu setup.  Install OpenLDAP:
 283
 284     $ sudo apt-get install slapd ldap-utils
 285
 286 Don't serve in the clear:
 287
 288     $ cat /etc/default/slapd
 289     ...
 290     SLAPD_SERVICES="ldaps:/// ldapi:///"
 291     ...
 292
 293 Avoid `Unrecognized database type (hdb)` by loading the `hdb` backend
 294 module before declaring `hdb` databases:
 295
 296     $ sudo cat /etc/ldap/slapd.conf
 297     ...
 298     moduleload back_hdb
 299     database hdb
 300     ...
 301
 302 Convert the old school `slapd.conf` to the new [slapd.d][]:
 303
 304     $ sudo mv slapd.d{,.bak}
 305     $ sudo mkdir slapd.d
 306     $ sudo slaptest -f slapd.conf -F slapd.d
 307     ...
 308     hdb_db_open: database "dc=example,dc=com": db_open(/var/lib/slapd/id2entry.bdb) failed: No such file or directory (2).
 309     ...
 310     slap_startup failed (test would succeed using the -u switch)
 311     ...
 312     $ sudo chown -R openldap.openldap slapd.d
 313
 314 Don't worry about that `db_open` error, the conversion to `slapd.d`
 315 will have completed successfully.
 316
 317 Set permissions on the database directory (note that the databases
 318 should be under `/var/lib/ldap` to match Ubuntu's default apparmor
 319 config.  Otherwise you'll see `invalid path: Permission denied` errors
 320 when `slapd` tries to initialize the databaes).
 321
 322     $ sudo chown openldap.openldap /var/lib/ldap/
 323     $ sudo chmod 750 /var/lib/ldap/
 324
 325 Configure your clients
 326
 327     $ cat /etc/ldap/ldap.conf
 328     BASE    dc=example,dc=com
 329     URI     ldaps://example.com
 330     TLS_CACERT  /etc/ldap/ssl/ldapserver.crt
 331
 332 Start `slapd` and add it to your default runlevel:
 333
 334     $ sudo /etc/init.d/slapd start
 335     $ sudo update-rc.d slapd defaults
 336
 337 Finally, import your directory data.  Dump the data on your master
 338 server:
 339
 340     master$ sudo slapcat -b 'dc=example,dc=com' > database.ldif
 341
 342 Load the data on your slave:
 343
 344     $ sudo /etc/init.d/slapd stop
 345     $ sudo slapadd -l database.ldif
 346     $ sudo /etc/init.d/slapd start
 347
 348 References
 349 ----------
 350
 351 There's a [good overview][schema] of schema and objectclasses by Brian
 352 Jones on O'Reilly.  If you want to use inetOrgPerson but also include
 353 the countryName attribute, ...
 354
 355 [LDAP]: http://en.wikipedia.org/wiki/LDAP
 356 [rfc4510]: http://tools.ietf.org/html/rfc4510
 357 [howto]: http://www.gentoo.org/doc/en/ldap-howto.xml
 358 [OpenLDAP]: http://www.openldap.org/
 359 [admin]: http://www.openldap.org/doc/admin/
 360 [inetorgperson]: http://www.apps.ietf.org/rfc/rfc2798.html
 361 [abook]: http://abook.sourceforge.net/
 362 [LDIF]: http://en.wikipedia.org/wiki/LDAP_Data_Interchange_Format
 363 [python-ldap]: http://www.python-ldap.org/
 364 [rfc4512]: http://tools.ietf.org/html/rfc4512
 365 [shelldap]: http://projects.martini.nu/shelldap/
 366 [mutts]: http://wiki.mutt.org/?QueryCommand
 367 [aab]: http://support.apple.com/kb/ht2486
 368 [SSL/TLS]: http://en.wikipedia.org/wiki/Transport_Layer_Security
 369 [certtool]:http://www.gnu.org/software/gnutls/manual/html_node/Invoking-certtool.html#Invoking-certtool
 370 [slapd.d]: http://www.openldap.org/doc/admin24/slapdconf2.html
 371 [schema]: http://www.oreillynet.com/pub/a/sysadmin/2006/11/09/demystifying-ldap-data.html
 372
 373 [[!tag tags/linux]]
 374 [[!tag tags/tools]]