13.4. Creating Browsing Indexes

A virtual list view (VLV) index is a way of creating a partial list, defined by the VLV search parameters, 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.
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 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.1.1, “Adding a Browsing Index Entry”.
  2. Running the dsconf backend vlv-index reindex command to generate the new set of browsing indexes to be maintained by the server. See Section 13.4.1.2, “Recreating the VLV Index”. Alternatively, launch an appropriate task under cn=tasks,cn=config (Section 13.4.1.3, “Creating a Browsing Index Using a cn=tasks Entry”).
  3. Ensuring that access control on VLV index information is set appropriately. See Section 13.4.2, “Setting Access Control for VLV Information”.

13.4.1.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 (ou=accounting)
  • 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: (ou=accounting)
    • 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.
    • 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:
    # ldapmodify -a -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
    
    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 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.1.2. Recreating the VLV Index

After creating the two browsing indexing entries or added additional attribute types to an existing indexing browsing entries, run the dsconf backend vlv-index reindex command to generate the new set of browsing indexes to be maintained by the Directory Server. After running the command, the new set of browsing indexes is active for any new data added to the directory and any existing data in the directory.
  1. Stop the server.
    # dsctl instance_name stop
  2. Start the reindex process:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend vlv-index reindex --parent-name="by MCC ou=People dc=example dc=com" userRoot
  3. Start the server.
    # dsctl instance_name start

13.4.1.3. Creating a Browsing Index Using a cn=tasks Entry

The cn=tasks,cn=config entry in the Directory Server configuration is a container entry for temporary entries the server uses to manage tasks. To initiate an index operation, create a task in the cn=index,cn=tasks,cn=config entry.
Use the ldapadd utility to add a new browsing index task. For example:
# ldapadd -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=example_VLV_index,cn=index,cn=tasks,cn=config
objectclass: top
objectclass: extensibleObject
cn: example_VLV_index
nsIndexVLVAttribute: "by MCC ou=people,dc=example,dc=com"
Set the nsIndexVLVAttribute attribute to the relative distinguished name RDN of the subentry of the VLV entry definition. The previous example uses the RND created in Section 13.4.1.1, “Adding a Browsing Index Entry”.
The preceding task initiates an operation on Directory Server to creates the index. When the task completes, the cn=tasks,cn=config entry is removed.
For further information, see the cn=index section in the Red Hat Directory Server Configuration, Command, and File Reference.

13.4.2. 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" ;)