| Exit Print View | |
Sun OpenDS Standard Edition 2.0 Command-Line Usage Guide |
|
|
|
The import-ldif command populates a directory server back end with data read from an LDIF file.
import-ldif options
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.0 Administration Guide.
You can run the import-ldif command in online or offline mode.
Online mode. In online mode, import-ldif contacts a running directory server instance over SSL, via the administration connector, and registers an import task. The command runs in online mode automatically if you specify any of the task back end connection options. For more information about the administration connector, see Managing Administration Traffic to the Server in Sun OpenDS Standard Edition 2.0 Administration Guide.
Offline mode. In offline mode, import-ldif accesses the database directly rather than through a directory server instance. To perform an offline import, the directory server must be stopped.
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).
Append the imported data to the data that already exists in the back end, rather than clearing the back end before starting the import.
Specify the path to a MakeLDIF template to generate the import data.
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.
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).
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.
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.
Specify the name of an attribute that should be excluded from the import. This option can be used multiple times to specify multiple attributes.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Running an online import requires access to the tasks back end. Access to the tasks back end is provided over SSL via the administration connector. These connection options are used when the import runs online.
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.
Contact the directory server on the specified hostname or IP address. If this option is not provided, a default of localhost is used.
Use the bind password in the specified file when authenticating to the directory server. This option must not be used in conjunction with --bindPassword.
Use the client keystore certificate in the specified path.
Use the specified certificate for client authentication.
Use the specified options for SASL authentication.
Contact the directory server at the specified administration port. If this option is not provided, a default administration port of 4444 is used.
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.
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.
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.
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.
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 -.
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.
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.
These options are used when you specify that the import should run as a scheduled task.
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.
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.
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.
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.
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 utility exits immediately.
Indicates that a properties file is not used to obtain the default command-line options.
Specify the path to the properties file that contains the default command-line options.
Run in quiet mode. Using quiet mode, no output is generated unless a significant error occurs during the import process.
Display command-line usage information for the utility and exit without making any attempt to run an import.
Display the version information for the directory server and exit rather than attempting to run this command.
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.
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
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
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
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 "*"
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"
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 "+"
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"
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
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 utility. For more information, see Configuring Commands As Tasks in Sun OpenDS Standard Edition 2.0 Administration Guide.
Offline mode. An exit code of 0 indicates that the operation completed successfully. A non-zero exit code indicates that an error occurred during processing.
Online mode. If -t or --start is specified, an exit code of 0 indicates that the task was created successfully. A nonzero exit code indicates that an error occurred when the task was created. If -t or --start is not specified, the exit codes are the same as those specified for offline mode.
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 Directory Server Commands.
The import-ldif command is located at these paths:
UNIX and Linux: install-dir/bin/import-ldif
Windows: install-dir\bat\import-ldif.bat
|
|