How-to: Best Practice - Relocating a UCS Primary Node to a New Datacenter (IP Address Change)

Knowledge Base Community
, , ,
1

How-to

When restructuring infrastructure or changing physical locations, administrators often face the task of relocating the central directory node. In a Univention Corporate Server (UCS) environment, the Primary Node (formerly DC Master) holds the domain’s unique Security Identifier (SID) and root certificates.

This article describes the best-practice approach for moving an existing UCS Primary Node to a new site involving a change of its IP address, network mask, and gateway.

Why Choose IP Modification Over “backup2master”?

For a production environment aiming for minimal downtime and absolute preservation of system identity, the Option (Modifying the IP of the existing Primary Node) is highly recommended over the backup2master procedure.

  • backup2master is primarily designed for disaster recovery or complete hardware replacements. It is an invasive process that forces all joint nodes within the domain to redefine their replication source.
    How To: backup2master
  • IP Modification preserves the SID and SSL certificates. When combined with precise DNS updates, this method is significantly less disruptive for clients, Managed Nodes, and Subordinate/Backup/Slave Nodes.

Environment

The procedure described below was successfully validated in a production environment running UCS 5.0-10 (with various errata levels). The environment remains on this version during the relocation and will be updated only after the migration is fully completed.

The baseline topology includes:

  • Primary Node: primary.example.com (UCS 5.0-10 errata1297)
  • Backup Node 1: backup1.example.com (UCS 5.0-10 errata1297, Installed: cups=2.2.1, samba4=4.16)
  • Backup Node 2: node1.example.com (UCS 5.0-10 errata1297, Installed: keycloak=26.1.4-ucs2)
  • Backup Node 3: node2.example.com (UCS 5.0-10 errata1297, Installed: keycloak=26.1.4-ucs2)
  • Backup Node 4: node3.example.com (UCS 5.0-10 errata1297, Installed: keycloak=26.1.4-ucs2)
  • Additional Node: subordinate.example.com (UCS 5.0-10 errata1220)
  • Slave Node: slave1.example.com (UCS 5.0-10 errata1297, Installed: dhcp-server=12.0, radius=5.0)

Migration Guide

Step 1: Preparation (At the Old Location)

Before shutting down the server or disconnecting it from the network, complete the following validation steps:

  1. Create a Full Backup / Virtual Machine Snapshot
    Compulsorily create a cold or consistent snapshot of the Primary Node VM.
  2. Verify Domain Replication Status
    Ensure that directory replication across all environment nodes is fully synchronous. Execute the following commands on the Primary Node and cross-check on the target nodes:
univention-directory-listener-ctrl status

/usr/lib/nagios/plugins/check_univention_replication

Step 2: Execution & Network Reconfiguration (At the New Location)

Once the physical or virtual host has been moved to the new location and booted into a restricted or local configuration network:

  1. Modify IP Configuration via UCR (Univention Configuration Registry)
    Update the network interface properties (assuming eth0 is the primary interface) to match the new network segment:
ucr set interfaces/eth0/address='<NEW_IP>' \
         interfaces/eth0/netmask='<NETMASK>' \
         interfaces/eth0/gateway='<GATEWAY>'
  1. Update the Primary Node’s LDAP Object
    The Primary Node must recognize its own updated IP address within the directory logic to ensure directory services bind correctly:
udm computers/domaincontroller_master modify \
  --dn "cn=$(hostname),cn=dc,cn=computers,$(ucr get ldap/base)" \
  --set IPAddress='<NEW_IP>'
  1. Correct DNS Records and Name Resolution
    Manually inspect the LDAP directory to ensure that the A-record for the Primary FQDN and essential aliases (such as univention-directory-manager) have adjusted properly. Test resolution locally:
host $(hostname -f) localhost
dig $(hostname -f)
  1. Perform a System Reboot
    While a restart of the networking service (systemctl restart networking) might apply the changes, a complete system reboot is strictly recommended to ensure all daemons cleanly bind to the new sockets.

Step 3: Post-Migration & Application Alignment

1. Active Directory Compatibility (Samba4)

Samba4 caches network locations inside internal databases. Force an Active Directory DNS structure refresh by running:

samba_dnsupdate --verbose

Monitor the Univention S4 Connector log file closely for synchronization errors or persistent references to the old network scheme:

tail -f /var/log/univention/connector-s4.log

2. Network, Routing, and Port Permissions

Unrestricted DNS resolution and SSH access are mandatory. Several internal management scripts rely on direct SSH connections back to the Primary Node. If the Primary Node is relocated behind a new firewall or proxy layer, verify that all necessary ports are explicitly allowed as documented in the official Univention Port Overview.

3. Domain-Wide Nameserver Alignment

Crucial Step: Ensure that the DNS configurations of all other nodes inside the domain (Backup, Slave, and Member nodes) are updated to point to the new IP address of the Primary Node as their primary DNS resolver.

4. Audit for Legacy IP References

After completing the core migration steps, execute a thorough search across the directory and system configuration files to catch orphaned references to the old IP footprint.

  • Search LDAP for the old IP address:
univention-ldapsearch -LLL -x -b "$(ucr get ldap/base)" | grep "OLD_IP_ADDRESS"

Remediation: Modify any returned objects using UDM or univention-ldapmodify.

  • Search configuration files inside /etc/:
grep -r "OLD_IP_ADDRESS" /etc/

Important Case Study Notes & Troubleshooting

Keycloak & App Ecosystem Alignment

Application stacks generally rely entirely on clean DNS resolution. If the FQDN remains identical, variables such as keycloak/server/sso/fqdn and umc/saml/idp-server require no manual intervention. This logic also applies to Docker-based enterprise applications.

Known Edge Case: Stale SAML Metadata in Multi-Node Keycloak Environments

During post-migration audits, you may encounter residual configuration lines pointing to old IP addresses of previously migrated nodes inside SimpleSAMLphp files, for example:

/etc/simplesamlphp/metadata.d/https:__node1.example.com_univention_saml_metadata.php:      'Location' => 'https://10.3.1.128/univention/saml/',
/etc/simplesamlphp/metadata.d/https:__node1.example.com_univention_saml_metadata.php:      'Location' => 'http://10.3.1.128/univention/saml/',

In this specific case, 10.3.1.128 represented the legacy IP address of a Backup Node hosting an inactive instance of a 3-node Keycloak Galera Cluster.

Root Cause & Resolution: These specific metadata files are automatically regenerated once the Keycloak application lifecycle scripts are triggered or re-initialized on that respective node. If identity provider anomalies or cluster synchronization failures persist on the affected node, follow the instructions in the official Univention Support Article to adjust the relevant UCR variables and modify the corresponding LDAP objects manually:
Univention Help: How to migrate from SimpleSAMLphp to Keycloak - Set UCR variables and modify LDAP object