Backport CR-3283 Fix for Server docs patch for OPENDJ-980: Allow copy/ past...

Mark Craig

31.17.2014 ae57abea41b1a1c805fee27ffcfeabc0ae07e969

 opends/src/main/docbkx/admin-guide/chap-indexing.xml

@@ -75,10 +75,12 @@
   allows clients to find people even when they misspell names as in the
   following example.</para>
   
   <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn~=Babs Jansen)" cn
dn: uid=bjensen,ou=People,dc=example,dc=com
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn~=Babs Jansen)" cn</userinput>
<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen</screen>
cn: Babs Jensen</computeroutput>
   </screen>
  </section>
  
  <section xml:id="indexes-equality">
@@ -93,9 +95,11 @@
   the search filter. An equality index requires clients to match values
   without wildcards or misspellings.</para>
   
   <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)" mail
dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com</screen>
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)" mail</userinput>
<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
mail: bjensen@example.com</computeroutput>
   </screen>
  </section>
  
  <section xml:id="indexes-ordering">
@@ -112,9 +116,10 @@
   
   <para>The following example shows a search that specifies ranges.</para>
   
   <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com
 "(&amp;(uidNumber&gt;=1120)(roomNumber&gt;=4500))" uid
dn: uid=charvey,ou=People,dc=example,dc=com
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com \
 "(&amp;(uidNumber&gt;=1120)(roomNumber&gt;=4500))" uid</userinput>
<computeroutput>dn: uid=charvey,ou=People,dc=example,dc=com
uid: charvey

dn: uid=eward,ou=People,dc=example,dc=com
@@ -124,7 +129,8 @@
uid: mvaughan

dn: uid=pchassin,ou=People,dc=example,dc=com
uid: pchassin</screen>
uid: pchassin</computeroutput>
   </screen>
  </section>
  
  <section xml:id="indexes-presence">
@@ -139,10 +145,12 @@
   attribute is indexed for presence by default to allow quick retrieval
   of entries with ACIs.</para>
   
   <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(aci=*)" -
dn: dc=example,dc=com
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(aci=*)" -</userinput>
<computeroutput>dn: dc=example,dc=com

dn: ou=People,dc=example,dc=com</screen>
dn: ou=People,dc=example,dc=com</computeroutput>
   </screen>
  </section>
  
  <section xml:id="indexes-substring">
@@ -156,8 +164,9 @@
   in the filter. Substring indexes can be expensive to maintain, especially
   for large attribute values.</para>
   
   <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Barb*)" cn
dn: uid=bfrancis,ou=People,dc=example,dc=com
   <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Barb*)" cn</userinput>
<computeroutput>dn: uid=bfrancis,ou=People,dc=example,dc=com
cn: Barbara Francis

dn: uid=bhal2,ou=People,dc=example,dc=com
@@ -171,7 +180,8 @@
cn: Babs Jensen

dn: uid=bmaddox,ou=People,dc=example,dc=com
cn: Barbara Maddox</screen>
cn: Barbara Maddox</computeroutput>
   </screen>
  </section>
  
  <section xml:id="indexes-vlv">
@@ -221,16 +231,18 @@
  <para>A simple way of checking the indexes that match a search is to request
  the <literal>debugsearchindex</literal> attribute in your results.</para>

  <screen>$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 "(uid=user.1000)"
 debugsearchindex
dn: cn=debugsearch
  <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 "(uid=user.1000)" \
 debugsearchindex</userinput>
<computeroutput>dn: cn=debugsearch
debugsearchindex: filter=(uid=user.1000)[INDEX:uid.equality][COUNT:1] final=[COU
 NT:1]</screen>
 NT:1]</computeroutput>
  </screen>

  <para>When you request the <literal>debugsearchindex</literal> attribute,
  instead of performing the search, OpenDJ returns debug information indicating
@@ -240,32 +252,37 @@
  <para>A less exact search requires more work from OpenDJ. In the following
  example OpenDJ would have to return over 10,000 entries.</para>

  <screen>$ ldapsearch
 --port 1389
 --baseDN dc=example,dc=com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 "(uid=*)"
 debugsearchindex
dn: cn=debugsearch
  <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN dc=example,dc=com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 "(uid=*)" \
 debugsearchindex</userinput>
<computeroutput>dn: cn=debugsearch
debugsearchindex: filter=(uid=*)[NOT-INDEXED] scope=wholeSubtree[LIMIT-EXCEEDED:
 10002] final=[NOT-INDEXED]</screen>
 10002] final=[NOT-INDEXED]</computeroutput>
</screen>

  <para>By default OpenDJ rejects unindexed searches when the number of
  candidate entries goes beyond the search or look-though limit.</para>

  <screen>$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*)"
SEARCH operation failed
  <screen>
$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*)"</userinput>
<computeroutput>SEARCH operation failed
Result Code:  50 (Insufficient Access Rights)
Additional Information:  You do not have sufficient privileges to perform
 an unindexed search</screen>
 an unindexed search</computeroutput>
  </screen>

  <para>When an unindexed search is performed, it shows up in the access
  log with the <literal>unindexed</literal> label.</para>

  <programlisting language="none"
  >...SEARCH RES ... result=50 message="You do not have sufficient privileges
 to perform an unindexed search" nentries=0 unindexed etime=1</programlisting>
  <programlisting language="none">
...SEARCH RES ... result=50 message="You do not have sufficient privileges
 to perform an unindexed search" nentries=0 unindexed etime=1
  </programlisting>

  <para>If directory users tell you their client applications are getting this
  error, then you can work with them either to help them make their search
@@ -293,8 +310,9 @@
  shows up in the access log with the label <literal>unindexed</literal>,
  usually with a large etime as well.</para>

  <programlisting language="none"
  >...SEARCH RES conn=11 op=1 msgID=2 result=0 nentries=10000 unindexed etime=1129</programlisting>
  <programlisting language="none">
...SEARCH RES conn=11 op=1 msgID=2 result=0 nentries=10000 unindexed etime=1129
  </programlisting>

  <para>There is a trade off between the cost of maintaining an index and the
  value the index has in speeding up searches. Although monitoring index use
@@ -303,36 +321,40 @@
  activate index analysis using the <command>dsconfig set-backend-prop</command>
  command.</para>

  <screen>$ dsconfig
 set-backend-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set index-filter-analyzer-enabled:true
 --no-prompt
 --trustAll</screen>
  <screen>
$ <userinput>dsconfig \
 set-backend-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --set index-filter-analyzer-enabled:true \
 --no-prompt \
 --trustAll</userinput>
  </screen>

  <para>The command causes OpenDJ to analyze filters used and keep the results
  in memory, so that you can read them through the <literal>cn=monitor</literal>
  interface.</para>

  <screen>$ ldapsearch
 --port 1389
 --baseDN "cn=userRoot Database Environment,cn=monitor"
 --bindDN "cn=Directory Manager"
 --bindPassword password
 "(objectclass=*)"
 filter-use
dn: cn=userRoot Database Environment,cn=monitor
  <screen>
$ <userinput>ldapsearch \
 --port 1389 \
 --baseDN "cn=userRoot Database Environment,cn=monitor" \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 "(objectclass=*)" \
 filter-use</userinput>
<computeroutput>dn: cn=userRoot Database Environment,cn=monitor
filter-use: (mail=aa*@maildomain.net) hits:1 maxmatches:0 message:
filter-use: (objectClass=*) hits:1 maxmatches:-1 message:presence index type is
 disabled for the objectClass attribute
filter-use: (uid=user.1000) hits:2 maxmatches:1 message:
filter-use: (uid=user.1001) hits:1 maxmatches:1 message:
filter-use: (cn=aa*) hits:1 maxmatches:10 message:
filter-use: (cn=b*) hits:1 maxmatches:834 message:</screen>
filter-use: (cn=b*) hits:1 maxmatches:834 message:</computeroutput>
  </screen>

  <para>The <literal>filter-use</literal> values consist of the filter, followed
  by <literal>hits</literal> being the number of times the filter was used,
@@ -342,16 +364,18 @@
  <para>You can turn off index analysis with the <command>dsconfig
  set-backend-prop</command> command as well.</para>

  <screen>$ dsconfig
 set-backend-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set index-filter-analyzer-enabled:false
 --no-prompt
 --trustAll</screen>
  <screen>
$ <userinput>dsconfig \
 set-backend-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --set index-filter-analyzer-enabled:false \
 --no-prompt \
 --trustAll</userinput>
  </screen>
 </section>

 <section xml:id="configure-indexes">
@@ -388,17 +412,19 @@
    <para>The following example creates a new substring index for
    <literal>description</literal>.</para>
    
    <screen>$ dsconfig
 create-local-db-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name description
 --set index-type:substring
 --trustAll
 --no-prompt</screen>
    <screen>
$ <userinput>dsconfig \
 create-local-db-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --index-name description \
 --set index-type:substring \
 --trustAll \
 --no-prompt</userinput>
    </screen>
   </example>
   
   <example xml:id="approx-index-example">
@@ -411,17 +437,19 @@
    <para>The following example configures an approximate index for
    <literal>cn</literal> (common name).</para>
    
    <screen>$ dsconfig
 set-local-db-index-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name cn
 --set index-type:approximate
 --trustAll
 --no-prompt</screen>
    <screen>
$ <userinput>dsconfig \
 set-local-db-index-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --index-name cn \
 --set index-type:approximate \
 --trustAll \
 --no-prompt</userinput>
    </screen>
   </example>

   <example xml:id="extensible-match-index-example">
@@ -439,19 +467,21 @@
    index for "later than" and "earlier than" generalized time matching on
    a <literal>lastLoginTime</literal> attribute.</para>

    <screen>$ dsconfig
 create-local-db-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --set index-type:extensible
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6
 --index-name lastLoginTime
 --trustAll
 --no-prompt</screen>
    <screen>
$ <userinput>dsconfig \
 create-local-db-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --set index-type:extensible \
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5 \
 --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6 \
 --index-name lastLoginTime \
 --trustAll \
 --no-prompt</userinput>
    </screen>
   </example>
  </section>
  
@@ -462,14 +492,20 @@
    <secondary>Virtual list view (browsing)</secondary>
   </indexterm>
   
   <para>In the OpenDJ Control Panel, select Manage Indexes &gt;
   New VLV Index..., and then set up your VLV index using the New VLV
   <para>In the OpenDJ Control Panel, select Manage Indexes >
   New VLV Index, and then set up your VLV index using the New VLV
   Index window.</para>
  
   <mediaobject xml:id="figure-create-vlv-index">
    <alt>New VLV Index window</alt>
    <imageobject>
     <imagedata fileref="images/create-vlv-index.png" format="PNG" />
    </imageobject>
    <textobject>
     <para>
      The New VLV Index window helps you to configure a browsing index.
     </para>
    </textobject>
   </mediaobject>

   <para>After you finish configuring your index and click OK, the Control
@@ -479,20 +515,22 @@
   <para>You can also create the equivalent index configuration using the
   <command>dsconfig</command> command.</para>
   
   <screen>$ dsconfig
 create-local-db-vlv-index
 --port 4444
 --hostname opendj.example.com
 --bindDn "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name people-by-last-name
 --set base-dn:ou=People,dc=example,dc=com
 --set filter:"(|(givenName=*)(sn=*))"
 --set scope:single-level
 --set sort-order:"+sn +givenName"
 --trustAll
 --no-prompt</screen>
   <screen>
$ <userinput>dsconfig \
 create-local-db-vlv-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDn "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --index-name people-by-last-name \
 --set base-dn:ou=People,dc=example,dc=com \
 --set filter:"(|(givenName=*)(sn=*))" \
 --set scope:single-level \
 --set sort-order:"+sn +givenName" \
 --trustAll \
 --no-prompt</userinput>
   </screen>

   <note>
    <para>When referring to a virtual list view (VLV) index after creation, you
@@ -525,15 +563,17 @@
    <para>The following example rebuilds the <literal>cn</literal> index
    immediately with the server online.</para>
    
    <screen>$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --index cn
 --start 0
Rebuild Index task 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM</screen>
    <screen>
$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --index cn \
 --start 0</userinput>
<computeroutput>Rebuild Index task 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM</computeroutput>
    </screen>
   </example>

   <example xml:id="rebuild-degraded-indexes-example">
@@ -542,14 +582,15 @@
    <para>The following example rebuilds degraded indexes immediately with
    the server online.</para>

    <screen>$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --rebuildDegraded
...
    <screen>
$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --rebuildDegraded</userinput>
<computeroutput>...
[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=7 msgID=8847510
 message="Due to changes in the configuration, index
 dc_example_dc_com_description is currently operating in a degraded state
@@ -562,7 +603,8 @@
 message="Rebuild complete. Processed 160 entries in 0 seconds (average
 rate 1860.5/sec)"
...
Rebuild Index task 20120131164324838 has been successfully completed</screen>
Rebuild Index task 20120131164324838 has been successfully completed</computeroutput>
    </screen>
   </example>

   <example xml:id="clear-degraded-indexes-example">
@@ -583,33 +625,37 @@
    is shown in the following example, where an index has just been created
    for <literal>newUnusedAttribute</literal>.</para>

    <screen>$ dbtest
 list-index-status
 --backendID userRoot
 --baseDN dc=example,dc=com
 | grep newUnusedAttribute
newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   false...
    <screen>
$ <userinput>dbtest \
 list-index-status \
 --backendID userRoot \
 --baseDN dc=example,dc=com \
 | grep newUnusedAttribute</userinput>
<computeroutput>newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   false...
newUnusedAttribute.presence   Index  ...newUnusedAttribute.presence   false...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  false...
$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --clearDegradedState
 --index newUnusedAttribute
 --start 0
Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
 PM CET
$ dbtest
 list-index-status
 --backendID userRoot
 --baseDN dc=example,dc=com
 | grep newUnusedAttribute
newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   true...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  false...</computeroutput>

$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --clearDegradedState \
 --index newUnusedAttribute \
 --start 0</userinput>
<computeroutput>Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
 PM CET</computeroutput>

$ <userinput>dbtest \
 list-index-status \
 --backendID userRoot \
 --baseDN dc=example,dc=com \
 | grep newUnusedAttribute</userinput>
<computeroutput>newUnusedAttribute.equality   Index  ...newUnusedAttribute.equality   true...
newUnusedAttribute.presence   Index  ...newUnusedAttribute.presence   true...
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  true...</screen>
newUnusedAttribute.substring  Index  ...newUnusedAttribute.substring  true...</computeroutput>
    </screen>

    <para>If the newly indexed attribute has already been used, rebuild indexes
    instead.</para>
@@ -650,8 +696,9 @@
   maintained. The "Undefined keys" are then listed below.</para>

   <informalexample><?dbfo pgwide="1"?>
    <screen>$ dbtest list-index-status --backendID userRoot --baseDN dc=example,dc=com
Index Name                 Index Type  JE Database Name                             Index Valid  Record Count  Undefined  95%  90%  85%
    <screen width="136">
$ <userinput>dbtest list-index-status --backendID userRoot --baseDN dc=example,dc=com</userinput>
<computeroutput>Index Name                 Index Type  JE Database Name                             Index Valid  Record Count  Undefined  95%  90%  85%
---------------------------------------------------------------------------------------------------------------------------------------
id2children                Index       dc_example_dc_com_id2children                true         2             1          0    0    0
id2subtree                 Index       dc_example_dc_com_id2subtree                 true         2             2          0    0    0
@@ -686,7 +733,8 @@
Undefined keys: [.net] [@maild] [aildom] [ain.ne] [domain] [et] [ildoma] [in.net] [ldomai] [maildo] [main.n] [n.net] [net] [omain.] [t]

Index: id2subtree
Undefined keys: [1] [2]</screen>
Undefined keys: [1] [2]</computeroutput>
    </screen>
   </informalexample>

   <para>In this case (for a directory with only about 10,000 entries) the
@@ -721,26 +769,29 @@
     production.</para>
    </important>

    <screen>$ dsconfig
 set-local-db-index-prop
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --backend-name userRoot
 --index-name objectClass
 --set index-entry-limit:5000
 --trustAll
 --no-prompt
$ rebuild-index
 --port 4444
 --hostname opendj.example.com
 --bindDN "cn=Directory Manager"
 --bindPassword password
 --baseDN dc=example,dc=com
 --index objectclass
 --start 0
Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</screen>
    <screen>
$ <userinput>dsconfig \
 set-local-db-index-prop \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --backend-name userRoot \
 --index-name objectClass \
 --set index-entry-limit:5000 \
 --trustAll \
 --no-prompt</userinput>

$ <userinput>rebuild-index \
 --port 4444 \
 --hostname opendj.example.com \
 --bindDN "cn=Directory Manager" \
 --bindPassword password \
 --baseDN dc=example,dc=com \
 --index objectclass \
 --start 0</userinput>
<computeroutput>Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</computeroutput>
    </screen>
   </example>
   
   <para>Alternatively, you can configure the index entry limit for all
@@ -769,12 +820,13 @@
   <para>The following example verifies the <literal>cn</literal> (common
   name) index for completeness and for errors.</para>

   <screen>$ verify-index
 --baseDN dc=example,dc=com
 --index cn
 --clean
 --countErrors
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
   <screen>
$ <userinput>verify-index \
 --baseDN dc=example,dc=com \
 --index cn \
 --clean \
 --countErrors</userinput>
<computeroutput>[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
 msgID=9437595 msg=Local DB backend userRoot does not specify the number of
 lock tables: defaulting to 97
[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
@@ -791,7 +843,8 @@
 msgID=8388712 msg=Average number of entries referenced is 1.58/record
[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
 msgID=8388713 msg=Maximum number of entries referenced by any
 record is 32</screen>
 record is 32</computeroutput>
   </screen>

   <para>Ignore the messages regarding lock tables and cleaner threads. The
   important information is whether any errors are found in the indexes.</para>