Importing Data Using import-ldif

The import-ldif command is used to populate a directory server back end with data read from an LDIF file or with data generated based on a Creating MakeLDIF Template Files. In most cases, import-ldif is significantly faster than adding entries using ldapmodify.

The import-ldif command supports both LDIF files and compressed files (.zip).

Note -

• A complete import to an entire Oracle Berkeley DB Java Edition (JE) back end will have better performance than a partial import to a branch of the JE back end. All imported LDIF files must use UTF-8 character-set encoding.

• Importing suffixes is a resource-intensive operation. If you import LDIF files that include a large number of suffixes, your system might have insufficient heap to complete the import operation. Before importing such LDIF files, you should therefore increase the heap as much as possible. For more information, see Tuning Performance and Improving Performance When Importing Large Data Sets.

You do not need root privileges to import an LDIF file, but you must authenticate as a user with root permissions, such as cn=Directory Manager.

import-ldif Operation Modes

The import-ldif command has two modes of operation: online and offline.

• Online mode. In online mode, import-ldif contacts a running directory server instance and registers an import task. The command accesses the task back end over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server. Online mode runs automatically when any connection options (such as --hostname, --port, --bindDN, and --bindPassword) are specified.

  In general, if you expect to do online imports, you should increase the heap when you start the server. For more information, see Tuning Performance.

• Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode, import-ldif accesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.

To Import Data in Offline Mode

This procedure imports a back-end database with new entries specified in an import LDIF file. The command runs in offline mode, which requires the server to be shut down prior to import.

1. Stop the server if it is running.

   $ stop-ds

2. Import the LDIF file, as shown in the following example:

   $ import-ldif -b dc=example,dc=com -n userRoot -l Example.ldif

   This command specifies the base DN for the branch of the data that should be included in the import (-b), the back-end ID into which the data is imported (-n), and the LDIF file used for the import (-l).

To Replace Existing Data During an Offline Import

The following procedure replaces an existing back-end with new entries specified in an import file.

1. Stop the server if it is running.

   $ stop-ds

2. Import the LDIF file, replacing the existing data. For example:

   $ import-ldif --includeBranch dc=example,dc=com --backendID userRoot \
     --replaceExisting --ldifFile Example.ldif

To Append Imported Data to Existing Data

The following procedure appends the entries in an import file to the existing entries in the back end.

1. Stop the server if it is running.

   $ stop-ds

2. Import the LDIF file, appending the new data to the existing data. For example:

   $ import-ldif --backendID userRoot --append --ldifFile new.ldif

To Import Fractional Files

The import-ldif command provides options to import a portion of an import file by specifying the base DN to include or exclude during the process.

This example imports all entries below the base DN, dc=example,dc=com, and excludes all entries below ou=People,dc=example,dc=com.

1. Stop the server if it is running.

   $ stop-ds

2. Import a portion of the LDIF file. For example:

   $ import-ldif --includeBranch dc=example,dc=com \
     --excludeBranch ou=People,dc=example,dc=com --backendID userRoot --replaceExisting \
     --ldifFile Example.ldif

To Import Fractional Files by Using Filters

The import-ldif command provides options to import part of an import file by using filters for data inclusion or exclusion. Make sure that you fully understand how this mechanism works before you use it.

In this example, the contents of an LDIF file are imported, except those entries that match the search filter l=Auckland (that is, location=Auckland).

Note - The --includeFilter option works in a similar manner to --excludeFilter, except that it includes all entries that match the search filter during import.

1. Stop the server if it is running.

   $ stop-ds

2. Import a portion of the file by using an exclude filter. For example:

   $ import-ldif --excludeFilter "(l=Auckland)" --backendID userRoot \
     --replaceExisting --ldifFile Example.ldif

To Include or Exclude Attributes During Import

The import-ldif command provides options to include and exclude attributes during import by using the --includeAttribute and --excludeAttribute options, respectively. Make sure that you fully understand how this mechanism works before you use it.

1. Stop the server if it is running.

   $ stop-ds

2. (Optional) View the entries of the import file before you start the import.

   The directory server provides useful utilities to search, modify, compare, or delete import files without connecting to the server. You can use the ldifsearch command to display an entry in your import file. For example, to display the entry for Sam Carter, use the following command:

   $ ldifsearch -b dc=example,dc=com --ldifFile Example.ldif "(cn=Sam Carter)"
   dn: uid=scarter,ou=People,dc=example,dc=com
   objectClass: person
   objectClass: inetOrgPerson
   objectClass: organizationalPerson
   objectClass: top
   givenname: Sam
   uid: scarter
   cn: Sam Carter
   telephonenumber: +1 408 555 4798
   sn: Carter
   userpassword: sprain
   roomnumber: 4612
   mail: scarter@example.com
   l: Sunnyvale
   ou: Accounting
   ou: People
   facsimiletelephonenumber: +1 408 555 9751

   In this entry, notice the presence of the roomnumber attribute below the telephonenumber attribute.

3. Import the file, excluding the roomnumber attribute for all entries.

   $ import-ldif --excludeAttribute "roomnumber" --backendID userRoot \
     --replaceExisting --ldifFile Example.ldif

4. Start the server.

   $ start-ds

5. Perform an ldapsearch to verify the import.

   The following example shows that the roomnumber attribute is now absent from Sam Carter's entry.

   $ ldapsearch --port 1389 --baseDN dc=example,dc=com --bindDN "cn=Directory Manager" \
     --bindPassword password "(cn=Sam Carter)"
   dn: uid=scarter,ou=People,dc=example,dc=com \
   objectClass: person
   objectClass: organizationalPerson
   objectClass: inetOrgPerson
   objectClass: top
   givenName: Sam
   uid: scarter
   cn: Sam Carter
   sn: Carter
   telephoneNumber: +1 408 555 4798
   ou: Accounting
   ou: People
   l: Sunnyvale
   mail: scarter@example.com
   facsimileTelephoneNumber: +1 408 555 9751

To Import a Compressed LDIF File

The import-ldif utility supports compressed LDIF files.

1. Stop the server if it is running.

   $ stop-ds

2. Import the compressed LDIF file.

   $ import-ldif --includeBranch dc=example,dc=com 
     --excludeBranch "ou=People,dc=example,dc=com" --ldifFile Example.ldif \
     --backendID userRoot --replaceExisting --isCompressed

To Record Rejected or Skipped Entries During Import

The import-ldif command provides a means to write to an output file for any entries that are rejected or skipped during the import process. This enables easy debugging of an LDIF file. Rejected entries occur when the directory server rejects the added entries due to schema violations. Skipped entries occur when entries cannot be placed under the specified base DN.

1. Stop the server if it is running.

   $ stop-ds

2. Import the file, using the --rejectFile and --skipFile options.

   You can also use the --overWrite option to replace any previous items in the two files. Without the option, the directory server appends new rejected and skipped entries to the existing files.

   $ import-ldif --backendID userRoot --append --ldifFile new.ldif 
     --overwrite --rejectFile rejected.ldif --skipFile skipped.ldif

3. (Optional) View the contents of the rejectFile and skipFile to determine which entries were rejected or skipped during the import. For example:

   $ more rejected.ldif
   # Entry ou=Contractors,dc=example,dc=com read from LDIF starting at line 1 
   is not valid because it violates the server's schema configuration: 
   Entry ou=Contractors,dc=example,dc=com violates the Directory Server schema 
   configuration because it includes attribute changeType which is not allowed. 
   changetype: add objectclasses defined in that entry objectclass: top 
   objectclass: organizationalUnit ou: Contractors ou: Product Testing 
   ou: Product Dev ou: Accounting ...
   
   $ more skipped.ldif
   # Skipping entry ou=People,dc=example,dc=com because the DN is not one that should be 
     included based on the include and exclude branches objectclass: top 
     objectclass: organizationalunit ou: People 
     aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr ="userpassword || 
     telephonenumber || facsimiletelephonenumber")(version 3.0;acl "Allow self entry 
     modification"; allow (write)(userdn = "ldap:///self");) 
     aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
     uid") (targetfilter ="(ou=Accounting)")(version 3.0;acl "Accounting Managers Group 
     Permissions"; allow (write) 
     (groupdn = "ldap:///cn=Accounting Managers,ou=groups,dc=example,dc=com");) 
     aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
     uid") (targetfilter ="(ou=Human Resources)")(version 3.0;acl "HR Group Permissions"; 
     allow write)(groupdn = "ldap:///cn=HR Managers,ou=groups,dc=example,dc=com");) aci: 
     (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn ||sn || uid") 
     (targetfilter ="(ou=Product Testing)")(version 3.0;acl "QA Group Permissions"; allow 
     (write)(groupdn = "ldap:///cn=QA Managers,ou=groups,dc=example,dc=com");) 
     aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || 
     uid") (targetfilter ="(ou=Product Development)")(version 3.0;acl "Engineering Group 
     Permissions"; allow (write)(groupdn = 
     "ldap:///cn=PD Managers,ou=groups,dc=example,dc=com");) ...

To Import Data From a MakeLDIF Template

The directory server includes the Java utility, makeLDIF, that can be used to generate sample data for import. The makeLDIF utility requires a template file. You can create your own template file, or you can use the template file located in install-dir/config/MakeLDIF/example.template, editing it as required. For more information, see Creating MakeLDIF Template Files.

1. Stop the server if it is running.

   $ stop-ds

2. Import the data, using a template file.

   The sample template generates 10,003 sample entries in the specified back end.

   $ import-ldif --backendID userRoot --templateFile example.template --randomSeed 0

See Also

make-ldif in Sun OpenDS Standard Edition 2.0 Command-Line Usage Guide

To Run an Import in Online Mode

The import-ldif utility can also be run with the server online. In online mode, the command accesses the task back end over SSL via the administration connector. To run the command in online mode you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates. For more information, see Managing Administration Traffic to the Server.

• Run the import-ldif command with the appropriate connection options.

  $ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -w password -X \
    -l /ldif-files/example.ldif

To Schedule an Import

The import-ldif utility provides a --start option for scheduling the import at some future date. You can view this scheduled task by using the manage-tasks utility. The command accesses the task back end over SSL via the administration connector. To schedule an import task, you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates. For more information, see

• Run the import-ldif command with the --start option.

  $ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -w password -X \
    -l /ldif-files/example.ldif --start 20080124121500

See Also

Configuring Commands As Tasks