Chapter 10. Managing cache settings

Directory Server uses the following caches:

  • The entry cache, which contains individual directory entries.
  • The distinguished name (DN) cache is used to associate DNs and relative distinguished names (RDN) with entries.
  • The database cache, which contains the database index files *.db files.

For the highest performance improvements, all cache sizes must be able to store all of their records. If you do not use the recommended auto-sizing feature and have not enough RAM available, assign free memory to the caches in the previously shown order.

10.1. How the cache-autosize and cache-autosize-split parameters influence the database and entry cache sizes

By default, Directory Server uses an auto-sizing feature to optimize the size of both the database and entry cache on the hardware resources of the server when the instance starts.

Important

Red Hat recommends to use the auto-sizing feature and not to set cache sizes manually.

The following parameters in the cn=config,cn=ldbm database,cn=plugins,cn=config entry control the auto-sizing:

nsslapd-cache-autosize

These settings control if auto-sizing is enabled for the database and entry cache. Auto-sizing is enabled:

  • For both the database and entry cache, if the nsslapd-cache-autosize parameter is set to a value greater than 0.
  • For the database cache, if the nsslapd-cache-autosize and nsslapd-dbcachesize parameters are set to 0.
  • For the entry cache, if the nsslapd-cache-autosize and nsslapd-cachememsize parameters are set to 0.
nsslapd-cache-autosize-split
  • The value sets the percentage of RAM that Directory Server uses for the database cache. The server uses the remaining percentage for the entry cache.
  • Using more than 1.5 GB RAM for the database cache does not improve the performance. Therefore, Directory Server limits the database cache to 1.5 GB.

By default, Directory Server uses the following defaults values:

  • nsslapd-cache-autosize: 25
  • nsslapd-cache-autosize-split: 25
  • nsslapd-dbcachesize: 1,536 MB

Using these settings, 25% of the system’s free RAM is used (nsslapd-cache-autosize). From this memory, the server uses 25% for the database cache (nsslapd-cache-autosize-split) and the remaining 75% for the entry cache.

Depending on the free RAM, this results in the following cache sizes:

Table 10.1. Cache sizes if both nsslapd-cache-autosize and nsslapd-cache-autosize-split use their default values

GB of free RAMDatabase cache sizeEntry cache size

1 GB

64 MB

192 MB

2 GB

128 MB

384 MB

4 GB

256 MB

768 MB

8 GB

512 MB

1,536 MB

16 GB

1,024 MB

3,072 MB

32 GB

1,536 MB

6,656 MB

64 GB

1,536 MB

14,848 MB

128 GB

1,536 MB

31,232 MB

10.2. Required cache sizes

The dsconf monitor dbmon command enables you to monitor cache statistics at runtime. To display the statistics, enter: 

# dsconf -D "cn=Directory Manager" ldap://server.example.com monitor dbmon
DB Monitor Report: 2022-02-24 10:25:16
--------------------------------------------------------
Database Cache:
 - Cache Hit Ratio:     50%
 - Free Space:          397.31 KB
 - Free Percentage:     2.2%
 - RO Page Drops:       0
 - Pages In:            2934772
 - Pages Out:           219075

Normalized DN Cache:
 - Cache Hit Ratio:     60%
 - Free Space:          19.98 MB
 - Free Percentage:     99.9%
 - DN Count:            100000
 - Evictions:           9282348

Backends:
  - dc=example,dc=com (userroot):
    - Entry Cache Hit Ratio:        66%
    - Entry Cache Count:            50000
    - Entry Cache Free Space:       2.0 KB
    - Entry Cache Free Percentage:  0.8%
    - Entry Cache Average Size:     8.9 KB
    - DN Cache Hit Ratio:           21%
    - DN Cache Count:               100000
    - DN Cache Free Space:          4.29 MB
    - DN Cache Free Percentage:     69.8%
    - DN Cache Average Size:        130.0 B

Optionally, pass the -b back_end or -x option to the command to display the statistics for a specific back end or the index.

If your caches are sufficiently sized, the number in DN Cache Count matches the values in the Cache Count backend entries. Additionally, if all of the entries and DNs fit within their respective caches, the Entry Cache Count count value matches the DN Cache Count value.

The output of the example shows:

  • Only 2.2% free database cache is left: 

    Database Cache:
 ...
 - Free Space:          397.31 KB
 - Free Percentage:     2.2%

    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 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 Setting the database cache size using the command line.

  • The DN cache of the userroot database is well-chosen: 

    Backends:
  - dc=example,dc=com (userroot):
    ...
    - DN Cache Count:               100000
    - DN Cache Free Space:          4.29 MB
    - DN Cache Free Percentage:     69.8%
    - DN Cache Average Size:        130.0 B

    The DN cache of the database contains 100000 records, 69,8% of the cache is free, and each DN in memory requires 130 bytes on average.

    To set the DN cache, see Setting the DN cache size using the command line.

  • The statistics on the entry cache of the userroot database indicates that the entry cache value should be increased for better performance: 

    Backends:
  - dc=example,dc=com (userroot):
  ...
    - Entry Cache Count:            50000
    - Entry Cache Free Space:       2.0 KB
    - Entry Cache Free Percentage:  0.8%
    - Entry Cache Average Size:     8.9 KB

    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, the cache must be increased to minimum of 890 MB (100000 DNs * 8,9 KB average entry size). However, Red Hat recommends to round the minimum required size to the next highest GB and double the result. In this example, the entry cache should be set to 2 Gigabytes.

    To set the entry cache, see Setting the entry cache size using the command line.

10.3. Setting the database cache size using the command line

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.

Procedure

  1. Disable automatic cache tuning 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend config set --cache-autosize=0

  2. Manually set the database cache size: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend config set --dbcachesize=268435456

    Specify the database cache size in bytes. In this example, the command sets the database cache to 256 MB.

  3. Restart the instance: 

    # dsctl instance_name restart

10.4. Setting the database cache size using the web console

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.

Prerequisites

  • You are logged in to the instance in the web console.

Procedure

  1. Navigate to Database → Global Database Configuration.
  2. Deselect Automatic Cache Tuning.
  3. Click Save Config.
  4. Enter the database cache size in bytes, such as 268435456 for 256 MB, into the Database Cache Size field.
  5. Click Save Config.
  6. Click Actions in the top right corner, and select Restart Instance.

10.5. Setting the DN cache size using the command line

Directory Server uses the entryrdn index to associate distinguished names (DN) and relative distinguished names (RDN) with entries. It enables the server to efficiently rename subtrees, move entries, and perform moddn operations. The server uses the DN cache to cache the in-memory representation of the entryrdn index to avoid expensive file I/O and transformation operations.

If you do not use the auto-tuning feature, for best performance, especially with but not limited to renaming entries and moving 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.

Procedure

  1. Display the suffixes and their corresponding back end: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com suffix list
dc=example,dc=com (userroot)

    This command displays the name of the back end database next to each suffix. You require the suffix’s database name in the next step.

  2. Set the DN cache size: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --dncache-memsize=20971520 userRoot

    This command sets the DN cache for the userRoot database to 20 megabytes.

  3. Restart the instance: 

    # dsctl instance_name restart

10.6. Setting the DN cache size using the web console

Directory Server uses the entryrdn index to associate distinguished names (DN) and relative distinguished names (RDN) with entries. It enables the server to efficiently rename subtrees, move entries, and perform moddn operations. The server uses the DN cache to cache the in-memory representation of the entryrdn index to avoid expensive file I/O and transformation operations.

If you do not use the auto-tuning feature, for best performance, especially with but not limited to renaming entries and moving 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.

Prerequisites

  • You are logged in to the instance in the web console.

Procedure

  1. Navigate to Database → Suffixes → suffix_name.
  2. Enter the DN cache size in bytes to the DN Cache Size field.
  3. Click Save Configuration.
  4. Click Actions in the top right corner, and select Restart Instance.

10.7. Setting the entry cache size using the command line

Directory Server uses the entry cache to store directory entries that are used during search and read operations. Setting the entry cache to a size that enables 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 distinguished names (DN) 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.

Procedure

  1. Disable automatic cache tuning: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend config set --cache-autosize=0

  2. Display the suffixes and their corresponding back end: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com suffix list
dc=example,dc=com (userroot)

    This command displays the name of the back end database next to each suffix. You require the suffix’s database name in the next step.

  3. Set the entry cache size in bytes for the database: 

    # dsconf -D "cn=Directory Manager" ldap://server.example.com backend suffix set --cache-memsize=2147483648 userRoot

    This command sets the entry cache for the userRoot database to 2 gigabytes.

  4. Restart the instance: 

    # dsctl instance_name restart

10.8. Setting the entry cache size using the web console

Directory Server uses the entry cache to store directory entries that are used during search and read operations. Setting the entry cache to a size that enables 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 distinguished names (DN) 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.

Prerequisites

  • You are logged in to the instance in the web console.

Procedure

  1. Navigate to Database → Suffixes → suffix_name → Settings.
  2. Disable the Automatic Cache Tuning setting.
  3. Click Save Configuration.
  4. Click Actions in the top right corner, and select Restart Instance.
  5. Navigate to Database → Suffixes → suffix_name → Settings.
  6. Set the size of the database cache in the `Entry Cache Size field.
  7. Click Save Configuration.
  8. Click Actions in the top right corner, and select Restart Instance.