Add draft Admin Guide chapter for working with LDIF

Mark Craig

30.22.2011 5910d0a7bc355b6d5d29d32dc10ce61147c0e02d

Add draft Admin Guide chapter for working with LDIF

 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 \
&gt; -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


&gt;&gt;&gt;&gt; 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]: 


&gt;&gt;&gt;&gt; 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


&gt;&gt;&gt;&gt; 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 \
&gt; -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 \
&gt; -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>