JE Backend

Note: this is an abstract component that cannot be instantiated.

The JE Backend uses the Berkeley DB Java Edition to store user-provided data in a local repository.

Direct Subcomponents Parent Component Properties dsconfig Usage

Direct Subcomponents

The following JE Backends are available in the server :

These JE Backends inherit from the properties described below.

Parent Component

The JE Backend component inherits from the Backend

Properties

The properties supported by this managed object are as follows:


General Configuration Basic Properties: Advanced Properties:
 backend-id  set-degraded-alert-when-disabled
 description  return-unavailable-when-disabled
 enabled  notification-manager
 base-dn  is-private-backend
 writability-mode
Storage Configuration Basic Properties: Advanced Properties:
 db-directory  db-directory-permissions
 hash-entries  compact-common-parent-dn
 compress-entries
Database Configuration Basic Properties: Advanced Properties:
 None  db-num-cleaner-threads
 db-cleaner-min-utilization
 db-evictor-critical-percentage
 db-checkpointer-wakeup-interval
 db-background-sync-interval
 db-use-thread-local-handles
 db-log-file-max
 db-logging-level
 je-property
Caching Configuration Basic Properties: Advanced Properties:
 db-cache-percent  default-cache-mode
 id2entry-cache-mode
 dn2id-cache-mode
 id2children-cache-mode
 id2subtree-cache-mode
 dn2uri-cache-mode
Priming Configuration Basic Properties: Advanced Properties:
 prime-method  prime-thread-count
 prime-time-limit
 prime-all-indexes
 system-index-to-prime
 system-index-to-prime-internal-nodes-only
 background-prime
Indexing Configuration Basic Properties: Advanced Properties:
 index-entry-limit  id2children-index-entry-limit
 composite-index-entry-limit  id2subtree-index-entry-limit
LDIF Import and Export Configuration Basic Properties: Advanced Properties:
 db-import-cache-percent  import-temp-directory
 import-thread-count
 export-thread-count
Transaction Configuration Basic Properties: Advanced Properties:
 None  db-txn-write-no-sync
 deadlock-retry-limit
 external-txn-default-backend-lock-behavior
 single-writer-lock-behavior
Other Configuration Basic Properties: Advanced Properties:
 None  subtree-delete-size-limit
 num-recent-changes
 offline-process-database-open-timeout

Basic Properties

backend-id (Read-Only)

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

description

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

enabled

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

base-dn

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

writability-mode

Property Group
General Configuration
Description
Specifies the behavior that the backend should use when processing write operations.
Default Value
None
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

db-directory

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.

hash-entries

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

db-cache-percent

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 JE 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

prime-method

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.

index-entry-limit

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.

composite-index-entry-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.

db-import-cache-percent

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


Advanced Properties

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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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 JE 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

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 JE 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


dsconfig Usage

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 delete an existing Backend:

dsconfig delete-backend
     --backend-name {name}