If you have never used an LDIF file before to manage a directory then you are in for a treat. If you are looking for techy information on how to build out an LDIF, including examples, then just look a little lower here.
So what is an LDIF file? An LDIF is a text file that you can feed into a directory to add, delete, move, or modify objects in the directory. You can adjust users, groups, and containers in the directory. If you are doing a single user then it might be easier to use any GUI tool you have available to do that request. But if you are doing a number of users, or need to do the exact same change on a number of trees, then an LDIF will make your life much easier. This is also a really great way to level set the information in different trees or on different objects in the same tree that should all have the same attribute settings.
When you do a command line LDAP search on a directory the results that the command gives is in LDIF format. If you redirect that output to a file then you can use that as a base or template for building out your LDIF file. I will give some examples of this at the bottom of the page. Keep in mind though that the ldapsearch command output is limited to a max of 80 characters across (and a lot of implementations go only 78 characters). So if you output a listing where some attributes give more than 80 characters of information then you will have line wraps that you need to deal with on creating an LDIF for input.
Several things to keep in mind with LDIF files. First, just like ldapsearch LDIF commands are case insensitive. You can use upper case, lower case, or mixed case. As far as the attributes themselves though, however you type them into the LDIF is how they will show up in the directory, and how they will display on output of a search. So if there is a particular need for case in the attribute you need to be mindful of that in creating your LDIF. Sometimes certain programs are written expecting a certain case for the attribute, and you need to put it in using the same case. Some people will use mixed case in a way to make names easier to read. If you want that then put it in that way in the LDIF. But the ldapmodify program will not care what the case is that you use.
Any line that starts with the pound or hash sign is considered a comment and will be ignored when the file is processed.
# This is the comment line and can be used to section things or note info
Trailing Spaces and Line-folding
You will want to make sure that there are no trailing spaces on any lines. The only time that trailing spaces are allowed is when you are line-folding an entry. If you have information that is going to be on two lines for a single attribute entry then you need to have a trailing space on that line and a single space at the beginning of the next line. The LDIF parser will then remove the spaces and concatenate the two lines.
End of record and multiple modify option separators
One other big gotcha that a lot of people get hit with is lacking a blank line at the end of each record. Every entry in an LDIF file needs to have a line with no spaces to end it. It is just a blank line with a carriage return. The file needs to end with a final clean carriage return too. You also need to be careful if you create the file in an editor on a Windows computer and then copy the file to a Linux or Unix server to run. It is possible you will not have the proper carriage return codes in the file for the *nix system since Windows uses different codes for carriage returns than *nix by default. A lot of text editors on Windows have a setting for using *nix returns.
If you are doing a modify on one or more records and are doing multiple operations on each object you need to separate the different operations with a hyphen. Look below to the modify section for examples of this.
The Big DN
Every item or object in the directory that you are going to modify is known by their DN. This is the fully qualified name of the object in the tree. This will be the first line for any record in the LDIF file that you are updating. The DN will be in LDAP format. The line will start with dn: and then have the full DN of the object. This is NOT case sensitive. If you are dealing with containers then the beginning of the DN will not start with cn= but will start with the type of container like ou= instead. Of course, make sure there is no trailing spaces in the line, just like all other lines or you will get an error.
Pushing the LDIF into the system
There are several ways to push an LDIF file into a system. Probably the most generic is to use the ldapmodify command. This is available on all *nix and Mac systems. You can find it for Windows too. If you are going against AD then you can download Microsoft's LDIFDE program to push the file in too. Some other environments have additional tools they make available to push the file into the system. The most basic ldapmodify line to accomplish this is:
ldapmodify -h hostname -D FQDNAdmin -w password -f filename.ldif
If you use this and there is a record that has an issue and throws an error then the processor will stop pushing entries and throw an error on the screen. If you want the program to keep processing records beyond the one that has the error then you can use a -c in the command line too. I will show an example later where this is very handy on a modify.
Note on system differences (and disclaimer)
LDAP and LDIF are supposed to be standards. But not everyone implements everything exactly the same way. You will find some slight differences between implementations. It is always good to test your LDIF files in a test directory before jumping in and going all gung ho in your production system. It is expected that you will use all due diligence in making sure you have a good LDIF file and will be updating your particular system the way that you are expecting to update it. One way to know how your particular system handles ldifs is to do an ldap search and export the information to a file. Command line ldap search programs will output in ldif format.
Adding objects to the system
If you want to add new users, groups, organizational units etc. then you need to perform an add operation. You designate the change type of an LDIF record with the changetype: line that goes right below the DN of the object you are adding or modifying.
With an add you need to make sure that you include the objectclass of the object you are creating. For most systems you should only need to specify the base class of the object and the system should fill in any additional entries. But I don't like leaving that to chance. So my recommendation is to do an ldapsearch for an object like the type you want to add and then copy the objectclass section right out of the export. That way you get all the objectclass lines for the new object.
Second, you MUST put in all required attributes of the object. You don't have to list any optional attributes unless you want to populate them. But you need to have the required attributes specified. This is something that will be different on various systems and platforms. Go into the definition of your class in the schema to determine what is required for any particular object class.
So let's make a couple users now. Let's make Clara Oswald and Bob Cratchit.
fullname: Clara Oswald
fullname: Bob Cratchit
Each attribute gets a line that starts with the name of the attribute ending in a colon followed by a space then the value you want in the attribute. If the attribute is a multivalued attribute and you want to put in multiple entries then simply use the attribute name several times and it will add each entry to the array in the attribute. If you have a binary entry then you will need to encode it in Base64.
I would recommend you export a user in ldif format using ldapsearch to see all the attributes that are populated for them. This is especially true with what objectclasses they should have. Most systems will not export the password. This will help in knowing how to format the entries for the new users to add.
Two things to note here too. First, the uid and the cn are different attributes and can be set to different values. Often they are set the same, but nothing prevents you from setting them to different values. And since they are different attributes they both need to be set.
Second, and this is a little known bit of information, the cn attribute is actually a multivalued attribute (at least on the systems I have tested it on). Typically you will only ever see a single value in it. But it is possible to stuff more than one in there. Most programs will only ever read the first value in the array (multivalued attributes present to programming languages as arrays). So if the one you really want is the second or third in the array you could find some really odd behavior in your program. This becomes more important in the modify change type that we will talk about below.
You can add a container in basically the same way. Let's do an OU.
Pretty simple eh? List out the attributes and the values for each one below the first two lines of the record, make sure there are no trailing spaces, and that you have a clean blank carriage free line at the end of each record in the file. If you are setting up a test tree and want a large number of records to test with then you can use a bash script, VBScript, or PowerShell program (or language of your choice) to generate the file using some sort of cool algorithm to generate all the names and passwords, then simply push the file in.
Often companies or organizations need to bring on board a number of people at the same time. Using ldif files can make that job much easier. In a future post I will show a vbscript that you can use to help easily make the ldif file to create users based on an Excel spreadsheet of users. It is often easy to get an Excel spreadsheet of the new users.
A future post will also show how you can modify existing users and groups and to delete objects in the tree.
I am truly a geeks geek. I have worked in computers for over three decades. I have worked on mainframes, Unix systems, Linux before almost anyone knew what it was, and many other systems. I love computers, and love making them do things people think is impossible.