3.4. Listener/notifier domain replication

3.4.1. Listener/notifier replication workflow

Replication of the directory data within a UCS domain occurs via the Univention Directory Listener/Notifier mechanism:

• The Univention Directory Listener service runs on all UCS systems.

• On the Primary Directory Node (and possibly existing Backup Directory Node systems) the Univention Directory Notifier service monitors changes in the LDAP directory and makes the selected changes available to the Univention Directory Listener services on the other UCS systems.

Fig. 3.2 Listener/Notifier mechanism

The active Univention Directory Listener instances in the domain connect to a Univention Directory Notifier service. If an LDAP change is performed on the Primary Directory Node (all other LDAP servers in the domain are read-only), this is registered by the Univention Directory Notifier and notified to the listener instances.

Each Univention Directory Listener instance uses a range of Univention Directory Listener modules. These modules are shipped by the installed applications; the print server package includes, for example, listener modules which generate the CUPS configuration.

Univention Directory Listener modules can be used to communicate domain changes to services which are not LDAP-compatible. The print server CUPS is an example of this: The printer definitions are not read from the LDAP, but instead from the /etc/cups/printers.conf file. Now, if a printer is saved in the UMC printer management, it is stored in the LDAP directory. This change is detected by the Univention Directory Listener module cups-printers and an entry added to, modified or deleted in /etc/cups/printers.conf based on the data in the LDAP.

Additional information on the setup of Univention Directory Listener modules and developing your own modules can be found in Univention Developer Reference [3].

LDAP replication is also performed by a listener module. If the LDAP server to be replicated to is not accessible, the LDAP changes are temporarily stored in the /var/lib/univention-directory-replication/failed.ldif file. The contents of the file are automatically transferred to the LDAP when the LDAP server is available again.

The listener/notifier mechanism works based on transactions. A transaction ID is increased for every change in the LDAP directory of the Primary Directory Node. A Univention Directory Listener instance which has missed several transactions - for example, because the computer was switched off - automatically requests all the missing transactions once the connection is available again until its local transaction ID corresponds to that of the Primary Directory Node.

3.4.2. Analysis of listener/notifier problems

3.4.2.1. Log files/debug level of replication

All status messages from the Univention Directory Listener and the executed listener modules are logged in the /var/log/univention/listener.log file. The level of detail of the log messages can be configured using the Univention Configuration Registry Variable listener/debug/level.

Status messages from the Univention Directory Notifier service are logged in the /var/log/univention/notifier.log file. The debug level can be configured using the notifier/debug/level.

3.4.2.2. Identification of replication problems

When the domain replication is running normally (normal system load, no network problems), the delay between changes being made in UMC modules and these changes being replicated to, for example, a Replica Directory Node is barely noticeable. An incomplete replication can be identified by comparing the transaction IDs of the listener and notifier services.

The transactions registered by the notifier service are written in the /var/lib/univention-ldap/notify/transaction file in ascending order on the Primary Directory Node. An example:

root@primary:~# tail -1 /var/lib/univention-ldap/notify/transaction
836 cn=replica3,cn=dc,cn=computers,dc=firma,dc=de m

The last transaction received by the listener system is stored in the /var/lib/univention-directory-listener/notifier_id file:

root@replica1:~# cat /var/lib/univention-directory-listener/notifier_id
836

This check can also be performed automatically by the Nagios service UNIVENTION_REPLICATION (see Preconfigured Nagios checks).

3.4.2.3. Reinitialization of listener modules

If there are problems in running a listener module, there is the option to reinitialize the module. In this case, all LDAP objects with which the listener module works are passed on again.

Warning

This is a destructive operation. It removes some internal state of the listener. Use with care!

The name of the listener module must be supplied to the command for the renewed initialization. The installed listener modules can be found in the /var/lib/univention-directory-listener/handlers/ directory.

The following command can be used to reinitialize the printer module, for example:

$ univention-directory-listener-ctrl resync cups-printers