Sun Directory Change Detection Connector

IBM Tivoli Directory Integrator

Sun Directory Change Detection Connector

The Sun Directory Change Detection Connector is a specialized instance of the LDAP Connector; this connector was previously called the Netscape/iPlanet Changelog Connector.

In Sun/iPlanet Directory Server 5.0, the format of the changelog was modified to a proprietary format. In earlier versions of iPlanet Directory Server, the change log was accessible through LDAP. Now the changelog is intended for internal use by the server only. If we have applications that must read the changelog, we will need to use the iPlanet Retro Change Log Plug-in for backward compatibility.

Since it is not always possible to run the Sun/iPlanet Directory Server in Retro Changelog mode, the Connector is able to run in two different Delivery Modes:

Changelog mode - in this mode the Connector will iterate trough the changelog (enabled by the iPlanet Retro Change Log Plug-in) and after delivering all Entries it will poll for new changes or use change notifications
Realtime mode - in this mode, only changes received as notifications will be delivered and offline changes will be lost. The Connector will not use the changelog in this mode. This delivery mode is necessary for Sun/Netscape/iPlanet Servers that do not support a changelog

This Connector supports Delta Tagging, in two different operation modes:

In Changelog mode Delta tagging is supported at the Entry level, the Attribute level and the Attribute Value level. It is the LDIF Parser that provides delta support at the Attribute and Attribute Value levels.
In Realtime mode Delta tagging will be performed at the Entry level only.

The Connector will detect modrdn operations in the Server's changelog, see Detect and handle modrdn operation for more information.

This component is not available in the TDI 7.1 General Purpose Edition.

Attribute merge behavior

In older versions of TDI, in the Sun Directory Change Detection Connector merging occurs between Attributes of the changelog Entry and changed Attributes of the actual Directory Entry. This creates issues because we cannot detect the attributes that have changed. The TDI 7.1 version of the Connector has logic to address these situations, configured by a parameter: Merge Mode. The modes are:

Merge changelog and changed data - The Connector merges the attributes of the Changelog Entry with changed attributes of the actual Directory Entry. This is the older implementation and keeps backward compatibility.
Return only changed data - Returns only the modified/added attributes and makes Changelog Iterator and Delta mode easier. This is the default; note that in configurations developed under and migrated from earlier versions of TDI, you may need to select Merge changelog and changed data manually so as to ensure identical behavior.
Return both - Returns an Entry which contains changed attributes of the actual Directory Entry and an additional attribute called "changelog" which contains attributes of the Changelog Entry. Allows you to easily distinguish between two sets of Attributes.

Delta tagging is supported in all merge modes and entries can be transferred between different LDAP servers without much scripting.

Note that in Realtime mode when the LDAP search base is different than "cn=changelog", the Connector cannot determine which attributes of Directory Entry are changed so no matter what value the Merge Mode parameter has, the output entry will still be the same. Of course, in Realtime mode when the server supports changelog and search base is set to "cn=changelog" the output entry is merged according to the chosen Merge Mode.

Configuration

The Connector needs the following parameters:

LDAP URL

The LDAP URL for the connection (ldap://host:port).

Login username

The LDAP distinguished name used for authentication to the server. Leave blank for anonymous access.

Login password

The credentials (password).

Iterator State Key

Specifies the name of the parameter that stores the current synchronization state in the User Property Store of the IBM TDI. This must be a unique name for all parameters stored in one instance of the IBM TDI User Property Store.

Pressing the Delete button causes this state information to be deleted from the User Property Store.

Start at changenumber

Specifies the starting changenumber. Each Changelog entry is named changenumber=intvalue and the Connector starts at the number specified by this parameter and automatically increases by one. The special value EOD means start at the end of the Changelog.

Note that this parameter is only used when the Iterator State is blank or not saved.

Pressing the Query button causes the first and last change numbers to be retrieved from the Server.

Authentication Method

Type of LDAP authentication. Can be one of the following:

Anonymous - If this authentication method is set then the server, to which a client is connected, does not know or care who the client is. The server allows such clients to access data configured for non-authenticated users. The Connector automatically specifies this authentication method if no username is supplied. However, if this type of authentication is chosen and Login username and Login password are supplied, then the Connector automatically sets the authentication method to Simple.
Simple - using Login username and Login password. Treated as anonymous if Login username and Login password are not provided. Note that the Connector sends the fully qualified distinguished name and the client password in cleartext, unless you configure the Connector to communicate with the LDAP Server using the SSL protocol.
CRAM-MD5 - This is one of the SASL authentication mechanisms. On connection, the LDAP Server sends some data to the LDAP client (that is, this Connector). Then the client sends an encrypted response, with password, using MD5 encryption. After that, the LDAP Server checks the password of the client. CRAM-MD5 is supported only by LDAP v3 servers. It is not supported against any supported versions of Tivoli Directory Server.
SASL - The client (this Connector) will use a Simple Authentication and Security Layer (SASL) authentication method when connecting to the LDAP Server. Operational parameters for this type of authentication will need to be specified using the Extra Provider Parameters option; for example, in order to setup a DIGEST-MD5 authentication we will need to add the following parameter in the Extra Provider Parameters field:
```
java.naming.security.authentication:DIGEST-MD5
```
For more information on SASL authentication and parameters see: http://java.sun.com/products/jndi/tutorial/ldap/security/sasl.html.

Not all directory servers support all SASL mechanisms and in some cases do not have them enabled by default. Check the documentation and configuration options for the directory server you are connecting to for this information.

Use SSL

If Use SSL is true, the Connector uses SSL to connect to the LDAP server. Note that the port number might need to be changed accordingly.

ChangeLog/Notifications Base

Specifies the search base where the Changelog is kept. The standard DN for this is cn=changelog. Also known as Notification Context for 'Realtime' Delivery Mode.

Extra Provider Parameters

Allows you to pass a number of extra parameters to the JNDI layer. It is specified as name:value pairs, one pair per line.

State Key Persistence

Governs the method used for saving the Connector's state to the System Store. The default and recommended setting is End of Cycle, and choices are:

After read: Updates the System Store when you read an entry from the Sun Directory Server change log, before you continue with the rest of the AssemblyLine.
End of cycle: Updates the System Store with the change log number when all Connectors and other components in the AssemblyLine have been evaluated and executed.
Manual: Switches off the automatic updating of the System Store with this Connector's state information; instead, we will need to save the state by manually calling the iPlanet Directory Server Changelog Connector's saveStateKey() method, somewhere in your AssemblyLine.

Merge Mode

Governs the method used for merging attributes of the Changelog Entry and changed attributes of the actual Directory Entry. The default is Return only changed data, and choices are:

Merge changelog and changed data: The Connector merges the attributes of the Changelog Entry with changed attributes of the actual Directory Entry. This option selects the behavior of older versions of TDI and maintains backwards compatibility.
Return only changed data: Returns only the modified or added attributes.
Return both: Returns entry with Changelog Attributes prefixed by "changelog." plus changed attributes of the Directory Entry.

Delivery Mode

Specifies whether to use changelog or (realtime) notifications entries. If the LDAP Server doesn't maintain a changelog, Realtime is the only applicable option. The default is Changelog.

Use Notifications

Specifies whether to use notification when waiting for new changes in Sun Directory Server. If enabled, the Connector will not sleep or timeout (and corresponding parameters are ignored) but instead wait for a Notification event from the Sun Directory Server.

Batch retrieval

Specifies how searches are performed in the changelog. When unchecked, the Connector will perform incremental lookups (backward compatible mode). When checked, and the server supports "Sort Control", searches will be performed with query "changenumber>=some_value", corresponding to the last retrieval you made. By default, this option is unchecked.

Timeout

Specifies the number of seconds the Connector waits for the next Changelog entry. The default is 0, which means wait forever.

Sleep Interval

Specifies the number of seconds the Connector sleeps between each poll. The default is 60.

Detailed Log

If this field is checked, additional log messages are generated.

Changing Timeout/SleepInterval values will automatically adjust its peer to a valid value after being changed (for example, when timeout is greater than sleep interval the value that was not edited is adjusted to be in line with the other). Adjustment is done when the field editor looses focus.