6443N/A<?
xml version="1.0" encoding="UTF-8"?>
6443N/A ! This work is licensed under the Creative Commons 6443N/A ! Attribution-NonCommercial-NoDerivs 3.0 Unported License. 6443N/A ! To view a copy of this license, visit 6443N/A ! or send a letter to Creative Commons, 444 Castro Street, 6443N/A ! Suite 900, Mountain View, California, 94041, USA. 6443N/A ! You can also obtain a copy of the license at 6443N/A ! See the License for the specific language governing permissions 6443N/A ! and limitations under the License. 6443N/A ! If applicable, add the following below this CCPL HEADER, with the fields 6443N/A ! enclosed by brackets "[]" replaced with your own identifying information: 6443N/A ! Portions Copyright [yyyy] [name of copyright owner] 7321N/A ! Copyright 2011-2015 ForgeRock AS. 6443N/A<
chapter xml:
id='chap-import-export' 6443N/A <
title>Importing & Exporting LDIF Data</
title>
6443N/A <
indexterm><
primary>Provisioning</
primary></
indexterm>
6443N/A <
indexterm><
primary>Importing data</
primary></
indexterm>
6443N/A <
primary>Restoring</
primary>
6443N/A <
secondary>From LDIF</
secondary>
6443N/A <
indexterm><
primary>Exporting data</
primary></
indexterm>
6443N/A <
indexterm><
primary>Backup</
primary></
indexterm>
6443N/A <
secondary>Import</
secondary>
6443N/A <
secondary>Export</
secondary>
6443N/A <
para>LDAP Data Interchange Format provides a mechanism for representing
6443N/A directory data in text format. LDIF data is typically used to initialize
6443N/A directory databases, but also may be used to move data between different
6443N/A directories that cannot replicate directly, or even as an alternative
6443N/A <
para>This chapter shows you how to import and export LDIF.
6443N/A This chapter also covers creating test data in LDIF format, and manipulating
6443N/A LDIF data with command-line tools.</
para>
6443N/A <
section xml:
id="generating-ldif">
6443N/A <
title>Generating Test Data</
title>
7255N/A you have the option of importing sample data
7255N/A that is generated during the installation.
7255N/A This procedure demonstrates how to generate LDIF by using the
7321N/A xlink:
href="reference#make-ldif-1" 7255N/A ><
command>make-ldif</
command></
link> command.
6443N/A <
procedure xml:
id="generate-ldif">
6443N/A <
title>To Generate Test LDIF Data</
title>
6443N/A <
primary>Importing data</
primary>
6443N/A <
secondary>Test data</
secondary>
6443N/A <
para>The <
command>make-ldif</
command> command uses templates to provide
6443N/A sample data. Default templates are located in the
6443N/A a suffix with entries of the type <
literal>inetOrgPerson</
literal>. You can
6443N/A do the equivalent in OpenDJ Control Panel (Directory Data > New Base
6443N/A DN... > Import Automatically Generated Example Data).</
para>
6443N/A <
para>Write a file to act as the template for your generated LDIF.</
para>
6443N/A <
para>The resulting test data template depends on what data you expect to
6443N/A encounter in production. Base your work on your knowledge of the production
6443N/A data, and on the sample template,
7321N/A <
para>See <
link xlink:
href="reference#make-ldif-template-5" 6443N/A <
para>Create additional data files for the content in your template to be
6443N/A selected randomly from a file, rather than generated by an expression.</
para>
6443N/A <
para>Additional data files are located in the same directory as your
6443N/A <
para>Decide whether you want to generate the same test data each time
6443N/A you run the <
command>make-ldif</
command> command with your template.</
para>
6443N/A <
para>If so, provide the same <
literal>randomSeed</
literal> integer each
6443N/A time you run the command.</
para>
6443N/A <
para>Before generating a very large LDIF file, make sure you have enough
6443N/A <
para>Run the <
command>make-ldif</
command> command to generate your
7097N/A<
computeroutput>Processed 1000 entries
7097N/ALDIF processing complete. 10003 entries written</
computeroutput>
6443N/A <
section xml:
id="importing-exporting-ldif">
6443N/A <
title>Importing & Exporting Data</
title>
7255N/A You can use OpenDJ Control Panel
7255N/A to import data (Directory Data > Import LDIF)
7255N/A and to export data (Directory Data > Export LDIF).
7255N/A The following procedures demonstrate how to use the
7321N/A xlink:
href="reference#import-ldif-1" 7255N/A ><
command>import-ldif</
command></
link> and
7321N/A xlink:
href="reference#export-ldif-1" 7255N/A ><
command>export-ldif</
command></
link> commands.
6443N/A <
procedure xml:
id="import-ldif">
6443N/A <
title>To Import LDIF Data</
title>
6443N/A <
para>The most efficient method of importing LDIF data is to take the
6443N/A OpenDJ server offline. Alternatively, you can schedule a task to import
6443N/A the data while the server is online.</
para>
6443N/A <
step performance="optional">
6443N/A <
para>If you do not want to use the default <
literal>userRoot</
literal>
6443N/A backend, create a new JE backend for your data.</
para>
6443N/A <
para>See <
xref linkend="create-database-backend" /> for details.</
para>
6443N/A <
para>The following example imports <
literal>dc=example,dc=org</
literal>
6443N/A data into the <
literal>userRoot</
literal> backend, overwriting existing
6443N/A <
para>If you want to speed up the process—for example because you
6443N/A have millions of directory entries to import—first shut down the
6443N/A server, and then run the <
command>import-ldif</
command> command.</
para>
7097N/A$ <
userinput>stop-ds</
userinput>
7097N/A --includeBranch dc=example,dc=org \
6443N/A <
para>If not, schedule a task to import the data while online.</
para>
7097N/A --bindDN "cn=Directory Manager" \
7097N/A --includeBranch dc=example,dc=org \
6443N/A <
para>Notice that the task is scheduled through communication over SSL on
6443N/A the administration port, by default <
literal>4444</
literal>. You can
6443N/A schedule the import task to start at a particular time using the
6443N/A <
option>--start</
option> option.</
para>
6443N/A <
para>The <
option>--trustAll</
option> option trusts all SSL certificates,
6443N/A such as a default self-signed certificate used for testing.</
para>
6443N/A <
procedure xml:
id="export-ldif">
6443N/A <
title>To Export LDIF Data</
title>
6443N/A <
para>The following example exports <
literal>dc=example,dc=org</
literal>
6443N/A data from the <
literal>userRoot</
literal> backend.</
para>
6443N/A <
para>If you want to speed up export, first shut down the server, and then
6443N/A export data using the <
command>export-ldif</
command> command.</
para>
7097N/A$ <
userinput>stop-ds</
userinput>
7097N/A --includeBranch dc=example,dc=org \
6443N/A <
para>If not, schedule a task to export the data while online.</
para>
7097N/A --bindDN "cn=Directory Manager" \
7097N/A --includeBranch dc=example,dc=org \
6443N/A <
para>The <
option>--start 20111221230000</
option> option tells OpenDJ to
6443N/A start the export at 11 PM on December 21, 2012.</
para>
6443N/A <
para>If OpenDJ is stopped at this time, then when you start OpenDJ again,
6443N/A the server attempts to perform the task after starting up.</
para>
6443N/A <
section xml:
id="ldif-tools">
6443N/A <
title>Other Tools For Working With LDIF Data</
title>
6443N/A <
secondary>Tools</
secondary>
7255N/A This section demonstrates the
7321N/A xlink:
href="reference#ldifsearch-1" 7255N/A ><
command>ldifsearch</
command></
link>,
7321N/A xlink:
href="reference#ldifmodify-1" 7255N/A ><
command>ldifmodify</
command></
link> and
7321N/A xlink:
href="reference#ldif-diff-1" 7255N/A ><
command>ldif-diff</
command></
link> commands.
6443N/A <
section xml:
id="ldifsearch-example">
6443N/A <
title>Searching in LDIF With <
command>ldifsearch</
command></
title>
6443N/A <
para>The <
command>ldifsearch</
command> command lets you search LDIF files
6443N/A in a similar way to how you search LDAP directories with the
6443N/A <
command>ldapsearch</
command> command.</
para>
7097N/A --baseDN dc=example,dc=org \
7097N/A<
computeroutput>dn: uid=user.4630,ou=People,dc=example,dc=org
7097N/Amobile: +1 728 983 6669</
computeroutput>
6443N/A <
para>The <
option>--ldifFile <
replaceable>ldif-file</
replaceable></
option>
6443N/A option replaces the <
option>--hostname</
option> and <
option>--port</
option>
6443N/A options used to connect to an LDAP directory. Otherwise the command syntax
6443N/A and LDIF output is familiar to <
command>ldapsearch</
command> users.</
para>
6443N/A <
section xml:
id="ldifmodify-example">
6443N/A <
title>Updating LDIF With <
command>ldifmodify</
command></
title>
6443N/A <
para>The <
command>ldifmodify</
command> command lets you apply changes to
6443N/A LDIF files, generating a new, changed version of the original file.</
para>
7097N/A<
computeroutput>dn: uid=user.0,ou=People,dc=example,dc=org
6443N/Adescription: This is the new description for Aaccf Amar.
6443N/A <
para>Notice that the resulting new LDIF file is likely to be about the
6443N/A same size as the source LDIF file.</
para>
6443N/A <
section xml:
id="ldif-diff-example">
6443N/A <
title>Comparing LDIF With <
command>ldif-diff</
command></
title>
6443N/A <
para>The <
command>ldif-diff</
command> command reports differences between
6443N/A two LDIF files in LDIF format.</
para>
7097N/A<
computeroutput>dn: uid=user.0,ou=People,dc=example,dc=org
6443N/Adescription: This is the new description for Aaccf Amar.
6443N/Adescription: This is the description for Aaccf Amar.
6443N/A <
para>As the <
command>ldif-diff</
command> command reads both files into
6443N/A memory, constructing tree maps to perform the comparison, the command
6443N/A is designed to work with small files and fragments. The command can quickly
6443N/A run out of memory when calculating differences between large files.</
para>
6443N/A <
section xml:
id="create-database-backend">
6443N/A <
title>Creating a New Database Backend</
title>
6443N/A <
primary>Database backend</
primary>
6443N/A <
secondary>Creating</
secondary>
7231N/A OpenDJ stores your directory data in a <
firstterm>backend</
firstterm>.
7231N/A Backends are what you backup and restore.
7231N/A By default, OpenDJ stores your data in a backend named <
literal>userRoot</
literal>.
7255N/A You can create new backends using the
7321N/A xlink:
href="reference#dsconfig-create-backend" 7255N/A ><
command>dsconfig create-backend</
command></
link> command.
7231N/A The following example creates a local backend named <
literal>testData</
literal>.
7097N/A$ <
userinput>dsconfig create-backend --backend-name testData --type local-db</
userinput>
7097N/A>>>> Configuring the "base-dn" property
6443N/A Specifies the base DN(s) for the data that the backend handles.
6443N/A A single backend may be responsible for one or more base DNs. Note that no
6443N/A two backends may have the same base DN although one backend may have a
6443N/A base DN that is below a base DN provided by another backend (similar to
6443N/A the use of sub-suffixes in the Sun Java System Directory Server). If any
6443N/A of the base DNs is subordinate to a base DN for another backend, then all
6443N/A base DNs for that backend must be subordinate to that same base DN.
7097N/AEnter a value for the "base-dn" property:</
computeroutput> <
userinput>dc=example,dc=org</
userinput>
6443N/AEnter another value for the "base-dn" property [continue]:
7097N/A>>>> Configuring the "enabled" property
6443N/A Indicates whether the backend is enabled in the server.
6443N/A If a backend is not enabled, then its contents are not accessible when
6443N/ASelect a value for the "enabled" property:
7097N/AEnter choice:</
computeroutput> <
userinput>1</
userinput>
7097N/A>>>> Configure the properties of the Local DB Backend
6443N/A --------------------------------------
6443N/A 2) base-dn "dc=example,dc=org"
6443N/A 9) writability-mode enabled
6443N/A f) finish - create the new Local DB Backend
7097N/AThe Local DB Backend was created successfully</
computeroutput>
6443N/A <
para>Alternatively, you can create a new backend in OpenDJ Control Panel
7097N/A (Directory Data > New Base DN > Backend > New Backend:
6443N/A <
replaceable>backend-name</
replaceable>).</
para>
7275N/A <
section xml:
id="set-database-backend-disk-thresholds">
7275N/A <
title>Setting Disk Space Thresholds For Database Backends</
title>
7275N/A <
primary>Database backend</
primary>
7275N/A <
secondary>Setting disk space thresholds</
secondary>
7275N/A Directory data growth depends on applications that use the directory.
7275N/A As a result, when directory applications add more data than they delete,
7275N/A the local database backend grows until it fills the available disk space.
7275N/A The system can end up in an unrecoverable state if no disk space is available.
7275N/A Local database backends therefore have advanced properties,
7275N/A ><
literal>disk-low-threshold</
literal></
link> and
7275N/A ><
literal>disk-full-threshold</
literal></
link>.
7275N/A When available disk space falls below <
literal>disk-low-threshold</
literal>,
7275N/A OpenDJ server only allows updates from users and applications
7275N/A xlink:
href="admin-guide#about-privileges" 7275N/A ><
literal>bypass-lockdown</
literal></
link>.
7275N/A When available space falls below <
literal>disk-full-threshold</
literal>,
7275N/A OpenDJ server stops allowing updates,
7275N/A instead returning an <
literal>UNWILLING_TO_PERFORM</
literal> error
7275N/A OpenDJ server continues to apply replication updates
7275N/A without regard to the thresholds.
7275N/A OpenDJ server can therefore fill available disk space despite the thresholds,
7275N/A by accepting replication updates made on other servers.
7275N/A You can give yourself more time to react to the situation
7275N/A both by monitoring directory data growth
7275N/A and also by increasing the thresholds.
7275N/A If growth across the directory service tends to happen quickly,
7275N/A set the thresholds higher than the defaults
7275N/A to allow more time to react when growth threatens to fill the disk.
7275N/A The following example sets <
literal>disk-low-threshold</
literal> to 2 GB
7275N/A <
literal>disk-full-threshold</
literal> to 1 GB
7275N/A for the <
literal>userRoot</
literal> local backend.
7275N/A --bindDN "cn=Directory Manager" \
7275N/A --set "disk-low-threshold:2 GB" \
7275N/A --set "disk-full-threshold:1 GB" \
7275N/A <
literal>disk-low-threshold</
literal> and <
literal>disk-full-threshold</
literal>
7275N/A are listed as "advanced" properties.
7275N/A To examine their values with the <
command>dsconfig</
command> command,
7275N/A use the <
option>--advanced</
option> option
7275N/A as shown in the following example.
7275N/A --bindDN "cn=Directory Manager" \
7275N/A --property disk-low-threshold \
7275N/A --property disk-full-threshold \
7275N/A<
computeroutput>Property : Value(s)
7275N/A--------------------:---------
7275N/Adisk-low-threshold : 2 gb</
computeroutput>
7231N/A <
section xml:
id="update-database-backend">
7231N/A <
title>Updating an Existing Backend to Add a New Base DN</
title>
7231N/A <
primary>Database backend</
primary>
7231N/A <
secondary>Updating</
secondary>
7231N/A In addition to letting you create new backends as described in
7231N/A <
xref linkend="create-database-backend" />,
7231N/A OpenDJ lets you add a new base DN to an existing backend.
7231N/A The following example adds the suffix <
literal>o=example</
literal>
7231N/A to the existing backend <
literal>userRoot</
literal>.
7231N/A --bindDN "cn=Directory Manager" \
7231N/A --bindDN "cn=Directory Manager" \
7231N/A<
computeroutput>Property : Value(s)
7231N/A---------:-------------------------------
7231N/Abase-dn : "dc=example,dc=com", o=example</
computeroutput>
7231N/A Alternatively, you can update an existing backend in OpenDJ Control Panel
7231N/A (Directory Data > New Base DN,
7231N/A then select the existing backend from the dropdown Backend list,
7231N/A and enter the new Base DN name).
6443N/A <
section xml:
id="delete-database-backend">
6443N/A <
title>Deleting a Database Backend</
title>
6443N/A <
primary>Database backend</
primary>
6443N/A <
secondary>Deleting</
secondary>
7255N/A You delete a database backend by using the
7321N/A xlink:
href="reference#dsconfig-delete-backend" 7255N/A ><
command>dsconfig delete-backend</
command></
link> command.
6443N/A <
para>When you delete a database backend by using the <
command>dsconfig
6443N/A delete-backend</
command> command, OpenDJ does not actually remove the
6443N/A database files for two reasons. First, a mistake could potentially cause
6443N/A lots of data to be lost. Second, deleting a large database backend could
6443N/A cause severe service degradation due to a sudden increase in I/O load.</
para>
6443N/A <
para>Instead, after you run the <
command>dsconfig delete-backend</
command>
6443N/A command you must also manually remove the database backend files.</
para>
6443N/A <
para>If you do run the <
command>dsconfig delete-backend</
command> command by
6443N/A mistake and have not yet deleted the actual files, then you can recover from
6443N/A the mistake by creating the backend again, reconfiguring the indexes that
6443N/A were removed, and rebuilding the indexes as described in the section on <
link 6443N/A xlink:
href="admin-guide#configure-indexes" 6443N/A Rebuilding Indexes</
citetitle></
link>.</
para>