From b4dc6090d103341932806786aad48b410c17412c Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Mon, 06 Oct 2014 16:06:20 +0000
Subject: [PATCH] Backport CR-4738 OPENDJ-1581: Cover disk space thresholds in the Admin Guide

---
 opends/src/main/docbkx/admin-guide/chap-import-export.xml |  105 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 104 insertions(+), 1 deletions(-)

diff --git a/opends/src/main/docbkx/admin-guide/chap-import-export.xml b/opends/src/main/docbkx/admin-guide/chap-import-export.xml
index 1a7cb37..2016f86 100644
--- a/opends/src/main/docbkx/admin-guide/chap-import-export.xml
+++ b/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>

--
Gitblit v1.10.0