The parallel-update Command-Line Tool

Use multiple concurrent threads to apply a set of add, delete, modify, and modify DN operations read from an LDIF file.

As with other tools like ldapmodify, changes in the LDIF file to be processed should be ordered such that if there are any dependencies between changes (for example, if one add change record creates a parent entry and another add change record creates a child of that parent), prerequisite changes come before the changes that depend on them. When this tool is preparing to process a change, it will determine whether the new change depends on any other changes that are currently in progress, and if so, will delay processing that change until its dependencies have been satisfied. If a change does not depend on any other changes that are currently being processed, then it can be processed in parallel with those changes.

This tool will keep track of any changes that fail in a way that indicates they succeed if re-tried later (for example, an attempt to add an entry that fails because its parent does not exist, but its parent may be created later in the set of LDIF changes), and can optionally re-try those changes after processing is complete. Any changes that are not retried, as well as changes that still fail after the retry attempts, will be written to a rejects file with information about the reason for the failure so that an administrator can take any necessary further action upon them.

Usage

parallel-update {arguments}

LDAP Connection and Authentication Arguments

• -h {host} / --hostname {host} — The IP address or resolvable name to use to connect to the directory server. If this is not provided, then a default value of 'localhost' will be used.
  
  
• -p {port} / --port {port} — The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
  The specified value must not be less than 1 or greater than 65,535.
  
  
• -D {dn} / --bindDN {dn} — The DN to use to bind to the directory server when performing simple authentication.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• -w {password} / --bindPassword {password} — The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  
  
• -j {path} / --bindPasswordFile {path} — The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  The specified path must refer to a file that exists.
  
  
• --promptForBindPassword — Indicates that the tool should interactively prompt the user for the bind password.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -Z / --useSSL — Use SSL when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -q / --useStartTLS — Use StartTLS when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --defaultTrust — Use the JVM's default trust store, and optionally an additional trust store specified using the --trustStorePath argument, to non-interactively determine whether to trust any certificate chain presented during TLS negotiation. If the chain cannot be trusted based on any of those sources, then negotiation will fail without prompting about whether to trust it.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -X / --trustAll — Trust any certificate presented by the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -K {path} / --keyStorePath {path} — The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
  
  
• -W {password} / --keyStorePassword {password} — The password to use to access the key store contents.
  
  
• -u {path} / --keyStorePasswordFile {path} — The path to the file containing the password to use to access the key store contents.
  The specified path must refer to a file that may or may not exist.
  
  
• --promptForKeyStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the key store contents.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --keyStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
  
  
• -P {path} / --trustStorePath {path} — The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
  
  
• -T {password} / --trustStorePassword {password} — The password to use to access the trust store contents.
  
  
• -U {path} / --trustStorePasswordFile {path} — The path to the file containing the password to use to access the trust store contents.
  The specified path must refer to a file that may or may not exist.
  
  
• --promptForTrustStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the trust store contents.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --trustStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
  
  
• --verifyCertificateHostnames — Indicates that the tool should verify that the hostname or IP addressed used to establish connections ot the LDAP server matches an address for which the server's TLS certificate was issued.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -N {nickname} / --certNickname {nickname} — The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
  
  
• --enableSSLDebugging — Enable Java's low-level support for debugging SSL/TLS communication. This is equivalent to setting the 'javax.net.debug' property to 'all'.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -o {name=value} / --saslOption {name=value} — A name-value pair providing information to use when performing SASL authentication.
  
  
• --useSASLExternal — Use the SASL EXTERNAL mechanism to authenticate.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --helpSASL — Provide information about the supported SASL mechanisms, including the properties available for use with each.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Change Processing Arguments

• -l {path} / --ldifFile {path} — The path to the LDIF file containing the changes to process. This must be specified, and the file must exist.
  The specified path must refer to a file that exists.
  
  
• -c / --isCompressed — Indicates that the LDIF file is gzip-compressed. This argument is no longer required, as the tool will automatically detect whether the LDIF file is compressed or encrypted.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --encryptionPassphraseFile {path} — The path to a file containing the passphrase needed to decrypt the contents of the LDIF file. If this argument is not provided and the LDIF file is encrypted, then the tool may interactively prompt for the encryption passphrase. If this argument is provided, then the file must exist and it must contain exactly one line that is comprised only of the encryption passphrase.
  The specified path must refer to a file that exists.
  
  
• -R {path} / --rejectFile {path} — The path to a file that will be written with a record of all operations that could not be completed successfully, even after all retry attempts. This must be specified, and the file does not need to exist, but the parent directory must exist.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --useFirstRejectResultCodeAsExitCode — Indicates that the tool should use the result code for the first rejected operation (if any) as the exit code. By default, the tool will use an exit code of zero if all changes were attempted, even if some of those changes were rejected.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -r / --neverRetry — Indicates that the tool should never attempt to retry any failed operations.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -L {path} / --logFile {path} — The path to a log file that will be written with a record of all operations attempted during processing. If this is specified, then the file does not need to exist, but the parent directory must exist. If this is not specified, then no log file will be kept.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• -a / --defaultAdd — Indicates that any LDIF records without a changetype should be treated as add requests. If this is not provided, then LDIF records without a changetype will be rejected.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --followReferrals — Indicates that the tool should attempt to follow any referrals that the server returns. If this is not provided, then referral results will be treated as failures.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -t {value} / --numThreads {value} — The number of threads to use when processing operations in parallel. The value must be greater than or equal to one, with a value of one indicating that processing should be performed in a single thread (without any parallelism). If this is not specified, a default of eight threads will be used.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• -s {value} / --ratePerSecond {value} — The maximum rate (in number of requests per second) at which the tool should attempt to process requests. If this is specified, the value must be greater than or equal to one. If this is not specified, then no rate limiting will be performed.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  

Request Control Arguments

• -M / --usePermissiveModify — Include the permissive modify request control in all modify requests. This control indicates that the server should not reject attempts to add attribute values that already exist in the entry or attempts to remove attribute values that do not exist in the entry.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --ignoreNoUserModification — Include the proprietary ignore NO-USER-MODIFICATION request control in all add and modify requests. This control indicates that the server should not reject requests in which the client attempts to set values for attribute types declared with the NO-USER-MODIFICATION constraint in the schema. This control primarily applies to add operations, but the server can be configured to allow it for a limited set of attributes in modify operation.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -Y {authzID} / --proxyAs {authzID} — Include the proxied authorization request control (as described in RFC 4370, also known as the proxied authorization v2 request control) in all add, delete, modify, and modify DN requests. This control indicates that the operation should be processed under the authority of an alternate authorization identity. That authorization identity should generally be specified as either the string 'dn:' followed by the DN of the entry for the target user or 'u:' followed by the username for the target user.
  
  
• --proxyV1As {dn} — Include the proxied authorization v1 request control (as described in draft-weltman-ldapv3-proxy-04) in all add, delete, modify, and modify DN requests. This control indicates that the operation should be processed under the authority of an alternate authorization identity, specified as the DN of the entry for the target user.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• --passwordUpdateBehavior {name=value} — Include the proprietary password update behavior request control in all add and modify requests. This control may be used to customize the server's treatment of any passwords contained in the request. Values for this argument must be provided in the form 'name=value', where the property can be any of the following: is-self-change, allow-pre-encoded-password, skip-password-validation, ignore-password-history, ignore-minimum-password-age, password-storage-scheme, and must-change-password. The value for the password-storage-scheme property should be the name of the desired scheme, and the value for all other properties should be either 'true' or 'false'. This argument can be provided multiple times to specify multiple password update behaviors.
  
  
• --operationPurpose {purpose} — Include the proprietary operation purpose request control in all requests. This control provides a human-readable reason for the associated operation.
  
  
• --useManageDsaIT — Include the manageDsaIT request control in all add, delete, modify, and modify DN request. This control indicates that the server should treat referral entries as regular entries, and that the server should attempt to process that change directly against the referral entry rather generating a referral to indicate that the change should be sent to another server or to a different location in the same server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --nameWithEntryUUID — Include the UnboundID-proprietary name with entryUUID request control in all add requests sent to the server to indicate that the server should use the entryUUID operational attribute as the naming attribute for the resulting entry instead of the provided RDN.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --useSoftDelete — Include the proprietary soft delete request control in all delete requests. This control indicates that the server should hide the target entry for a period of time before actually removing it so that it may be restored with an undelete operation if the delete should be reverted.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --useHardDelete — Include the proprietary hard delete request control in all delete requests. This control indicates that the server should completely remove the target entry, even if it would have otherwise automatically processed the operation as a soft delete.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --allowUndelete — Include the proprietary undelete request control in all add requests that include the 'ds-undelete-from-dn' attribute. This control indicates that the server should un-delete the target soft-deleted entry rather than creating a new entry. The server must be configured to allow soft delete operations, and the requester must hav ethe soft-delete-read privilege.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --useAssuredReplication — Include the UnboundID-proprietary assured replication request control to indicate that the update response should be delayed until the change has been sufficiently replicated to other servers.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --assuredReplicationLocalLevel {none|received-any-server|processed-all-servers} — The replication assurance level that should be used for servers in the same location as the server that originally processed the change. The value must be one of 'none', 'received-any-server', or 'processed-all-servers'. If this is not provided, the server will determine an appropriate local assurance level.
  A provided value should be one of the following: 'received-any-server', 'processed-all-servers', 'none'.
  
  
• --assuredReplicationRemoteLevel {level} — The assurance level to request when replicating changes to other servers in a different location from the server that originally received the change. The value should be one of 'none', 'received-any-remote-location', 'received-all-remote-locations', or 'processed-all-remote-servers'. If this is not specified, then the server will determine an appropriate remote assurance level.
  A provided value should be one of the following: 'processed-all-remote-servers', 'none', 'received-any-remote-location', 'received-all-remote-locations'.
  
  
• --assuredReplicationTimeout {duration} — The timeout to use for assured replication processing. If provided, the value should be in the form of an integer followed by a time unit that is one of 'nanosecond', 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day', or 'week' (or one of their plurals or abbreviations). For example, values of '500 milliseconds', '500 ms', and '500ms' all specify a timeout of 500 milliseconds. If this is not specified, then the server will select an appropriate timeout.
  The provided value must contain an integer followed by a unit of 'ns' (for nanoseconds), 'us' (for microseconds), 'ms' (for milliseconds), 's' (for seconds), 'm' (for minutes), 'h' (for hours), 'd' (for days), or 'w' (for weeks). The specified duration must not be less than 0ns or greater than 9223372036854775807ns.
  
  
• --replicationRepair — Include the proprietary replication repair request control in all add, delete, modify, and modify DN requests. This control indicates that the requested operation should only be processed in the server instance that originally received the change, and it should not be replicated to other servers in the topology. This should generally only be used under the direction of support personnel.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressOperationalAttributeUpdates {attr} — Include the proprietary suppress operational attribute update request control in all add, bind, delete, modify, and modify DN requests. This control indicates that the server should not update the specified operational attribute in the course of processing the operation. The value may be one of 'last-access-time', 'last-login-time', 'last-login-ip', or 'lastmod'. This argument may be provided multiple times to suppress updates to multiple operational attributes.
  A provided value should be one of the following: 'last-access-time', 'last-login-ip', 'last-login-time', 'lastmod'.
  
  
• --suppressReferentialIntegrityUpdates — Include the proprietary suppress referential integrity updates request control in all delete and modify DN requests. This control indicates that the server should not perform any referential integrity processing for the associated operation.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --addControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the specified control in all add requests.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• --bindControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the specified control in all bind requests.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• --deleteControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the specified control in all delete requests.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• --modifyControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the specified control in all modify requests.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• --modifyDNControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the specified control in all modify DN requests.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  

Additional Arguments

• --interactive — Launch the tool in interactive mode.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -H / --help — Display usage information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -V / --version — Display version information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --propertiesFilePath {path} — The path to a properties file used to specify default values for arguments not supplied on the command line.
  The specified path must refer to a file that exists.
  
  
• --generatePropertiesFile {path} — Write an empty properties file that may be used to specify default values for arguments.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --noPropertiesFile — Do not obtain any argument values from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressPropertiesFileComment — Suppress output listing the arguments obtained from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Dependent Argument Sets

• If the --keyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --keyStorePasswordFile argument is provided, then the --keyStorePath argument must also be provided.
• If the --promptForKeyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --trustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --trustStorePasswordFile argument is provided, then the --trustStorePath argument must also be provided.
• If the --promptForTrustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --keyStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --defaultTrust argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustAll argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --bindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --bindPasswordFile argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --promptForBindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --assuredReplicationLocalLevel argument is provided, then the --useAssuredReplication argument must also be provided.
• If the --assuredReplicationRemoteLevel argument is provided, then the --useAssuredReplication argument must also be provided.
• If the --assuredReplicationTimeout argument is provided, then the --useAssuredReplication argument must also be provided.

Exclusive Argument Sets

• The following arguments cannot be used together: --useSSL, --useStartTLS
• The following arguments cannot be used together: --keyStorePassword, --keyStorePasswordFile, --promptForKeyStorePassword
• The following arguments cannot be used together: --trustStorePassword, --trustStorePasswordFile, --promptForTrustStorePassword
• The following arguments cannot be used together: --defaultTrust, --trustAll
• The following arguments cannot be used together: --trustAll, --trustStorePath
• The following arguments cannot be used together: --bindDN, --saslOption, --useSASLExternal
• The following arguments cannot be used together: --bindPassword, --bindPasswordFile, --promptForBindPassword
• The following arguments cannot be used together: --followReferrals, --useManageDsaIT
• The following arguments cannot be used together: --proxyAs, --proxyV1As
• The following arguments cannot be used together: --useSoftDelete, --useHardDelete
• The following arguments cannot be used together: --useAssuredReplication, --replicationRepair
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

Examples

• Uses ten concurrent threads to apply the changes read from the changes.ldif file against the LDAP server at server.example.com:636 over a TLS-encrypted connection. Any rejected changes will be written to the rejects.ldif file, and processing will be limited to a rate of 5000 attempts per second.

    parallel-update --hostname server.example.com --port 636 --useSSL \
         --bindDN uid=admin,dc=example,dc=com --promptForBindPassword \
         --ldifFile changes.ldif --rejectFile rejects.ldif --defaultAdd \
         --numThreads 10 --ratePerSecond 5000