The IBM® Tivoli® Directory
Server (TDS) Changelog Connector is a specialized instance of the LDAP Connector. The IBM Directory
Server Changelog Connector contains logic to iterate the Changelog.
It returns various attributes, including the changes attribute.
This attribute is of type java.lang.String and contains
an incremental LDIF that you can read using the Parser FC and the
LDIF Parser. This technique will also retrieve any changes made to
the "objectClass" of the changed entry as well (since the objectClass
Attribute returned by the Connector is that of the changelog entry
itself).
The Connector can be used in batch-oriented runs where it starts
at a specific change number and stops after the last Changelog entry.
It can also be run in continuous mode where you specify the timer
values for periodically checking for the next Changelog entry.
The Connector reads Changelog entries and automatically increases
the Changelog counter by one for each iteration. When the Connector
tries to read a non-existing Changelog entry, the Connector goes to
sleep for a period of time (Sleep Interval).
If the total time the Connector is waiting for a new entry exceeds
the Timeout value, then the Connector returns
to the caller with a null value (end of iteration).
This connector also exposes a "Use Notifications"
option which specifies whether the Connector will use a polling or
a notification mechanism to retrieve new IDS changes. If set to false the
Connector will poll for new changes. If this parameter is set to true then
after processing all existing changes the Connector will block and
wait for an unsolicited event notification from the IBM Directory
Server. The Connector will not sleep and timeout when the notification
mechanism is used.
This connector also supports Delta Tagging, 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 older versions of Tivoli Directory
Integrator, in the IBM Directory Server Changelog
Connector merging occurs between Attributes of the changelog Entry
and changed Attributes of the actual Directory Entry. This creates
issues because you cannot detect the attributes that have changed.
The Tivoli Directory
Integrator 7.1.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 compatibility with earlier versions.
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 Tivoli Directory
Integrator, you may need to
select Merge changelog and changed data manually
so as to ensure identical behavior.
Return both - Returns an Entry that contains
changed attributes of the actual Directory Entry and an additional
attribute called "changelog" that 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.
There are some differences in the way the changes to password policy
operational attributes are logged to cn=changelog in IBM
Tivoli Directory Server on z/OS® and
in Distributed IBM Tivoli Directory Server (which runs on other platforms).
The currently known differences in behavior are listed below:
Modify of userpassword
A modify operation to change the userpassword will
remove attributes such as pwdfailuretime, pwdreset, pwdaccountlockedtime, pwdgraceusetime and pwdexpirationswarned from
an entry in the directory. It will also update the pwdchangedtime.
Distributed
TDS records these updates in the LDIF along with the replace of the userpassword value
in the changelog entry.
z/OS TDS only records the replace of
the userpassword in the LDIF, omitting the generated deletion
of the operational attributes.
A password change can also
conditionally update the pwdhistory attribute of an entry.
We know that this change is not logged in z/OS TDS. Although we
have no test data to show that it is indeed logged in Distributed
TDS, we suspect it is.
Password value in the changelog LDIF
z/OS TDS suppresses the
actual value (for security reasons) and instead displays the value
as "userpassword: *ComeAndGetIt*".
Distributed
TDS shows the userpassword value as is. Note that we only
have test output where password encryption is not being used, and
thus the actual password is displayed "in the clear". If password
encryption is active, probably the tagged, encrypted value is shown.
Add of a user entry
An add operation of a user entry containing
a password will conditionally add the pwdreset attribute
with a value of true if the effective policy for the user indicates
this to be the case for new entries.
Distributed TDS includes
"PWDRESET: true" in the changelog entries LDIF for the
add, but z/OS TDS does not.
Authentication via a grace login
When a password is expired,
but "grace" logins are allowed, authentication (via either a bind
or compare operation) succeeds and an additional value of the attribute pwdgraceusetime is
added to the user entry. Distributed TDS records this as a single
value added to the entry. z/OS TDS records this as a replace of the
entire set of values for the pwdgraceusetime attribute,
listing all the old values and the one new one.
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).
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 you will need to add the
following parameter in the Extra Provider Parameters field:
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 (that is, checked),
the Connector uses SSL to connect to the LDAP server. Note that the
port number might need to be changed accordingly.
ChangeLog Base
The search base where the Changelog is kept. The standard
DN for this is cn=changelog.
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.
Iterator State Key
Specifies the name of the parameter that stores the current
changelog number in the User Property Store of the IBM Tivoli Directory
Integrator, to allow
processing to stop and begin again at the last processed change. This
must be a unique name for all parameters stored in one instance of
the IBM Tivoli Directory
Integrator User Property Store. If this value is left blank, the connector
will start processing at the beginning of the changes with each AssemblyLine
restart. The Delete button deletes
this information from the User Property Store.
Start at
Specifies the starting change number (default value:1) 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. This parameter is only used when
the Iterator State is blank or not saved.
The Query button
retrieves the first and last change numbers from the Server.
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 directory
server's 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, you will need to save
the state by manually calling the IBM 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 Tivoli Directory
Integrator and maintains compatibility
with earlier versions.
Return only changed data
Returns only the modified or added attributes.
Return both
Returns changed attributes of the actual Directory
Entry, plus an additional attribute called "changelog" that
contains an Entry with changelog attributes.
Use Notifications
Specifies whether to use notification when waiting for new changes
in IBM Directory Server. If enabled, the Connector will not sleep
or timeout (and the corresponding parameters are ignored), but instead
wait for a Notification event from the IBM Directory
Server.
Batch retrieval
Specifies how searches are performed in IDS changelog. When
unchecked, the Connector will perform incremental lookups (backward
compatible mode). When checked, and the server supports "Sort Control",
searches will be preformed with query 'changenumber>=some_value',
corresponding to the last retrieval you made; this works in conjunction
with the next parameter, Page Size. By default,
this option is unchecked.
Page Size
Specifies the size of the pages IDS will return entries on (default
value is 500). It is used only when Batch retrieval is
set to true, that is, checked.
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.
Note:
Changing Timeout or Sleep Interval 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.
Directory Integrator, Version 7.1.1