8. Managing the Database Cache Settings

Directory Server uses the following caches:
  • The Entry cache, which contains individual directory entries.
  • The DN cache is used to associate DNs and RDNs with entries.
  • The Database cache, which contains the database index files *.db and *.db4 files.
For the highest performance improvements, configure all cache sizes to be able to store all of their records. If you do not have enough RAM, assign free memory to the caches in the previously shown order.

8.1. Determining the Required Cache Sizes

The dbmon.sh script enables you to monitor cache statistics at runtime and continuously outputs the statistics. To terminate the script, press the Ctrl+C key combination.

Note

The dbmon.sh requires you to pass the options as environment variables to the script. For further details see the Directory Server Configuration, Command, and File Reference.

Example 2. Using the dbmon.sh Script

To display the statistics, enter for example: 
# BINDDN="cn=Directory Manager" BINDPW=secret HOST=server.example.com PORT=389 dbmon.sh
dbcachefree 397310 free% 2.2 roevicts 9282348 hit% 50 pagein 2934772 pageout 219075
      dbname            count          free  free%    size
      userroot:ent      50000          2400    0.8  8972.7
      userroot:dn      100000       4294735   69.8   130.0
To list the total number of DNs in the userroot database, enter: 
# dbscan -f /var/lib/dirsrv/slapd-instance_name/db/userRoot/id2entry.db -t 200 | \
     grep -c rdn:
If your caches are sufficiently sized, the number returned by the previous command matches the value in the count column of the dbmon.sh script's output. Additionally, if all of the entries and DNs fit within their respective caches, the userroot:ent count value matches the userroot:dn count value.
The output of the dbmon.sh script example shows:
  • Only 2.2% free database cache is left: 
    dbcachefree 397310 free% 2.2 roevicts 9282348 hit% 50 pagein 2934772 pageout 219075
    However, to operate efficiently, at least 15% free database cache is required. To determine the optimal size of the database cache, calculate the sizes of all *.db and *.db4 files in the /var/lib/dirsrv/slapd-instance_name/db/ directory including subdirectories and the changelog database, and add 12% for overhead.
    To set the database cache, see Section 8.4, “Tuning the Database Cache”.
  • The DN cache of the userroot database is well-chosen: 
    dbname            count          free  free%    size
userroot:dn      100000       4294735   69.8   130.0
    The DN cache of the database contains 100000 records. 69,8% of the cache is free. Based on the count value and the bytes used, each DN in memory requires 130 bytes on average.
    To set the DN cache, see Section 8.4, “Tuning the Database Cache”.
  • The statistics on the entry cache of the userroot database indicates that the entry cache value should be increased for better performance: 
    dbname            count          free  free%    size
userroot:ent      50000          2400    0.8  8972.7
    The entry cache contains in this database 50000 records and only 2 Kilobytes of free space are left. To enable Directory Server to cache all 100000 DNs, reported by the dbscan utility's output, the cache must be increased to minimum of 856 Megabytes (100000 DNs * 8972,7 bytes average entry size). However, it is recommended to round the minimum required size to the next highest Gigabyte and double the result. In this example, the entry cache should be set to 2 Gigabytes.
    To set the entry cache, see Section 8.2, “Tuning the Entry Cache”.

8.2. Tuning the Entry Cache

The entry cache is used to store directory entries that are used during search and read operations. Setting the entry cache to a size that enables the Directory Server to store all records has the highest performance impact on search operations.
If entry caching is not configured, Directory Server reads the entry from the id2entry.db database file and converts the DNs from the on-disk format to the in-memory format. Entries that are stored in the cache enable the server to skip the disk I/O and conversion steps.

8.2.1. Setting the Entry Cache Size in the Directory Server Console

For example, to set the entry cache for the cn=userRoot database to 2 GB:
  1. Start the Directory Server Console.
  2. Select the Configuration tab and, in the navigation tree, expand the Data icon.
  3. Expand the suffix associated with the database, such as dc=example,dc=com, and then select the database.
  4. In the Database Settings tab, fill the Memory available for cache field and select the unit. For example:
  5. Click Save.
  6. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

8.2.2. Setting the Entry Cache Size From the Command Line

For example, to set the entry cache for the LDBM database to 2 GB:
  1. Set the value in the Directory Server configuration: 
    # ldapmodify -D "cn=directory manager" -W -x 

dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-cachememsize
nsslapd-cachememsize: 2147483648
  2. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

8.3. Tuning the DN Cache

The entryrdn index is used to associate DNs and RDNs with entries. It enables the server to efficiently perform subtree rename, entry move, and moddn operations. The DN cache is used to cache the in-memory representation of the entryrdn index to avoid expensive file I/O and transformation operations. For best performance, especially with but not limited to entry rename and move operations, set the DN cache to a size that enables Directory Server to cache all DNs in the database.
If a DN is not stored in the cache, Directory Server reads the DN from the entryrdn.db index database file and converts the DNs from the on-disk format to the in-memory format. DNs that are stored in the cache enable the server to skip the disk I/O and conversion steps.
To set the size of the DN cache for the LDBM database to 20 MB:
  1. Update the value in the Directory Server configuration: 
    # ldapmodify -D "cn=directory manager" -W -x 

dn: cn=database_name,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-dncachememsize
nsslapd-dncachememsize: 20971520
  2. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

8.4. Tuning the Database Cache

The database cache contains the Berkeley database index files for the database, meaning all of the *.db and other files used for attribute indexing by the database. This value is passed to the Berkeley DB API function set_cachesize().
This cache size has less of an impact on Directory Server performance than the entry cache size, but if there is available RAM after the entry cache size is set, increase the amount of memory allocated to the database cache.

Note

The operating system also has a file system cache which may compete with the database cache for RAM usage. Refer to the operating system documentation to find information on file system cache settings and monitoring the file system cache.
When setting the database cache value, monitor the cache usage.

8.4.1. Setting the Database Cache Size in the Directory Server Console

For example, to set the database cache to 256 megabytes:
  1. Start the Directory Server Console.
  2. Select the Configuration tab and, in the navigation tree, expand the Data icon.
  3. Select the Database Settings entry.
  4. In the LMDB Plug-in Settings tab, fill the Maximum cache size field and select the unit.
  5. Click Save.
    The Directory Server Console returns an LDAP_UNWILLING_TO_PERFORM error message when you set:
    • a value that is not a number.
    • a value that is too big for a 32-bit signed integer (2147483647) on a 32-bit system.
    • a value that is too big for a 64-bit signed integer (9223372036854775807) on a 64-bit system.
  6. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

8.4.2. Setting the Database Cache Size From the Command Line

For example, to set the database cache to 256 megabytes:
  1. Update the value in the Directory Server configuration: 
    # ldapmodify -D "cn=directory manager" -W -x

dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-dbcachesize
nsslapd-dbcachesize: 268435456
  2. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

8.4.3. Storing the Database Cache on a RAM Disk

If your system running the Directory Server instance has enough free RAM, you can optionally store the database cache on a RAM disk for further performance improvements:
  1. Create a directory for the database cache and metadata on the RAM disk: 
    # mkdir -p /dev/shm/slapd-instance_name/
  2. Set the path to the directory on the RAM disk in the nsslapd-db-home-directory attribute: 
    # ldapmodify -D "cn=directory manager" -W -x

dn: cn=config,cn=ldbm database,cn=plugins,cn=config
changetype: modify
replace: nsslapd-db-home-directory
nsslapd-db-home-directory: /dev/shm/slapd-instance_name/
  3. Restart the Directory Server instance: 
    # systemctl restart dirsrv.target

Note

When the database cache is stored on a RAM disk, Directory Server needs to recreate it after each reboot. As a consequence, the service start and initial operations are slower until the cache is recreated.