The Local DB Backend uses the Berkeley DB Java Edition to store user-provided data in a local repository.
It is the traditional "Directory Server" backend and stores the entries in an encoded form and also provides indexes that can be used to quickly locate target entries based on different kinds of criteria.
The Local DB Backend component inherits from the JE Backend
The following components have a direct composition relation from Local DB Backends:
The following components have a direct aggregation relation from Local DB Backends:
The properties supported by this managed object are as follows:
Property Group | General Configuration |
Description | Specifies a name to identify the associated backend. The name must be unique among all backends in the server. The backend ID may not be altered after the backend is created in the server. |
Default Value | None |
Allowed Values | A string |
Multi-Valued | No |
Required | Yes |
Admin Action Required | None. Modification requires no further action |
Property Group | General Configuration |
Description | A description for this Backend |
Default Value | None |
Allowed Values | A string |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
Property Group | General Configuration |
Description | Indicates whether the backend is enabled in the server. If a backend is not enabled, then its contents are not accessible when processing operations. |
Default Value | None |
Allowed Values | true false |
Multi-Valued | No |
Required | Yes |
Admin Action Required | None. Modification requires no further action |
Property Group | General Configuration |
Description | Specifies the base DN(s) for the data that the backend handles. A single backend may be responsible for one or more base DNs. Note that no two backends may have the same base DN although one backend may have a base DN that is below a base DN provided by another backend (similar to the use of sub-suffixes in the Sun Java System Directory Server). If any of the base DNs is subordinate to a base DN for another backend, then all base DNs for that backend must be subordinate to that same base DN. |
Default Value | None |
Allowed Values | A valid DN. |
Multi-Valued | Yes |
Required | Yes |
Admin Action Required | No administrative action is required by default although some action may be required on a per-backend basis before the new base DN may be used.
Although it is currently supported, the use of multiple base DNs per backend is not recommended and this capability may be removed in the future. If you are considering the use of multiple base DNs in a backend, you should first contact Ping Identity support to discuss this configuration |
Property Group | Storage Configuration |
Description | Specifies the path to the filesystem directory that is used to hold the Berkeley DB Java Edition database files containing the data for this backend. The files for this backend are stored in a sub-directory named after the backend-id. The path may be either an absolute path or a path relative to the directory containing the base of the Directory Server installation. The path may be any valid directory path in which the server has appropriate permissions to read and write files and has sufficient space to hold the database contents. |
Default Value | db |
Allowed Values | A filesystem path |
Multi-Valued | No |
Required | Yes |
Admin Action Required | The Directory Server must be restarted for changes to this setting to take effect. Modification requires that the Directory Server be stopped, the database directory manually relocated, and then the Directory Server restarted. While the Directory Server is stopped, the directory and files pertaining to this backend in the old database directory must be manually moved or copied to the new location. |
Property Group | Storage Configuration |
Description | Indicates whether to calculate and store a message digest of the entry contents along with the entry data, in order to provide a means of verifying the integrity of the entry data. If the entry digest is enabled, then it will always be written whenever an entry is created or updated. If the verify-entry-digests global configuration property is enabled, then the entry digest will be verified whenever an entry is read from the database; otherwise it will be ignored (but may still be used by other validation utilities). If this feature is enabled while there are already entries in the database, then those entries will remain without a message digest until they are updated, which will cause them to be re-written with a digest. |
Default Value | false |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
Property Group | Caching Configuration |
Description | Specifies the percentage of JVM memory to allocate to the database cache. Specifies the percentage of memory available to the JVM that should be used for caching database contents. Unless the use-shared-database-cache-across-all-local-db-backends property in the global configuration is set to true, each local DB backend will have its own separate cache, so the total db-cache-percent value across all local DB backends must not be too high, as it could oversubscribe available JVM memory. You must also ensure that an adequate amount of memory is still available for other data that the server needs to retain in memory during processing, as well as for JVM garbage collection processing. This property will be ignored if the use-shared-database-cache-across-all-local-db-backends global configuration property is set to true. In that case, the shared-local-db-backend-database-cache-percent global configuration property will be used to specify the percentage of the available JVM memory that will be used for caching across all local DB backends. |
Default Value | 10 |
Allowed Values | An integer value. Lower limit is 1. Upper limit is 90 . |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
Property Group | Priming Configuration |
Description | Specifies the method that should be used to prime caches with data for this backend. If any priming is to be performed for the backend, then the prime method should be chosen based on the type of caching to be used. If the server will primarily rely upon the database cache, then the preload method should be used. When using a preload or preload-internal-nodes-only option, the cache-mode settings also affect what is preloaded. If a cache-mode is set to "no-caching", then nothing will be preloaded for that index. If a cache-mode is set to "cache-keys-only", then only the internal database nodes will be preloaded, which includes the database keys and any values that are small enough to be embedded in the internal database nodes (e.g., index keys that match four or fewer entries). |
Default Value | none |
Allowed Values | none - Do not attempt to prime the backend when it is initialized. preload - Use a database-specific preload mechanism to prime the contents of the backend into the database cache. The cache-mode settings also affect what is preloaded. If a cache-mode is set to "no-caching", then nothing will be preloaded for that index. If a cache-mode is set to "cache-keys-only", then only the internal database nodes will be preloaded, which includes the database keys and any values that are small enough to be embedded in the internal database nodes (e.g., index keys that match four or fewer entries). preload-internal-nodes-only - Use a database-specific preload mechanism to prime internal database nodes into the database cache, which includes the database keys and any values that are small enough to be embedded in the internal database nodes (e.g., index keys that match four or fewer entries). For keys with larger database values (e.g., the encoded entry contents or large index ID lists), only the keys will be primed This will be faster than other prime methods, but the server caches may still need to "warm up" in order to achieve steady-state performance. It may be useful in environments in which a full prime is not required before the server begins accepting client requests. Note that "internal nodes" refers to the internal structure of the underlying database (i.e., the B-tree and database keys) and not to LDAP entries within the DIT that are not leaf entries. cursor-across-indexes - Use database cursors to iterate through backend contents. This is similar to (and likely slower than) using the preload mechanism, but it does provide the ability to prime the database cache in the background after the server has started. |
Multi-Valued | Yes |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
Property Group | Indexing Configuration |
Description | Specifies the maximum number of entries that are allowed to match a given index key before that particular index key is no longer maintained. Note that this is the default limit for the backend, and it may be overridden on a per-attribute basis. |
Default Value | 4000 |
Allowed Values | An integer value. Lower limit is 1. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | If any index keys have already reached this limit, indexes must be rebuilt before they will be allowed to use the new limit. |
Property Group | Indexing Configuration |
Description | Specifies the maximum number of entries that are allowed to match a given composite index key before that particular composite index key is no longer maintained. Note that this is the default limit for the backend, and it may be overridden on a per-attribute basis. |
Default Value | 100000 |
Allowed Values | An integer value. Lower limit is 1. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | If any composite index keys have already reached this limit, those composite indexes must be rebuilt before they will be allowed to use the new limit. |
Property Group | LDIF Import and Export Configuration |
Description | The percentage of JVM memory to allocate to the database cache during import operations. Specifies the percentage of memory available to the JVM that should be used for caching database contents during import. Note that unlike db-cache-percent and db-cache-size, this value will always be used even if the db-cache-size property is set. Setting this value too large can have a large negative impact on import performance. It should not be set above the default unless the heap is over 16GB. |
Default Value | 60 |
Allowed Values | An integer value. Lower limit is 10. Upper limit is 80 . |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
writability-mode (Advanced Property)
Property Group | General Configuration |
Description | Specifies the behavior that the backend should use when processing write operations. |
Default Value | enabled |
Allowed Values | enabled - Allows write operations to be performed in that backend (if the requested operation is valid, the user has permission to perform the operation, the backend supports that type of write operation, and the global writability-mode property is also enabled). disabled - Causes all write attempts to fail. internal-only - Causes external write attempts to fail but allows writes by replication and internal operations. |
Multi-Valued | No |
Required | Yes |
Admin Action Required | None. Modification requires no further action |
set-degraded-alert-when-disabled (Advanced Property)
Property Group | General Configuration |
Description | Determines whether the Directory Server enters a DEGRADED state (and sends a corresponding alert) when this Backend is disabled. |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
return-unavailable-when-disabled (Advanced Property)
Property Group | General Configuration |
Description | Determines whether any LDAP operation that would use this Backend is to return UNAVAILABLE when this Backend is disabled. |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
notification-manager (Advanced Property)
Property Group | General Configuration |
Description | Specifies a notification manager for changes resulting from operations processed through this Backend |
Default Value | None |
Allowed Values | The DN of any Notification Manager. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
is-private-backend (Advanced Property)
Property Group | General Configuration |
Description | Indicates whether this backend should be considered a private backend in the server. Private backends are meant for storing server-internal information and should not be used for user or application data. |
Default Value | false |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
db-directory-permissions (Advanced Property)
Property Group | Storage Configuration |
Description | Specifies the permissions that should be applied to the directory containing the backend database files and to directories and files created during backup or LDIF export of the backend. They should be expressed as three-digit octal values, which is the traditional representation for UNIX file permissions. The three digits represent the permissions that are available for the directory's owner, group members, and other users (in that order), and each digit is the octal representation of the read, write, and execute bits. Execute permissions are only applied to directories. Note that this property only impacts permissions on the database directory and not on the files written into that directory. On UNIX systems, the user's umask controls permissions given to the database files. |
Default Value | 700 |
Allowed Values | Any octal value between 700 and 777 (the owner must always have read, write, and execute permissions on the directory). |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
compact-common-parent-dn (Advanced Property)
Property Group | Storage Configuration |
Description | Provides a DN of an entry that may be the parent for a large number of entries in the backend. This may be used to help increase the space efficiency when encoding entries for storage. |
Default Value | None |
Allowed Values | A valid DN. |
Multi-Valued | Yes |
Required | No |
Admin Action Required | None. Modification requires no further action |
compress-entries (Advanced Property)
Property Group | Storage Configuration |
Description | Indicates whether the backend should attempt to compress entries before storing them in the database. Note that this property applies only to the entries themselves and does not impact the index data. Further, the effectiveness of the compression is based on the type of data contained in the entry. |
Default Value | false |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes to this setting take effect only for writes that occur after the change is made. It is not retroactively applied to existing data until those entries are updated. |
db-num-cleaner-threads (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the number of threads that the backend should maintain to keep the database log files at or near the desired utilization. A value of zero indicates that the number of cleaner threads should be automatically configured based on the number of available CPUs. In environments with high write throughput, multiple cleaner threads may be required to maintain the desired utilization. If the number of cleaner threads is to be automatically tuned, then the number of threads will be set based on the number of available CPUs. For less than 16 CPUs, there will be 1 cleaner thread, and for 16 or more CPUs there will be 2 cleaner threads. If monitoring of the cleaner-backlog value indicates that a backlog exists, then the number of cleaner threads can be increased with a manual setting. |
Default Value | 0 |
Allowed Values | An integer value. Lower limit is 0. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
db-cleaner-min-utilization (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the minimum percentage of "live" data that the database cleaner attempts to keep in database log files. If the amount of live data in the database environment drops below this percentage, then the cleaner moves some live data to the end of the database. As a result of cleaning, some database log files may no longer contain live data. These files will be removed at the next checkpoint. |
Default Value | 75 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 90 . |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
db-evictor-critical-percentage (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the percentage over the configured maximum that the database cache is allowed to grow. It is recommended to set this value slightly above zero when the database is too large to fully cache in memory. In this case, a dedicated background evictor thread is used to perform evictions once the cache fills up reducing the possibility that server threads are blocked. When the database is too large to fully cache in memory, the server threads that process operations are responsible for evicting data from the cache to make room for new data. This eviction process is typically fast, but it can block other server threads while it happens. To avoid this, it is recommended to set this property to a non-zero value (5 is typically enough), so that a dedicated thread begins evicting data from the cache once it is full. Server threads do not have to do any evictions unless the cache is more than the configured critical percentage above being 100% full. Changes to this property do not take effect until the backend is restarted. |
Default Value | 0 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 100 . |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
db-checkpointer-wakeup-interval (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the maximum length of time that should pass between checkpoints. |
Default Value | 60s |
Allowed Values | A duration. Lower limit is 1 milliseconds. Upper limit is 4294000 milliseconds. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
db-background-sync-interval (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the interval to use when performing background synchronous writes in the database environment in order to smooth overall write performance and increase data durability. A value of "0 s" will disable background synchronous writes. |
Default Value | 1000 ms |
Allowed Values | A duration. Lower limit is 0 milliseconds. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
db-use-thread-local-handles (Advanced Property)
Property Group | Database Configuration |
Description | Indicates whether to use thread-local database handles to reduce contention in the backend. |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
db-log-file-max (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the maximum size for a database log file. |
Default Value | 50mb |
Allowed Values | A positive integer representing a size. Lower limit is 1048576. Upper limit is 4294967296 . |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
db-logging-level (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the log level that should be used by the database when it is writing information into the je.info file. The database trace logging level is (in increasing order of verbosity) chosen from: OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST. |
Default Value | CONFIG |
Allowed Values | A string |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
je-property (Advanced Property)
Property Group | Database Configuration |
Description | Specifies the database and environment properties for the Berkeley DB Java Edition database serving the data for this backend. Any Berkeley DB Java Edition property can be specified using the following form: property-name=property-value. Refer to the Directory Server documentation for further information on related properties, their implications, and range values. The definitive identification of all the property parameters is available in the example.properties file of Berkeley DB Java Edition distribution. |
Default Value | None |
Allowed Values | A string |
Multi-Valued | Yes |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
default-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used for any database for which the cache mode is not explicitly specified. This includes the id2entry database, which stores encoded entries, and all attribute indexes. |
Default Value | cache-keys-and-values |
Allowed Values | cache-keys-and-values - For each database, the server will keep both the keys and values of the database in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - This value can reduce the cache memory requirements. For each database, the server will keep only the internal database nodes in the database cache. This includes the database keys and any values that are small enough to be embedded in the internal database nodes (e.g., index keys that match four or fewer entries). The memory savings are dependent on the data set and indexing, but typically the steady-state database cache requires less than 20% of the memory of an environment using the default "cache-keys-and-values" option to fully cache the database. Using this option typically limits the server performance to the performance of the disk. However, when the backend is stored on a solid state disk (SSD), this is often the best option to get fast, consistent performance for databases that are too large to fully cache. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. The savings are dependent on the data set and indexing, but typically the steady-state database cache requires less than 5% of the memory of a fully-cached database. While this requires less memory, it relies more heavily on the disk, and puts more pressure on Java garbage collection. It is only recommended to set default-cache-mode to this value when frequently used system and user-defined indexes have a cache mode of "cache-keys-and-values" or "cache-keys-only". |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
id2entry-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the id2entry database, which provides a mapping between entry IDs and entry contents. Consider configuring uncached entries or uncached attributes in lieu of changing from the "cache-keys-and-values" default value. |
Default Value | The cache mode specified by the default-cache-mode property will be used. |
Allowed Values | cache-keys-and-values - The server will keep both the entry ID keys and the encoded entry contents in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - The server will keep only the entry IDs in the database cache, saving memory. The savings vary based on the size of the encoded entry, but typically the steady-state database cache requirements of id2entry using "cache-keys-only" requires only about 2% of the memory of a fully cached index. The file system will be accessed on every access to an entry. When performance is important, the "cache-keys-only" setting should only be used when the backend is stored on a solid state disk (SSD). no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. The savings vary, but typically the steady-state database cache requires less than 1% of the memory of an environment using the default "cache-keys-and-values" option to fully cache the index. While this requires less memory, it relies more heavily on the disk, puts more pressure on Java garbage collection, and can lead to database cleaning issues. When performance is important, the "no-caching" setting should not be used. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
dn2id-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the dn2id database, which provides a mapping between normalized entry DNs and the corresponding entry IDs. |
Default Value | The cache mode specified by the default-cache-mode property will be used. |
Allowed Values | cache-keys-and-values - The server will keep both the DN key and the corresponding entry ID in the database cache. This offers the best performance, but it also requires the most memory. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. The savings vary, but typically the steady-state database cache requires less than 2% of the memory of an environment using the default "cache-keys-and-values" setting to fully cache the index. While this requires less memory, it relies more heavily on the disk and puts more pressure on Java garbage collection. When performance is important, the "no-caching" setting should not be used. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
id2children-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the id2children database, which provides a mapping between the entry ID of a particular entry and the entry IDs of all of its immediate children. This index may be used when performing searches with a single-level scope if the search filter cannot be resolved to a small enough candidate list. The size of this database directly depends on the number of entries that have children. |
Default Value | The cache mode specified by the default-cache-mode property will be used. |
Allowed Values | cache-keys-and-values - The server will keep both the parent entry ID key and the corresponding list of child entry IDs in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - The server will keep only the parent entry ID keys (known as the "internal database nodes") in the database cache, saving memory. The savings vary based on the number of entries in the backend that have children. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
id2subtree-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the id2subtree database, which provides a mapping between the entry ID of a particular entry and the entry IDs of all of its children to any depth. This index may be used when performing searches with a whole-subtree or subordinate-subtree scope if the search filter cannot be resolved to a small enough candidate list. The size of this database directly depends on the number of entries that have children. |
Default Value | The cache mode specified by the default-cache-mode property will be used. |
Allowed Values | cache-keys-and-values - The server will keep both the parent entry ID key and the corresponding list of subtree entry IDs in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - The server will keep only the parent entry ID keys (known as the "internal database nodes") in the database cache, saving memory. The savings vary based on the number of entries in the backend that have children. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
dn2uri-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the dn2uri database, which provides a mapping between a normalized entry DN and a set of referral URLs contained in the associated smart referral entry. |
Default Value | The cache mode specified by the default-cache-mode property will be used. |
Allowed Values | cache-keys-and-values - The server will keep both the parent entry ID key and the corresponding list of referral URLs in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - The server will keep only the parent entry ID keys (known as the "internal database nodes") in the database cache, saving memory. The savings vary based on the number of entries in the backend that have references. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
uncached-id2entry-cache-mode (Advanced Property)
Property Group | Caching Configuration |
Description | Specifies the cache mode that should be used when accessing the records in the uncached-id2entry database, which provides a way to store complete or partial encoded entries with a different (and presumably less memory-intensive) cache mode than records written to id2entry. If the system has enough memory available to fully cache the internal nodes for this database, then "cache-keys-only" is recommended, otherwise it will likely be better to select "no-caching" to minimize the amount of memory required for interacting with the uncached-id2entry database. The "cache-keys-and-values" cache mode should generally only be used for deployments in which uncached attributes are to be used rather than uncached entries, and then only in cases in which the server has enough memory to fully cache all internal and leaf nodes in this database but the uncached attributes should not be retrieved and decoded unless they are specifically needed for processing the operation. |
Default Value | cache-keys-only |
Allowed Values | cache-keys-and-values - The server will keep both the entry ID keys and the encoded entry contents in the database cache, which requires the most memory of any of these settings. This means the attributes or entries are not actually uncached. This mode should generally only be used for deployments in which uncached attributes are to be used rather than uncached entries, and then only in cases in which the server has enough memory to fully cache this database but the uncached attributes should not be retrieved and decoded unless they are specifically needed for processing the operation. cache-keys-only - The server will keep only the entry IDs of the uncached entries/attributes in the database cache. This is the recommended setting if the system has enough memory available to fully cache this information. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. This option should be selected when there is insufficient memory to use the "cache-keys-only" setting. |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
uncached-attribute-criteria (Advanced Property)
Property Group | Caching Configuration |
Description | The criteria that will be used to identify attributes that should be written into the uncached-id2entry database rather than the id2entry database. This will only be used for entries in which the associated uncached-entry-criteria does not indicate that the entire entry should be uncached. This will apply to all entry writes, including add, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes will take effect immediately for writes occurring after the change is made. If no value is specified, then all attributes will be written into the id2entry database. |
Default Value | None |
Allowed Values | The DN of any Uncached Attribute Criteria. The associated uncached attribute criteria object must be enabled. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
uncached-entry-criteria (Advanced Property)
Property Group | Caching Configuration |
Description | The criteria that will be used to identify entries that should be written into the uncached-id2entry database rather than the id2entry database. This will apply to all entry writes, including add, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes will take effect immediately for writes occurring after the change is made. If no value is specified, then all entries will be written into the id2entry database. |
Default Value | None |
Allowed Values | The DN of any Uncached Entry Criteria. The associated uncached entry criteria object must be enabled. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
prime-thread-count (Advanced Property)
Property Group | Priming Configuration |
Description | Specifies the number of threads to use when priming. At present, this applies only to the preload and cursor-across-indexes prime methods. |
Default Value | 2 |
Allowed Values | An integer value. Lower limit is 1. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
prime-time-limit (Advanced Property)
Property Group | Priming Configuration |
Description | Specifies the maximum length of time that the backend prime should be allowed to run. A duration of zero seconds indicates that there should not be a time limit. |
Default Value | 0s |
Allowed Values | A duration. Lower limit is 0 milliseconds. Upper limit is 2147483647 milliseconds. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
prime-all-indexes (Advanced Property)
Property Group | Priming Configuration |
Description | Indicates whether to prime all indexes associated with this backend, or to only prime the specified set of indexes (as configured with the system-index-to-prime property for the system indexes, and the prime-index property in the attribute index definition for attribute indexes). |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
system-index-to-prime (Advanced Property)
Property Group | Priming Configuration |
Description | Specifies which system index(es) should be primed when the backend is initialized. This property will only be used if the prime-all-indexes property has a value of false. |
Default Value | None |
Allowed Values | dn2id - Index from normalized DN to entry ID. id2entry - Index from entry ID to the entire encoded entry. id2children - Index from entry ID to an entry ID list of its immediate children. id2subtree - Index from entry ID to an entry ID list of its subordinates. dn2uri - The referral database index that maps a normalized DN string to labeled URIs. |
Multi-Valued | Yes |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
system-index-to-prime-internal-nodes-only (Advanced Property)
Property Group | Priming Configuration |
Description | Specifies the system index(es) for which internal database nodes only (i.e., the database keys but not values) should be primed when the backend is initialized. This property will only be used if the prime-all-indexes property has a value of false and the prime-method property has a value of preload. If a system index is contained in both the system-index-to-prime and the system-index-to-prime-internal-nodes-only properties, then the entire index will be primed rather than internal nodes only. Note that "internal nodes" refers to the internal structure of the underlying database (i.e., the B-tree and database keys) and not to LDAP entries within the DIT that are not leaf entries. |
Default Value | None |
Allowed Values | dn2id - Index from normalized DN to entry ID. id2entry - Index from entry ID to the full or partial encoded entry. uncached-id2entry - Index from entry ID to the full or partial encoded entry in a manner that should generally be less cached than id2entry. id2children - Index from entry ID to an entry ID list of its immediate children. id2subtree - Index from entry ID to an entry ID list of its subordinates. dn2uri - The referral database index that maps a normalized DN string to labeled URIs. |
Multi-Valued | Yes |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
background-prime (Advanced Property)
Property Group | Priming Configuration |
Description | Indicates whether to attempt to perform the prime using a background thread if possible. If background priming is enabled, then the Directory Server may be allowed to accept client connections and process requests while the prime is in progress. This configuration property applies only to the cursor-across-indexes prime method. Preload-based prime methods will never be processed with a background thread. |
Default Value | false |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
id2children-index-entry-limit (Advanced Property)
Property Group | Indexing Configuration |
Description | Specifies the maximum number of entry IDs to maintain for each entry in the id2children system index (which keeps track of the immediate children for an entry, to assist in otherwise unindexed searches with a single-level scope). A value of 0 means there is no limit, however this could have a big impact on database size on disk and on server performance. |
Default Value | The value of the index-entry-limit configuration option will be used. |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | If this limit is increased, then the contents of the backend must be exported to LDIF and re-imported to allow the new limit to be used for any id2children keys that had already hit the previous limit. |
id2subtree-index-entry-limit (Advanced Property)
Property Group | Indexing Configuration |
Description | Specifies the maximum number of entry IDs to maintain for each entry in the id2subtree system index (which keeps track of all descendants below an entry, to assist in otherwise unindexed searches with a whole-subtree or subordinate subtree scope). A value of 0 means there is no limit, however this could have a big impact on database size on disk and on server performance. |
Default Value | The value of the index-entry-limit configuration option will be used. |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | If this limit is increased, then the contents of the backend must be exported to LDIF and re-imported to allow the new limit to be used for any id2subtree keys that had already hit the previous limit. |
import-temp-directory (Advanced Property)
Property Group | LDIF Import and Export Configuration |
Description | Specifies the location of the directory that is used to hold temporary information during the index post-processing phase of an LDIF import. The specified directory is only used while an import is in progress and the files created in this directory are deleted as they are processed. It may be an absolute path or one that is relative to the instance root directory. |
Default Value | import-tmp |
Allowed Values | A filesystem path |
Multi-Valued | No |
Required | Yes |
Admin Action Required | None. Changes do not take effect for any import that may already be in progress. |
import-thread-count (Advanced Property)
Property Group | LDIF Import and Export Configuration |
Description | Specifies the number of threads to use for concurrent processing during an LDIF import. This should generally be a small multiple (for example, 2x) of the number of CPUs in the system for a traditional system, or equal to the number of CPU strands for a CMT system. |
Default Value | 16 |
Allowed Values | An integer value. Lower limit is 1. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes do not take effect for any import that may already be in progress. |
export-thread-count (Advanced Property)
Property Group | LDIF Import and Export Configuration |
Description | Specifies the number of threads to use for concurrently retrieving and encoding entries during an LDIF export. A value of zero indicates that the value should be automatically tuned based on the number of available CPUs. |
Default Value | 0 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Changes do not take effect for any export that may already be in progress. |
db-txn-write-no-sync (Advanced Property)
Property Group | Transaction Configuration |
Description | Indicates whether the database should synchronously flush data as it is written to disk. If this value is set to "false", then all data written to disk is synchronously flushed to persistent storage and thereby providing full durability. If it is set to "true", then data may be cached for a period of time by the underlying operating system before actually being written to disk. This may improve performance, but could cause the most recent changes to be lost in the event of an underlying OS or hardware failure (but not in the case that the Directory Server or the JVM exits abnormally). |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | The Local DB Backend must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
deadlock-retry-limit (Advanced Property)
Property Group | Transaction Configuration |
Description | Specifies the number of times that the server should retry an attempted operation in the backend if a deadlock results from two concurrent requests that interfere with each other in a conflicting manner. A value of "0" indicates no retry will be attempted. |
Default Value | 3 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
external-txn-default-backend-lock-behavior (Advanced Property)
Property Group | Transaction Configuration |
Description | Specifies the default behavior that should be exhibited by external transactions (e.g., an LDAP transaction or an atomic multi-update operation) with regard to acquiring an exclusive lock in this backend. If an exclusive lock is acquired for an operation, then no other operations will be allowed within the same backend until the operation holding the exclusive lock completes. Acquiring the backend lock can eliminate the potential for conflicts between operations, but at the expense of concurrency. This may be overridden on a per-transaction basis using the transaction settings request control. |
Default Value | acquire-after-retries |
Allowed Values | do-not-acquire - Do not attempt to acquire the exclusive backend lock for the initial attempt or any retries. This will provide the greatest concurrency, but also offers the greatest risk of operation failures due to lock conflicts. acquire-after-retries - Do not attempt to acquire the exclusive backend lock for the initial attempt or any of the configured number of retries, but if all attempts fail because of lock conflicts, then make one additional attempt after acquiring the backend lock. This will provide a great deal of concurrency but will fall back to acquiring the lock if it is not possible to succeed without it. acquire-before-retries - Do not attempt to acquire the exclusive backend lock for the initial attempt, but acquire it before any retry attempts. This ensures one attempt without holding the lock, but eliminates the possibility for lock conflicts with other operations during retries. acquire-before-initial-attempt - Acquire the exclusive backend lock before the initial attempt. This will prevent any lock conflicts resulting from processing performed by other operations, but it also minimizes concurrency by preventing other operations in the backend while an external transaction is being processed. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
single-writer-lock-behavior (Advanced Property)
Property Group | Transaction Configuration |
Description | Specifies the condition under which to acquire a single-writer lock to ensure that the associated operation will be the only write in progress at the time the lock is held. The single-writer lock can help avoid problems that result from database lock conflicts that arise between two write operations being processed at the same time in the same backend. This will not have any effect on the read operations processed while the write is in progress. The single-writer lock can be used as an alternative to the exclusive backend lock. The exclusive backend lock is controlled by the external-txn-default-backend-lock-behavior and by the transaction attempt settings request control. When the exclusive lock is held, the backend will ensure that no other operations (whether read or write operations) will be able to interfere with those processed by the owner of the exclusive lock. This provides the greatest degree of protection against database lock conflicts that arise from concurrent operations, but at a significant performance penalty when multiple requests are being processed at the same time. The single-writer lock can be used to ensure that only one write operation is in progress at any time, but without affecting read concurrency. This can dramatically reduce the performance impact in environments in which write operations are often seen to conflict with each other but do not conflict with read operations. |
Default Value | acquire-on-retry |
Allowed Values | acquire-on-retry - Indicates that the backend should acquire the single-writer lock when re-trying an operation that has already failed at least once because of a database lock conflict. The majority of concurrent write operations will be allowed to progress simultaneously, but if a conflict arises between two write operations, the single-writer lock ensures that any retry attempts for those operations will be processed without any other write operations in progress at the same time. always-acquire - Indicates that the backend should always acquire the single-writer lock when attempting to process a write operation. This will ensure that the backend will never attempt to process more than one write operation at a time. This option is recommended for environments in which a high percentage of write operations are likely to conflict with each other, and it can lead to improved performance for those write operations by reducing the likelihood that they will block for an extended period of time in the event of a lock conflict. This option may reduce the overall write throughput that the server can achieve when there are no write conflicts, but the server should still be able to process thousands of write operations per second, which is more than enough for most deployments. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
subtree-delete-size-limit (Advanced Property)
Property Group | Other Configuration |
Description | Specifies the maximum number of entries that may be deleted from the backend when using the subtree delete control. If a subtree contains more than this number of entries, then it cannot be removed using the subtree delete control. A value of zero indicates that subtree delete operations will not be allowed. |
Default Value | 5000 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
num-recent-changes (Advanced Property)
Property Group | Other Configuration |
Description | Specifies the number of recent LDAP entry changes per replica for which the backend keeps a record to allow replication to recover in the event that the server is abruptly terminated. Increasing this value can lead to an increased peak server modification rate as well as increased replication throughput. The size of various replication queues is derived from the minimum value of this setting across all backends. This ensures that replication never has more uncommitted outstanding changes than are recoverable from the backend. Increasing this value will lead to slight increases in on-disk and memory requirements, but it will also increase the maximum server modification rate and replication throughput, which reduces the likelihood of replication backlogs. |
Default Value | 50000 |
Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
Multi-Valued | No |
Required | No |
Admin Action Required | The Directory Server must be restarted for changes to this setting to take effect. In order for this modification to take effect the server must be restarted |
offline-process-database-open-timeout (Advanced Property)
Property Group | Other Configuration |
Description | Specifies a timeout duration which will be used for opening the database environment by an offline process, such as export-ldif. A timeout should be set for opening the database environment by an offline process since this will prohibit deleting obsolete log files for the online database environment. While database files are prohibited from being deleted, disk space consumed by the database environment will increase and may fill the storage volume. Opening the database environment in an offline process, such as export-ldif and verify-index, may take a long time if an in-memory database recovery must be performed to construct the database structure since the last checkpoint. A value of 0s means wait indefinitely while opening the database environment in an offline process. |
Default Value | 1 h |
Allowed Values | A duration. Lower limit is 0 seconds. |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
set-degraded-alert-for-untrusted-index (Advanced Property)
Property Group | Other Configuration |
Description | Determines whether the Directory Server enters a DEGRADED state when this Local DB Backend has an index whose contents cannot be trusted. |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
return-unavailable-for-untrusted-index (Advanced Property)
Property Group | Other Configuration |
Description | Determines whether the Directory Server returns UNAVAILABLE for any LDAP search operation in this Local DB Backend that would use an index whose contents cannot be trusted. |
Default Value | true |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
process-filters-with-undefined-attribute-types (Advanced Property)
Property Group | Other Configuration |
Description | Determines whether the Directory Server should continue filter processing for LDAP search operations in this Local DB Backend that includes a search filter with an attribute that is not defined in the schema. This will only apply if check-schema is enabled in the global configuration. This is useful when searching on attributes that are not defined in the schema but might be in entries with the extensibleObject objectclass. Enabling this will decrease the efficiency of searches operations with unknown attributes in the filter since the operation might become unindexed. |
Default Value | false |
Allowed Values | true false |
Multi-Valued | No |
Required | No |
Admin Action Required | None. Modification requires no further action |
To list the configured Backends:
dsconfig list-backends [--property {propertyName}] ...
To view the configuration for an existing Backend:
dsconfig get-backend-prop --backend-name {name} [--tab-delimited] [--script-friendly] [--property {propertyName}] ...
To update the configuration for an existing Backend:
dsconfig set-backend-prop --backend-name {name} (--set|--add|--remove) {propertyName}:{propertyValue} [(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Local DB Backend:
dsconfig create-backend --backend-name {name} --type {type} --set enabled:{propertyValue} --set base-dn:{propertyValue} [--set {propertyName}:{propertyValue}] ...
To delete an existing Backend:
dsconfig delete-backend --backend-name {name}