The LDIF Directory Exchange Tool

Importing Changes to AD
To use Ldifde to import data into AD, you simply use the -i parameter to specify import mode and use the -f parameter to specify the LDIF file. Let's look at how to use Ldifde to write LDIF files that create, delete, and modify AD objects.

Creating objects. The easiest way to compose an LDIF file that creates a new object is to export an already existing object. Remember, whenever you use Ldifde to export an object, Ldifde outputs the object with a changetype of add. If you then import the Ldifde file to the same directory, Ldifde will try to create a duplicate of the object you just exported. Therefore, you can export a sample object (e.g., an existing user object), then edit the LDIF file so that it creates a new object. When you use this method, you must remove some attribute definitions from the original export file because only the directory service can set some attributes. For example, if you try to set the whenChanged attribute on a user object, Ldifde will display the message Add error on line 1: Constraint Violation. The server side error is "The attribute cannot be modified because it is owned by the system." Although Ldifde exports all attributes, including read-only attributes, by default, the utility can also correctly migrate data from one directory to another. To do this, you simply include the -k parameter when you import the LDIF file, which tells Ldifde to ignore constraint violations and object already exists errors. To improve performance for large imports, you can specify the -y parameter, which causes Ldifde to use lazy commits.

Deleting objects. Creating an LDIF file that deletes one or more objects is a relatively easy process. Simply enter the DN line, then specify delete on the changetype line. For example,

dn: cn=Robert Hall, ou=Marketing, dc=acme, dc=com
changetype: delete

instructs Ldifde to delete Robert Hall's user account from the acme.com domain.

Modifying objects. Without a doubt, using LDIF files to modify AD objects is the most challenging of the three types of imports Ldifde can perform. You must begin the LDIF file by listing the DN, then specifying modify on the changetype line. Next, you must specify the type of operation you want Ldifde to perform, followed by the name of the attribute you want to change. For example,

"replace: displayName"

tells Ldifde that the line or lines that follow will specify a new value or new values for the displayName attribute of the object you identified with a DN. (I specified the optional plural lines and values in the previous statement for those cases in which you're modifying multivalue attributes and you need to specify several values for the same attribute.)

The next line of the LDIF file needs to specify the attribute value. For example,

sn: Johnson

specifies the surname Johnson. If you have additional values to set for the same attribute, simply list them on additional lines in the same format. After you specify the final value line for that attribute, add a line with a single dash on it. For example,

dn: CN=Joe Stokes,OU=Monterey,
DC=ad,DC=local
changetype: modify
replace: sn
sn: Johnson
-

changes Joe's surname to Johnson.

In addition to using the replace operation, you can specify add and delete operations. You use the add operation when the attribute has never been set for the object of interest. In the case of multivalue attributes, when you use add, Ldifde will add values you specify to the existing values for that attribute. For example,

dn: CN=Managers,OU=Monterey,
DC=ad,DC=local
changetype: modify
add: member
member: CN=Joe Stokes,OU=Monterey,DC=ad,DC=local
member: CN=James White,OU=Monterey,DC=ad,DC=local
member: CN=Lamar McCluney,OU=Monterey,DC=ad,DC=local
-

adds Joe, James, and Lamar to the Managers group. By simply changing add: member to replace: member, Ldifde will delete any users who are already members of the Managers group before adding Joe, James, and Lamar. If you use the add operation on single-value attributes such as sn (surname) where a value already exists, Ldifde might report the message Multiple values were specified for an attribute that can have only one value. You use the delete operation to delete all attribute values as though the attribute had never been set for that object. For example,

dn: CN=Joe Stokes,OU=Monterey,
DC=ad,DC=local
changetype: modify
delete: sn
-

deletes Joe's current surname. You can also use the delete operation to delete a specific value from a multivalue attribute. For example,

dn: CN=Managers,OU=Monterey,
DC=ad,DC=local
changetype: modify
delete: member
member: CN=Joe Stokes,OU=Monterey,DC=ad,DC=local
-

deletes Joe from the Managers group without affecting any other members. This modification is similar to setting a field in a Microsoft SQL Server database row to null. To add, replace, or delete multiple attributes for the same object, simply use a single dash to separate the lines for each attribute. For example,

dn: cn=John Smith, ou=Accounting, dc=acme, dc=com changetype: modify add: postaladdress postaladdress: 100 Main St $ Greenville, CA $ 29605 - replace: telephonenumber telephonenumber: +1 864 555 1212 telephonenumber: +1 864 230 1212 - delete: facsimiletelephonenumber -

adds John's postal address, replaces his telephone number with two numbers, and deletes his fax number.

Using Ldifde and Csvde
Now that you understand the concepts behind the LDIF file structure, you can begin to put Ldifde and Csvde to work. For example, perhaps you need to create a new phone directory that includes the name, office phone, mobile and pager numbers, department, and job title of every employee in your organization. To produce a CSV-formatted file, run

csvde -f users.txt -d
"DC=acme,DC=com" -r "(objectClass=user)" -l
"name,department,title,telephoneNumber,
mobile,pager"

then import that file, users.txt, into an Access database to print it as a report or display it on an intranet Web page.

What if you need to obtain specific information about your employees? Many shops are faced with developing part, if not all, of their identity management applications inhouse. Identity management encompasses the life cycle of an employee's user accounts, password resets, and access-level changes, from hiring through job changes and finally to termination. For example, imagine that you need to extract all user accounts for the Research and Development division. Simply run

csvde -f users.LDIF -d 
"DC=acme,DC=com" -r "(&(objectClass=user)
(division=Research and Development))" -l 
"SAMAccountName,employeeID,telephone
Number,department"

to obtain the user logon name, employee ID, telephone, and department for all employees within that division.

Perhaps your identity management application needs to be able to disable user accounts when closing an employee's HR record. To accomplish this, program your application to create an LDIF file structured as

dn: 
changetype: modify
replace: userAccountControl
userAccountControl: 514
-

where <distinguished name> is the employee's DN. Then, program the application to run

"ldifde -f  -I"

to reimport the data into AD. If you need to delete a user from a group, create an LDIF such as

dn: 
changetype: modify
delete: member
member: 
-

where <group> is the group's DN and <user> is the DN for the user you want to remove from the group.

Ldifde and Csvde Options
Ldifde has a few additional options for fine-tuning how it runs. By default, Ldifde and Csvde use your user credentials to access AD. However, you can use the -b <username> <domain password> parameter to specify the credentials you want Ldifde and Csvde to use. If you don't want to include the password on the command line or in a script, you can substitute an asterisk (*) for <domain password>, in which case Ldifde will prompt you to enter the password without displaying it as you type. If you want Ldifde to execute the import or export against a specific server, simply use the -s parameter to specify the server name. Likewise, if you want Ldifde to list the DN of each object as it's processed, use the -v parameter.

Ldifde and Csvde are great tools for getting information in and out of AD or other LDAP directories without writing any Active Directory Service Interfaces (ADSI) code. Use Ldifde when you need to transfer objects from one directory to another or when you need to modify information within AD, and use Csvde when you need to extract data for use with other applications. For more information about LDIF, see RFC 2849 at http://www.faqs.org/rfcs/rfc2849.html. To learn more about Ldifde, see the Microsoft article "Using LDIFDE to Import and Export Directory Objects to Active Directory" (http://support.microsoft.com/?kbid=237677).