3.2. Redundancy and failover for the Primary Directory Node

The Primary Directory Node is the central writing instance for the directory service in a Nubus for UCS domain. For an overview of system roles, see Understanding system roles.

A disruption to this single system represents a critical risk with significant consequences:

• Users can’t authenticate to the domain.

• Administrators can’t create or modify users and groups.

• Password resets and account management operations fail.

• New systems can’t join the domain.

• Mail services, file sharing, and other integrated applications can’t serve domain users.

• All domain members lose their ability to modify critical directory data and manage domain resources.

This page describes two complementary strategies to mitigate this risk:

Redundancy

Distribute directory data across Backup and Replica Directory Nodes to ensure read access continues if the Primary becomes unavailable.

Failover

Promote a Backup Directory Node to Primary, restoring write capability when the current Primary becomes unavailable.

Whether you are planning infrastructure from scratch or recovering from an outage, this page guides you through building and maintaining a resilient directory service.

3.2.1. Fault-tolerant domain setup

A Nubus for UCS domain relies on critical services such as LDAP, DNS, Kerberos, DHCP, and Active Directory-compatible domain controllers. To ensure these services remain available during hardware failures or maintenance, distribute them across multiple Directory Nodes.

Consider the following when planning redundancy:

At least one Backup Directory Node

Provides full data replication and promotion capability to a Primary Directory Node. Essential for production environments.

Geographic distribution

Place Backup and Replica Directory Nodes in different locations for disaster recovery and local access.

Network connectivity

Ensure all systems can reliably communicate with the Primary Directory Node.

Service distribution

Plan which services run on which systems, such as LDAP, DNS, Kerberos, DHCP, and Samba.

Building a fault-tolerant domain requires two steps:

1. Install redundant Directory Nodes

   Add Backup and Replica Directory Nodes to your domain. For more information, see Joining domains in Univention Corporate Server - Manual for users and administrators [3].

2. Configure service redundancy

   Configure LDAP, Kerberos, DNS, DHCP, and Samba to use multiple servers.

The article KB 6682 - Fail-safe domain setup in the Univention Support database provides detailed configuration instructions for each service. Follow the procedures in the article after installing your Backup and Replica Directory Nodes to complete your fault-tolerant domain configuration.

LDAP server failover

Configure additional LDAP servers with UCR variables, so clients automatically fail over if the Primary Directory Node becomes unavailable.

Kerberos Key Distribution Centers

Set up multiple Kerberos KDCs for authentication redundancy.

DNS name servers

Configure multiple name servers to ensure name resolution continues during maintenance or failures.

DHCP redundancy

Install the DHCP server app on additional systems to ensure network configuration remains available.

Active Directory-compatible Domain Controllers

If you need Active Directory functionality, deploy the Samba component on Backup and Replica Directory Nodes to provide redundant domain controller functionality.

3.2.2. Backup to Primary promotion

A Nubus for UCS domain consists of only one Primary Directory Node, but has no limit in the number of Backup Directory Nodes. In contrast to the Primary Directory Node, the Backup Directory Node can’t write changes to the domain data. For descriptions about the system roles, see the following sections:

• Primary Directory Node

• Backup Directory Node

You can promote any Backup Directory Node to a Primary Directory Node. The following promotion scenarios exist:

Emergency

In an emergency, for example if the hardware of the Primary Directory Node fails.

Replacement

To replace a fully functional Primary Directory Node with modern hardware.

3.2.2.1. Prepare backup to primary promotion

The promotion primarily involves transferring authentication-related services such as LDAP, DNS, Kerberos, and Samba. You need to manually adjust the installed software through the management modules App Center and Package Management.

For example, if the previous Primary Directory Node has the mail component installed, the promotion process doesn’t install the app on the promoted Primary Directory Node. To minimize manual changes after the promotion, consider Fault-tolerant domain setup.

Caution

The promotion of a Backup Directory Node to a Primary Directory Node is a serious and irreversible configuration change.

Before promoting:

• Shut down the Primary Directory Node and keep it powered off during and after the promotion.

• Compare installed packages, see Synchronize LDAP schema packages, and configuration, see Compare Univention Configuration Registry, between Primary and Backup Directory Nodes.

• If the Primary is unavailable in an emergency, use a file backup for comparison.

After promoting, see Validate the promotion:

• Remove or update all references to the old Primary Directory Node across the domain.

To prepare the backup to primary promotion, follow these steps:

Synchronize LDAP schema packages

If the Primary Directory Node has additional LDAP schema packages installed, you need to install them on the Backup Directory Node before you run the promotion.

1. Save the package list from the Primary Directory Node

   To create the package list, run the command in Listing 3.1.

   Listing 3.1 Save the package list

   $ dpkg --get-selections \* > dpkg.selection
   

2. List packages with LDAP schema on the Primary Directory Node

   To list all packages on the Primary Directory Node with an LDAP schema, run the command in Listing 3.2.

   Listing 3.2 List of packages with an LDAP schema

   $ dpkg -S /etc/ldap/schema/*.schema \
     /usr/share/univention-ldap/schema/*.schema
   

3. Compare the package lists on the Backup Directory Node

   Compare the dpkg.selection file with the output from the same command on the Backup Directory Node. Ensure that the package list only differs in the packages univention-server-master and univention-server-backup.

   If the comparison reveals other missing packages, you need to install them on the Backup Directory Node. Packages that install an LDAP schema are especially important.

4. Install the same packages on the Backup Directory Node

   Use the dpkg.selection file created on the Primary Directory Node in Listing 3.1 and run the command in Listing 3.3 on the Backup Directory Node.

   Listing 3.3 Install the same packages on the Backup Directory Node

   $ dpkg --set-selections < dpkg.selection
   $ apt-get dselect-upgrade
   

Compare Univention Configuration Registry

You need to save the Univention Configuration Registry inventory so that you can compare the configuration adjustments on the promoted Primary Directory Node.

1. Compare the following files on the Primary Directory Node with those on the Backup Directory Node:

   • /etc/univention/base.conf

   • /etc/univention/base-forced.conf

2. UCS saves a copy of those files every night to /var/univention-backup/ucr-backup_%Y%m%d.tgz.

3.2.2.2. Run the backup to primary promotion

To promote a Backup Directory Node to the Primary Directory Node, run the /usr/lib/univention-ldap/univention-backup2master command on the Backup Directory Node. The Backup Directory Node system must reboot after the promotion. The promotion process logs to the /var/log/univention/backup2master.log log file.

The univention-backup2master command runs the following steps:

1. Verify the environment:

   • The system must be a Backup Directory Node that has already joined the domain.

   • The Backup Directory Node can resolve the Primary Directory Node through DNS and reaches the repository server.

   • The Primary Directory Node is offline and not reachable anymore.

2. Run component scripts in the /usr/lib/univention-backup2master/pre directory before the promotion begins. The directory contains executable scripts for components that require custom handling for the Primary Directory Node.

3. Reconfigure the critical services:

   • Stop the most important services OpenLDAP, Samba, Kerberos, Univention Directory Notifier, and Directory Listener.

   • Change important UCR variables, such as ldap/master and server/role.

   • Make the UCS Root CA certificate available through the web server on the Backup Directory Node.

   • Start the services OpenLDAP, Samba, Kerberos, Univention Directory Notifier, and Listener.

4. Update the DNS service record kerberos-adm from the old Primary Directory Node to the promoted Primary Directory Node.

5. If present, remove the Univention Univention S4 connector from the computer object of the old Primary Directory Node and schedule it for re-configuration on the promoted Primary Directory Node.

6. Change the server role of the promoted Primary Directory Node to domaincontroller_master in the OpenLDAP directory service. Adjust the DNS service record _domaincontroller_master._tcp accordingly.

7. If present, remove all entries of the old Primary Directory Node from the local Samba directory service. Additionally, transfer the FSMO roles to the promoted Primary Directory Node.

8. Delete the computer object of the old Primary Directory Node from the OpenLDAP directory.

9. Search the OpenLDAP directory service for any remaining references to the old Primary Directory Node. Show all found references, such as DNS records, and suggest fixing them.

   You need to verify and confirm the suggested fixes one by one.

10. Finally, replace the package univention-server-backup with univention-server-master.

11. Run component scripts in the /usr/lib/univention-backup2master/post directory after the promotion completed. The directory contains executable scripts for components that require custom handling for the Primary Directory Node.

3.2.2.3. Validate the promotion

After the promotion completes, remove or update all references to the old Primary Directory Node across the domain.

The article Univention Help 19514 - “How To: backup2master” provides detailed validation procedures for:

• Checking UCR variables on all domain systems for old hostname and IP references.

• Verifying and updating DNS host entries in LDAP.

• Reviewing and updating domain policies in the Managment UI.

Test regular domain operations after validation to ensure correct functionality.