shadow man Administrator's Guide
Red Hat Directory Server
Previous      Contents      Index      DocHome      Next     

Chapter 10   Managing Indexes


The Red Hat Directory Server Deployment Guide introduced the concept of indexing, the costs and benefits, and different types of index shipped with Red Hat Directory Server (Directory Server). This chapter begins with a description of the searching algorithm itself, so as to place the indexing mechanism in context, and then describes how to create, delete, and manage indexes. This chapter contains the following sections:

About Indexes

This section provides an overview of indexing in Directory Server. It contains the following topics:

About Indexes and Indexing Performance

Indexes are stored in files in the directory's databases. Each index is composed of a table of index keys and matching entry ID lists. This entry ID list is used by the directory to build a list of candidate entries that may match a client application's search request, which speeds up searches.

The names of the files are based on the indexed attribute, not the type of index contained in the file. Each index file may contain multiple types of indexes if multiple indexes are maintained for the specific attribute. For example, all indexes maintained for the common name attribute are contained in the cn.db3 file.

Indexes are time- and resource-consuming for the directory to maintain. For every modification to an indexed attribute, new indexes are generated. Also, index files can be large for large databases and become larger as the number of attributes and types of indexes increase. See "Balancing the Benefits of Indexing" for an example of maintaining indexes. However, for large directories (larger than 1000 entries) the cost of maintaining indexes is balanced by overall improved performance. Also, the secondary index structure has been redesigned to allow grately improved indexing, write (change), and search performance, which also offsets the costs of indexing.

In previous versions, write performance was limited by the number of bytes per second that could be written into the storage manager's transaction log file. The secondary index structure was separated into two levels:

Because it had no insight into the internal structure of the ID lists, the storage manager had to treat ID lists as opaque byte arrays. From the storage manager's perspective, when the content of an ID list changed, the entire list had changed. For a single ID that was inserted or deleted from an ID list, the corresponding number of bytes written to the transaction log was the maximum configured size for that ID list, about 8Kbytes; log file verbosity could easily be 100 times the corresponding number of bytes changed in the Directory Server since most of the log file contents relate to index changes (insert and delete operations). Also, every database page on which the list was stored was marked as dirty, since the "entire" list had changed.

In the redesigned index, the storage manager has visibility into the fine-grain index structure, which optimizes transaction logging so that only the number of bytes actually changed need to be logged for any given index modification. The BerkeleyDB feature provides ID list semantics, which are implemented by the storage manager. The enhanced Berkeley API supports duplicate index keys, inserting and deleting individual IDs stored against a common key, and an optimized mechanism retrieve the complete ID list for a given key.

This means the storage manager has direct knowledge of the application's intent when changes are made to ID lists. As a result:

For each entry ID list, there is a size limit that is globally applied to all index keys managed by the server. This limit used to be called the All IDs Threshold, which set a limit on how large a single entry ID list could get because maintaining large ID lists in memory can affect performance. When a list hit a certain pre-determined size, the search acted as if the index contained the entire directory.

The difficulty in setting the All IDs Threshold hurt peformance. If the threshold was too low, too many searches examined every entry in the directory. If it was too high, too many large ID lists had to be maintained in memory.

The problems addressed by the All IDs Threshold are no longer present because of the efficiency of entry insertion, modification, and deletion in the BerkeleyDB design. The All IDs Threshold is removed for database write operations, and every ID list is now maintained accurately.

Since loading a long ID list from the database can still significantly reduce search performance, the configuration parameter nsslapd-idlistscanlimit sets a limit on the number of IDs that is read before a key is considered to equal the entire directory. nsslapd-idlistscanlimit is analagous to the All IDs Threshold, but it only applies to the behavior of the search, not the content of the database. See "Overview of the Searching Algorithm", for more information on searching and indexes.

Note  

While Directory Server can support the old database design, only the new design is installed with the Directory Server. Upon startup, the server will read the database version from the DBVERSION file, which contains the text Netscape-ldbm/6.2 (old database version) and Netscape-ldbm/7.1 (new database format). If the file indicates that the old format is used, then the old code is selected for the database. Because the DBVERSION file stores everything per-backend, it is theoretically possible to have different database formats for different individual backends. However, the old database format is not recommended.

Migrate all databases to Directory Server 7.1 when the system is upgraded. For releases earlier than version 6.2 or for large databases, export the databases to LDIF, and install Directory Server fresh. For more information, see chapter 6, "Migrating from Previous Versions," in the Red Hat Directory Server Installation Guide.



Index Types

Directory Server supports six index types, which means that the index list will allow up to six different types of searches, such as an exact match, a "sounds-like" search, or a search on a string within the entry. The types of indexes are outlines here:

Indexing may be required for large databases. For instance, if you have more than 1000 entries in a database, you must create a browsing index to be able to view directory entries from the Console. Also, index sizes can be larger than in previous releases, so you may want to increase your database cache size. To reconfigure your cache size, refer to "nsslap-dbcachesize" in the Red Hat Directory Server Configuration, Command, and File Reference.

About Default, System, and Standard Indexes

When you install Directory Server, a set of default and system indexes is created per database instance. To maintain these indexes, the directory uses standard indexes.

Overview of Default Indexes

The default indexes can be modified depending on your indexing needs, although you should ensure that no server plug-ins or other servers in your enterprise depend on this index before you remove it.

Table 10-1 lists the default indexes installed with the directory.


Table 10-1    Default Indexes  


Attribute

Eq

Pres

Sub

Purpose

cn

X

X

X

Improves the performance of the most common types of user directory searches.

givenName

X

X

X

Improves the performance of the most common types of user directory searches.

mail

X

X

X

Improves the performance of the most common types of user directory searches.

mailHost

X

-

-

Used by a messaging server.

member

X

-

-

Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See "Maintaining Referential Integrity", for more information.

owner

X

-

-

Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See "Maintaining Referential Integrity", for more information.

seeAlso

X

-

-

Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See "Maintaining Referential Integrity", for more information.

sn

X

X

X

Improves the performance of the most common types of user directory searches.

telephoneNumber

X

X

X

Improves the performance of the most common types of user directory searches.

uid

X

-

-

Improves Directory Server performance.

uniquemember

X

-

-

Improves Directory Server performance. This index is also used by the Referential Integrity Plug-in. See "Maintaining Referential Integrity", for more information.



Overview of System Indexes

System indexes are indexes that cannot be deleted or modified. They are required by the directory to function properly. Table 10-2 lists the system indexes included with the directory.


Table 10-2    System Indexes  


Attribute

Eq

Pres

Purpose

aci

-

X

Allows the Directory Server to quickly obtain the access control information maintained in the database.

dnComp

X

-

Used to help accelerate subtree searches in the directory.

objectClass

X

-

Used to help accelerate subtree searches in the directory.

entryDN

X

-

Speeds up entry retrieval based on DN searches.

parentID

X

-

Enhances directory performance during one-level searches.

numSubordinates

-

X

Used by the Directory Server Console to enhance display performance on the Directory tab.

nsUniqueID

X

-

Used to search for specific entries.



Overview of Standard Indexes

Because of the need to maintain default indexes and other internal indexing mechanisms, the Directory Server also maintains certain standard index files. The following standard indexes exist by default, and you do not need to generate them:

Overview of the Searching Algorithm

Indexes are used to speed up searches. To understand how the directory uses indexes, it helps to understand the searching algorithm. Each index contains a list of attributes (such as the cn, common name, attribute) and a pointer to the entries corresponding to each value. Directory Server processes a search request as follows:

  1. An LDAP client application, such as the Directory Server Gateway, sends a search request to the directory.
  2. The directory examines the incoming request to make sure that the specified base DN matches a suffix contained by one or more of its databases or database links.
  3. If the search request for each database attribute can be satisfied by a single index, then the server reads that index to generate a list of potential matches.
    4. If there is no index for the attribute, the directory generates a candidate list that includes all entries in the database, which makes the search considerably slower.
     
    If a search request contains multiple attributes, the directory consults multiple indexes and then combines the resulting lists of candidate entries.
     
  4. If there is an index for the attribute, the directory takes the candidate matches from the index files in the form of a series of entry ID numbers.
  5. The directory uses the returned entry ID numbers to read the corresponding entries from the id2entry.db3 file. The Directory Server then examines each of the candidate entries to see if any match the search criteria. The directory returns matching entries to the client as each is found.
    6. The directory continues until either it has examined all candidate entries or it reaches the limit set in one of the following attributes:
     

See Red Hat Directory Server Configuration, Command, and File Reference for further information about these attributes.

idlistscanlimit

When the server uses indexes in the processing of a search operation, it is possible that one index key matches a large number of entries. For example, consider a search for objectclass=inetorgperson in a directory that contained one million inetorgperson entries. When the server reads the inetorgperson index key in the objectclass index, it would find one million matching entries. In cases like this, it is usually more efficient simply to conclude in the index lookup that all the entries in the database match the query. This causes subsequent search processing to scan the entire database content, checking each entry as to whether it matches the search filter. The idea is that the time required to fetch the index keys is not worthwhile; the search operation is likely to be processed more efficiently by omitting the index lookup.

Directory Server, then, examines an index, and, if more than a certain number of entries are found, the server will stop reading the index and mark the search as unindexed with respect to that particular index. The threshold number of entries is called the idlistscanlimit and is configured with the nsslapd-idlistscanlimit configuration attribute. The default value is 4000, which is designed to give good performance for a common range of database sizes and access patterns. Typically, it is not necessary to change this value. However, in rare circumstances it may be possible to improve search performance with a different value. For example, lowering the value will improve performance for searches that will otherwise eventually hit the default limit of 4000. This might, of course, reduce performance for other searches that would benefit from indexing. Conversely, increasing the limit could improve performance for searches that were previously hitting the limit. With a higher limit, these searches could benefit from indexing where previously they did not.

Phonetic Searches

In addition, the directory uses a variation of the metaphone phonetic algorithm to perform searches on an approximate index. Each value is treated as a sequence of words, and a phonetic code is generated for each word.

Note  

The metaphone phonetic algorithm in Directory Server supports only US-ASCII letters. Therefore, use approximate indexing only with English values.



Values entered on an approximate search are similarly translated into a sequence of phonetic codes. An entry is considered to match a query if both of the following are true:

For example:



Name in the Directory (Phonetic Code)

Query String (Phonetic code)

Match Comments

Alice B Sarette
(ALS B SRT)

Alice Sarette
(ALS SRT)

Matches. Codes are specified in the correct order.

 

Alice Sarrette
(ALS SRT)

Matches. Codes are specified in the correct order, despite the misspelling of Sarette.

 

Surette
(SRT)

Matches. The generated code exists in the original name, despite the misspelling of Sarette.

 

Bertha Sarette
(BR0 SRT)

No match. The code BR0 does not exist in the original name.

 

Sarette, Alice
(SRT ALS)

No match. The codes are not specified in the correct order.



Balancing the Benefits of Indexing

Before you create new indexes, balance the benefits of maintaining indexes against the costs. Keep in mind that:

The following example illustrates exactly how time-consuming indexes can become. Consider the procedure for creating a specific attribute:

  1. The Directory Server receives an add or modify operation.
  2. The Directory Server examines the indexing attributes to determine whether an index is maintained for the attribute values.
  3. If the created attribute values are indexed, then the Directory Server generates the new index entries.
  4. Once the server completes the indexing, the actual attribute values are created according to the client request.

For example, suppose the Directory Server is asked to add the entry

dn: cn=John Doe, ou=People,dc=example,dc=com
objectclass: top
objectClass: person
objectClass: orgperson
objectClass: inetorgperson
cn: John Doe
cn: John
sn: Doe
ou: Manufacturing
ou: people
telephonenumber: 408 555 8834
description: Manufacturing lead for the Z238 line of widgets.

Further suppose that the Directory Server is maintaining the following indexes:

Then to add this entry to the directory, the Directory Server must perform these steps:

  1. Create the common name equality index entry for John and John Doe.
  2. Create the appropriate common name approximate index entries for John and John Doe.
  3. Create the appropriate common name substring index entries for John and John Doe.
  4. Create the surname equality index entry for Doe.
  5. Create the appropriate surname approximate index entry for Doe.
  6. Create the appropriate surname substring index entries for Doe.
  7. Create the telephonenumber equality index entry for 408 555 8834.
  8. Create the appropriate telephonenumber substring index entries for 408 555 8834.
  9. Create the appropriate description substring index entries for Manufacturing lead for the Z238 line of widgets. A large number of substring entries are generated for this string.

The example shows that indexing can be costly.

Creating Indexes

This section describes how to create presence, equality, approximate, substring, and international indexes for specific attributes using the Directory Server Console and the command-line.

Note  

Given that this version of Directory Server can operate in either a single or multi-database environment, you need to remember to create your new indexes in every database instance since newly created indexes are not automatically created in the other databases.

However, the same is not entirely true for default indexes because they are automatically present and maintained in subsequent database instances but not added to existing ones. In other words, the directory uses your most recently created set of default indexes in subsequent databases. This means that if you add a default index to your second database instance, it will not be maintained in your first database instance but will be maintained in any subsequent instances.



As the procedure for creating browsing indexes is different, it is covered in a separate section.

This section contains the following procedures:

Creating Indexes from the Server Console

Using the Directory Server Console, you can create presence, equality, approximate, substring, and international indexes for specific attributes.

To create indexes:

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand the Data node, expand the suffix of the database you want to index, and select the database.
  3. Select the Indexes tab in the right pane.

    4. Note  

    Do not click on the Database Settings node because this will take you to the Default Index Settings window and not the window for configuring indexes per database.



  4. If the attribute you want to index is listed in the Additional Indexes table, skip to Step 6. Otherwise, click Add Attribute.
    5. A dialog box appears containing a list of all of the available attributes in the server schema.
     
  5. Select the attribute you want to index, and click OK.
    6. The server adds the attribute to the Additional Indexes table.
     
  6. Select the checkbox for each type of index you want to maintain for each attribute.
  7. If you want to create an index for a language other than English, enter the OID of the collation order you want to use in the Matching Rules field.
    8. You can index the attribute using multiple languages by listing multiple OIDs separated by commas (but no whitespace). For a list of languages, their associated OIDs, and further information regarding collation orders, see Appendix D, "Internationalization."
     
  8. Click Save.
    9. The Indexes dialog box appears, displaying the status of the index creation and informing you when the indexes have been created. You can click on the Status Logs box to view the status of the indexes created. Once the indexing is complete, click Close to close the Indexes dialog box.
     

The new index is immediately active for any new data that you add and any existing data in your directory. You do not have to restart your server.

Creating Indexes from the Command-Line

You can create presence, equality, approximate, substring, and international indexes for specific attributes from the command-line.

Creating indexes from the command-line involves two steps:

The following sections describe the steps involved in creating indexes.

Adding an Index Entry

Use ldapmodify to add the new index attributes to your directory. If you want to create a new index that will become one of the default indexes, add the new index attributes to the cn=default indexes,cn=config,cn=ldbm database, cn=plugins,cn=config entry.

To create a new index for a particular database, add it to the cn=index,cn=database_name ,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.

Note  

Avoid creating entries under cn=config in the dse.ldif file. The cn=config entry in the simple, flat dse.ldif configuration file is not stored in the same highly scalable database as regular entries. As a result, if many entries, particularly entries that are likely to be updated frequently, are stored under cn=config, performance will probably suffer.

Although we recommend you do not store simple user entries under cn=config for performance reasons, it can be useful to store special user entries such as the Directory Manager entry or Replication Manager (supplier bind DN) entry under cn=config since this allows you to centralize configuration information.



For information on the LDIF update statements required to add entries, see "LDIF Update Statements".

For example, assume you want to create presence, equality, and substring indexes for the sn (surname) attribute in the Example1 database.

First, type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Run the ldapmodify command-line utility as follows:

ldapmodify -a -h server -p 389 -D "cn=directory manager" -w password

The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.

Next, you add the following entry for the new indexes:

dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
objectClass:top
objectClass:nsIndex
cn:sn
nsSystemIndex:false
nsIndexType:pres
nsIndexType:eq
nsIndexType:sub
nsMatchingRule:2.16.840.1.113730.3.3.2.3.1

The cn attribute contains the name of the attribute you want to index, in this example, the sn attribute. The entry is a member of the nsIndex object class. The nsSystemIndex attribute is false, indicating that the index is not essential to Directory Server operations. The multi-valued nsIndexType attribute specifies the presence (pres), equality (eq) and substring (sub) indexes. Each keyword has to be entered on a separate line. The nsMatchingRule attribute specifies the OID of the Bulgarian collation order.

Specifying an index entry with no value in the nsIndexType attribute results in all indexes (except international) being maintained for the specified attribute. For example, suppose instead that you specify the following entry for your new sn indexes:

dn: cn=sn,cn=index,cn=database_name ,cn=ldbm database,cn=plugins,cn=config
objectClass:top
objectClass:nsIndex
cn:sn
nsSystemIndex:false
nsIndexType:

This new entry results in all indexes for the sn (surname) attribute.

You can use the keyword none in the nsIndexType attribute to specify that no indexes are to be maintained for the attribute. For example, suppose you want to temporarily disable the sn indexes you just created on the Example1 database. You change the nsIndexType to none as follows:

dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
objectClass:top
objectClass:nsIndex
cn:sn
nsSystemIndex:false
nsIndexType:none

For a complete list of collation orders and their OIDs, see Appendix D, "Internationalization."

For more information about the index configuration attributes, see the Red Hat Directory Server Configuration, Command, and File Reference.

For more information about the ldapmodify command-line utility, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

Note  

You should always use the attribute's primary name (not the attribute's alias) when creating indexes. The primary name of the attribute is the first name listed for the attribute in the schema; for example, uid for the userid attribute. See Table 10-3, for a list of all primary and alias attribute names.



Running the db2index.pl Script

Once you have created an indexing entry or added additional index types to an existing indexing entry, run the db2index.pl script to generate the new set of indexes to be maintained by the Directory Server. Once you run the script, the new set of indexes is active for any new data you add to your directory and any existing data in your directory.

To run the db2index.pl Perl script:

  1. From the command-line, change to the following directory:
    2. serverRoot  /slapd-serverID
     
  2. Run the db2index.pl Perl script.
    3. For more information about using this Perl script, refer to Red Hat Directory Server Configuration, Command, and File Reference.
     

This example generates an index using the db2index.pl UNIX shell script:

db2index.pl -D "cn=Directory Manager" -w passsword  -n ExampleServer -t sn

The following table describes the db2index.pl options used in the examples:



Option

Description

-D

Specifies the DN of the administrative user.

-w

Specifies the password of the administrative user.

-n

Specifies the name of the database into which you are importing the data.

-t

Specifies the name of the attribute contained by the index.



For more information about the db2index.pl Perl script, see the Red Hat Directory Server Configuration, Command, and File Reference.

Creating VLV Indexes from the Server Console

A virtual list view (VLV) index is a way of creating a truncated list for faster searching while enhancing server performance. The VLV index itself can be resource-intensive to maintain but is beneficial for large directories (over 1000 entries).

To create a VLV index from the Console:

  1. In the Directory Server Console, select the Directory tab.
  2. In the left navigation tree, create a suffix where you want to create the VLV index. For instance, for views based on the locality (l) attribute, name this organizational unit Location Views.
  3. Right-click on ou=Location Views, and select New>Other.
  4. Select nsview from the New Object menu, and hit okay.
  5. In the Property Editor window, hit the "Add Value" button, and add the organization unit object class.
  6. Name the organization unit according to how you want to organize the VLVs you will create. For instance, ou=Sunnyvale. Make the ou attribute the naming attribute.
  7. Hit the "Add Attribute" button, and add the nsviewfilter attribute.
  8. Create a filter that reflects the views you will create. For example:

    9. (l=Sunnyvale)

  9. Hit okay to close the attributes box, and hit okay again to save the new VLV index.

The new index is immediately active for any new data that you add to your directory. You do not have to restart your server.

For more information on how to change the VLV search information or the access control rules that are set by default for VLV searches, see "Adding a Browsing Index Entry", and "Setting Access Control for VLV Information".

A browsing index is a type of VLV index that organizes the entries listed into alphabetical order, making it easier to find entries. To create a browsing index using the Directory Server Console:

  1. In the Directory Server Console, select the Directory tab.
  2. In the left navigation tree (for example, People), select the entry for which you want to create the index.
  3. From the Object menu, select Create Browsing Index.
    4. The Create Browsing Index dialog box appears displaying the status of the index creation. You can click on the Status Logs box to view the status of the indexes created.
     
  4. Click Close to close the Create Browsing Index dialog box.
    5. The new index is immediately active for any new data that you add to your directory. You do not have to restart your server.
     

Creating VLV Indexes from the Command-Line

Creating a browsing index or virtual list view (VLV) index from the command-line involves these steps:

The following sections describe the steps involved in creating browsing indexes.

Adding a Browsing Index Entry

The type of browsing index entry you want to create depends on the type of ldapsearch attribute sorting you want to accelerate. It is important to take the following into account:

For example, you want to create a browsing index to accelerate an ldapsearch on the entry ou=People,dc=example,dc=com held in the Example1 database where:

First, type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Run the ldapmodify command-line utility as follows:

ldapmodify -a -h server -p 389 -D "cn=directory manager" -w password

The ldapmodify utility binds to the server and prepares it to add an entry to the configuration file.

Next, you need to add two browsing index entries which define your browsing index. The first entry you add specifies the base, scope, and filter of the browsing index:

dn: cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvSearch
cn: MCC ou=People dc=example dc=com
vlvBase: ou=People, dc=example,dc=com
vlvScope: 1
vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))

The cn contains the browsing index identifier, which specifies the entry on which you want to create the browsing index; in this example, the ou=People,dc=example,dc=com entry. We recommend you use the dn of the entry for your browsing index identifier, which is the approach adopted by the Directory Server Console, to prevent identical browsing indexes from being created. The entry is a member of the vlvSearch object class.

The vlvbase attribute value specifies the entry on which you want to create the browsing index; in this example, the ou=People,dc=example,dc=com entry (the browsing index identifier).

The vlvscope attribute is 1, indicating that the base for the search you want to accelerate is 1. A search base of 1 means that only the immediate children of the entry specified in the cn attribute, and not the entry itself, will be searched.

The vlvfilter specifies the filter to be used for the search; in this example, (|(objectclass=*)(objectclass=ldapsubentry)).

The second entry you add specifies the sorting order you want for the returned attributes:

dn: cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn= config
objectClass: top
objectClass: vlvIndex
cn: by MCC ou=People dc=example dc=com
vlvSort: cn givenname o ou sn

The cn contains the browsing index sort identifier. The above cn is the type created by the Console by default, which has the sorting order as being set "by" the browsing index base. The entry is a member of the vlvIndex object class.

The vlvsort attribute value specifies the order in which you want your attributes to be sorted; in this example, cn, givenname, o, ou, and then sn.

Note  

This first browsing index entry must be added to the cn=database_name ,cn=ldbm database,cn=plugins,cn=config directory tree node, and the second entry must be a child of the first entry.



Running the vlvindex Script

Once you have created the two browsing indexing entries or added additional attribute types to an existing indexing browsing entries, run the vlvindex script to generate the new set of browsing indexes to be maintained by the Directory Server. After you run the script, the new set of browsing indexes is active for any new data you add to your directory and any existing data in your directory.

To run the vlvindex script:

  1. From the command-line, change to the following directory:
    2. serverRoot /slapd-serverID
     
  2. Stop the server:

    3. ./stop-slapd

  3. Run the vlvindex script.
    4. For more information about using this script, refer to Red Hat Directory Server Configuration, Command, and File Reference.
     
  4. Restart the server.

    5. ./start-slapd

This example generates a browsing index using the vlvindex UNIX shell script:

vlvindex -n Example1 -T "by MCC ou=people dc=example dc=com"

The following table describes the vlvindex options used in the examples:



Option

Description

-n

Name of the database containing the entries to index.

-T

Browsing index identifier to use to create browsing indexes.



For more information about the vlvindex script, see the Red Hat Directory Server Configuration, Command, and File Reference.

Setting Access Control for VLV Information

The default access control for the VLV index information is to allow anyone who has authenticated. If a site requires anonymous users to use the VLV index information, modify the access control set for cn: VLV Request Control in the Directory Server's configuration.

  1. Change to the configuration directory:
    2. serverRoot /slapd-serverID /config
     
  2. In a text editor, open the dse.ldif file.
  3. Locate oid=2.16.840.1.113730.3.4.9; you should see these lines:
    4. dn: oid=2.16.840.1.113730.3.4.9,cn=features,cn=config
    objectClass: top
    objectClass: directoryServerFeature
    oid: 2.16.840.1.113730.3.4.9
    cn: VLV Request Control
    aci: (targetattr != "aci")(version 3.0; acl "VLV Request Control"; allow( read, search, compare, proxy ) userdn = "ldap:///all" ;)
    creatorsName: cn=server,cn=plugins,cn=config
    modifiersName: cn=server,cn=plugins,cn=config
    ...
     
  4. Change "ldap://all" to "ldap://anyone" and save your changes.

Deleting Indexes

This section describes how to delete presence, equality, approximate, substring, international, and browsing indexes for specific attributes.

Note  

Because this version of Directory Server can operate in either a single or multi-database environment, you have to delete any unwanted indexes from every database instance. Any default indexes you delete will not be deleted from previous sets of indexes on existing database instances.



As the procedure for deleting browsing indexes is different, it is covered in a separate section. This section contains the following procedures:

Deleting Indexes from the Server Console

Using the Directory Server Console you can delete indexes you have created, indexes used by other server applications such as a messaging or web server, and default indexes. You cannot delete system indexes.

To delete indexes using the Directory Server Console:

  1. In the Directory Server Console, select the Configuration tab.
  2. Expand the Data node and expand the suffix associated with the database containing the index. Select the database from which you want to delete the index.
  3. Locate the attribute containing the index you want to delete. Clear the checkbox under the index.
    4. If you want to delete all indexes maintained for a particular attribute, select the attribute's cell under Attribute Name, and click Delete Attribute.
     
  4. Click Save.
    5. A Delete Index warning dialog box appears asking you to confirm that you want to delete the index.
     
  5. Click Yes to delete the index.
  6. The Delete Browsing Index dialog box appears displaying the status of the index deletion. You can click on the Status Logs button to view the status of the indexes deleted.
  7. Once the indexing is complete, click on Close to close the Delete Browsing Index box.

Deleting Indexes from the Command-Line

You can browsing indexes, or virtual list view (VLV) indexes, using the ldapdelete command-line utility as follows:

The following sections describe the steps involved in deleting an index.

Deleting an Index Entry

Use the ldapdelete command-line utility to delete either the entire indexing entry or the unwanted index types from an existing entry.

If you want to delete the indexes for a particular database, you remove your index entry from the cn=index,cn=database_name ,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.

To delete a default index, remove it from the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config entry.

For example, you want to delete presence, equality, and substring indexes for the sn attribute on the database named Example1.

You want to delete the following entry:

dn: cn=sn,cn=index,cn=Example1,cn=ldbm database,cn=plugins,cn=config
objectClass:top
objectClass:nsIndex
cn:sn
nsSystemIndex:false
nsIndexType:pres
nsIndexType:eq
nsIndexType:sub
nsMatchingRule:2.16.840.1.113730.3.3.2.3.1

To run the ldapdelete command-line utility, type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Perform the ldapdelete as follows:

ldapdelete -D "cn=Directory Manager" -w password -h ExampleServer -p845 "cn=sn,cn=index,cn=Example1,cn=ldbm database, cn=plugins,cn=config"

The following table describes the ldapdelete options used in the example:



Option

Description

-D

Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the Directory Server, and it must also have the authority to modify the entries.

-w

Specifies the password associated with the distinguished name specified in the -D option.

-h

Specifies the name of the host on which the server is running.

-p

Specifies the port number that the server uses.



For full information on ldapdelete options, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

Once you have deleted this entry, the presence, equality, and substring indexes for the sn attribute will no longer be maintained by the Example1 database.

Running the db2index.pl Script

Once you have deleted an indexing entry or deleted some of the index types from an indexing entry, run the db2index.pl script to generate the new set of indexes to be maintained by the Directory Server. Once you run the script, the new set of indexes is active for any new data you add to your directory and any existing data in your directory.

To run the db2index.pl Perl script:

  1. From the command-line, change to the following directory:
    2. serverRoot /slapd-serverID
     
  2. Run the db2index.pl Perl script.
    3. For more information about using the db2index.pl Perl script, refer to Red Hat Directory Server Configuration, Command, and File Reference.
     

This example generates a new set of indexes to be maintained by the server, using the db2index.pl UNIX shell script:

db2index.pl -D "cn=Directory Manager" -w password -n Example1

The following table describes the db2index.pl options used in the examples:



Option

Description

-D

Specifies the DN of the administrative user.

-w

Specifies the password of the administrative user.

-n

Specifies the name of the database into which you are importing the data.



For more information about the db2index.pl Perl script, see the Red Hat Directory Server Configuration, Command, and File Reference.

Deleting Browsing and VLV Indexes from the Server Console

Using the Directory Server Console, you can delete browsing indexes and VLV indexes.

To delete a virtual list:

  1. In the Directory Server Console, select the Directory tab.
  2. Select the virtual list that you want to delete, such as ou=Sunnyvale,ou=LocationViews,dc=example,dc=com (to delete all the virtual lists, you can delete the entire subsuffix, ou=LocationViews,dc=example,dc=com).
  3. Right-click on the entry, and select Delete from the drop-down menu. You can also select the entry, and select Object>Delete from the tool menu at the top.
  4. A dialog box appears asking you to confirm that you want to delete the entry. Click Yes to delete.

To delete a browsing index:

  1. In the Directory Server Console, select the Directory tab.
  2. Select the entry from which you want to delete the index in the navigation tree, and select Delete Browsing Index from the Object menu. You can also select and right-click the entry of the index you want to delete in the navigation tree and then choose Delete Browsing Index from the pop-up menu.
  3. A Delete Browsing Index dialog box appears asking you to confirm that you want to delete the index. Click Yes to delete.
  4. The Delete Browsing Index dialog box appears displaying the status of the index deletion.

Deleting Browsing and VLV Indexes from the Command-Line

Deleting a browsing index or virtual list view (VLV) index from the command-line involves two steps:

The actual entries for an alphabetical browsing index and virtual list view are the same. The following sections describe the steps involved in deleting browsing indexes.

Deleting a Browsing Index Entry

Use the ldapdelete command-line utility to either delete browsing indexing entries or edit existing browsing index entries.

To delete browsing indexes for a particular database, you remove your browsing index entries from the cn=index,cn=database_name ,cn=ldbm database,cn=plugins,cn=config entry, where cn=database_name corresponds to the name of the database.

For example, you want to delete a browsing index for accelerating ldapsearch operations on the entry ou=People,dc=example,dc=com held in the Example1 database where the search base is ou=People,dc=example,dc=com, the search filter is (|(objectclass=*)(objectclass=ldapsubentry)), the scope is 1, and the sorting order for the returned attributes is cn, givenname, o, ou, and sn.

To delete this browsing index, you need to delete the two corresponding browsing index entries which follow:

dn: cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config
objectClass: top
objectClass: vlvSearch
cn: MCC ou=People dc=example dc=com
vlvBase: ou=People, dc=example,dc=com
vlvScope: 1
vlvFilter: (|(objectclass=*)(objectclass=ldapsubentry))

and

dn: cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn= config
objectClass: top
objectClass: vlvIndex
cn: by MCC ou=People dc=example dc=com
vlvSort: cn givenname o ou sn

To run the ldapdelete command-line utility, type the following to change to the directory containing the utility:

cd serverRoot /shared/bin

Perform the ldapdelete as follows:

ldapdelete -D "cn=Directory Manager" -w password -h ExampleServer -p 845 "cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn=config"
"cn=by MCC ou=People dc=example dc=com,cn=MCC ou=People dc=example dc=com, cn=userRoot, cn=ldbm database, cn=plugins, cn= config"

The following table describes the ldapdelete options used in the example:



Option

Description

-D

Specifies the distinguished name with which to authenticate to the server. The value must be a DN recognized by the Directory Server, and it must also have the authority to modify the entries.

-w

Specifies the password associated with the distinguished name specified in the -D option.

-h

Specifies the name of the host on which the server is running.

-p

Specifies the port number that the server uses.



For full information on ldapdelete options, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

Once you have deleted these two browsing index entries, the browsing index for accelerating ldapsearch operations on the entry ou=People dc=example dc=com held in the Example1 database where the search base is ou=People,dc=example,dc=com, the search filter is (|(objectclass=*)(objectclass=ldapsubentry)), the scope is 1, and the sorting order for the returned attributes is cn, givenname, o, ou, and sn will no longer be maintained by the Example1 database.

Running the vlvindex Script

Once you have deleted browsing indexing entries or deleted unwanted attribute types from existing browsing indexing entries, run the vlvindex script to generate the new set of browsing indexes to be maintained by the Directory Server. Once you run the script, the new set of browsing indexes is active for any new data you add to your directory and any existing data in your directory.

To run the vlvindex script:

  1. From the command-line, change to the following directory:
    2. serverRoot /slapd-serverID
     
  2. Stop the server:

    3. ./stop-slapd

  3. Run the vlvindex script.
    4. For more information about using the vlvindex script, refer to Red Hat Directory Server Configuration, Command, and File Reference.
     
  4. Restart the server:

    5. ./start-slapd

This example recreates the indexes using the vlvindex UNIX shell script:

vlvindex -n Example1 -T "by MCC ou=people dc=example dc=com"

The following table describes the vlvindex options used in the examples.



Option

Description

-n

Name of the database containing the entries to index.

-T

Browsing index identifier to use to create browsing indexes.



For more information about the vlvindex script, see the Red Hat Directory Server Configuration, Command, and File Reference.

Attribute Name Quick Reference Table

Table 10-3 lists all attributes which have a primary or real name as well as an alias. When creating indexes be sure to use the primary name.


Table 10-3    Attribute Name Quick Reference Table  


Attribute Primary Name

Attribute Alias

dn

distinguishedName

cn

commonName

sn

surName

c

countryName

l

localityName

st

stateOrProvinceName

street

streetAddress

o

organization

ou

organizationalUnitName

facsimileTelephoneNumber

fax

uid

userId

mail

rfc822mailbox

mobile

mobileTelephoneNumber

pager

pagerTelephoneNumber

co

friendlyCountryName

labeledUri

labeledUri

ttl

timeToLive

dc

domainComponent

authorCn

documentAuthorCommonName

authorSn

documentAuthorSurname

drink

favoriteDrink







Previous      Contents      Index      DocHome      Next     

© 2001 Sun Microsystems, Inc. Portions copyright 1999, 2002-2004 Netscape Communications Corporation, 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.


Last Updated September 05, 2008