Managing Data Within an LDAP Server

The purpose of this guide is to convey a basic understanding of how to manipulate data that is stored within an LDAP server. It does not speak to setting up the server, configuring the LDAP service itself, or securing the LDAP server. For information on these topics, see this article.

A hell of a lot of entirely new acronyms are going to be introduced and then used throughout this article. It is critical you learn them, as LDAP possess an extensive and unique vocabulary. LDAP itself will become a lot less confusing the more you readily recognize and understand its associated acronyms. Scroll to the bottom of this article for an LDAP glossary.

There are three command-line tools that we will use to manipulate LDAP data. They are:

• ldapsearch: A read-only tool that allows the querying of existing LDAP records for all or specific fields.
• ldapadd: The tool for adding a wholly new LDAP record (a collection of fields, belonging to a single distinguishing name, or DN).
• ldapmodify: Permits the modifying of an existing LDAP record through adding, replacing, or deleting one or more fields within a DN.

The basic structure within LDAP can be visualized as a series of nested "folders", each containing other "folders" or "files" (attributes). Unlike UNIX, which uses a / as both the path separator and point of origin, LDAP uses special record types and commas as path separators, and assumes you are using your domain's TLD as the point of origin.

For example, let us assume that the user John Doe is to be placed within the users "bucket", and that your FQDN is example.com:

Written in LDAP query nomenclature, the above is:

uid=johndoe,cn=users,dc=example,dc=com

Alternatively, assuming the same user appears within the Relative Distinguished Name, or RDN, of ou=employees,dc=example,dc=com, then the DN now looks like this:

Written in standard form, the above is:

uid=johndoe,ou=employees,dc=example,dc=com

For example, let us now specify John Doe's email address and office telephone number. First, we will add the attribute mail which will contain his email address:

This means that the DN uid=johndoe,ou=employees,dc=example,dc=com now has an attribute, mail, which contains the data john@example.com.

Let's add his office phone number:

Now the DN uid=johndoe,ou=employees,dc=example,dc=com contains two attributes, mail and telephoneNumber.

You might now be wondering what attributes are available to a given DN, or is it entirely free-form? The answer is that the attribute names, and the kind of data each can contain, are specified by the schema you use for the DN. An in-depth discussion of schemata would fill an article twice the size of this one, and is beyond the scope of this particular article; but suffice to say, available schemata are defined on the LDAP server itself, and the most common one for use with address book-like LDAP implementations is called inetOrgPerson. The rest of this article assumes that the inetOrgPerson schema is configured and in use on your LDAP server.

Let us now return to the aforementioned command-line tools, and take a look at ldapsearch.

First, before we can simply query an LDAP server for data, we must authenticate ourselves. LDAP supports three levels of permissions:

• Bind
• Read
• Write

Bind simply allows us to connect to the LDAP server, usually for purposes of then authenticating with a username and password. Once authenticated, we are then allowed to read or write DNs based on how the server is configured. The most common default configuration is to allow everyone ("anonymous") to bind, and after authentication, to permit read for all DNs, and only write for our own DN ("self").

Thus, to use any of the LDAP command-line tools, we must pass certain authentication information when we invoke the command. For example:

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W

So far all that has done is invoke the LDAP search command and authenticate to the server. We now need to specify something known as the search base, or RDN. This will limit our search to a specific portion of the Directory Information Tree, or DIT, so that our search is both fast and accurate:

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com"

Last but not least, we must now specify what it is for which we are looking. If we skip this step, the ldapsearch command will return the entire contents of the RDN, which is (probably) not very useful and may be extremely large. Let us look specifically for the user "Jane Doe", except we don't know exactly what her User ID is. Let's assume it probably starts with jane:

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" "uid=jane*"

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" "uid=j*"

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" "uid=*jane*"

Let us now refine our search further to just see Jane's email address:

$ ldapsearch -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -b "ou=users,dc=example,dc=com" "uid=jane*" mail

The data returned by the ldapsearch command is in LDAP Data Interchange Format, or LDIF. This is the same format used when adding and change data within LDAP, as we will now see.

To add a new record (usually, a DN and associated attributes) to a DIT, we will first need to create a text file that is formatted in LDIF.

Let's add a new user, "Joe Smith", to the DN ou=users,dc=example,dc=com, and specify both his email address and telephone number. Here's the LDIF, which we'll assume has been saved to a file named new_user.ldif:

dn: uid=joesmith,ou=users,dc=example,dc=com
objectClass: inetOrgPerson
uid: joesmith
mail: joe@example.com
telephoneNumber: (123) 555-2121

To import this LDIF data into LDAP we use the ldapadd command. It uses many of the parameters we've previously seen from ldapsearch, as we must bind to the LDAP server before we can write to it; however, we do not need to specify a search base:

$ ldapadd -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -f new_user.ldif

While ldapadd is useful for inserting new data into LDAP, it cannot be used to overwrite existing data. To add a new attribute to a DN, delete an existing attribute from a DN, or to modify an existing attribute, you need to use the ldapmodify command.

Like the ldapadd command, the ldapmodify command reads LDIF from a file and applies the changes on the LDAP server.

Let's update Joe's email address. Here is the LDIF, which we will save to a file named update_email.ldif:

dn: uid=joesmith,ou=users,dc=example,dc=com
changetype: modify
replace: mail
mail: joe_smith@example.com

$ ldapmodify -h "ldap.example.com" -D "uid=johndoe,ou=users,dc=example,dc=com" -W -f update_email.ldif

The LDIF for modifying existing DNs can specify more than a single change at a time by separating them with a line containing a single hyphen; for example, to change both Joe's email and his telephone number at the same time:

dn: uid=joesmith,ou=users,dc=example,dc=com
changetype: modify
replace: mail
mail: joe_smith@example.com
-
replace: telephoneNumber
telephoneNumber: (555) 555-1234

dn: uid=joesmith,ou=users,dc=example,dc=com
changetype: modify
replace: mail
mail: joe_smith@example.com
 
dn: uid=janedoe,ou=users,dc=example,dc=com
changetype: modify
replace: mail
mail: jane_doe@example.com

When modifying (or adding) multiple records from a single LDIF file, the default behavior is to abort upon the first error. It may be useful to continue despite an error, however; to do this, pass the -c parameter to the ldapadd or ldapmodify command.

If SASL is broken on your LDAP server for some reason, you can instruct any of the ldap* commands to use simple authentication instead. Simply pass the -x parameter to the command.

If your LDAP server requires TLS before it will do more than let you bind to it, pass the -Z parameter to the command. To force TLS to be used (always a good idea assuming your LDAP server supports TLS) add a second Z like this: -ZZ.