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:
- Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
- Select the instance.
- Open themenu and select the entry.
- Open the Full Re-Synchronization.menu next to the synchronization agreement you want to synchronize and selectResynchronizing 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:
- Open themenu.
- Select theentry.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
andnsDS5ReplicaCredentials
). - The connection method (
nsDS5ReplicaTransportInfo
).It is only possible to change thensDS5ReplicaTransportInfo
fromLDAP
toStartTLS
and vice versa. It is not possible to change to or fromLDAPS
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.
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.
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
orntGroup
) 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