This is intended to be a brief guide to setting up LDAP authentication under Linux, mainly focusing on the bits that might trip you up. It isn't intended to be perfect -- a lot of the stuff is just the way I've done things and it works for me. Although I've noticed several of the guides around the internet give you a few different ways to do things anyway.

Installing the LDAP Server

Firstly, you'll want to install the LDAP server and get it running. Under Debian, you can simply apt-get install slapd. You may have to compile it or build it from source or whatever. If you want TLS (probably a good idea) under Debian, you'll have to build from source using a source deb or whatever. See LDAPNotes for details on how to do this.

Here you want to ensure you have included the correct schemas in your slapd.conf. I have the following, and they work. Samba isn't required unless you want to do tricky Samba LDAP auth (not covered here)
include /etc/ldap/schema/core.schema include /etc/ldap/schema/cosine.schema include /etc/ldap/schema/nis.schema include /etc/ldap/schema/inetorgperson.schema include /etc/ldap/schema/samba.schema include /etc/ldap/schema/rfc822.schema
Now, rfc822.schema is a tricky one. I noticed the migration tools (next section) wanted to do stuff that needed this. Bear in mind that if all you want is simple password auth off ldap, this probably isn't needed, but I didn't have time to play with the migration tools to exclude it, and you can just delete irrelevant sections later. Here are the contents of my rfc822.schema, which I discovered in a mailing list archive



NAME 'rfc822MailMember' DESC 'rfc822 mail address of group member(s)' EQUALITY caseIgnoreIA5Match SYNTAX




NAME 'nisMailAlias' SUP top STRUCTURAL DESC 'NIS mail alias' MUST cn MAY rfc822MailMember


Seemed to work for me, or at least, it stopped the migration script from barfing halfway through.

Update: /etc/ldap/schema/rfc822.schema is a substract of /etc/ldap/schema/misc.schema . You can either use rfc822.schema as shown above or add
include /etc/ldap/schema/misc.schema

atop the /etc/ldap/slapd.conf file. Then restart slapd.

You also want to make sure you've got the correct ACLs. Something like this is required to let the admin see the shadowed crypted passwords, and nobody else

access to attribute=userPassword

by dn="cn=admin,dc=wlug,dc=org,dc=nz" write by anonymous auth by self write by * none

Migrating your Configuration

Once slapd is up and running, after choosing a sensible base dn and so on (this is beyond the scope of this document -- does someone want to wiki setting up slapd? or I'll do it later), it's time to migrate your existing files. This is easiest done by using PADL's excellent Migration Tools, or simply apt-get install migrationtools if you're lucky enough to be running Debian.

Edit your file and enter in the values appropriate for your setup. Under Debian, it'll be in /usr/share/migrationtools. Also, please do not set $EXTENDED_SCHEMA = 1 unless you really have the extended schemas. You'll want to pay attention to any gids/uids you want to ignore. It's probably a good idea to ignore 'system' users and groups. The defaults in Debian are users below 1000 (probably a good idea) and groups below 100. However, I have several groups I would consider 'system' groups (netsaint, etc, among others) at 101, 102... user groups don't start until 1000. So I suggest ignoring groups below 1000. Greig says this is inclusive, so maybe ignore below 999. Another issue I had was that if I tell it to ignore ANY groups, it ignores ALL the groups, so my groups ended up empty on my LDAP server (This is to do with a bug in the migration script, which I'm surprised didn't leap out at you straight away. It was comparing the higher and lower GID settings with a variable called $uid -- which didn't exist. $gid was the one it was reading from the group file. This has been fixed in unstable, but its not in stable (woody) nor ever will be I think -- DanielLawson) (The culprit lines are on lines 55 and 56 of and - change $uid to $gid -- TomHibbert). I had to tell it to ignore none and delete the ones I didn't want manually. Greig says this works for him under Woody and RH, but it certainly didn't work for me. YMMV. (Also, you may run into a problem where barfs because its trying to add the same entry twice. This happens when you have two entries of the same name (in my case news: root) in /etc/aliases-- TomHibbert)

After you've configured this, run the script and let the tools do all the work. I had a few hiccups here, but that was mainly due to slapd being horribly misconfigured. If you have any problems you can't find solutions to, it's probably a good idea to restart slapd several times, or simply stop it for a while, and try again. I don't really know why, but this seemed to fix some of my problems magically.

Setting up PAM

Next, you want to get PAM and NSS working. First, make sure you're on an OS that uses PAM. If you're not, complicated things happen. Fortunately, if you're using Linux, that shouldn't be a problem. You now want to install libpam-ldap and libnss-ldap. Under Debian, apt-get the packages. ('When Debconf asks you for Root login account, its your rootdn.' --TomHibbert) Under anything else, either RPMs or source as usual. Now that you've done that, you get to configure a few files.

/etc/ldap/ldap.conf tells LDAP clients where to access the LDAP server. Your slapd configuration may have already set this up for you. You probably want something like this
BASE dc=wlug,dc=org,dc=nz HOST

/etc/libpam_ldap.conf is the configuration file for the LDAP nameservice switch library and the LDAP PAM module. This file is relatively simple too -- when you installed it under Debian, all your configuration is probably done, but you should flip through it anyway.

host base dc=wlug,dc=org,dc=nz ldap_version 3 rootbinddn cn=admin,dc=wlug,dc=org,dc=nz scope sub

...and that should be all. Note, you need rootbinddn to get set, and a valid password for it in /etc/ldap.secret (at least, that's where it is under Debian...). This is because you can't see the crypted passwords on the LDAP server as anything other than admin. Also, scobe sub is not included as part of the Debian default config, but I think it's a good idea to have it there. It sets the search scope to all subdirectories. It may be a terrible idea to have it there.

/etc/libnss-ldap.conf (see libnss-ldap.conf(5)) is the configuration file for the LDAP NSS library. You probably want it to contain something like this
host base dc=wlug,dc=org,dc=nz ldap_version 3 scope sub

Note the lack of rootbinddn, nss doesn't need to bind as admin. Note, however, that if this file is readable only by root, users won't be able to resolve anything! As a solution, you can either install nscd(8), a caching daemon which runs as root (this is a good idea anyway, see later) or set this file world readable.

Now that that's done, you probably want to edit /etc/nsswitch.conf and tell it to look at your LDAP server by default. This is done easily enough, change the lines
passwd: compat group: compat shadow: compat
(note that it may be 'files' or something else instead of 'compat', depending on your dist) to
passwd: ldap files group: ldap files shadow: ldap files

...and you should be looking at your ldap server instead of files. Testing this is a little weird, and you should probably leave it til sometime after the next step...

Setting up Application PAM LDAP Authentication

Now is the time to set up LDAP authentication for individual PAM applications. In /etc/pam.d there are a whole lot of files controlling how PAM authentication works for various different applications. Edit the entries of those you want to authenticate off LDAP. The general rule I used was to look for anything authenticating off and add the line:

xxx sufficient

...above it, where xxx is whatever that field was for the line. Bear in mind that where parameters are being passed to (eg, password required nullok obscure min=4 max=8 md5), may barf, so it's best to leave them off or experiment (carefully!).

A good idea is to do a service you can easily test first (say, pop3) and make sure everything's working. You could also temporarily delete your user or a user you care little about from /etc/passwd, /etc/shadow and /etc/group, to ensure that it really is getting things from LDAP. I'm not sure how much of a brilliant idea this is, but if you're careful it should be okay. DON'T REMOVE ROOT FROM /etc/passwd. root isn't in the ldap server.

So once you can telnet to the pop3 port and log on with pop3 against LDAP, start shifting some other services over, and test them as you go. Note that ssh likes to be restarted after you change it's pam.d file, this caught me out. Be careful shifting things like 'login' over. :)

Have a look at for a few tips and tricks.

The End

And that's it! After the services you want to use are shifted over, you're now running a system authenticating off LDAP. Delete your local users and leave the LDAP ones there. Don't delete user root, and don't put root on the LDAP server. It's probably not a good idea. Things may be going a little slowly, so you might want to install nscd(8) to speed things up, as it caches all ldap requests. To set up other machines to authenticate off this server, just perform the steps from "Setting up PAM" and onwards on the other machine, but using the IP of your real LDAP server instead of (obviously).


1) Everything is working fine, but any authentication I do is REALLY slow. I expected some slowdown, but not this. What's wrong with my machine?

Actually, there isn't really any slowdown when using LDAP for authentication, even on very slow machines. I had this problem, and eventually discovered it was because I had turned loglevel up to around 40 in slapd.conf, which was causing pages of logs to spew out every time I touched the server, reducing it to running like a dog or some other slow running animal. Turn the logging off once you have everything working, and it's fine.

2) How can I tell if I'm really pulling information out of LDAP?

Make sure you have a user entry, or group entry, that is only in LDAP. Removing a user or group from your /etc/passwd or /etc/group is a good way of ensuring this. As said before, do NOT remove root.

Verify the user doesn't exist in /etc/passwd

  1. cat /etc/passwd | grep daniel


Now use getent to check that nsswitch can see the user

  1. getent passwd daniel

daniel:x:1000:1000:Daniel Lawson (LDAP):/home/daniel:/bin/bash #

So this verifies that nsswitch can see the user. As long as you have your pam setup appropriately, you should be able to login as this user

3) I can't access protocols / services / host / ethers / etc information after I migrated to LDAP / libnss_ldap

EG: you can't do telnet hostname imap, you have to use the numeric port. Or you can't ping - it says unknown protocol icmp (see CommonErrors)

You (or your system package manager when you installed libnss_ldap) have probably told /etc/nsswitch.conf that your LDAP server is authoritative for these, whereas in fact its not. Remove the bits for these databases that pertain to LDAP, and you should be fine. Or, set up the protocols / services / hosts / ethers or what have you groups in the LDAP tree correctly. Duh!)

RedHat Specific

This assumes you've migrated at least your /etc/{passwd,group,shadow} files into working LDAP server and can browse this information using a client like gq (

Configuring clients to authentication off your LDAP server is pretty easy. Just run authconfig and select LDAP where nessessary and enter in your server settings. It is advisable to enable TLS as without it passwords are sent over your network in clear text.

The only "tweak" I made was to edit /etc/pam_ldap.conf to have the "pam_password" attribute set to "exop". In my experiementation I could only get the "clear", "crypt", and "exop" pam_password methods working. MD5 always failed. I think it might have had something to do with the way OpenLDAP & GQ were interacting when setting passwords encoded with MD5 tho. You might have better luck. Anyway when you use "pam_password exop" and then use passwd(1) to set your passwords in the LDAP directory they are stored encrypted using the very secure SSHA algorythm.

Note: I think I discovered a bug in authconfig. If you run it multiple times it can bugger up you /etc/pam.d/system-auth file. It appears to append lines to the end of existing configurations. This is bad. You need to make sure your system-auth file is properly setup. It should look like this

auth required /lib/security/ auth sufficient /lib/security/ likeauth nullok auth sufficient /lib/security/ use_first_pass auth required /lib/security/

account required /lib/security/ account [default=ok user_unknown=ignore service_err=ignore system_err=ignore? /lib/security/

password required /lib/security/ retry=3 password sufficient /lib/security/ nullok use_authtok md5 shadow password sufficient /lib/security/ use_authtok password required /lib/security/

session required /lib/security/ session required /lib/security/ session optional /lib/security/

Be aware that if you edit this file it is likely to be overwritten the next time you run authconfig.

Authconfig also edits your /etc/nsswitch.conf file to enable looking up users and groups via LDAP. You shouldn't need to edit this file unless you also want to add things like aliases, networks, and ethers etc into your LDAP tree.

SASL Notes

If you are using any tools that link against libsasl (and openldap2 is one of them, by default), and are trying to use any services that also link against libsasl, you'll probably run into an issue where the calling application (eg, Cyrus IMAPd) dies with SIGSEGV (SIG11, Segmentation Fault). This is to do with a non-rentrant bug in libsasl. See SASLNotes for more information