The Changelog Backend provides an Identity Data Store backend implementation that exposes an LDAP change log.
This backend may be used to discover recent changes that have been made to entries in this server. The change log conforms to the Changelog Internet draft specification. Some implementations of this specification are known as Retro Change Logs.
↓Parent Component
↓Properties
↓dsconfig Usage
The Changelog Backend component inherits from the Backend
The properties supported by this managed object are as follows:
| 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 | 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 |
| 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 |
| 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 |
| 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 UnboundID support to discuss this configuration |
set-degraded-alert-when-disabled
| Description | Determines whether the Identity Data Store 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
| 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 |
| 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 Identity Data Store 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 | Unknown |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Identity Data Store must be restarted for changes to this setting to take effect. Modification requires that the Identity Data Store be stopped, the database directory manually relocated, and then the Identity Data Store restarted. While the Identity Data Store 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. |
| Description | Specifies the period of time after which changelog entries are deleted automatically. |
| Default Value | None |
| Allowed Values | A duration. Lower limit is 1 milliseconds. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the percentage of JVM memory to allocate to the changelog database cache. Specifies the percentage of memory available to the JVM that should be used for caching changelog database contents. |
| Default Value | 1 |
| Allowed Values | An integer value. Lower limit is 1. Upper limit is 90 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies which attribute types will be included in a changelog entry for ADD and MODIFY operations. This restricts the set of attributes whose changes are recorded in the 'changes' attribute of changelog entries. By default all attribute types are included in the changes for ADD and MODIFY operations, but if this property is specified, then only attributes in this list will be included. If no attributes in this list are included in an operation, then no changelog entry will be created. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute to include in the changes. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies a set of attribute types that should be excluded in a changelog entry for ADD and MODIFY operations. This restricts the set of attributes whose changes are recorded in the 'changes' attribute of changelog entries. By default all attribute types are included in changelog entries for ADD and MODIFY operations, but if this property is specified, then all attributes except the ones in this list will be included. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute to exclude from the changes. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-deleted-entry-include-attribute
| Description | Specifies a set of attribute types that should be included in a changelog entry for DELETE operations. Attributes specified in this list will be recorded in the 'deletedEntryAttrs' attribute on the changelog entry when an entry is deleted. This attribute is not present by default. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute to include in the changes. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-deleted-entry-exclude-attribute
| Description | Specifies a set of attribute types that should be excluded from a changelog entry for DELETE operations. This restricts the set of attributes whose changes are recorded in the changelog on DELETE operation. Attributes specified in this list will be excluded from the 'deletedEntryAttrs' attribute on changelog entries. By default all attribute types are included in 'deletedEntryAttrs' for DELETE operations if 'use-reversible-form' is set to true. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute to exclude from the changes. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies whether values of creatorsName, ds-create-time, modifiersName and ds-update-time attributes will be written to changelog entries. Note: a virtual attribute provider can generate createTimestamp and modifyTimestamp values for returned changelog entries only if the ds-create-time and ds-update-time values were included when the entry was written. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies whether the changelog should provide enough information to be able to revert the changes if desired. If this property is set to true, the changelog entries are affected as follows: Each changelog entry of type 'DELETE' will include the contents of the deleted entry in 'deletedEntryAttrs'. For changelog entries of type 'MODIFY', the changes will only contain DELETE of the previous values and ADD of the new values (avoiding the use of REPLACE values and omitting those values that didn't change). Note that using this setting alone will not provide you with any previous values of an attribute that did not change. To capture these values, you can use the 'changelog-max-before-after-values' property. Furthermore, virtual attributes are not included in the reversible form of the changes; these values can be obtained from the before and after values if you have configured the 'include-virtual-attributes' property to include virtual attributes in the before and after values that are stored. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
apply-access-controls-to-changelog-entry-contents
| Description | Indicates whether the contents of changelog entries should be subject to access control and sensitive attribute evaluation such that the contents of attributes like changes, deletedEntryAttrs, ds-changelog-entry-key-attr-values, ds-changelog-before-values, and ds-changelog-after-values may be altered based on attributes the user can see in the target entry. If this feature is enabled and the user does not have permission to read an entry at all, or if that user does not have permission to see any attributes that were targeted by the change, then the associated changelog entries pertaining to those operations may be suppressed. If a user does not have permission to see certain attributes within the target entry, then references to those attributes in the changelog entry will be suppressed. Regardless of the value for this option, the requester must still have access control permission to read changelog entries in order to retrieve them in any form. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
report-excluded-changelog-attributes
| Description | Indicates whether changelog entries that have been altered by applying access controls should include additional information about any attributes that may have been removed. Access controls are applied when changelog entries are accessed through standard LDAP searches and apply-access-controls-to-changelog-entry-contents is set to true, or when they are accessed with the Get Changelog Batch extended operation with pareEntriesForUserDN set. |
| Default Value | none |
| Allowed Values | none - Indicates that changelog entries should not include any information about attributes that have been removed. attribute-counts - Indicates that changelog entries should include the number of user and/or operational attributes that have been removed. If any user attribute information was excluded from a changelog entry, then the number of the excluded user attributes will be reported in the ds-changelog-num-excluded-user-attributes attribute of the changelog entry. If any operational attribute information was excluded from a changelog entry, then the number of the excluded operational attributes will be reported in the ds-changelog-num-excluded-operational-attributes attribute of the changelog entry. Both the ds-changelog-num-excluded-user-attributes and ds-changelog-num-excluded-operational-attributes attributes are operational and must be explicitly requested by clients (or all operational attributes requested via "+") in order to be returned. attribute-names - Indicates that changelog entries should include the names of user and/or operational attributes that have been removed. If any user attribute information was excluded from a changelog entry, then the names of the excluded user attributes will be reported in the ds-changelog-excluded-user-attribute attribute of the changelog entry. If any operational attribute information was excluded from a changelog entry, then the names of the excluded operational attributes will be reported in the ds-changelog-excluded-operational-attribute attribute of the changelog entry. Both the ds-changelog-excluded-user-attribute and ds-changelog-excluded-operational-attribute attributes are operational and must be explicitly requested by clients (or all operational attributes requested via "+") in order to be returned. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
db-directory-permissions (Advanced Property)
| Description | Specifies the permissions that should be applied to the directory containing the backend database files and to directories and files created during backup 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 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 |
changelog-include-key-attribute (Advanced Property)
| Description | Specifies which attribute types will be included in a changelog entry on every change. This property will cause the current (after-change) value of the specified attributes to be recorded in the 'ds-changelog-entry-key-attr-values' attribute on the changelog entry. This applies for all change types. On a DELETE operation, the values are from the entry before it was deleted. The key values will be recorded on every change and are not restricted by the settings configured in 'changelog-include-attribute', 'changelog-exclude-attribute', 'changelog-deleted-entry-include-attribute', or 'changelog-deleted-entry-exclude-attribute'. Virtual attributes will be included in a separate attribute called 'ds-changelog-entry-key-virtual-values' if and only if the include-virtual-attributes property is configured correctly to include virtual attributes in the "key" attributes that are stored. |
| Default Value | There are no key attributes to include. |
| Allowed Values | The name or OID of an attribute type defined in the server schema. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
index-include-attribute (Advanced Property)
| Description | Specifies which attribute types are to be specifically included in the set of attribute indexes maintained on the changelog. If this property does not have any values then no attribute types are indexed. Attribute indexes allow efficient processing of Get-Changelog-Batch requests that require filtering of the results to only include changes involving specific attributes. Attribute Indexes are maintained for the set of attributes that meet the index-include-attribute and index-exclude-attribute rules. When there is an addition to the set of indexed attributes, existing changelog entries will not be indexed for the new attributes; only subsequent changelog entries will be indexed. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. In the event of a conflict between index-include-attribute and index-exclude-attribute, the index-exclude-attribute takes precedence. |
| Default Value | No attribute indexes are maintained. |
| Allowed Values | The name or OID of an attribute to be included, or "*" or "+". |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
index-exclude-attribute (Advanced Property)
| Description | Specifies which attribute types are to be specifically excluded from the set of attribute indexes maintained on the changelog. This property is useful when the index-include-attribute property contains one of the special values "*" and "+". Attribute indexes allow efficient processing of Get-Changelog-Batch requests that require filtering of the results to only include changes involving specific attributes. Attribute Indexes are maintained for the set of attributes that meet the index-include-attribute and index-exclude-attribute rules. When there is an addition to the set of indexed attributes, existing changelog entries will not be indexed for the new attributes; only subsequent changelog entries will be indexed. The special values "*" and "+" can be used to specify all user attributes or all operational attributes, respectively. In the event of a conflict between index-include-attribute and index-exclude-attribute, the index-exclude-attribute takes precedence. |
| Default Value | There are no index exclude attributes. |
| Allowed Values | The name or OID of an attribute to be excluded, or "*" or "+". |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-max-before-after-values (Advanced Property)
| Description | This controls whether all attribute values for a modified attribute (even those values that have not changed) will be included in the changelog entry. If the number of attribute values does not exceed this limit, then all values for the modified attribute will be included in the changelog entry. Setting this property to a non-zero value will cause all of the old values and all of the new values (up to the specified maximum) for each changed attribute to be stored in the changelog entry. Note that this can be expensive for attributes with hundreds or thousands of values, such as a group entry; the number of values that are stored per attribute is capped by the value of this property. The values will be stored in the 'ds-changelog-before-values' and 'ds-changelog-after-values' attributes on the changelog entry. These attributes are not present by default. If any attributes have more than the maximum number of values, their names and number of before/after values will be stored in the 'ds-changelog-attr-exceeded-max-values-count' or 'ds-changelog-virtual-attr-exceeded-max-values-count' attribute on the changelog entry. These are multi-valued attributes whose format is "attr=attributeName,beforeCount=100,afterCount=101", where "attributeName" is the name of the attribute and the "beforeCount" and "afterCount" are the total number of values for that attribute before and after the change, respectively. In either case (before or after the change) if the number of values is exceeding the maximum, then those values will not be stored. Virtual attributes will be included in separate attributes called 'ds-changelog-before-virtual-values', and 'ds-changelog-after-virtual-values' if and only if the include-virtual-attributes property is configured correctly to include virtual attributes in the before and after values that are stored. Note that the maximum is enforced independently for real and virtual attributes; a changelog entry can store up to n real values and n virtual values, where n is the value of this property. |
| Default Value | 0 |
| Allowed Values | An integer value. Lower limit is 0. A value of "-1" or "unlimited" for no limit. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-write-batch-size (Advanced Property)
| Description | Specifies the number of changelog entries written in a single database transaction. |
| Default Value | 100 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-purge-batch-size (Advanced Property)
| Description | Specifies the number of changelog entries purged in a single database transaction. |
| Default Value | 1000 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
changelog-write-queue-capacity (Advanced Property)
| Description | Specifies the capacity of the changelog write queue in number of changes. |
| Default Value | 100 |
| Allowed Values | An integer value. Lower limit is 1. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Changelog Backend must be disabled and re-enabled for changes to this setting to take effect. This modification requires that you disable and then re-enable this component for the change to take effect |
include-virtual-attributes (Advanced Property)
| Description | Specifies the changelog entry elements (if any) in which virtual attributes should be included. |
| Default Value | Virtual attributes will not appear in any element of changelog entries. |
| Allowed Values | add-attributes - Indicates that virtual attributes should be included in the set of attributes listed for an add operation. deleted-entry-attributes - Indicates that virtual attributes should be included in the set of deleted entry attributes listed for a delete operation. before-and-after-values - Indicates that virtual attributes should be included in the set of before and after values for attributes targeted by the changes. key-attribute-values - Indicates that virtual attributes should be included in the set of entry key attribute values. |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
je-property (Advanced Property)
| Description | Specifies the database and environment properties for the Berkeley DB Java Edition database for this changelog backend. Any Berkeley DB Java Edition property can be specified using the following form: property-name=property-value. Refer to the Identity Data Store 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 | Changes to this configuration property will only take effect if the Identity Data Store is restarted. |
soft-delete-entry-included-operation (Advanced Property)
| Description | Specifies which operations performed on soft-deleted entries will appear in the changelog. This property pertains only to delete and modify operations on existing soft-deleted entries. Logging of soft delete operations and undelete operations are not affected by this property. Soft delete operations are logged like delete operations but with additional information in the changelog entry about the soft-deleted entry that was created. Undelete operations are logged like add operations but with additional information in the changelog entry about the soft-deleted entry that was undeleted. |
| Default Value | Updates to soft-deleted entries are not included in the changelog by default. |
| Allowed Values | modify - Modification of soft deleted entries will be included in the changelog. delete - Permanent deletion of soft deleted entries will be included in the changelog. |
| Multi-Valued | Yes |
| 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 Changelog Backend:
dsconfig create-backend
--backend-name {name}
--type changelog
--set enabled:{propertyValue}
--set base-dn:{propertyValue}
--set changelog-maximum-age:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Backend:
dsconfig delete-backend
--backend-name {name}