Museum

Home

Lab Overview

Retrotechnology Articles

Online Manuals

⇒

Media Vault

Software Library

Restoration Projects

Artifacts Sought

NT Directory Synchronization


he Directory Server NT Directory Synchronization service allows you to synchronize the entries in your Windows NT directory with the entries in your Directory Server directory. Both NT users and NT groups can be synchronized. As entries are created, modified, or deleted in one directory, the synchronization service makes the corresponding change to the other directory.

Directory synchronization occurs in both directions: NT to directory server and directory server to NT. All NT account information, including passwords, can be synchronized. There are no requirements as to which environment (the NT domain or the directory server) you use to master NT directory data. However, you are strongly recommended to master directory data in just one environment, because this will simplify the administration of your NT accounts. By strictly identifying where and how NT account information is changed, you greatly reduce the chance of conflicts and errors in the management of this information.

 The NT Synchronization Service can only be used with a 3.1 directory server.

  

The Synchronization Service

 NT directory synchronization is performed using the Netscape NT Directory Synchronization service. This service can be configured to automatically synchronize your directories based on a schedule that you supply.

Usage of the synchronization service requires the following restrictions:
  • The synchronization service must synchronize entries to one and only one directory subtree.

    •
  • A directory subtree can be managed by one and only one synchronization service; synchronization services from different PDCs must manage account information in different branches of the directory tree.

    •
 

Synchronization: NT to Directory Server

 Each NT domain can be synchronized with one and only one directory server. Further, the synchronization service can use only one directory server subtree.

 To perform synchronization, the synchronization service examines the local NT directory for changes and then transfers these changes to the directory server using an LDAPS (LDAP over SSL) connection.
    Note
    You should not set up your synchronization service so that two separate NT domains are synchronized to a single directory subtree. This is because unique user IDs are ensured within an NT domain, but not within multiple NT domains in the same network. Therefore, if you synchronize multiple NT domains to a single directory subtree, you run the risk of DN conflicts.
 

How NT Directory Changes Are Discovered

 The synchronization service finds changes in the NT directory by using two methods:
  • With the exception of passwords, all changes to NT user and group accounts are discovered by examining the Security Accounts Manager (SAM) database. Changes made to this database since the last synchronization are replayed in the directory server.

    •
  • Changes to user passwords are captured by a special DLL, which traps and then stores the password changes in encrypted form in a private area. On each synchronization schedule, the synchronization service first examines the SAM file for changes, and then checks this private area for passwords to be synchronized. Once the passwords have been synchronized, the passwords are deleted from the DLL's private area. Note that it is possible to disable NT to directory server password synchronization.

    •
All NT directory changes are transferred to the directory server using LDAPS (LDAP over SSL) which ensures the privacy of the NT user and group information.

  

Creating User Entries

 When you create an NT user account, the synchronization service automatically creates a corresponding entry on the directory server. The new entry is created in the subtree that you identify when you configure the synchronization service.

The new directory server entry is created using the inetOrgPerson and NTUser object classes. NTUser attributes are set as described for the definition for "ntUser" on page 367. In addition, the following inetOrgPerson attributes are set:

  • The common name (CN) attribute is set to the NT user account's username name field. In addition, if a full name is set on the NT user account, then this value is set as a second cn attribute value on the directory server entry.

    •
  • The value set for the NT account's password is captured by the synchronization service DLL and transferred to the directory server over LDAPS.

    •
  • The description attribute is set to the NT user account's comment field.

In addition, if the synchronization service has been told to automatically create messaging server accounts, then the mailRecipient and nsLicenseUser object classes are set on the new directory server account and the following attribute values are set on the entry:
  • The nsLicensedFor attribute is set given a value of mail

    •
  • The mailHost attribute is set to the value defined for the synchronization service configuration tool's Messaging | Host field (see "Configuring Mail Accounts to be Created on the Directory Server" on page 290 for details).

  • The mail attribute is set to the string <uid>@<mailHost>. That is, if the mailHost attribute is set to airius.com and the uid attribute is set to bjensen, then the mail attribute is set to bjensen@airius.com.

    •
  • The mailDeliveryOption attribute is set to mailbox

    •
  • If messaging server accounts are being created by the synchronization service, the uid attribute is also set to the value derived by the algorithm selected in the synchronization service's Messaging tab. For more information, see "Configuring Mail Accounts to be Created on the Directory Server" on page 290.

 

Creating Group Entries

 When you create an NT group, the synchronization service will automatically create a corresponding group entry on the directory server. The new group is created in the subtree that you identify when you configure the synchronization service.

 The new directory server group entry is created using the groupOfUniqueNames and NTGroup object classes. NTGroup attributes are set as described for the definition for "NTGroup" on page 354. Specifically, the ntGroupDomainID attribute is set with the following value:


	ntGroupDomainID: <NT domain name>:<NT Group Name>
The ntGroupType attribute is also set with a value of local or global.

 In addition, the following groupOfUniqueNames attributes are set:
  • The common name (cn) attribute is set to the NT Groupname value

    •
  • A uniqueMember attribute is set for each NT group member

    •
  • The description attribute is set to the NT description field value

    •
 

Initially Creating Entries

 When you first start the synchronization service, the service does not automatically add any existing NT users to the directory server. To have existing NT users added to the directory server, use the Add all users and groups button in the Synchronization Schedule tab.

 This causes the synchronization service to add every currently existing user and group to the directory server. The new directory server entries are created as described in "Creating User Entries" on page 282.

 

Synchronization: Directory Server to NT

Each directory server can communicate with multiple synchronization services. Consequently, the directory server tree should be structured such that all of the NT user entries from a given NT domain are collected within a single directory server subtree. If the directory server is synchronizing with multiple NT domains, then a separate directory server subtree should be used for each NT domain.

  

How Synchronization Occurs

 The directory server uses a non-LDAP SSL connection to communicate with the NT synchronization service. The directory server uses this connection to:

  • Validate any proposed changes to NTUser or NTGroup information. To validate proposed changes, the directory server uses the non-LDAP connection to check the proposed change against the NT directory rules defined for the domain. If a change is vetoed by the domain, then the LDAP modification operation is rejected by the directory server.

    •
  • Transmit NTUser and NTGroup changes directly to NT for inclusion into the NT domain. This transmission occurs as soon as the change has been made on the directory server. This means that directory server 3.1 to synchronization service communications do not occur over LDAP. Also, the changes are not batched as they are with 1.x directory servers; they always occur immediately upon completion on the directory server.

    •
Because of the importance of this non-LDAP connection, the synchronization service cannot be started if the corresponding directory server is not listening on the port defined for this communication.

  

Creating User Entries

 The NT synchronization service will create an NT user account on the local PDC if both of the following conditions are true:
  • A directory server user entry is created in the subtree being monitored by the synchronization service.

    •
  • The new directory server entry uses the NTUser object class.

    •
In this situation, the synchronization service creates the new user based on the following information:
  • The NT domain and NT user name is identified based on the information stored in the ntUserDomainID attribute.

    •
  • The common name (cn) attribute is used for the NT user account's full name field.

    •
  • The description attribute is used for the NT user account's comment field.

    •
  • The NT account's password is set to the password value of the directory server user entry.

    •
 

Creating Group Entries

 The NT synchronization service will create an NT group account on the local PDC if both of the following conditions are true:
  • A directory server group entry is created in the subtree being monitored by the synchronization service.

    •
  • The new directory server entry uses the NTGroup object class.

    •
In this situation, the synchronization service creates the new group based on the following information:
  • The NT domain and NT group name is identified based on the information stored in the ntGroupDomainID attribute.

    •
  • The common name (cn) attribute is used for the NT group's Groupname field.

    •
  • The description attribute is used for the NT group's description field.

    •
  • The group is created as an NT local or NT global group depending on the value of the ntGroupType attribute.

    •
 

Creating Duplicate Entries

 If an entry is created in the directory server, and the NT user account identified by the ntUserDomainID attribute already exists, then the synchronization service's behavior is dependent upon the directory server entry's ntUserCreateNewAccount attribute. Similarly, if a group is created in the directory server, and the NT group account identified by the ntGroupDomainID attribute already exists, then the synchronization service's behavior is determined by the ntGroupCreateNewAccount attribute.

 If the ntUserCreateNewAccount or ntGroupCreateNewAccount attribute does not exist on the entry or if this attribute is set to false, then the synchronization service will attempt to modify the existing NT group or user account with the common name and description information stored on the directory server entry.

If the ntUserCreateNewAccount or ntGroupCreateNewAccount attribute is set to true, then the synchronization service will report an error indicating that it attempted to create the new group or user account but that it already existed.

  

Deleting Entries

 The NT synchronization service will delete an NT group or user account if the following conditions are true:
  • A directory server entry is deleted from the subtree being monitored by the synchronization service.

    •
  • The directory server entry included the ntUserDeleteAccount or ntUserDeleteGroup attribute, and this attribute value was set to true.

    •
 

Modifying Entries

 The synchronization service will modify a user or group account on the PDC anytime the corresponding directory server entry is modified. For details on how this synchronization process occurs, see "How Synchronization Occurs" on page 281.

 

Concurrently Changing Directory Server and NT Account Values

Because NT synchronization is configured to synchronize in two directions, NT to directory server and directory server to NT, there is a potential for losing data. This can happen if you change corresponding entries in both directories before synchronization can occur. For example, if you change an NT user account's comment field and you also change the corresponding directory server entry's description field before the synchronization service can transfer the comment field changes, then you will lose the changes to one of the two fields.

 Note that the window of opportunity for losing data is driven entirely by the schedule that you set up for the NT to directory server synchronization. This is because the directory server to NT synchronization occurs as soon as changes are made on the directory server. If you make a change on the NT domain, and then make a conflicting change in the directory server before NT to directory server synchronization happens, then the changes to the NT domain will be lost.

 Make a habit out of changing NT values in only one of the two directories. This will reduce potential confusion and help to avoid any problems that might occur because of conflicting changes in the two directories.

 

The Synchronization Configuration Tool

 You configure and control directory synchronization using the directory server NT synchronization configuration tool.

This tool is a native Windows NT application that you use to:

  • start and stop the synchronization service

    •
  • identify the directory server with which synchronization should occur

    •
  • identify the ports on which synchronization occurs

    •
  • identify whether SSL is used to communicate with the directory, and if so the certificate database that the synchronization service should use for SSL communications with the directory server (the use of SSL is recommended)

    •
  • schedule synchronization

    •
  • examine synchronization status

    •
  • optionally sets messaging server account details (for more information, see "Configuring Mail Accounts to be Created on the Directory Server" on page 290)

This tool is installed with the NT synchronization service. You can install the NT synchronization service when you install the directory server, or you can install it after the directory server has been installed.

  

About the OK, Cancel, Apply, and Help Buttons

 The configuration tool contains four standard buttons:
  • Apply--Applies any changes made in the synchronization service settings since the time the tool was opened, or since the time of the last apply.

    •
  • Cancel--Cancels any changes that have not been applied and closes the configuration tool window.

    •
  • OK--Applies any changes that have not previously been applied, and then closes the configuration tool window.

    •
  • Help--Displays online help about the tab that you are currently looking at.

    •
 

Configuring Synchronization

 To set up NT synchronization, you must:
  • Use the Service Settings tab to configure the synchronization service to use the appropriate port, log file, and (optionally) certificate database. You can optionally use this tab to turn off NT to directory server synchronization.

  • Use the Directory Server Settings tab to identify the directory server and directory subtree with which synchronization is to occur. You can optionally use this tab to turn off directory server to NT synchronization.

  • If you are allowing NT to directory server synchronization, you should set the synchronization schedule using the Synchronization Schedule tab.

  • If you are allowing directory server to NT synchronization, you must turn on the synchronization plugins on the directory server. You do this from the directory server manager. For information on how this is performed, see "Managing Network Settings" on page 232.

 

Configuring Service Settings

 Use the Service Settings tab to identify the following about the synchronization service:
  • The local port which the synchronization configuration tool uses to communicate with the synchronization service. By default, this is 5007. When the Synchronization Configuration Tool starts up, it opens a connection to the synchronization service on this port and maintains this connection until the tool exits.

    •
  • The location of the synchronization service event log file. For example, "c:\Netscape\Suitespot\dssynch\synch-log.txt." This log file is used by the synchronization service to record significant events and problems. Each time a user or group is added, deleted, modified, or renamed in the NT domain, the synchronization service records the event to this file.

  • Whether SSL is used for synchronization. If yes (this is recommended), you also specify the path and filenames of the security certificate database file. For information on how to not use SSL for synchronization, see "Turning Off SSL" on page 292. For information on how to obtain a certificate database for your NT Synchronization Service, see "Using Certificate-Based Authentication" on page 241.

  • If you do not want to synchronize NT passwords to the directory server (you only want to synchronize users and groups), set the checkbox on the Service Settings tab.

    •
If you want to disable NT to directory server synchronization, click Disable Synchronization from NT to Directory Server.

  

Configuring Directory Server Settings

 Use the Directory Server Settings tab to identify the following information:
  • The DNS name of the host on which the Directory Server is running.

    •
  • The port number which the Directory Server is using for communications. If the synchronization service is configured for SSL, then the default is 636. Otherwise it is 389. You cannot change this port number when the synchronization service is running.

    •  LDAPS connections are not maintained for the life of the synchronization service. Instead, LDAPS connections are established at each scheduled synchronization or when the administrator uses the "Synchronize" or "Add All Users & Groups" buttons on the configuration tool. If there is a problem creating the LDAPS connection to the directory server, a dialog box will be raised and a message will be written to the synchronization log file. Such problems are often caused by misconfiguration of the synchronization service. See "Troubleshooting Errors at Synchronization Time" on page 292 for information on these misconfigurations.

  • The distinguished name and password that the synchronization service should use to bind to the directory server (for example, "cn=admin, o=airius.com"). This can either be the Root DN, or it can be a distinguished name that has full read, write, add, delete, search, and compare privileges to the directory server subtree containing the NTUser entries. You are strongly recommended to avoid using the Root DN for normal bind operations such as this.

  • The directory base. This is the directory subtree where the synchronization service will create, modify, and delete entries. For example, if you used the sample LDIF file that is shipped with this server to create a directory database, then a valid directory base would be "ou=people, o=airius.com."

    •  If the name of the directory subtree you want to use as the directory base contains a comma, you must escape the comma with a backslash (\) when you enter the value in the directory base field. For example, to use the Airius Bolivia, S.A. subtree as the directory base, you would enter Airius Bolivia\, S.A. in the directory base field.

  • The directory tree in which you want to enforce uniqueness in the UID. SuiteSpot requires that all person entries in the directory have a unique UID attribute. Most SuiteSpot servers are configured to enforce this uniqueness in the entire directory tree (that is, from the directory suffix down). If SuiteSpot servers are managing users in other areas of the directory tree than the area in which the synchronization service is managing, then you should enter your directory suffix here. Otherwise, simply enter the same DN as you entered for directory base.

  • The port number on which the directory server's synchronization plugin accepts non-LDAP connections. Default is 5009. When the synchronization service starts up, it establishes several connections to this port, and these are maintained while the synchronization service is running. When these connections are established, a message is written to the synchronization log file. Absence of these messages from the logfile is a good indicator of a problem to come. Synchronization from the Directory Server to NT cannot occur if these connections are not fully established. This sometimes occurs due to misconfiguration of the synchronization service. See "Troubleshooting Errors at Synchronization Time" on page 292 for information on these misconfigurations.

If you want to disable directory server to NT synchronization, click Disable Synchronization from Directory Server to NT.

  

If the Selected UID is Not Unique

 If the synchronization service attempts to create a directory account, and the proposed UID that the synchronization service wants to use is not unique within the identified directory subtree, then the synchronization service does not create the directory entry and a warning message is written to the NT Event Log and to the synchronization service's log file (for information on this log file, see "Configuring Service Settings" on page 286)

When this happens, use the administration server to create the new entry. See Managing Netscape Servers for information on how to create new entries in the directory.

 

Scheduling Synchronization

 Use the Synchronization Schedule tab to schedule NT to directory server synchronization.

 There is no corresponding scheduling area for directory server to NT synchronization, because that synchronization always occurs as soon as relevant directory server data is changed.

 You use the following two fields to schedule synchronization:

  • Synchronize every--This field allows you to specify the interval between synchronization startup times. Units are selectable between minutes and hours. For example, if you select 30 minutes for this field, then synchronization will begin every 30 minutes.

    •
  • Start at--This field allows you to specify the time when the synchronization cycle begins. For example, if you specify a time of 1:15 and then you specify an interval of 15 minutes in the Synchronize every field, then synchronization will occur at 1:15, 1:30, 1:45, 2:00, 2:15, and so forth.

    • Note that changing the start time does not cause the synchronization tool to wait for that time to begin synchronization; this field is used only for calculating the next synchronization event. For example, suppose the Start at field is currently set to 1:00 and the Synchronize every field is set to 15 minutes. If the current time is 2:20, then the next synchronization is scheduled for 2:30. Now suppose you change the Start at field to 1:40. Then synchronization will occur at 1:40, 1:55, 2:10, 2:25, and so forth. Therefore, the next synchronization will occur at 2:25 rather than the original 2:30.

Note that the next scheduled synchronization event for each direction is always shown in the Next synchronization at field.

  

Manually Performing Synchronization

 While synchronization will always occur based on the schedule set in the synchronization configuration tool, you can manually perform synchronization if you have an immediate need for a synchronization to occur.

 To manually perform synchronization, go to the Status tab in the synchronization configuration tool, and click the Synchronize button.

 Note that the synchronization schedule you have set in the configuration tool is unaffected by this manual synchronization. That is, if a synchronization is scheduled for 1:30 and you perform a synchronization at 1:25, then the 1:30 synchronization will still occur.

  

Configuring Mail Accounts to be Created on the Directory Server

 Use the Account Details tab to indicate whether the synchronization service should create mail accounts on the directory server when creating new ntUser entries on the directory server.

 To cause mail accounts to be created, simply click "Automatically create Messaging Server accounts for new Directory Server users."

 You must then identify the following information:
  • the host name of the messaging server for which the new accounts are to be created. In the Create new accounts on the Messaging Server named field, enter the full DNS host name on which the messaging server is running. For example, mail.airius.com.

    •
  • The method by which the messaging server user name is generated when the mail account is created. This user name corresponds to the UID attribute value placed on the directory server entry. This value must be unique within the subtree managed by the synchronization service.

    • The safest algorithm is also the default--the NT user name is used for the UID attribute value. This is the safest method of UID creation because the NT user name must be unique within the NT domain managed by the local PDC.

 

Surname-based NT Accounts

 Some cultures commonly begin their names with their surnames. If your NT domain is populated with names such as these, then you must configure the synchronization service with this information so that it can determine how to generate UIDs for the NT user accounts. To do this, go the Account Details tab in the synchronization configuration tool and select "NT account full name begins with surname."

  

Starting and Stopping the Synchronization Service

 Use the Status tab to start and stop the synchronization service.

Note that the service is not running when it is first installed. However, the service is configured to automatically start when your NT system reboots. To reconfigure the service so that it does not start when NT reboots:
  1. Go to the NT Control Panel, and select Services.

  2. Scroll through the list of services until you see Netscape Directory Synchronization Service. Note that the Startup field is set to Automatic.

  3. Double-click on Netscape Directory Synchronization Service.

  4. Select the Disabled radio button, and then click OK.

  5. Click Close in the Services control panel.

 

Checking Synchronization Status

You can use the synchronization configuration tool to check synchronization status. From the Status area, you can determine:

  • whether the synchronization service is running

    •
  • when synchronization is scheduled to occur for each synchronization direction

    •
  • whether the directory server is running

    •
 

Turning Off SSL

 You are strongly recommended to use SSL for NT to directory synchronization because of the sensitive nature of the information that you are synchronizing. However, you may feel that SSL is unnecessary, especially if you are using the synchronization service in a non-production (lab) environment. Do the following to cause the synchronization service to not use SSL when synchronizing with your directory server.
  1. Go to the directory server and edit the slapd.conf file to include the ntsynchUseSSL parameter:

    2. ntsynchUseSSL off

    For more information on this parameter, see page 340

  2. Go to the Service Settings tab in the NT Synchronization Configuration Tool and make sure that Use SSL is not selected.

  3. In the Directory Server Settings tab, make sure the LDAP port is not set to 636 (it should probably be 389).

 

Troubleshooting Errors at Synchronization Time

If your synchronization service is not properly configured, synchronization does not occur and a message box is raised by the configuration tool indicating the error.

 The message box indicates that the directory base DN and/or other configuration attributes are not correct. Ensure that the directory base DN and the administrator DN and password that you have supplied are correct. Also verify that the port numbers used for LDAPS and the synchronization plugins match on the directory server and the synchronization service.

 If the message box indicates error 81, then the synchronization service and/or the directory server have not been properly configured for SSL communications. Examine the directory server access log file to see if the connection attempt was received by the directory server. You may also find helpful messages directory server's error log file.

 To narrow down the source of the misconfiguration, try to establish an LDAPS connection to the directory server using Netscape Communicator. If this connection attempt fails, check all values (port number, host name, search base, and so forth) to see if any of these are the problem. If all else fails, reconfigure the directory server with a new certificate.

 Note: A common problem is to fail to trust your certificate authority when obtaining certificates. You can successfully obtain a server certificate and still not trust your CA. For information on how to trust your CA, see "Creating a Certificate Database" on page 234.

If the communicator connection is successful, it is likely that the misconfiguration is on the synchronization service side. Recheck all configuration values and examine the synchronization log file for error messages.

Typewritten Software • bear@typewritten.org • Edmonds, WA 98026