16.12. Modifying the Synchronization Agreement

Certain attributes of the sync agreement can be modified, including the connection information. Using the command line, many additional parameters can be created with or added to the sync agreement, including changing the sync interval and setting a sync schedule.

16.12.1. Editing the Synchronization Agreement in the Console

Most of the information which can be edited in the Console is limited to connection information, including the protocol to use and the bind credentials. It is also possible to edit the sync agreement description.
  1. In the Configuration tab, expand the Replication folder.
  2. Expand the database being synchronized. All of the synchronization agreements are listed below the database. Double-click the sync agreement to open it in the main window.
    Selecting the Synchronization Agreement

    Figure 16.7. Selecting the Synchronization Agreement

  3. Click the Connection tab.
    The Connection tab

    Figure 16.8. The Connection tab

    There are three areas of information that can be edited.
    • The connection type (standard, TLS, and Start TLS).
    • The bind user, both DN and password.
    • Whether to sync new Directory Server users and new Directory Server groups automatically.
    There are three options for the connection type — standard, TLS, and Start TLS — but there are really only two connection protocols, LDAP and LDAPS. Both a standard connection and Start TLS connection use LDAP (Start TLS creates a secure connection over an insecure port).
    It is not possible to change the connection protocol because it is not possible to change the port number used to connect to the Windows sync peer.
    It is possible to change the connection type between the standard connection and Start TLS, but it is not possible to change from TLS to either the standard or Start TLS connections. Likewise, it is not possible to go from standard or Start TLS to TLS. If you need to change the connection protocol or the port number, delete the sync agreement and create a new one.

16.12.2. Adding and Editing the Synchronization Agreement in the Command Line

Creating or editing the sync agreement through the command line is more flexible and provides more options than using the Directory Server Console. The full list of sync agreement attributes are described in the corresponding section in the Red Hat Directory Server Configuration, Command, and File Reference.

16.12.2.1. Creating a Basic Synchronization Agreement

The most basic sync agreement defines the Directory Server database and the Active Directory sync peer:
  • For the Directory Server database:
    • The synchronized subtree in the directory (nsds7DirectoryReplicaSubtree)
    • The Directory Server root DN (nsDS5ReplicaRoot)
  • For the Active Directory domain:
    • The synchronized subtree in the Active Directory domain (nsds7WindowsReplicaSubtree)
    • The Active Directory domain name (nsds7WindowsDomain)
It also defines the connection information that the Directory Server uses to bind to the Active Directory domain:
  • The Active Directory host name, IPv4 address, or IPv6 address (nsDS5ReplicaHost).
  • The Active Directory port (nsDS5ReplicaPort).
  • The type of connection (nsDS5ReplicaTransportInfo), which can be standard (LDAP), TLS (SSL), or StartTLS (TLS), which is a secure connection over a standard port.
  • The user name (nsDS5ReplicaBindDN) and password (nsDS5ReplicaCredentials) for the Directory Server to use to bind to the Active Directory server.
For example, using ldapmodify: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x
dn: cn=replication_agreement_name,cn=replica,cn="dc=example,dc=com",cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: nsDSWindowsReplicationAgreement
cn: replication_agreement_name
nsds7WindowsReplicaSubtree: cn=Users,dc=ad1
nsds7DirectoryReplicaSubtree: ou=People,dc=example,dc=com
nsds7WindowsDomain: ad1
nsDS5ReplicaRoot: dc=example,dc=com
nsDS5ReplicaHost: ad1.windows-server.com
nsDS5ReplicaPort: 389
nsDS5ReplicaBindDN: cn=sync user,cn=Users,dc=ad1
nsDS5ReplicaCredentials: {DES}ffGad646dT0nnsT8nJOaMA==
nsDS5ReplicaTransportInfo: TLS
nsds7NewWinUserSyncEnabled: on
nsds7NewWinGroupSyncEnabled: on
To synchronize among multiple subtree pairs, see Section 16.8, “Configuring Multiple Subtrees and Filters in Windows Synchronization”.

16.12.2.2. 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.12.2.3. 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 TLS and vice versa. It is not possible to change to or from SSL 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: TLS

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/Start TLS 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.12.2.4. 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.9. 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.10. 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 behavior from none, then edit the synchronization agreement to add the winSyncMoveAction attribute. Using ldapmodify: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=replication_agreement_name,cn=replica,cn="dc=example,dc=com",cn=mapping tree,cn=config
changetype: modify
add: winSyncMoveAction
winSyncMoveAction: unsync