Extracts changes matching a given set of criteria from a Directory Server audit log so that they may be replayed (for example, as part of a disaster recovery process) or reverted (for example, to back out changes made in error).
This tool is designed to be used in conjunction with the server's data recovery log files (in the logs/data-recovery directory). It may be used in conjunction with other audit log files, but for best results, the logger should be configured to operate in reversible form, to include the requester DN and IP address, and to include information about any intermediate client control that may have been provided in the request.
This tool must not be used with a log file that the server may update while the tool is running, or that may have some content stored in an unwritten buffer (which is especially likely if the log is compressed or encrypted). To use this tool with the server online, you should only specify a log file that has already been rotated to ensure that no more writes will be made to that file. If necessary, you may use the rotate-log tool to force the current active file to be rotated.
To use this tool to revert an inappropriate set of changes, run it with '--direction revert' and an additional set of arguments that identify which changes should be reverted (for example, based on the address of the client, the authorization DN of the requester, the time frame in which the changes were applied, etc.).
To use this tool to replay changes that were previously applied (for example, after restoring an old backup or importing an old LDIF file), run it with '--direction replay' and an appropriate set of arguments to select the desired set of changes. Also, make sure to use 'dsreplication pre-external-initialization' before performing the restore or import and applying the changes, and then use 'dsreplication post-external-initialization' after the changes have been applied. See the Directory Server Administration Guide for additional information.
This tool will extract changes from the selected log file (and any previously rotated files, unless the --doNotFollowRotationChain argument is provided) and output them in LDIF change format. If the --outputFile argument is provided, then the changes will be written to that file; otherwise, they will be written to standard output. If changes are to be written to a file, then the output will be compressed if the input files were compressed (unless the --doNotCompressOutput argument was provided), and the output will be encrypted if the input files were encrypted (unless --doNotEncryptOutput was provided). You may wish to first run the tool without specifying an output file so that you can verify that the selected change are correct. Once you are certain that the appropriate changes have been selected, then you can use a tool like ldapmodify or parallel-update to apply those changes to the server.
Extract all add and modify change records for operations processed at or after midnight on January 1, 2018 (in the local time zone) from the default data recovery log file (and any older log files that are available) and write the extracted changes for forward replay to 'extracted-changes.ldif':
extract-data-recovery-log-changes --direction replay --startTime 20180101000000 \
--changeType add --changeType modify --outputFile extracted-changes.ldif
Extract all change records for operations authorized by user 'cn=Bad Client,ou=Applications,dc=example,dc=com' using IP address '1.2.3.4' from the specified data recovery log file (and all relevant earlier log files) and write the extracted changes for reversion to file 'revert-changes.ldif'. Any failures encountered will be written to 'extract-failures.log':
extract-data-recovery-log-changes \
--auditLogFile logs/data-recovery/data-recovery.20180102030405Z.gz.encrypted \
--direction revert \
--includeAuthorizationDN "cn=Bad Client,ou=Applications,dc=example,dc=com" \
--includeAddressMask 1.2.3.4 --outputFile extracted-changes.ldif \
--failureLogFile extract-failures.log
-V
--version
| Description | Display Directory Server version information |
-H
--help
| Description | Display general usage information |
--help-debug
| Description | Display help for using debug options |
| Advanced | Yes |
--auditLogFile {path}
| Description | The path to the audit log file containing the changes to extract. If changes are to be read from a chain of log files, this should be the most recent log file in the chain. If this is not specified, the server's default data recovery log will be used. Note that the default file can only be used if the server is offline to ensure that it is not actively being written (which may interfere with the ability to parse it, especially if it is compressed or encrypted). To run against the most recent data with the server running, use the rotate-log tool to force the active file to be rotated closed and rotated out of service |
| Required | No |
| Multi-Valued | No |
--auditLogEncryptionPassphraseFile {path}
| Description | The path to a file containing the passphrase used to encrypt the audit log file. If this is not provided and the audit log file is encrypted, the server will attempt to obtain the appropriate passphrase from the encryption settings database, or it will interactively prompt for the passphrase if it cannot be automatically determined |
| Required | No |
| Multi-Valued | No |
--doNotFollowRotationChain
| Description | Indicates that the tool should only examine the specified audit log file without looking through any older files that may be available. If this is not provided, then the tool will attempt to look for applicable changes in earlier files |
--outputFile {path}
| Description | The path to the output file to which extracted changes will be written. If this is not provided, then extracted changes will be written to standard output |
| Required | No |
| Multi-Valued | No |
--outputFileEncryptionPassphraseFile {path}
| Description | The path to a file containing the passphrase used to encrypt the audit log file. If this is not provided and the audit log file is encrypted, the server will attempt to obtain the appropriate passphrase from the encryption settings database, or it will interactively prompt for the passphrase if it cannot be automatically determined |
| Required | No |
| Multi-Valued | No |
--doNotCompressOutput
| Description | Indicates that the output file should not be compressed. By default, the output file will be compressed if the audit log file was compressed |
--doNotEncryptOutput
| Description | Indicates that the output file should not be encrypted. By default, the output file will be encrypted if the audit log file was encrypted |
--failureLogFile {path}
| Description | The path to a file to which any failures (for example, unparsable audit log messages or changes that cannot be reverted) will be written. If this is not provided, then failure messages will be written to standard error |
| Required | No |
| Multi-Valued | No |
--direction {replay|revert}
| Description | The direction in which extracted changes will be applied. The value may be either 'replay' (to indicate that changes should be replayed in the same manner as they were originally processed, which is suitable for recovery from an older backup) or 'revert' (to indicate that the changes should be reversed, which is suitable for undoing changes that had previously been processed) |
| Required | Yes |
| Multi-Valued | No |
--changeType {add|delete|modify|modify-dn}
| Description | The operation change types for changes to extract. Allowed values include 'add', 'delete', 'modify', and 'modify-dn'. This argument may be provided multiple times to indicate that multiple change types should be extracted. If this argument is omitted, then all types of changes will be eligible |
| Required | No |
| Multi-Valued | Yes |
--excludeSubtreeDeletes
| Description | Indicates that subtree delete operations should be excluded from the set of changes to extract. By default, subtree delete operations will be included |
--excludeSoftDeletes
| Description | Indicates that soft delete operations should be excluded from the set of changes to extract. By default, soft delete operations will be included |
--excludeUndeletes
| Description | Indicates that undelete operations should be excluded from the set of changes to extract. By default, undelete operations will be included |
--excludeDeletesOfSoftDeletedEntries
| Description | Indicates that deletes of soft-deleted entries should be excluded from the set of changes to extract. By default, deletes of soft-deleted entries will be included |
--excludeModifiesOfSoftDeletedEntries
| Description | Indicates that deletes of soft-deleted entries should be excluded from the set of changes to extract. By default, deletes of soft-deleted entries will be included |
--startTime {timestamp}
| Description | A timestamp that indicates the oldest start time for changes that should be extracted. The timestamp should be provided in the YYYYMMDDhhmmss.uuu format to select changes in the JVM's default time zone, or in any valid generalized time format to specify a time in an alternate time zone. If this is not provided, then changes will not be excluded for being too old |
| Required | No |
| Multi-Valued | No |
--endTime {timestamp}
| Description | A timestamp that indicates the most recent start time for changes that should be extracted. The timestamp should be provided in the YYYYMMDDhhmmss.uuu format to select changes in the JVM's default time zone, or in any valid generalized time format to specify a time in an alternate time zone. If this is not provided, then changes will not be excluded for being too recent |
| Required | No |
| Multi-Valued | No |
--includeAddressMask {address-mask}
| Description | An address mask that identifies the requester addresses for changes to include in the extract. Address masks may be specified as a single IPv4 or IPv6 address, an IPv4 address range using CIDR notation (e.g., '192.168.1.0/24'), an IPv4 address range using a subnet mask (e.g., '192.168.1.0/255.255.255.0'), a range of IPv4 addresses using asterisks as wildcards in any of the octets (e.g., '192.168.1.*'), a fully-qualified DNS hostname (e.g., 'ldap.example.com'), or a named subdomain using an asterisk as a wildcard (e.g., '*.example.com'). This argument may be provided multiple times to specify multiple include address masks. If any include address masks are specified, then only changes requested by a client matching at least one of these masks will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeAddressMask {address-mask}
| Description | An address mask that identifies the requester addresses for changes to exclude from the extract. Address masks may be specified as a single IPv4 or IPv6 address, an IPv4 address range using CIDR notation (e.g., '192.168.1.0/24'), an IPv4 address range using a subnet mask (e.g., '192.168.1.0/255.255.255.0'), a range of IPv4 addresses using asterisks as wildcards in any of the octets (e.g., '192.168.1.*'), a fully-qualified DNS hostname (e.g., 'ldap.example.com'), or a named subdomain using an asterisk as a wildcard (e.g., '*.example.com'). This argument may be provided multiple times to specify multiple exclude address masks. If any exclude address masks are specified, then no changes requested by a client matching at least one of these masks will be included |
| Required | No |
| Multi-Valued | Yes |
--ignoreDownstreamAddresses
| Description | Indicates that the tool should only consider the address of the immediate client from which the change was received. By default, the tool will also look at any available information about downstream clients (for example, as provided in an intermediate client request control or in replication metadata) to identify the address of the client that actually requested the operation |
--includeConnectionID {connection-id}
| Description | A numeric connection ID for a client connection whose changes should be included in the extract. Note that this only targets the connection ID for clients that are directly connected to the Directory Server; use the --includeDownstreamConnectionID argument to target downstream connection IDs. This argument may be provided multiple times to specify multiple include connection IDs. If any include connection IDs are specified, then only changes made by clients on those connection IDs will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeConnectionID {connection-id}
| Description | A numeric connection ID for a client connection whose changes should be excluded from the extract. Note that this only targets the connection ID for clients that are directly connected to the Directory Server; use the --excludeDownstreamConnectionID argument to target downstream connection IDs. This argument may be provided multiple times to specify multiple exclude connection IDs. If any exclude connection IDs are specified, then no changes made by clients on those connection IDs will be included |
| Required | No |
| Multi-Valued | Yes |
--includeDownstreamConnectionID {connection-id}
| Description | A numeric connection ID for a downstream client connection (for example, as provided in an intermediate client request control) whose changes should be included in the extract. This argument may be provided multiple times to specify multiple include downstream connection IDs. If any include downstream connection IDs are specified, then only changes made by clients on those downstream connection IDs will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeDownstreamConnectionID {connection-id}
| Description | A numeric connection ID for a downstream client connection (for example, as provided in an intermediate client request control) whose changes should be excluded from the extract. This argument may be provided multiple times to specify multiple exclude downstream connection IDs. If any exclude downstream connection IDs are specified, then only changes made by clients on those downstream connection IDs will be excluded |
| Required | No |
| Multi-Valued | Yes |
--includeAuthenticationDN {dn}
| Description | The authentication DN (that is, the bind DN) for a requester whose changes should be included in the extract. Note that this applies only to the authentication DN of the directly connected client, and in many cases the authorization DN (which reflects the identify of the user under whose authority the operation was processed) is more appropriate. This argument may be provided multiple times to specify multiple include authentication DNs. If any include authentication DNs are specified, then only changes made on connections with that authentication DN will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeAuthenticationDN {dn}
| Description | The authentication DN (that is, the bind DN) for a requester whose changes should be excluded from the extract. Note that this applies only to the authentication DN of the directly connected client, and in many cases the authorization DN (which reflects the identify of the user under whose authority the operation was processed) is more appropriate. This argument may be provided multiple times to specify multiple exclude authentication DNs. If any exclude authentication DNs are specified, then no changes made on connections with that authentication DN will be included |
| Required | No |
| Multi-Valued | Yes |
--includeAuthorizationDN {dn}
| Description | The authorization DN for a requester whose changes should be included in the extract. By default, the authorization DN for an operation will be the same as the authentication DN, but it may be different if the request includes a proxied authorization or intermediate client request control, or if the request is received over a connection authenticated with a SASL bind that specified an alternate authorization identity. This argument may be provided multiple times to specify multiple include authorization DNs. If any include authorization DNs are specified, then only changes made by operations with that authorization DN will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeAuthorizationDN {dn}
| Description | The authorization DN for a requester whose changes should be excluded from the extract. By default, the authorization DN for an operation will be the same as the authentication DN, but it may be different if the request includes a proxied authorization or intermediate client request control, or if the request is received over a connection authenticated with a SASL bind that specified an alternate authorization identity. This argument may be provided multiple times to specify multiple exclude authorization DNs. If any exclude authorization DNs are specified, then no changes made by operations with that authorization DN will be included |
| Required | No |
| Multi-Valued | Yes |
--includeChangesWithOrigin {origin}
| Description | Indicates that only changes with the specified origin value should be included in the extract. This argument may be provided multiple times to indicate that multiple origin values should be included |
| Required | No |
| Multi-Valued | Yes |
--excludeChangesWithOrigin {origin}
| Description | Indicates that any changes with the specified origin value should be excluded from the extract. This argument may be provided multiple times to indicate that multiple origin values should be excluded |
| Required | No |
| Multi-Valued | Yes |
--includeChangesWithAnyOrigin
| Description | Indicates that only changes that include an origin value (regardless of what that value is) should be included in the extract |
--excludeChangesWithAnyOrigin
| Description | Indicates that any changes that include an origin value (regardless of what that value is) should be excluded from the extract |
--includeTargetEntryBaseDN {dn}
| Description | The base DN for a portion of the DIT whose changes should be included in the extract. This argument may be provided multiple times to specify multiple include base DNs. If any include base DNs are specified, then only changes targeting entries at or below one of those base DNs will be included |
| Required | No |
| Multi-Valued | Yes |
--excludeTargetEntryBaseDN {dn}
| Description | The base DN for a portion of the DIT whose changes should be excluded from the extract. This argument may be provided multiple times to specify multiple exclude base DNs. If any exclude base DNs are specified, then no changes targeting entries at or below one of those base DNs will be included |
| Required | No |
| Multi-Valued | Yes |
--includeChangesFromPrivateBackends
| Description | Indicates that changes targeting entries in private backends (server backends containing entries generated by the server or intended for administration purposes rather than user-supplied data) should be included in the extract. By default, changes targeting entries in private backends will not be included |
--includeAddOperationsMatchingFilter {filter}
| Description | A search filter that may be used to identify add operations to include in the extract. This may be provided multiple times to specify multiple include filters. If any include add operation filters are specified, then add operations for entries that do not match at least one of those filters will be excluded from the extract |
| Required | No |
| Multi-Valued | No |
--excludeAddOperationsMatchingFilter {filter}
| Description | A search filter that may be used to identify add operations to exclude from the extract. This may be provided multiple times to specify multiple exclude filters. If any exclude add operation filters are specified, then add operations for entries that match at least one of those filters will be excluded from the extract |
| Required | No |
| Multi-Valued | No |
--includeDeleteOperationsMatchingFilter {filter}
| Description | A search filter that may be used to identify delete operations to include in the extract. This may be provided multiple times to specify multiple include filters. If any include delete operation filters are specified, then delete operations for entries that do not match at least one of those filters, including delete operations that are not logged in reversible form and for which the entry is not available, will be excluded from the extract |
| Required | No |
| Multi-Valued | No |
--excludeDeleteOperationsMatchingFilter {filter}
| Description | A search filter that may be used to identify delete operations to exclude from the extract. This may be provided multiple times to specify multiple exclude filters. If any exclude delete operation filters are specified, then delete operations for entries that match at least one of those filters, as well as delete operations not logged in reversible form and for which the entry is not available, will be excluded from the extract |
| Required | No |
| Multi-Valued | No |
--includeModifyOperationsTargetingAttribute {attribute}
| Description | The name or OID of an attribute type that must be altered by a modify operation for that modify operation to be included in the extract. This may be provided multiple times to specify multiple include attribute types |
| Required | No |
| Multi-Valued | Yes |
--excludeModifyOperationsTargetingAttribute {attribute}
| Description | The name or OID of an attribute type that must be altered by a modify operation for that modify operation to be excluded from the extract. This may be provided multiple times to specify multiple exclude attribute types |
| Required | No |
| Multi-Valued | Yes |
--includeOnlyAttributeInAdd {attribute}
| Description | The name or OID of an attribute type that should be included in add operations included in the extract, regardless of whether the add is the replay of an earlier add or the revert of a delete. This may be provided multiple times to specify multiple include attributes. If any include attributes are specified, then only those attributes will be included in extracted add operations |
| Required | No |
| Multi-Valued | Yes |
--excludeAttributeFromAdd {attribute}
| Description | The name or OID of an attribute type that should be excluded from add operations included in the extract, regardless of whether the add is the replay of an earlier add or the revert of a delete. This may be provided multiple times to specify multiple exclude attributes |
| Required | No |
| Multi-Valued | Yes |
--includeOnlyModificationsToAttribute {attribute}
| Description | The name or OID of an attribute type that must be altered by a modify operation for that modify operation to be included in the extract. This may be provided multiple times to specify multiple include attribute types |
| Required | No |
| Multi-Valued | Yes |
--excludeModificationsToAttribute {attribute}
| Description | The name or OID of an attribute type that must be altered by a modify operation for that modify operation to be excluded from the extract. This may be provided multiple times to specify multiple exclude attribute types |
| Required | No |
| Multi-Valued | Yes |
--suppressOperationalAttributesFromAdd {all|none|no-user-modification}
| Description | The behavior that the tool should use when determining which operational attributes to include in add operations in the extract. The value of this argument must be one of 'all' (to indicate that all operational attributes should be suppressed), 'none' (to indicate that no operational attributes should be suppressed), or 'no-user-modification' (to indicate that operational attributes declared with the NO-USER-MODIFICATION constraint will be suppressed but others will be included). If this argument is not provided, then a default value of 'no-user-modification' will be assumed. This argument is only applicable if the --includeOnlyAttributeInAdd argument is not provided, because if that argument is present, then only the attributes named in it will be included (and any attributes listed there will be included even if they would have otherwise been excluded by this setting) |
| Required | No |
| Multi-Valued | No |
--suppressOperationalAttributesFromModify {all|none|no-user-modification}
| Description | The behavior that the tool should use when determining which operational attributes to include in modify operations in the extract. The value of this argument must be one of 'all' (to indicate that all operational attributes should be suppressed), 'none' (to indicate that no operational attributes should be suppressed), or 'no-user-modification' (to indicate that operational attributes declared with the NO-USER-MODIFICATION constraint will be suppressed but others will be included). If this argument is not provided, then a default value of 'no-user-modification' will be assumed. This argument is only applicable if the --includeOnlyModificationsToAttribute argument is not provided, because if that argument is present, then only the attributes named in it will be included (and any attributes listed there will be included even if they would have otherwise been excluded by this setting) |
| Required | No |
| Multi-Valued | No |
--suppressRequestControl {control-name}
| Description | Indicates that the specified request control should be omitted from changes written to the output. Allowed values include 'ignore-no-user-modification', 'manage-dsa-it', 'password-update-behavior', 'permissive-modify', and 'subtree-delete'. This argument may be provided multiple times to indicate that multiple types of controls should be suppressed |
| Required | No |
| Multi-Valued | Yes |
--interactive
| Description | Launch the tool in interactive mode. |
--propertiesFilePath {path}
| Description | The path to a properties file used to specify default values for arguments not supplied on the command line. |
| Required | No |
| Multi-Valued | No |
--generatePropertiesFile {path}
| Description | Write an empty properties file that may be used to specify default values for arguments. |
| Required | No |
| Multi-Valued | No |
--noPropertiesFile
| Description | Do not obtain any argument values from a properties file. |
--suppressPropertiesFileComment
| Description | Suppress output listing the arguments obtained from a properties file. |