From 5910d0a7bc355b6d5d29d32dc10ce61147c0e02d Mon Sep 17 00:00:00 2001 From: Mark Craig <mark.craig@forgerock.com> Date: Mon, 30 May 2011 16:22:24 +0000 Subject: [PATCH] Add draft Admin Guide chapter for working with LDIF --- opendj3/src/main/docbkx/admin-guide/chap-import-export.xml | 270 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 267 insertions(+), 3 deletions(-) diff --git a/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml b/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml index 4c12ba7..45ff62b 100644 --- a/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml +++ b/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml @@ -37,9 +37,273 @@ directories that cannot replicate directly, or even as an alternative backup format.</para> - <para>This chapter shows you how to backup and restore OpenDJ data, including - how to import and export LDIF. This chapter also covers creating test data - in LDIF format, and manipulating LDIF data with command-line tools.</para> + <para>This chapter shows you how to import and export LDIF. + This chapter also covers creating test data in LDIF format, and manipulating + LDIF data with command-line tools.</para> + + <procedure> + <title>To Generate Test LDIF Data</title> + + <para>When you install OpenDJ, you have the option of importing sample + data generated at installation time. This procedure demonstrates how to + generate LDIF on the command line using the + <command>make-ldif</command>.</para> + + <para>The <command>make-ldif</command> command uses templates to provide + sample data. Default templates are located in the + <filename>OpenDJ/config/MakeLDIF/</filename> directory. The + <filename>example.template</filename> file can be used to create + a suffix with <literal>inetOrgPerson</literal> entries of the type you have + the option to generate at installation time.</para> + + <step> + <para>Write a file to act as the template for your generated LDIF.</para> + <para>The resulting test data template depends on what data you expect to + encounter in production. Base your work on your knowledge of the production + data, and on the sample template, + <filename>OpenDJ/config/MakeLDIF/example.template</filename>, and + associated data.</para> + </step> + <step> + <para>Create additional data files for the content in your template to be + selected randomly from a file, rather than generated by an expression.</para> + <para>Additional data files are located in the same directory as your + template file.</para> + </step> + <step> + <para>Decide whether you want to generate the same test data each time + you run the <command>make-ldif</command> command with your template.</para> + <para>If so, pick an integer same random seed to provide each time you run + the command.</para> + </step> + <step> + <para>Before generating a very large LDIF file, make sure you have enough + space on disk.</para> + </step> + <step> + <para>Run the <command>make-ldif</command> command to generate your + LDIF file.</para> + <screen width="80">$ make-ldif --randomSeed 0 -t /path/to/my.template \ +> -o generated.ldif +Processed 1000 entries +Processed 2000 entries +... +Processed 10000 entries +LDIF processing complete. 10003 entries written</screen> + </step> + </procedure> + <procedure> + <title>To Import LDIF Data</title> + + <para>You can also use the OpenDJ Control Panel to import data (Directory + Data > Import LDIF...). This procedure demonstrates how to import LDIF using + the command line tool, <command>import-ldif</command>.</para> + + <para>You can import LDIF most quickly after shutting down OpenDJ directory + server. Alternatively, if you do not want to shut the server down, you can + schedule a task to import the data while the server is online.</para> + + <step performance="optional"> + <para>To speed up the operation for large data sets such as importing + millions of entries, first shut down the server where you plan to import + data.</para> + <screen width='80'>$ stop-ds</screen> + </step> + <step performance="optional"> + <para>Create a new JE backend for your data if you do not want to use + an existing backend, such as <literal>userRoot</literal>, and set the + base DN corresponding to your data.</para> + <screen width='80'>$ dsconfig create-backend --backend-name testData --type local-db + + +>>>> Configuring the "base-dn" property + + Specifies the base DN(s) for the data that the backend handles. + + A single backend may be responsible for one or more base DNs. Note that no + two backends may have the same base DN although one backend may have a + base DN that is below a base DN provided by another backend (similar to + the use of sub-suffixes in the Sun Java System Directory Server). If any + of the base DNs is subordinate to a base DN for another backend, then all + base DNs for that backend must be subordinate to that same base DN. + + Syntax: DN + +Enter a value for the "base-dn" property: dc=example,dc=org + +Enter another value for the "base-dn" property [continue]: + + +>>>> Configuring the "enabled" property + + Indicates whether the backend is enabled in the server. + + If a backend is not enabled, then its contents are not accessible when + processing operations. + +Select a value for the "enabled" property: + + 1) true + 2) false + + ?) help + q) quit + +Enter choice: 1 + + +>>>> Configure the properties of the Local DB Backend + + Property Value(s) + -------------------------------------- + 1) backend-id testData + 2) base-dn "dc=example,dc=org" + 3) compact-encoding true + 4) db-cache-percent 10 + 5) db-cache-size 0 b + 6) db-directory db + 7) enabled true + 8) index-entry-limit 4000 + 9) writability-mode enabled + + ?) help + f) finish - create the new Local DB Backend + q) quit + +Enter choice [f]: + +The Local DB Backend was created successfully</screen> + </step> + <step> + <para>The following example imports <literal>dc=example,dc=org</literal> + data into the existing <literal>userRoot</literal> JE backend, replacing + any data already loaded.</para> + <stepalternatives> + <step> + <para>If you stopped the server, import the data directly.</para> + <screen width='80'>$ import-ldif -b dc=example,dc=org -n userRoot -l /path/to/generated.ldif</screen> + </step> + <step> + <para>If not, schedule a task to import the data while online.</para> + <screen width='80'>$ import-ldif -X -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \ +> -b dc=example,dc=org -n userRoot -l /path/to/generated.ldif</screen> + <para>Notice that the task is scheduled through communication over SSL on + the administration port, by default <literal>4444</literal>. You can + schedule the import task to start at a particular time using the + <option>--start</option> option.</para> + <para>The <option>-X</option> option trusts all SSL certificates, such + as a default self-signed certificate used for testing.</para> + </step> + </stepalternatives> + </step> + </procedure> + + <procedure> + <title>To Export LDIF Data</title> + + <para>You can also use the OpenDJ Control Panel to export data (Directory + Data > Export LDIF...). This procedure demonstrates how to export LDIF using + the command line tool, <command>export-ldif</command>.</para> + + <step performance="optional"> + <para>To speed up the operation for large data sets such as exporting + millions of entries, first shut down the server.</para> + <screen width='80'>$ stop-ds</screen> + </step> + <step> + <para>The following example exports <literal>dc=example,dc=org</literal> + data from the <literal>userRoot</literal> JE backend.</para> + <stepalternatives> + <step> + <para>If you stopped the server, export the data directly.</para> + <screen width='80'>$ export-ldif -b dc=example,dc=org -n userRoot -l /path/to/backup.ldif</screen> + </step> + <step> + <para>If not, schedule a task to export the data while online.</para> + <screen>$ export-ldif -X -p 4444 -h `hostname` -D "cn=Directory Manager" -w password \ +> -b dc=example,dc=org -n userRoot -l /path/to/backup.ldif \ +--start 20111221230000</screen> + <para>The <option>--start 20111221230000</option> option tells OpenDJ to + start the export at 11 PM on December 21, 2012, assuming the world has + not ended yet.</para> + </step> + </stepalternatives> + </step> + </procedure> + + <section> + <title>Other Tools For Working With LDIF Data</title> + + <para>This section demonstrates the <command>ldifsearch</command>, + <command>ldifmodify</command>, and <command>ldif-diff</command> tools.</para> + + <section> + <title>Searching in LDIF With <command>ldifsearch</command></title> + + <para>The <command>ldifsearch</command> command lets you search LDIF files + in a similar way to how you search LDAP directories with the + <command>ldapsearch</command> command.</para> + + <screen width="80">$ ldifsearch -b dc=example,dc=org -l generated.ldif "(sn=Grenier)" mobile +dn: uid=user.4630,ou=People,dc=example,dc=org +mobile: +1 728 983 6669 + +</screen> + + <para>The <option>-l <replaceable>ldif-file</replaceable></option> option + compares to the hostname and port options used to connect to an LDAP + directory. Otherwise the command syntax and LDIF output is familiar to + <command>ldapsearch</command> users.</para> + </section> + + <section> + <title>Updating LDIF With <command>ldifmodify</command></title> + + <para>The <command>ldifmodify</command> command lets you apply changes to + LDIF files, generating a new, changed version of the original file.</para> + + <screen width="80">$ cat changes.ldif +dn: uid=user.0,ou=People,dc=example,dc=org +changetype: modify +replace: description +description: This is the new description for Aaccf Amar. +- +replace: initials +initials: AAA + +$ ldifmodify -s generated.ldif -m changes.ldif -t new.ldif</screen> + + <para>Notice that the resulting new LDIF file is likely to be about the + same size as the source LDIF file.</para> + </section> + + <section> + <title>Comparing LDIF With <command>ldif-diff</command></title> + + <para>The <command>ldif-diff</command> command reports differences between + two LDIF files in LDIF format.</para> + + <screen width="80">$ ldif-diff -s old.ldif -t new.ldif +dn: uid=user.0,ou=People,dc=example,dc=org +changetype: modify +add: initials +initials: AAA +- +delete: initials +initials: ASA +- +add: description +description: This is the new description for Aaccf Amar. +- +delete: description +description: This is the description for Aaccf Amar. + +</screen> + + <para>The <option>-o <replaceable>ldif-file</replaceable></option> option + can be used to save the output to a file.</para> + </section> + </section> </chapter> -- Gitblit v1.10.0