test

Sun Java System Directory Server Enterprise Edition 6.2 Administration Guide

Chapter 12 Directory Server Indexing

Like a book index, Directory Server indexes speed up searches by associating search strings with references to the directory contents.

For information about the types of indexes and index tuning, see Chapter 6, Directory Server Indexing, in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

This chapter covers the following topics:

Managing Indexes

This section describes how to manage indexes for specific attributes. The section includes information about creating, modifying, and deleting indexes. See Managing Browsing Indexes for procedures specific to virtual list view (VLV) operations.

ProcedureTo List Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. To list your existing indexes and their properties, use this command:


    $ dsconf list-indexes -h host -p port -v suffix-DN

ProcedureTo Create Indexes

Note –

You cannot create a new system index. Only the existing system indexes defined internally by Directory Server are maintained.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Create the new index configuration.

    Use the dsconf create-index command-line utility to configure the new index information by specifying the attribute that you want to index.

    For example, to create an index entry for the preferredLanguage attribute, use this command:


    $ dsconf create-index -h host -p port dc=example,dc=com preferredLanguage
    Note –

    The command dsconf create-index sets the index configuration, but does not actually create the index files necessary for searches. Generating the index files can affect performance. To give you more control over the indexing procedure, generating the index files is done manually after the new index configuration has been created.

    Always use the attribute’s primary name when creating indexes. Do not use the attribute’s alias. The primary name of the attribute is the first name listed for the attribute in the schema, for example, uid for the userid attribute.

  2. (Optional) Set the index properties by using the dsconf set-index-prop command.

    The dsconf create-index command creates an index with default properties. If you want to modify these properties, use the dsconf set-index-prop command . For more information about modifying index properties, see To Modify Indexes.

  3. Generate the index files.

    See To Generate Indexes.

  4. Repeat the previous steps for all servers that you want to be indexed.

ProcedureTo Modify Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Modify the index properties.


    $ dsconf set-index-prop -h host -p port suffix-DN attr-name property:value

    For example, to enable the approximate index approx-enabled for the preferredLanguage index , use the command:


    $ dsconf set-index-prop -h host -p port dc=example,dc=com preferredLanguage approx-enabled:on

    You can modify the following properties for each index:

    • eq-enabled equality

    • pres-enabled presence

    • sub-enabled substring

    One of the properties that you might want to modify is the optional nsMatchingRule attribute. This attribute contains the OID for any matching rule known by the server. It enables the OID of a language collation order for internationalized indexes, and other matching rules such as CaseExactMatch. For a list of supported locales and the OID of their associated collation order, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

    For more information about index configuration attributes, see Sun Java System Directory Server Enterprise Edition 6.2 Reference.

  2. Regenerate your new indexes.

    See To Generate Indexes.

  3. Repeat the previous steps for all servers that include the modified attribute index.

ProcedureTo Generate Indexes

This procedure generates index files so that new or modified indexes can be searchable.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Generate your index files in one of the following ways:

    • Generate your new index files online.


      $ dsconf reindex -h host -p port [-t attr] suffix-DN

      where -t specifies that only the specified attribute or attributes are to be reindexed, not all attributes.

      For example, to regenerate the preferredLanguage index, type:


      $ dsconf reindex -h host -p port -t preferredLanguage dc=example,dc=com

      While the dsconf reindex command is running, the contents of the suffix remain available through the server. However, searches are not indexed until the command has completed. Reindexing is a resource-intensive task that can impact the performance of other operations on the server.

    • Generate your new index files offline. 


      $ dsadm reindex -t attr instance-path suffix-DN

      For example, to regenerate the preferredLanguage index, type:


      $ dsadm reindex -t preferredLanguage /local/ds dc=example,dc=com

    • Regenerate all of your indexes quickly offline by reinitializing your suffix.

      When you reinitialize a suffix, all index files are automatically regenerated. Depending on the size of the directory, reinitializing the suffix is usually faster than reindexing two or more attributes. However, the suffix is unavailable during the initialization. For more information, see Reindexing a Suffix by Reinitialization.

    Note –

    If you run either dsconf import or dsconf reindex or both commands on multiple suffixes in parallel, transaction logs will grow and might negatively affect performance.

ProcedureTo Delete Indexes

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Remove all indexes that are configured for an attribute.


    $ dsconf delete-index -h host -p port suffix-DN attr-name

    For example, the following command deletes all indexes for the preferredLanguage attribute:


    $ dsconf delete-index -h host -p port dc=example,dc=com preferredLanguage

    Take great care when deleting default indexes because it can affect Directory Server functioning.

Changing the Index List Threshold

Slow searches might be a result of your system index list size exceeding the index list threshold. The index list threshold is the maximum number of values for each index key. To determine whether the index list threshold size has been exceeded, examine the access log. The notes=U flag at the end of an access log RESULT message indicates that an unindexed search was performed. A previous SRCH message for the same connection and operation specifies the search filter that was used. The following two-line example traces an unindexed search for cn=Smith that returns 10,000 entries. Timestamps have been removed from the messages.


conn=2 op=1 SRCH base="o=example.com" scope=0 filter="(cn=Smith)"
conn=2 op=1 RESULT err=0 tag=101 nentries=10000 notes=U

If your system often exceeds the index list threshold, consider increasing the threshold to improve performance. The following procedure uses the dsconf set-server-prop command to modify the all-ids-threshold property. For more information about tuning indexes and the all-ids-threshold property, see Tuning Indexes for Performance in Sun Java System Directory Server Enterprise Edition 6.2 Reference.

ProcedureTo Change the Index List Threshold

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Adjust the index list threshold.

    You can adjust your index list threshold at any of the following levels:

    • At the instance level:


      dsconf set-server-prop -h host -p port all-ids-threshold:value

    • At the suffix level:


      dsconf set-suffix-prop -h host -p port suffix-DN all-ids-threshold:value

    • At the entry level:


      dsconf set-index-prop -h host -p port suffix-DN all-ids-threshold:value

    • At the index level, by search type:


      dsconf set-index-prop -h host -p port suffix-DN all-ids-threshold search-type:value

      where search-type is one of the following:

      • eq-enabled equality

      • pres-enabled presence

      • sub-enabled substring

      The all-ids-threshold property cannot be configured for the approximate index.

    You can use DSCC to set the threshold at the index level, by search type. For more information, see the Directory Server online help.

  2. Regenerate the suffix indexes.

    See To Generate Indexes.

  3. If the database cache size was tuned for the old all IDs threshold value and the server has adequate physical memory, consider increasing the database cache size.

    Increase the database cache size by 25 percent of the magnitude of the increase to the all IDs threshold.

    In other words, if you increase the all IDs threshold from 4000 to 6000, you can increase the database cache size by about 12 ½ percent to account for the increase in index list size.

    Database cache size is set using the attribute dbcachesize. Find the optimum size empirically before applying changes to production servers.

Reindexing a Suffix

If your index files become corrupt, you must reindex the suffix to recreate the index files in the corresponding database directory. You can reindex a suffix either by reindexing the suffix while the directory server is running or by reinitializing the suffix.

Reindexing a Suffix While the Directory Server Is Running

When you reindex a suffix, the server examines all of the entries the suffix contains and rebuilds the index files. During reindexing, the contents of the suffix are read-only. Because the server must scan the entire suffix for every attribute that is reindexed, this process might take up to several hours for suffixes with millions of entries. The length of time also depends on the indexes you configure. In addition, while the suffix is being reindexed, indexes are not available and server performance is impacted.

ProcedureTo Reindex All Indexes on A Suffix

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Reindex all indexes on a suffix.


    $ dsconf reindex -h host -p port suffix-DN

    For example, to initialize all indexes on the dc=example,dc=com suffix, use this command:


    $ dsconf reindex -h host -p port dc=example,dc=com

Reindexing a Suffix by Reinitialization

When you reinitialize a suffix, the new contents are imported, which means that the suffix contents are replaced and new index files are created. Reinitializing a suffix can be faster than reindexing more than one attribute because all attributes are indexed in parallel as the entries are loaded. However, be aware that the suffix is unavailable while it is being reinitialized.

ProcedureTo Reindex a Suffix Through Reinitialization

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Set the suffix to read-only, as described in Setting Referrals and Making a Suffix Read-Only.

  2. Export the entire suffix to an LDIF file, as described in Backing Up to LDIF.

  3. Import the same LDIF file to reinitialize the suffix, as described in Importing Data From an LDIF File.

    During the initialization, the suffix is unavailable. When the initialization is complete, all configured indexes are ready to be used.

  4. Make the suffix writable again, as described in Setting Referrals and Making a Suffix Read-Only.

Managing Browsing Indexes

Browsing indexes are special indexes used only for search operations that request server-side sorting of results. Sun Java System Directory Server Enterprise Edition 6.2 Reference explains how browsing indexes work in Directory Server.

Browsing Indexes for Client Searches

Customized browsing indexes for sorting client search results must be defined manually. To create a browsing index, or virtual list view (VLV) index, use the following procedure. This section also includes procedures for adding or modifying browsing index entries and for regenerating browsing indexes.

ProcedureTo Create a Browsing Index

For parts of this procedure, you can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help. Other parts of the procedure can only be done using the command line.

  1. Add new browsing index entries or edit existing browsing index entries by using the ldapmodify command.

    For instructions, see To Add or Modify Browsing Index Entries.

  2. Run the dsconf reindex command to generate the new set of browsing indexes to be maintained by the server.

    For instructions, see To Regenerate Browsing Indexes.

ProcedureTo Add or Modify Browsing Index Entries

A browsing index is specific to a given search on a given base entry and its subtree. The browsing index configuration is defined in the database configuration of the suffix that contains the entry.

  1. Configure the vlvBase, vlvScope, and vlvFilter attributes for each browsing index on a directory server.

    These attributes configure the base of the search, the scope of the search, and a filter for the search. These attributes use the vlvSearch object class.

  2. Configure the vlvSort attribute for each browsing index.

    This attribute specifies the name of the attribute or attributes that sort the index. This entry is a child of the first entry and uses the vlvIndex object class to specify which attributes to sort and in what order.

    The following example uses the ldapmodify command to create the browsing index configuration entries:


    $ ldapmodify -a -h host -p port -D cn=admin,cn=Administrators,cn=config -w -
Enter bind password:
dn: cn=people_browsing_index, cn=database-name,
cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvSearch
cn: Browsing ou=People
vlvBase: ou=People,dc=example,dc=com
vlvScope: 1
vlvFilter: (objectclass=inetOrgPerson)

dn: cn=Sort rev employeenumber, cn=people_browsing_index,
 cn=database-name,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvIndex
cn: Sort rev employeenumber
vlvSort: -employeenumber
^D

    The vlvScope is one of the following:

    • 0 for the base entry alone

    • 1 for the immediate children of the base

    • 2 for the entire subtree rooted at the base

    The vlvFilter is the same LDAP filter that is used in the client search operations. Because all browsing index entries are located in the same place, you should use descriptive cn values to name your browsing indexes.

    Each vlvSearch entry must have at least one vlvIndex entry. The vlvSort attribute is a list of attribute names that defines the attribute to sort on and the sorting order. The dash ( -) in front of an attribute name indicates reverse ordering. You can define more than one index for a search by defining several vlvIndex entries. With the previous example, you could add the following entry:


    $ ldapmodify -a -h host -p port
 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Sort sn givenname uid, cn=people_browsing_index,
 cn=database-name,cn=ldbm database,cn=plugins,cn=config
objectClass: top
objectClass: vlvIndex
cn: Sort sn givenname uid
vlvSort: sn givenname uid
^D

  3. To modify a browsing index configuration, edit the corresponding vlvSearch entry or the corresponding vlvIndex entry.

  4. To remove a browsing index so that the browsing index is no longer maintained by the server, remove the individual vlvIndex entries.

    Alternatively, if only one vlvIndex entry exists, remove both the vlvSearch entry and the vlvIndex entry.

ProcedureTo Regenerate Browsing Indexes

  1. After you have created the browsing index entries, generate the new browsing indexes for the attributes specified.


    $ dsadm reindex -l -t attr-index instance-path suffix-DN

    The command scans the directory contents and creates a database file for the browsing index.

    The following example generates the browsing index that you defined in the previous section:


    $ dsadm reindex -l -b database-name -t Browsing /local/ds \
 ou=People,dc=example,dc=com

    For more information about the dsadm reindex command, see the dsadm(1M) man page.