16.11. Sending Synchronization Updates

Synchronization occurs as frequently as is set in the winSyncInterval setting (for retrieving changes from the Active Directory domain) or nsds5replicaupdateschedule setting (for pushing changes from the Directory Server). By default, changes are retrieved from Active Directory every five minutes, and changes from the Directory Server are sent immediately.
A sync update can be triggered manually. It is also possible to do a full resynchronization, which sends and pulls every entry in the Directory Server and Active Directory as if it were new. A full resynchronization includes existing Directory Server entries which may not have previously been synchronized.

16.11.1. Performing a Manual Incremental Synchronization

During normal operations, all the updates made to entries in the Directory Server that need to be sent to Active Directory are collected to the changelog and then replayed during an incremental update.
To manually synchronize the changes:
# dsconf -D "cn=Directory Manager" ldap://server.example.com repl-winsync-agmt poke --suffix="dc=example,dc=com" example-agreement

16.11.2. Performing a Full Synchronization

If there have been major changes to data, or synchronization attributes are added to pre-existing Directory Server entries, it is necessary to initiate a resynchronization. Resynchronization is a total update; the entire contents of synchronized subtrees are examined and, if necessary, updated. Resynchronization is done without using the changelog. This is similar to initializing or reinitializing a consumer in replication.

16.11.2.1. Performing a Full Synchronization Using the Command Line

To start a full synchronization using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com repl-winsync-agmt init --suffix="suffix" agreement_name
To display the synchronization status:
# dsconf -D "cn=Directory Manager" ldap://server.example.com repl-winsync-agmt init-status --suffix="suffix" agreement_name

16.11.2.2. Performing a Full Synchronization Using the Web Console

To start a full synchronization:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Replication menu and select the Winsync Agreements entry.
  4. Open the Choose Action menu next to the synchronization agreement you want to synchronize and select Full Re-Synchronization.
    Resynchronizing does not delete data on the sync peer. The process sends and receives all updates and adds any new or modified Directory Server entries. For example, the process adds a pre-existing Directory Server user that had the ntUser object class added.
To display the synchronization status in the web console:
  1. Open the Replication menu.
  2. Select the Winsync Agreements entry.
    If the synchronization completed successfully, the web console displays the Error (0) Replica acquired successfully: Incremental update succeeded message in the Last Update Status column.

16.11.3. Setting Synchronization Schedules

Synchronization works two ways. The Directory Server sends its updates to Active Directory on a configurable schedule, similar to replication, using the nsds5replicaupdateschedule attribute. The Directory Server polls the Active Directory to check for changes; the frequency that it checks the Active Directory server is set in the winSyncInterval attribute.
By default, the Directory Server update schedule is to always be in sync. The Active Directory interval is to poll the Active Directory every five minutes.
To change the schedule the Directory Server uses to send its updates to the Active Directory, edit the nsds5replicaupdateschedule attribute. The schedule is set with start (SSSS) and end (EEEE) times in the form HHMM, using a 24-hour clock. The days to schedule sync updates are use ranging from 0 (Sunday) to 6 (Saturday).
nsds5replicaupdateschedule: SSSS EEEE DDDDDDD
For example, this schedules synchronization to run from noon to 2:00pm on Sunday, Tuesday, Thursday, and Saturday:
nsds5replicaupdateschedule: 1200 1400 0246

Note

The synchronization times cannot wrap around midnight, so the setting 2300 0100 is not valid.
To change how frequently the Directory Server checks the Active Directory for changes to Active Directory entries, reset the winSyncInterval attribute. This attribute is set in seconds, so the default of 300 means that the Directory Server polls the Active Directory server every 300 seconds, or five minutes. Setting this to a higher value can be useful if the directory searches are taking too long and affecting performance.
winSyncInterval: 1000

16.11.4. Changing Synchronization Connections

Two aspects of the connection for the sync agreement can be altered:
  • The bind user name and password (nsDS5ReplicaBindDN and nsDS5ReplicaCredentials).
  • The connection method (nsDS5ReplicaTransportInfo).
    It is only possible to change the nsDS5ReplicaTransportInfo from LDAP to StartTLS and vice versa. It is not possible to change to or from LDAPS because it is not possible to change the port number, and switching between LDAP and LDAPS requires changing the port number.
For example:
nsDS5ReplicaBindDN: cn=sync user,cn=Users,dc=ad1
nsDS5ReplicaCredentials: {DES}ffGad646dT0nnsT8nJOaMA==
nsDS5ReplicaTransportInfo: StartTLS

Warning

It is not possible to change the port number of the Active Directory sync peer. Therefore, it is also not possible to switch between standard/STARTTLS connections and TLS connections, since that requires changing between standard and insecure ports.
To change to or from TLS, delete the sync agreement and add it again with the updated port number and new transport information.

16.11.5. Handling Entries That Move Out of the Synchronized Subtree

The sync agreement defines what subtrees in both Active Directory and Directory Server are synchronized between each other. Entries within the scope (the subtree) are synchronized; other entries are ignored.
However, the synchronization process actually starts at the root DN to begin evaluating entries for synchronization. Entries are correlated based on the samAccount in the Active Directory and the uid attribute in Directory Server. The synchronization plug-in notes if an entry (based on the samAccount/uid relationship) is removed from the synchronized subtree either because it is deleted or moved. That is the signal to the synchronization plug-in that the entry is no longer to be synchronized.
The issue is that the sync process needs some configuration to determine how to handle that moved entry. There are three options: delete the corresponding entry, ignore the entry (the default), or unsync the entry.

Note

These sync actions only relate to how to handle on the Directory Server side when an entry is moved out of scope on the Active Directory side. This does not affect any Active Directory entry if an entry is moved out of the synchronized subtree on the Directory Server side.
The default behavior in Directory Server 9.0 was to delete the corresponding Directory Server entry. This was true even if the entry on the Active Directory side was never synchronized over to the Directory Server side. Starting in Directory Server 9.1, the default behavior is to ignore the entry and take no action.
For example, a user with the samAccount ID of jsmith was created in the ou=Employees subtree on Active Directory. The synchronized subtree is ou=Users, so the jsmith user was never synchronized over to Directory Server.
Active Directory Tree

Figure 16.4. Active Directory Tree

For 7.x and 8.x versions of Directory Server, synchronization simply ignored that user, since it was outside the synchronized subtree.
Starting in Directory Server 9.0, Directory Server began supporting subtree renames — which means that existing entries could be moved between branches of the directory tree. The synchronization plug-in, then, assumes that entries in the Active Directory tree which correspond to a Directory Server user (samAccount/uid relationship) but are outside the synchronized subtree are intentionally moved outside the synchronized subtree — essentially, a rename operation. The assumption then was that the "corresponding" Directory Server entry should be deleted.
Active Directory and Directory Server Trees Compared

Figure 16.5. Active Directory and Directory Server Trees Compared

This assumption is not necessarily an accurate one, particularly for user entries which always existed outside the synchronized subtree.
The winSyncMoveAction attribute for the synchronization agreement sets instructions on how to handle these moved entries:
  • none takes no action, so if a synchronized Directory Server entry exists, it may be synchronized over to or create an Active Directory entry within scope. If no synchronized Directory Server entry exists, nothing happens at all (this is the default behavior in the Directory Server version 9.1 and later).
  • unsync removes any sync-related attributes (ntUser or ntGroup) from the Directory Server entry but otherwise leaves the Directory Server entry intact.

    Important

    There is a risk when unsyncing entries that the Active Directory entry may be deleted at a later time, and the Directory Server entry will be left intact. This can create data inconsistency issues, especially if the Directory Server entry is ever used to recreate the entry on the Active Directory side later.
  • delete deletes the corresponding entry on the Directory Server side, regardless of whether it was ever synchronized with Active Directory (this was the default behavior in 9.0).

    Important

    You almost never want to delete a Directory Server entry without deleting the corresponding Active Directory entry. This option is available only for compatibility with Directory Server 9.0 systems.
If it is necessary to change the default:
# dsconf -D "cn=Directory Manager" ldap://server.example.com repl-winsync-agmt --move-action="action" --suffix="suffix" agreement_name