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.

Note

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.

13.4.1. Creating Browsing Indexes from the Server Console

  1. Select the Directory tab.
  2. In the left navigation tree, select the entry, such as People, for which to create the index.
  3. 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.
  4. 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 13.4.2.1, “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:
  1. Using ldapmodify to add new browsing index entries or edit existing browsing index entries. See Section 13.4.2.1, “Adding a Browsing Index Entry”.
  2. Running the vlvindex script to generate the new set of browsing indexes to be maintained by the server. See Section 13.4.2.2, “Running the vlvindex Script”. Alternatively, launch an appropriate task under cn=tasks,cn=config (Section 13.4.2.3, “Using a cn=tasks Entry to Create a Browsing Index”).
  3. Ensuring that access control on VLV index information is set appropriately. See Section 13.4.3, “Setting Access Control for VLV Information”.

13.4.2.1. Adding a Browsing Index Entry

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 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 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
  1. Run ldapmodify and add an entry which specifies the base, scope, and filter of the browsing index:
    # ldapmodify -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))
    • 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)).
  2. 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.

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.

13.4.2.2. Running the vlvindex Script

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:
  1. Stop the server.
    # systemctl stop dirsrv@instance_name
  2. Run the vlvindex script.
    # 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 vlvindex script in the Red Hat Directory Server Configuration, Command, and File Reference.
  3. Start the server.
    # systemctl start dirsrv instance

13.4.2.3. Using a cn=tasks Entry to Create a Browsing Index

As an alternative to running the vlvindex script, it is possible to initiate an indexing task directly.

Note

Running the indexing task is the same as running the vlvindex script.
The cn=tasks,cn=config entry 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=config to 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.
For example:
# ldapmodify -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 cn=tasks entries.

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 aci attribute to set the userdn parameter to ldap://anyone:
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: oid=2.16.840.1.113730.3.4.9,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" ;)