Exit Print View

Sun OpenDS Standard Edition 2.2 Command-Line Usage Guide

Get PDF Book Print View
 

Document Information

Before You Start

Server Administration Commands

Data Administration Commands

backup

base64

dbtest

export-ldif

import-ldif

list-backends

manage-account

rebuild-index

restore

split-ldif

verify-index

LDAP Client Utilities Commands

Other Commands

General Tool Usage Information

import-ldif

The import-ldif command populates a directory server back end with data read from an LDIF file.

This command is not supported for the proxy.

Synopsis

import-ldif options

Description

The import-ldif command populates a directory server back end with data read from an LDIF file, or with data generated based on a MakeLDIF template. In most cases, using import-ldif is significantly faster than adding entries by using ldapmodify. Note that a complete import to an entire Oracle Berkeley Java Edition (JE) back end has better performance than a partial import to a branch of the JE back end.

The import-ldif command can run the import immediately or can schedule the import to run at a specified date and time. For more information, see Configuring Commands As Tasks in Sun OpenDS Standard Edition 2.2 Administration Guide.

You can run the import-ldif command in online or offline mode.

Options

The import-ldif command accepts an option in either its short form (for example, -b baseDN) or its long form equivalent (for example, --includeBranch baseDN).

-a, --append

Append the imported data to the data that already exists in the back end, rather than clearing the back end before starting the import.

-A, --templateFile filename

Specify the path to a MakeLDIF template to generate the import data.

-b, --includeBranch branchDN

Specify the base DN for a branch or subtree of the data that should be included in the import. This option can be used multiple times to specify multiple base DNs. If this option is provided, entries contained in the import source that are not at or below one of the provided base DNs are skipped. Any existing entries above the provided base DNs are preserved.

-B, --excludeBranch branchDN

Specify the base DN branch or subtree that should be omitted from the import. This option can be used multiple times to specify multiple base DNs. If this option is provided, entries contained in the import source that are at or below one of the base DNs are skipped. Note that the use of the --excludeBranch option takes precedence over the --includeBranch option. If an entry is at or below a DN contained in both the included and excluded lists, it is omitted from the import. This capability makes it possible to include data for only a part of a branch (for example, all entries below dc=example,dc=com except those below ou=People,dc=example,dc=com).

-c, --isCompressed

Specify that the LDIF import file is compressed. The file should be compressed using the GZIP format, which is the format used by the --compressLDIF option of the export-ldif command.

--countRejects

Return the number of rejected entries during import. If the number of rejected entries is between 0 and 255, that number is returned. If the number of rejected entries is greater than 255, the command returns the value 255. For example, if you run import-ldif with the --countRejects option and get 16 rejected entries, the command returns the value 16. If you run import-ldif and get 300 rejected entries, the command returns the value 255. Note that this option is not supported for online imports.

-e, --excludeAttribute attribute

Specify the name of an attribute that should be excluded from the import. This option can be used multiple times to specify multiple attributes.

-E, --excludeFilter filter

Specify the search filter to identify entries that should be excluded from the import. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the import source that matches the filter is skipped. Note that the --excludeFilter option takes precedence over the --includeFilter option. If an entry matches filters in both the include and exclude filters, the entry is skipped during import.

-F, --clearBackend

Confirm deletion of all existing entries for all base DNs in the specified back end when importing without the --append option. This only applies when importing a multiple base DN back end specified by the back end ID. This option is implied for back ends with only one base DN.

-i, --includeAttribute attribute

Specify the attributes that should be included in the import. This option can be used multiple times to specify multiple attributes. If this option is used, attributes not listed in this set are omitted from the entries that are imported.

-I, --includeFilter filter

Specify the search filter to identify entries that should be included in the import. This option can be used multiple times to specify multiple filters. If this option is provided, any entry in the import source that does not match the results of the filter is skipped.

-l, --ldifFile filename

Read the LDIF file located at the specified path. This option must not be used in conjunction with --templateFile.

For online imports, the root for relative paths is the instance root, rather than the current working directory. So, for example, a path of imports/ldif.ldif here refers to instance-root/imports/ldif.ldif.

-n, --backendID backendID

Specify the ID of the back end into which the data should be imported. To display the available back ends in the server, use the list-backends command.

-O, --overwrite

Overwrite the specified skip file or reject file, if it already exists. If this option is not provided, any skipped or rejected entries are appended to their corresponding files rather than overwriting them. This option is only applicable if the --rejectFile or --skipFile options are provided.

-r, --replaceExisting

Replace existing data with the content from the import. If this option is not provided, existing entries are not overwritten. This is only applicable if the --append option has also been provided.

-R, --rejectFile filename

Use the specified file to hold any rejected entries during the import. Rejected entries occur if entries are not compliant with the default schema. A comment is included before the entry indicating the reason that it was rejected. If this option is not provided, no reject file is written.

-s, --randomSeed seed

Use the specified seed number for the random number generator when generating entries from a MakeLDIF template. Seeding the random number generator with a particular value can help to ensure that the same template and random seed always generate exactly the same data.

--skipDNValidation

Perform limited parental DN validation during a later part of the LDIF import. If this option is specified, no duplicate DN checking is done. Do not use this option if you are not certain that your LDIF import file is correct.

--skipFile filename

Use the specified file to identify entries that were skipped during the import. Skipped entries occur if entries cannot be placed under any specified base DN during an import or if the --excludeBranch, --excludeAttribute, or --excludeFilter option is used.

-S, --skipSchemaValidation

Do not perform any schema validation on the entries as they are imported. This option can provide improved import performance, but should only be used if you are certain that the import data is valid.

--threadCount count

Specify the number of threads that are used to read the LDIF file. If this option is not specified, a default of two threads per CPU is used.

You can use this option to increase the number of threads if you are importing particularly large LDIF files, but you should not use the option unless you are certain of the resulting impact on performance.

--tmpDirectory directory

Use the specified directory for index scratch files created during the import. If no directory is specified, the default install-dir/import-tmp is used.

Task Back End Connection Options

Running an online import requires access to the tasks back end. Access to the tasks back end is provided over SSL through the administration connector. These connection options are used when the import runs online.

-D, --bindDN bindDN

Use the bind DN to authenticate to the directory server. This option is used when performing simple authentication and is not required if SASL authentication is to be used. The default value for this option is cn=Directory Manager.

-h, --hostname hostname

Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.

-j, --bindPasswordFile filename

Use the bind password in the specified file when authenticating to the directory server. This option must not be used in conjunction with --bindPassword.

-K, --keyStorePath path

Use the client keystore certificate in the specified path.

-N, --certNickname nickname

Use the specified certificate for client authentication.

-o, --saslOption name=value

Use the specified options for SASL authentication.

-p, --port port

Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.

-P, --trustStorePath path

Use the client trust store certificate in the specified path. This option is not needed if --trustAll is used, although a trust store should be used when working in a production environment.

-T, --trustStorePassword password

Use the password needed to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (which most trust stores do not require). This option must not be used in conjunction with --trustStorePasswordFile.

-u, --keyStorePasswordFile filename

Use the password in the specified file to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePassword.

-U, --trustStorePasswordFile filename

Use the password in the specified file to access the certificates in the client trust store. This option is only required if --trustStorePath is used and the specified trust store requires a password in order to access its contents (most trust stores do not require this). This option must not be used in conjunction with --trustStorePassword.

-w, --bindPassword password

Use the bind password when authenticating to the directory server. This option can be used for simple authentication as well as password-based SASL mechanisms. This option must not be used in conjunction with --bindPasswordFile. To prompt for the password, type -w -.

-W, --keyStorePassword password

Use the password needed to access the certificates in the client keystore. This option is only required if --keyStorePath is used. This option must not be used in conjunction with --keyStorePasswordFile.

-X, --trustAll

Trust all server SSL certificates that the directory server presents. This option can be used for convenience and testing purposes, but for security reasons a trust store should be used to determine whether the client should accept the server certificate.

Task Scheduling Options

These options are used when you specify that the import should run as a scheduled task.

--completionNotify emailAddress

Specify the email address of a recipient to be notified when the task completes. This option can be specified more than once in a single command.

--dependency taskId

Specify the ID of a task upon which this task depends. A task does not start executing until all of its dependencies have completed execution.

--errorNotify emailAddress

Specify the email address of a recipient to be notified if an error occurs when this task executes. This option can be specified more than once in a single command.

--failedDependencyAction action

Specify the action that this task will take if one of its dependent tasks fails. The value must be one of PROCESS, CANCEL, or DISABLE. If no value is specified, the default action is CANCEL.

--recurringTask schedulePattern

Indicates that the task is recurring and will be scheduled according to the schedulePattern, expressed as a crontab(5) compatible time and date pattern.

-t, --start startTime

Indicates the date and time at which the operation starts when scheduled as a directory server task expressed in the format YYYYMMDDhhmmss. A value of 0 schedules the task for immediate execution. When this option is specified, the operation is scheduled to start at the specified time after which the command exits immediately.

Command Input/Output Options
--noPropertiesFile

Indicates that a properties file is not used to obtain the default command-line options.

--propertiesFilePath path

Specify the path to the properties file that contains the default command-line options.

-Q, --quiet

Run in quiet mode. Using quiet mode, no output is generated unless a significant error occurs during the import process.

General Options
-?, -H, --help

Display command-line usage information for the command and exit without making any attempt to run an import.

-V, --version

Display the version information for the directory server and exit rather than attempting to run this command.

Examples

The following examples show how to use the directory server commands. You can use the commands on any UNIX, Linux, or Windows system that has at least the Java SE 5 (at least Sun version 1.5.0_08, preferably the latest version of Java SE 6) runtime environment installed on its target system.

Example 65
Running an Offline Import

This example imports an LDIF file to the userRoot back end. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif
Example 66
Importing Part of an LDIF File Offline

This example imports part of an LDIF file to the userRoot back end. The import includes the base DN dc=example,dc=com but excludes the branch ou=people. Existing entries are replaced (-r) and information about any rejected entries are written to /usr/tmp/rejects.ldif. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -B "ou=people,dc=example,dc=com" \
  -l /usr/tmp/Example.ldif -n userRoot -r -R /usr/tmp/rejects.ldif
Example 67
Importing Data From a MakeLDIF Template

This example imports sample data from a MakeLDIF template to the userRoot back end. The random seed (-s) determines the randomness of the data. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -n userRoot -A example.template -s 0
Example 68
Importing User Attributes Only

This example imports an LDIF file to the userRoot back end. Only user attributes are imported, specified by -i "*". The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the asterisk in quotation marks ("*") or to escape the asterisk using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif -i "*"
Example 69
Importing User Attributes and Excluding an Attribute

This example imports an LDIF file to the userRoot back end. All user attributes are imported, specified by -i "*", but the roomnumber attribute is excluded. The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the asterisk in quotation marks ("*") or to escape the asterisk using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif \
  -i "*" -e "roomnumber"
Example 70
Importing Operational Attributes Only

This example imports an LDIF file to the userRoot back end. Only operational attributes are imported, specified by -i "+". The LDIF file path must be an absolute path on all platforms. On some systems, you might be required to enclose the plus sign in quotation marks ("+") or to escape the plus sign using a character appropriate to your shell. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif -i "+"
Example 71
Importing Selected User and Operational Attributes

This example imports an LDIF file to the userRoot back end. Only the uid, cn, sn, dc, and creatorsname attributes are imported. The LDIF file path must be an absolute path on all platforms. The directory server must be stopped before running an offline import.

$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l /var/tmp/Example.ldif \
  -i "uid" -i "cn" -i "sn" -i "dc" -i "creatorsname"
Example 72
Running an Online Import

An import is automatically run online if you specify any of the task back end connection options. Because an online import contacts the server over SSL, you must specify how to trust the SSL server certificate. This examples uses the -X option to trust all certificates.

$ import-ldif -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \
    -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif
Example 73
Scheduling an Import

You can schedule an import to run at some future date by using the -t or --start option to specify the start time. Like a regular online import, a scheduled import contacts the task back end of a running directory server and the relevant task back end connection options must be specified.

This example schedules an import to the userRoot back end to start on December 24.

$ import-ldif -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \
  -b dc=example,dc=com -n userRoot -l /usr/tmp/Example.ldif --start 20081224121500
Import task 2008101712361910 scheduled to start Dec 24, 2008 12:15:00 PM SAST

You can view a scheduled task by using the manage-tasks command. For more information, see Configuring Commands As Tasks in Sun OpenDS Standard Edition 2.2 Administration Guide.

Exit Codes
Using a Properties File

The directory server supports the use of a properties file that passes in any default option values used with the export-ldif command. The properties file is convenient when working in different configuration environments, especially in scripted or embedded applications. For more information, see Using a Properties File With Server Commands.

Location

The import-ldif command is located at these paths:

Related Commands