Show Table of Contents
13.4. Creating Browsing (VLV) Indexes
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.
VLV indexes are not applied to attributes, like standard indexes are, but they are dynamically generated based on attributes set in entries and the location of those entries in the directory tree. VLV indexes, unlike standard indexes, are special entries in the database rather than configuration settings for the database.
VLV indexes are similar to simple paged results, which can be returned with some external LDAP clients. Simple paged results are calculated per search, while VLV indexes are a permanent list, so VLV indexes are overall faster for searches, but do require some overhead for the server to maintain.
Simple paged results and VLV indexes cannot be used on the same search.
For more information, see Section 14.7.4, “Using Simple Paged Results”.
13.4.1. Creating Browsing Indexes from the Server Console
- 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.
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 18.104.22.168, “Adding a Browsing Index Entry” and Section 13.4.3, “Setting Access Control for VLV Information”.
13.4.2. Creating Browsing Indexes from the Command Line
Creating a browsing index or virtual list view (VLV) index from the command line has these steps:
ldapmodifyto add new browsing index entries or edit existing browsing index entries. See Section 22.214.171.124, “Adding a Browsing Index Entry”.
- Running the
vlvindexscript to generate the new set of browsing indexes to be maintained by the server. See Section 126.96.36.199, “Running the vlvindex Script”. Alternatively, launch an appropriate task under
cn=tasks,cn=config(Section 188.8.131.52, “Using a cn=tasks Entry to Create a Browsing Index”).
- Ensuring that access control on VLV index information is set appropriately. See Section 13.4.3, “Setting Access Control for VLV Information”.
184.108.40.206. Adding a Browsing Index Entry
The type of browsing index entry to create depends on the type of
ldapsearchattribute 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 searchFor more information on specifying filters for searches, see Chapter 14, 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.
For example, create a browsing index to accelerate an
ldapsearchon the entry
ou=People,dc=example,dc=comheld in the
Example1database with the following attributes:
- The search base is
- The search filter is
- The scope is
- The sorting order for the returned attributes is
ldapmodifyand add an entry which specifies the base, scope, and filter of the browsing index:
-a-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=MCC ou=People dc=example dc=com,cn=userRoot,cn=ldbm database,cn=plugins,cn=config changetype: add 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))
cncontains the browsing index identifier, which specifies the entry on which to create the browsing index; in this example, the
ou=People,dc=example,dc=comentry. Red Hat recommends using the
dnof 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
vlvbaseattribute value specifies the entry on which you want to create the browsing index; in this example, the
ou=People,dc=example,dc=comentry (the browsing index identifier).
1, indicating that the scope for the search you want to accelerate is
1. A search scope of
1means that only the immediate children of the entry specified in the
cnattribute, and not the entry itself, will be searched.
vlvFilterspecifies the filter to be used for the search; in this example,
- 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
cncontains the browsing index sort identifier. The above
cnis 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
vlvSortattribute value specifies the order in which you want your attributes to be sorted; in this example,
ou, and then
This first browsing index entry must be added to the
,cn=ldbm database,cn=plugins,cn=configdirectory tree node, and the second entry must be a child of the first entry.
220.127.116.11. Running the vlvindex Script
After creating the two browsing indexing entries or added additional attribute types to an existing indexing browsing entries, run the
vlvindexscript 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
- Stop the server.
# systemctl stop dirsrv@instance_name
- Run the
# vlvindex -Z instance_name -n Example1 -T "by MCC ou=people dc=example dc=com"For information about the parameters used in the example, see the description of the
vlvindexscript in the Red Hat Directory Server Configuration, Command, and File Reference.
- Start the server.
# systemctl start dirsrv instance
18.104.22.168. Using a cn=tasks Entry to Create a Browsing Index
As an alternative to running the
vlvindexscript, it is possible to initiate an indexing task directly.
Running the indexing task is the same as running the
cn=tasks,cn=configentry in the Directory Server configuration is a container entry for temporary entries that the server uses to manage tasks. Several common directory tasks have container entries under
cn=tasks,cn=config. Temporary task entries can be created under
cn=index,cn=tasks,cn=configto initiate an indexing operation.
This task entry requires a unique name (
cn) and one other attribute,
nsIndexVLVAttribute, which gives the name of the browsing index definition entry to use to generate the VLV index.
-a-D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=example VLV index,cn=index,cn=tasks,cn=config changetype: add objectclass: extensibleObject cn: example VLV index nsIndexVLVAttribute: "by MCC ou=people,dc=example,dc=com"
As soon as the task is completed, the entry is removed from the directory configuration.
The Red Hat Directory Server Configuration, Command, and File Reference has more information on running Directory Server tasks under the
13.4.3. Setting Access Control for VLV Information
The default access control instruction (ACI) allows only authenticated users to use the VLV index information. If you additionally require to allow non-authenticated users to use the VLV index information, update the
aciattribute to set the
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: oid=2.16.840.1.113722.214.171.124,cn=features,cn=config changetype: modify replace: aci aci: (targetattr != "aci")(version 3.0; acl "VLV Request Control"; allow( read, search, compare, proxy ) userdn = "ldap://anyone" ;)