Backport CR-4738 OPENDJ-1581: Cover disk space thresholds in the Admin Guide

Mark Craig

06.06.2014 b4dc6090d103341932806786aad48b410c17412c

Backport CR-4738 OPENDJ-1581: Cover disk space thresholds in the Admin Guide

 opends/src/main/docbkx/admin-guide/chap-import-export.xml

@@ -362,7 +362,7 @@
   run out of memory when calculating differences between large files.</para>
  </section>
 </section>
 

 <section xml:id="create-database-backend">
  <title>Creating a New Database Backend</title>
  <indexterm>
@@ -454,6 +454,109 @@
  <replaceable>backend-name</replaceable>).</para>
 </section>

 <section xml:id="set-database-backend-disk-thresholds">
  <title>Setting Disk Space Thresholds For Database Backends</title>

  <indexterm>
   <primary>Database backend</primary>
   <secondary>Setting disk space thresholds</secondary>
  </indexterm>

  <para>
   Directory data growth depends on applications that use the directory.
   As a result, when directory applications add more data than they delete,
   the local database backend grows until it fills the available disk space.
   The system can end up in an unrecoverable state if no disk space is available.
  </para>

  <para>
   Local database backends therefore have advanced properties,
   <link
    xlink:href="${configRefBase}/local-db-backend.html#disk-low-threshold"
    xlink:show="new"
   ><literal>disk-low-threshold</literal></link> and
   <link
    xlink:href="${configRefBase}/local-db-backend.html#disk-full-threshold"
    xlink:show="new"
   ><literal>disk-full-threshold</literal></link>.
   When available disk space falls below <literal>disk-low-threshold</literal>,
   OpenDJ server only allows updates from users and applications
   that have the privilege to
   <link
    xlink:show="new"
    xlink:href="admin-guide#about-privileges"
    xlink:role="http://docbook.org/xlink/role/olink"
   ><literal>bypass-lockdown</literal></link>.
   When available space falls below <literal>disk-full-threshold</literal>,
   OpenDJ server stops allowing updates,
   instead returning an <literal>UNWILLING_TO_PERFORM</literal> error
   to each update request.
  </para>

  <para>
   <emphasis>
    OpenDJ server continues to apply replication updates
    without regard to the thresholds.
   </emphasis>
   OpenDJ server can therefore fill available disk space despite the thresholds,
   by accepting replication updates made on other servers.
   You can give yourself more time to react to the situation
   both by monitoring directory data growth
   and also by increasing the thresholds.
  </para>

  <para>
   If growth across the directory service tends to happen quickly,
   set the thresholds higher than the defaults
   to allow more time to react when growth threatens to fill the disk.
   The following example sets <literal>disk-low-threshold</literal> to 2 GB
   <literal>disk-full-threshold</literal> to 1 GB
   for the <literal>userRoot</literal> local backend.
  </para>

  <screen>
$ <userinput>dsconfig \
 set-backend-prop \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --set "disk-low-threshold:2 GB" \
 --set "disk-full-threshold:1 GB" \
 --trustAll \
 --no-prompt</userinput>
  </screen>

  <para>
   The properties
   <literal>disk-low-threshold</literal> and <literal>disk-full-threshold</literal>
   are listed as "advanced" properties.
   To examine their values with the <command>dsconfig</command> command,
   use the <option>--advanced</option> option
   as shown in the following example.
  </para>

  <screen>
$ <userinput>dsconfig \
 get-backend-prop \
 --advanced \
 --hostname opendj.example.com \
 --port 4444 \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --property disk-low-threshold \
 --property disk-full-threshold \
 --trustAll \
 --no-prompt</userinput>
<computeroutput>Property            : Value(s)
--------------------:---------
disk-full-threshold : 1 gb
disk-low-threshold  : 2 gb</computeroutput>
  </screen>
 </section>

 <section xml:id="update-database-backend">
  <title>Updating an Existing Backend to Add a New Base DN</title>
  <indexterm>