10.2. 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.
Because Directory Server 8.0 can operate in either a single or multi-database environment, remember to create new indexes in every database instance since newly-created indexes are not automatically created in the other databases. However, the same is not 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 the 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.
The procedure for creating browsing indexes is different than for creating other index types; that procedure is covered in Section 10.2.3, “Creating Browsing Indexes from the Server Console”.
This section describes how to create presence, equality, approximate, substring, and international indexes for specific attributes using the Directory Server Console.
To create any of these indexes, do the following:
Select the Configuration tab.
Expand the Data node, expand the suffix of the database to index, and select the database.
Select the Indexes tab in the right pane.
Do not click the Database Settings node because this opens the Default Index Settings window, not the window for configuring indexes per database.
If the attribute to be indexed is listed in the Additional Indexes table, go to step 6. Otherwise, click Add Attribute to open a dialog box with a list of all of the available attributes in the server schema.
Select the attribute you want to index, and click OK.
The server adds the attribute to the Additional Indexes table.
Select the checkbox for each type of index to maintain for each attribute.
To create an index for a language other than English, enter the OID of the collation order to use in the Matching Rules field.
To index the attribute using multiple languages, list 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.
Click Save.
The Indexes dialog box appears, displaying the status of the index creation and informing you when the indexes have been created. Click the Status Logs box to view the status of the indexes created. Once the indexing is complete, click Close.
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 presence, equality, approximate, substring, and international indexes for specific attributes from the command-line involves two steps:
Using the ldapmodify command-line utility to add a new index entry or edit an existing index entry. See Section 10.2.2.1, “Adding an Index Entry”.
Running the db2index.pl Perl script to generate the new set of indexes to be maintained by the server. See Section 10.2.2.2, “Running the db2index.pl Script”.
You cannot create new system indexes because system indexes are hard-coded in Directory Server.
Use ldapmodify[9] to add the new index attributes to your directory.
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.
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 centralizes configuration information.
For information on the LDIF update statements required to add entries, see Section 2.4, “LDIF Update Statements”.
For example, to create presence, equality, and substring indexes for the sn (surname) attribute in the Example1 database, do the following:
Open the Directory Server LDAP tool directory.[9]
cd /usr/lib/mozldap
Run ldapmodify.
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.
Add the LDIF 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 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, the following entry creates all index types for the sn index.
dn: cn=sn,cn=index,cn=database_name,cn=ldbm database,cn=plugins,cn=config
objectClass:top
objectClass:nsIndex
cn:sn
nsSystemIndex:false
nsIndexType:
You can use the keyword none in the nsIndexType attribute to specify that no indexes are to be maintained for the attribute. This example temporarily disables the sn indexes on the Example1 database by changing the nsIndexType to none:
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, and for the index configuration attributes or the ldapmodify command-line utility, see the Directory Server Configuration, Command, and File Reference.
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 user ID attribute. See Table 10.7, “Attribute Name Quick Reference Table” for a list of all primary and alias attribute names.
After creating 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. After the script is run, the new set of indexes is active for any new data added to the directory and any existing data in the directory.
To run the db2index.pl Perl script, do the following:
Open the Directory Server instance directory. [10]
cd /usr/lib/dirsrv/slapd-instance_name
Run the db2index.pl Perl script.
db2index.pl-D "cn=Directory Manager" -w password -n ExampleServer -t sn
For more information about using this Perl script, see the Directory Server Configuration, Command, and File Reference.
Table 10.6, “db2index Options” describes the db2index.pl options:
| 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 being indexed. |
| -t | Specifies the name of the attribute contained by the index. |
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 it can be beneficial in large directories (over 1000 entries).
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, do the following:
Select the Directory tab.
In the left navigation tree, select the entry, such as People, for which to create the index.
From the Object menu, select Create Browsing Index.
The Create Browsing Index dialog box appears displaying the status of the index creation. Click the Status Logs box to view the status of the indexes created.
Click Close.
The new index is immediately active for any new data that is added to the 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 Section 10.2.4.1, “Adding a Browsing Index Entry” and Section 10.2.4.3, “Setting Access Control for VLV Information”.
Creating a browsing index or virtual list view (VLV) index from the command-line has these steps:
Using ldapmodify to add new browsing index entries or edit existing browsing index entries. See Section 10.2.4.1, “Adding a Browsing Index Entry”.
Running the vlvindex script to generate the new set of browsing indexes to be maintained by the server. See Section 10.2.4.2, “Running the vlvindex Script”.
Ensuring that access control on VLV index information is set appropriately. See Section 10.2.4.3, “Setting Access Control for VLV Information”.
The type of browsing index entry to create depends on the type of ldapsearch attribute sorting to accelerate. It is important to take the following into account:
The scope of the search (base, one, sub)
The base of the search (the entry to use as a starting point for the search)
The attributes to sort
The filter of the search
For more information on specifying filters for searches, see Appendix B, Finding Directory Entries.
The LDBM database to which the entry that forms the base of the search belongs. You can only create browsing indexes in LDBM databases.
There is more information on ldapsearch options in the Directory Server Configuration, Command, and File Reference.
For example, create a browsing index to accelerate an ldapsearch on the entry ou=People,dc=example,dc=com held in the Example1 database with the following attributes:
The search base is ou=People,dc=example,dc=com
The search filter is (|(objectclass=*)(objectclass=ldapsubentry))
The scope is one
The sorting order for the returned attributes is cn, givenName, o, ou, and sn
Run ldapmodify.[9]
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.
Add an entry which 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 to create the browsing index; in this example, the ou=People,dc=example,dc=com entry. Red Hat recommends using the dn of the entry for the 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 scope for the search you want to accelerate is 1. A search scope 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)).
Add the second entry, to specify the sorting order 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.
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.
After creating 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 running the script, the new set of browsing indexes is active for any new data added to the directory and any existing data in the directory.
To run the vlvindex script, do the following:
Open the Directory Server instance directory.[10]
cd /usr/lib/dirsrv/slapd-instance_name
Stop the server.[11]
service dirsrv stop instance
Run the vlvindex script.
vlvindex -n Example1 -T "by MCC ou=people dc=example dc=com"
For more information about using this script, see the Directory Server Configuration, Command, and File Reference.
Restart the server.
service dirsrv start instance
Table 10.4, “vlvindex Options” 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. |
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.
Open the Directory Server configuration directory:[10]
cd /etc/dirsrv/slapd-instance_name
In a text editor, open the dse.ldif file.
Locate the oid=2.16.840.1.113730.3.4.9 entry.
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 ...
Change "ldap://all" to "ldap://anyone" and save your changes.
[9]
The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 i386; directories for other platforms are listed in Section 1.2, “LDAP Tool Locations”. However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL and allow simple authentication.
[10] This is the location for Red Hat Enterprise Linux. File locations for other platforms are listed in Section 1.1, “Directory Server File Locations”.
[11] The command to stop the Directory Server on platforms other than Red Hat Enterprise Linux is described in Section 1.3, “Starting and Stopping Servers”.