PingDirectory

Working with the parallel-update tool

The PingDirectory server provides a parallel-update tool, which reads change information (add, delete, modify, and modify DN) from an LDIF file and applies the changes in parallel.

This tool is a multi-threaded version of the ldapmodify tool that is designed to process a large number of changes as quickly as possible.

The parallel-update tool provides logic to prevent conflicts resulting from concurrent operations targeting the same entry or concurrent operations involving hierarchically-dependent entries, such as modifying an entry after it has been added or adding a child after its parent.

The tool also has a retry capability that can help ensure that operations are ultimately successful even when interdependent operations are not present in the correct order in the LDIF file, such as if the change to add a parent entry is provided later in the LDIF file than a change to add a child entry.

After the tool applies the changes and reaches the end of the LDIF file, it automatically displays the update statistics described in the following table.

Processing Statistic Description

Attempts

Number of update attempts

Successes

Number of successful update attempts

Rejects

Number of rejected updates

ToRetry

Number of updates that will be retried

AvgOps/S

Average operations per second

RctOps/S

Recent operations per second

Total number of operations from the last interval of change updates

AvgDurMS

Average duration in milliseconds

RctDurMS

Recent duration in milliseconds

Total duration from the last interval of change updates

Running the parallel-update tool

Steps

  1. Create an LDIF file with your changes.

    Example:

    The third change in this example generates a rejected entry because its userPassword attribute contains an encoded value, which is not allowed.

    dn:uid=user.2,ou=People,dc=example,dc=com
changetype: delete

dn:uid=user.99,ou=People,dc=example,dc=com
changetype: moddn
newrdn: uid=user.100
deleteoldrdn: 1

dn:uid=user.101,ou=People,dc=example,dc=com
changetype: add
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
postalAddress: Ziggy Zad$15172 Monroe Street$Salt Lake City, MI 49843
postalCode: 49843
description: This is the description for Ziggy Zad.
uid: user.101
userPassword: {SSHA}IK57iPozIQybmIJMMdRQOpIRudIDn2RcF6bDMg==

dn:uid=user.100,ou=People,dc=example,dc=com
changetype: modify
replace: st
st: TX
-
replace: employeeNumber
employeeNumber: 100

  2. To apply the changes in the LDIF file to a target server, run parallel-update with the --ldifFile and --rejectFile options.

    The --ldifFile and --rejectFile options are required.

    Example:

    In this example, there are ten concurrent threads. The optimal number of threads depends on your underlying system.

    $ bin/parallel-update --hostname 127.0.0.1 \
  --ldifFile changes.ldif --rejectFile reject.ldif --numThreads 10

    Result:

    Reached the end of the LDIF file
Attempts Successes Rejects ToRetry AvgOps/S RctOps/S AvgDurMS RctDurMS
-------- --------- ------- ------- -------- -------- -------- ---------
       4         3       1       0        3        3       26       26
All processing complete Attempted 4 operations in 1 seconds

  3. View the rejects files for any failed updates.

    Result:

    The following sample elaborates on the rejected file.

    # ResultCode=53, Diagnostic Message=Pre-encoded passwords are not allowed for
# the password attribute userPassword
dn: uid=user.101,ou=People,dc=example,dc=com
changetype: add
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
postalAddress: Ziggy Zad$15172 Monroe Street$Salt Lake City, MI 49843
postalCode: 49843
description: This is the description for Ziggy Zad.
uid: user.101
userPassword: {SSHA}IK57iPozIQybmIJMMdRQOpIRudIDn2RcF6bDMg==