How-to: Best Practices for Upgrading to UCS 5.2

Knowledge Base Community
, , , ,
1

Best Practices for Upgrading to UCS 5.2

Abstract

Upgrading to Univention Corporate Server (UCS) 5.2 is a major system upgrade that involves multiple UCS versions, two Debian release upgrades, kernel changes, and internal data migrations. This article provides practical guidance, highlights common pitfalls, and explains why a step-by-step upgrade approach is strongly recommended to minimize risk and downtime.

1. General Recommendation

You do need to be careful when upgrading to UCS 5.2.

From practical experience supporting a large number of UCS upgrades, the most stable and predictable approach is to:

  • Perform minor and patch upgrades step-by-step
  • Reboot the system after each upgrade step
  • Carefully follow the pre-update checks described in the release notes
  • Ensure sufficient disk space in /boot
  • Create snapshots or backups before major upgrade steps

Skipping versions or combining too many upgrade steps significantly increases the risk of failures caused by package conflicts, kernel issues, or blocked migrations.

2. Mandatory Reading: UCS 5.2 Release Notes

Before starting any upgrade, you must read the official UCS 5.2 release notes, especially the preparation section:

https://docs.software-univention.de/release-notes/5.2-0/en/index.html#preparation-of-update

These release notes describe:

  • Known upgrade blockers
  • Required preconditions
  • Breaking changes
  • Migration steps executed during the upgrade

3. Recommended Upgrade Strategy (Step-by-Step)

3.1 Upgrade UCS 5.0 Patch Levels Sequentially to the latest

If your system is still on UCS 5.0, do not upgrade directly to UCS 5.2, without any backup or snapshot.

Proceed step-by-step:

univention-upgrade --ignoressh --ignoreterm --updateto=5.0-10

Reboot the system completely.

4. Create a Snapshot or Backup (Critical Step)

Before upgrading to UCS 5.2, power off the system and create:

  • A VM snapshot or
  • A full system backup

This provides a safe rollback option in case of unexpected upgrade failures and significantly reduces recovery time.

5. Run the Pre-Update Check Script

Before starting the actual upgrade to UCS 5.2, run the official pre-update check described in the release notes:

https://docs.software-univention.de/release-notes/5.2-0/en/index.html#script-to-check-for-known-update-issues

This script detects:

  • Unsupported package sources
  • Disk space issues
  • Known configuration conflicts
  • Incompatible system states

Common Update Blockers

A collection of frequent pre-update check failures and their resolutions is documented here:

6. Debian Release Transitions (Why This Upgrade Is Special)

The UCS 5.2 upgrade includes two Debian release upgrades:

UCS Version Debian Version
UCS 5.0 Debian 10 (Buster)
UCS 5.1* Debian 11 (Bullseye)
UCS 5.2 Debian 12 (Bookworm)
  • UCS 5.1 is not an official long-term release, but is used internally as a transition step.

Each Debian upgrade also includes:

  • New kernels
  • Updated bootloader components
  • Low-level system library changes

Kernel upgrades are one of the most common sources of upgrade issues, especially when /boot is too small.

7. Upgrade to UCS 5.1 (Transition Step)

Proceed with the intermediate upgrade:

univention-upgrade --ignoressh --ignoreterm --updateto=5.1-0

Reboot the system completely.

Check /boot Disk Space

After rebooting, ensure that sufficient space is available in /boot.

If necessary, remove older kernels after confirming the newest kernel is active:

https://help.univention.com/t/problem-ucs-5-2-upgrade-fails-during-pre-update-checks/24597#p-77718-h-2-free-space-in-boot-7

8. Upgrade to UCS 5.2

Now perform the upgrade to UCS 5.2:

univention-upgrade --ignoressh --ignoreterm --updateto=5.2-0

Reboot the system completely.

After reboot:

  • Check /boot again
  • Remove outdated kernels if required

9. Snapshot After Reaching UCS 5.2

Once UCS 5.2 is running correctly, it is strongly recommended to:

  • Power off the system
  • Create another snapshot or backup

This gives you a clean and stable rollback point for future patch-level updates.

10. Important Change in UCS 5.2-2: LDAP Migration

With UCS 5.2-2, a new LDAP attribute named univentionObjectIdentifier is introduced.

During the update:

  • A migration is executed
  • The attribute is added to all LDAP objects

Depending on the number of objects, this migration may take considerable time.

Further details:

11. Patch-Level Updates: Proceed Carefully

Patch-level updates in UCS 5.2 frequently include kernel updates. Therefore, the same step-by-step approach is recommended.

Kernel-Related Errata (Examples)

Disk Space Requirement

Always ensure at least 300 MB of free space in /boot:

https://help.univention.com/t/problem-ucs-5-2-upgrade-fails-during-pre-update-checks/24597#p-77718-h-2-free-space-in-boot-7

12. Recommended Patch-Level Upgrade Sequence

Apply patch updates sequentially and reboot when required:

univention-upgrade --ignoressh --ignoreterm --updateto=5.2-1

univention-upgrade --ignoressh --ignoreterm --updateto=5.2-2

univention-upgrade --ignoressh --ignoreterm --updateto=5.2-3

univention-upgrade --ignoressh --ignoreterm --updateto=5.2-4

13. Summary

Key takeaways:

  • Always upgrade step-by-step
  • Reboot after each major upgrade
  • Read the release notes carefully
  • Run the pre-update check
  • Watch /boot disk space
  • Expect longer runtimes due to kernel and LDAP migrations
  • Use snapshots/backups strategically

Following this approach significantly reduces the risk of upgrade failures and ensures a smooth transition to UCS 5.2.

1 Like