From 83022d82aea5dfd8a0ebd9c963b770ff3b1577a7 Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Fri, 31 Jan 2014 13:21:24 +0000
Subject: [PATCH] CR-2918 fix for OPENDJ-1298: output of 'dbtest list-index-status' should be documented in detail
---
opends/src/main/docbkx/admin-guide/man-dbtest.xml | 136 ++++++++++++++++++++++++++++++++--
opends/resource/man/man1/dbtest.1 | 81 ++++++++++++++++++-
opends/src/main/docbkx/admin-guide/chap-indexing.xml | 17 +++-
3 files changed, 215 insertions(+), 19 deletions(-)
diff --git a/opends/resource/man/man1/dbtest.1 b/opends/resource/man/man1/dbtest.1
index 8834cc4..36da749 100644
--- a/opends/resource/man/man1/dbtest.1
+++ b/opends/resource/man/man1/dbtest.1
@@ -2,12 +2,12 @@
.\" Title: dbtest
.\" Author:
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 03/21/2012
+.\" Date: 01/31/2014
.\" Manual: Tools Reference
-.\" Source: OpenDJ 2.5.0
+.\" Source: OpenDJ 2.7.0-SNAPSHOT
.\" Language: English
.\"
-.TH "DBTEST" "1" "03/21/2012" "OpenDJ 2\&.5\&.0" "Tools Reference"
+.TH "DBTEST" "1" "01/31/2014" "OpenDJ 2\&.7\&.0\-SNAPSHOT" "Tools Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -30,8 +30,8 @@
.SH "NAME"
dbtest \- gather OpenDJ JE database debugging information
.SH "SYNOPSIS"
-.HP \w'\fBdbtest\fR\fBsubcommand\fR\ 'u
-\fBdbtest\fR\fBsubcommand\fR [options]
+.HP \w'\fBdbtest\fR \fBsubcommand\fR\ 'u
+\fBdbtest\fR \fBsubcommand\fR [options]
.SH "DESCRIPTION"
.PP
This utility can be used to debug the JE database\&.
@@ -42,6 +42,8 @@
\fBdbtest dump\-database\-container\fR
.RS 4
Dump records from a database container
+.sp
+Depending on database size, this subcommand can generate lots of output\&.
.RE
.PP
\fBdbtest list\-database\-containers\fR
@@ -57,6 +59,73 @@
\fBdbtest list\-index\-status\fR
.RS 4
List the status of indexes in an entry container
+.sp
+When you list index status, the result is a table, followed by a "Total", which is the total number of indexes, followed by a list of indexes with "Undefined keys" to show the values for which the number of entries exceeded the index entry limit\&. The table has the following columns\&.
+.PP
+Index Name
+.RS 4
+Name of the index, which takes the form
+\fIattr\&.type\fR
+for attribute indexes, and vlv\&.\fIname\fR
+for VLV indexes\&. Some indexes are for OpenDJ directory server\*(Aqs internal use\&.
+.sp
+Example:
+givenName\&.substring
+.RE
+.PP
+Index Type
+.RS 4
+Type of the index, which is
+Index
+for attribute indexes, and
+VLVIndex
+for VLV indexes\&.
+.RE
+.PP
+JE Database Name
+.RS 4
+Name of the Berkeley Java Edition database, which reflects how OpenDJ directory server organizes the data in the database\&.
+.sp
+Example:
+dc_example_dc_com_givenName\&.substring
+.RE
+.PP
+Index Valid
+.RS 4
+This is
+true
+for valid indexes\&. If this is
+false, the index might be degraded.
+Verify the index, and rebuild the index if necessary\&.
+.RE
+.PP
+Record Count
+.RS 4
+Number of indexed keys\&. Use the
+\fBdbtest dump\-database\-container\fR
+command to see how many entry IDs correspond to each key\&.
+.RE
+.PP
+Undefined
+.RS 4
+Number of keys for which there are too many values to maintain an index, based on the index entry limit\&. This is recorded as
+\-
+for VLV indexes\&.
+.sp
+In other words, with the default index entry limit of 4000, if every user in your large directory has a mail address ending in
+@example\&.com, and a substring index is maintained for
+mail, then OpenDJ directory server does not maintain indexes for keys corresponding to substrings in
+@example\&.com\&.
+.sp
+As a result, an LDAP search with the filter
+"(mail=*@example\&.com)"
+becomes an unindexed search even though a substring index exists for the mail attribute\&. By default OpenDJ directory server does not allow unindexed searches except by privileged users\&. This is usually exactly the behavior you want in order to prevent client applications for example from sending searches that return every user in the directory\&. Clients should refine their search filters instead\&.
+.RE
+.PP
+95%, 90%, 85%
+.RS 4
+Number of keys for which the number of values is approaching the index entry limit, having reached the specified percentage\&. This is a measure of how full the entry ID lists are\&.
+.RE
.RE
.PP
\fBdbtest list\-root\-containers\fR
@@ -120,5 +189,5 @@
.\}
.SH "COPYRIGHT"
.br
-Copyright \(co 2011-2012 ForgeRock AS
+Copyright \(co 2011-2014 ForgeRock AS
.br
diff --git a/opends/src/main/docbkx/admin-guide/chap-indexing.xml b/opends/src/main/docbkx/admin-guide/chap-indexing.xml
index 544e0c0..6d6d725 100644
--- a/opends/src/main/docbkx/admin-guide/chap-indexing.xml
+++ b/opends/src/main/docbkx/admin-guide/chap-indexing.xml
@@ -20,15 +20,15 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2013 ForgeRock AS
+ ! Copyright 2011-2014 ForgeRock AS
!
-->
<chapter xml:id='chap-indexing'
xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
- xmlns:xlink='http://www.w3.org/1999/xlink'
- xmlns:xinclude='http://www.w3.org/2001/XInclude'>
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'
+ xmlns:xlink='http://www.w3.org/1999/xlink'>
<title>Indexing Attribute Values</title>
<indexterm>
<primary>Indexes</primary>
@@ -696,9 +696,16 @@
to be used in search filters. The <literal>id2children</literal> and
<literal>id2subtree</literal> are for OpenDJ's internal use.</para>
+ <para>
+ For an explanation of the output
+ of the <command>dbtest list-index-status</command> command, see
+ <link xlink:show="new" xlink:href="admin-guide#dbtest-1"
+ xlink:role="http://docbook.org/xlink/role/olink">dbtest(1)</link>.
+ </para>
+
<para>If you do find the limit is too low for a certain key, you can change
the index entry limit on a per index basis.</para>
-
+
<example xml:id="change-index-entry-limit">
<title>Change Index Entry Limit</title>
diff --git a/opends/src/main/docbkx/admin-guide/man-dbtest.xml b/opends/src/main/docbkx/admin-guide/man-dbtest.xml
index 076d3e9..5588610 100644
--- a/opends/src/main/docbkx/admin-guide/man-dbtest.xml
+++ b/opends/src/main/docbkx/admin-guide/man-dbtest.xml
@@ -20,17 +20,16 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2014 ForgeRock AS
!
-->
<refentry xml:id='dbtest-1'
xmlns='http://docbook.org/ns/docbook'
version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
- xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
- xmlns:xlink='http://www.w3.org/1999/xlink'
- xmlns:xinclude='http://www.w3.org/2001/XInclude'>
- <info><copyright><year>2011-2012</year><holder>ForgeRock AS</holder></copyright></info>
+ xsi:schemaLocation='http://docbook.org/ns/docbook
+ http://docbook.org/xml/5.0/xsd/docbook.xsd'>
+ <info><copyright><year>2011-2014</year><holder>ForgeRock AS</holder></copyright></info>
<refmeta>
<refentrytitle>dbtest</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -42,9 +41,7 @@
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
- <command>dbtest</command>
- <command>subcommand</command>
- <arg>options</arg>
+ <command>dbtest</command> <command>subcommand</command> <arg>options</arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
@@ -59,6 +56,10 @@
<term><command>dbtest dump-database-container</command></term>
<listitem>
<para>Dump records from a database container</para>
+
+ <para>
+ Depending on database size, this subcommand can generate lots of output.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
@@ -77,6 +78,125 @@
<term><command>dbtest list-index-status</command></term>
<listitem>
<para>List the status of indexes in an entry container</para>
+
+ <para>
+ When you list index status, the result is a table,
+ followed by a "Total", which is the total number of indexes,
+ followed by a list of indexes with "Undefined keys" to show
+ the values for which the number of entries exceeded the index entry limit.
+ The table has the following columns.
+ </para>
+
+ <variablelist>
+ <varlistentry>
+ <term>Index Name</term>
+ <listitem>
+ <para>
+ Name of the index,
+ which takes the form <replaceable>attr.type</replaceable>
+ for attribute indexes,
+ and vlv.<replaceable>name</replaceable> for VLV indexes.
+ Some indexes are for OpenDJ directory server's internal use.
+ </para>
+
+ <para>
+ Example: <literal>givenName.substring</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Index Type</term>
+ <listitem>
+ <para>
+ Type of the index,
+ which is <literal>Index</literal> for attribute indexes,
+ and <literal>VLVIndex</literal> for VLV indexes.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>JE Database Name</term>
+ <listitem>
+ <para>
+ Name of the Berkeley Java Edition database,
+ which reflects how OpenDJ directory server
+ organizes the data in the database.
+ </para>
+
+ <para>
+ Example: <literal>dc_example_dc_com_givenName.substring</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Index Valid</term>
+ <listitem>
+ <para>
+ This is <literal>true</literal> for valid indexes.
+ If this is <literal>false</literal>,
+ the index might be degraded.
+ Verify the index, and rebuild the index if necessary.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Record Count</term>
+ <listitem>
+ <para>
+ Number of indexed keys.
+ Use the <command>dbtest dump-database-container</command> command
+ to see how many entry IDs correspond to each key.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Undefined</term>
+ <listitem>
+ <para>
+ Number of keys for which there are too many values
+ to maintain an index, based on the index entry limit.
+ This is recorded as <literal>-</literal> for VLV indexes.
+ </para>
+
+ <para>
+ In other words, with the default index entry limit of 4000,
+ if every user in your large directory has a mail address
+ ending in <literal>@example.com</literal>,
+ and a substring index is maintained for <literal>mail</literal>,
+ then OpenDJ directory server does not maintain indexes for
+ keys corresponding to substrings in <literal>@example.com</literal>.
+ </para>
+
+ <para>
+ As a result, an LDAP search with the filter
+ <literal>"(mail=*@example.com)"</literal> becomes an unindexed search
+ even though a substring index exists for the mail attribute.
+ By default OpenDJ directory server does not allow unindexed searches
+ except by privileged users.
+ This is usually exactly the behavior you want
+ in order to prevent client applications for example
+ from sending searches that return every user in the directory.
+ Clients should refine their search filters instead.
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>95%, 90%, 85%</term>
+ <listitem>
+ <para>
+ Number of keys for which the number of values is approaching
+ the index entry limit, having reached the specified percentage.
+ This is a measure of how full the entry ID lists are.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
</listitem>
</varlistentry>
<varlistentry>
--
Gitblit v1.10.0