12.10. Modifying the Sync 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.

12.10.1. Editing the Sync 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 synced. All of the synchronization agreements are listed below the database. Double-click the sync agreement to open it in the main window.
  3. Click the Connection tab.
    There are three areas of information that can be edited.
    • The connection type (standard, TLS/SSL, 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/SSL, 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/SSL to either the standard or Start TLS connections. Likewise, it is not possible to go from standard or Start TLS to TLS/SSL. If you need to change the connection protocol or the port number, delete the sync agreement and create a new one.

12.10.2. Adding and Editing the Sync 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 listed in Section 12.10.2.5, “Sync Agreement Attributes” and described in the Configuration and Command-Line Tool Reference.

12.10.2.1. Creating a Basic Sync 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)
    • The synchronized subtree in the directory (nsds7DirectoryReplicaSubtree)
  • 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), SSL (SSL), or Start TLS (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: 
ldapmodify -a -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=ExampleSyncAgreement,cn=sync replica,cn=dc=example\,dc=com,cn=mapping tree,cn=config
changetype: add
objectclass: top
objectclass: nsDSWindowsReplicationAgreement
cn: ExampleSyncAgreement
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=config
nsDS5ReplicaCredentials: {DES}ffGad646dT0nnsT8nJOaMA==
nsDS5ReplicaTransportInfo: TLS
nsds7NewWinUserSyncEnabled: on
nsds7NewWinGroupSyncEnabled: on

12.10.2.2. Setting Sync 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

12.10.2.3. Changing Sync 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=config
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 SSL connections, since that requires changing between standard and insecure ports.
To change to or from SSL/TLS, delete the sync agreement and add it again with the updated port number and new transport information.

12.10.2.4. Handling Entries That Move Out of the Synced 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 synced 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 synced.
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 synced 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 12.4. Active Directory Tree

For 7.x and 8.x versions of Directory Server, synchronization simply ignored that user, since it was outside the synced 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 synced subtree are intentionally moved outside the synced 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 12.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 synced subtree.
The winSyncMoveAction attribute for the synchronization agreement sets instructions on how to handle these moved entries:
  • none takes no action, so if a synced Directory Server entry exists, it may be synced over to or create an Active Directory entry within scope. If no synced Directory Server entry exists, nothing happens at all (this is the default behavior in Directory Server 9.1).
  • 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 synced 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: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=ExampleSyncAgreement,cn=sync replica,cn=dc=example\,dc=com,cn=mapping tree,cn=config
changetype: modify
add: winSyncMoveAction
winSyncMoveAction: unsync

12.10.2.5. Sync Agreement Attributes

The common sync agreement attributes are listed in Table 12.6, “Sync Agreement Attributes”. All of the possible sync agreement attributes are described in detail in the Red Hat Directory Server 9 Configuration, Command, and File Reference.

Table 12.6. Sync Agreement Attributes

Object Class or Attribute Description
nsDSWindowsReplicationAgreement An operational object class which contains the sync agreement attributes.
cn Gives the name for the sync agreement.
nsds7WindowsReplicaSubtree Specifies the Windows server suffix (root or sub) that is synced.
nsds7DirectoryReplicaSubtree Specifies the Directory Server suffix (root or sub) that is synced.
nsds7NewWinUserSyncEnabled Sets whether new Windows user accounts are automatically created on the Directory Server.
nsds7NewWinGroupSyncEnabled Specifies whether new Windows group accounts are automatically created on the Directory Server.
nsds7WindowsDomain Identifies the Windows domain being synchronized; analogous to nsDS5ReplicaHost in a replication agreement.
nsds5replicaport
Gives the LDAP port for the Windows server.
To use TLS/SSL, give the secure port number (636 by default) and set the nsds5ReplicaTransportInfo attribute to SSL.
To use Start TLS, which initiates a secure connection over a standard port, use the standard port, 389, with the nsds5ReplicaTransportInfo attribute to TLS.
nsds5replicatransportinfo
To use TLS/SSL, set this parameter to SSL.
To use Start TLS, which initiates a secure connection over a standard port, set this parameter to TLS.
To use simple authentication, set this parameter to LDAP.
nsds5ReplicaBindDN The sync user DN used by the Directory Server instance to bind to the Windows server.
nsds5replicabindmethod
The connection type for replication between the servers. The connection type defines how the supplier authenticates to the consumer.
Leaving the bind method empty or setting it to SIMPLE means that the server uses basic password-based authentication. This requires the nsds5ReplicaBindDN and nsds5ReplicaCredentials attributes to give the bind information.
The SSLCLIENTAUTH option uses a secure connection. This requires setting the nsds5ReplicaTransportInfo attribute be set to SSL or TLS.
nsDS5ReplicaCredentials Only for simple authentication. Stores the hashed password used with the bind DN given for simple authentication.
nsds5replicaroot Sets which Directory Server subtree is synchronized. Usually, it is recommended that the synchronized subtree be high in the directory tree so that the entire database is synchronized. For example: 
dc=example,dc=com
description A text description of the replication agreement. Make this a useful description so it is easier to manage sync agreements.
nsds5replicaupdateschedule
Sets the start and end time for the replication updates and the days on which replication occurs in the form start_time end_time days. If the schedule is omitted, synchronization occurs all of the time.
oneWaySync Optional. Configures synchronization updates to come from only one direction, either from Active Directory to Directory Server (fromWindows) or from Directory Server to Active Directory (toWindows). This attribute is not set by default, so synchronization is bi-directional.
winSyncInterval Optional. Sets how frequently, in seconds, the Directory Server polls the Windows server for updates to write over. If this is not set, the default is 300, which is 300 seconds or five (5) minutes.
winSyncMoveAction Optional. Sets how the sync plug-in handles corresponding entries that are discovered in Active Directory outside of the synced subtree. The sync process can ignore these entries (none, the default) or it can assume that the entries were moved intentionally to remove them from synchronization, and it can then either delete the corresponding Directory Server entry (delete) or remove the synchronization attributes and no longer sync the entry (unsync).
nsds5BeginReplicaRefresh Optional. Performs an online (immediate) initialization of the sync peer. If this is set, the attribute is only present as long as the sync peer is being updated initialized; when the initialization is complete, the attribute is deleted automatically. The only value when adding this attribute is start.