Classic major OS upgrade

The explicit per-hop path for major OS upgrades: set exactly one _${FROM}_TO_${TO}=YES control variable in /root/.barracuda.cnf, then run barracuda up-lts system. This is the manual alternative to the automated codename chain — the same per-codename machinery, but you name each hop and run each pass yourself.

Reach for the classic path when you need finer control than the automated drivers give: an intermediate Debian-to-Debian hop, stopping at a specific codename, or staying on Debian rather than migrating to Devuan.

Backup, test the backup, then proceed. This path involves more manual intervention than the automated one, so the snapshot discipline matters more, not less. Take a fresh VM snapshot, restore it to a throwaway VM, verify it boots and BOA works, then proceed. There is no in-place rollback.

Pre-flight

# Refresh the BOA meta-installers
wget -qO- https://files.boa.io/BOA.sh.txt | bash

# Clean baseline pass
screen
barracuda up-lts system

# Reboot and confirm boot is clean before triggering the hop
boa reboot

If the reboot is not clean, fix it before setting any _${FROM}_TO_${TO} variable.

Devuan → Devuan hops

Edit /root/.barracuda.cnf and set exactly one of:

_DAEDALUS_TO_EXCALIBUR=YES   # Daedalus → Excalibur
_CHIMAERA_TO_DAEDALUS=YES    # Chimaera → Daedalus
_BEOWULF_TO_CHIMAERA=YES     # Beowulf → Chimaera

Then run the upgrade pass:

barracuda up-lts system

Each variable drives a single codename advance. To walk multiple codenames, complete one hop (including its reboot), confirm the host is stable, then set the next variable and run another pass.

Debian → Devuan hops (the migration path)

_TRIXIE_TO_EXCALIBUR=YES     # Debian 13 → Devuan Excalibur
_BOOKWORM_TO_DAEDALUS=YES    # Debian 12 → Devuan Daedalus
_BULLSEYE_TO_CHIMAERA=YES    # Debian 11 → Devuan Chimaera
_BUSTER_TO_BEOWULF=YES       # Debian 10 → Devuan Beowulf
_STRETCH_TO_BEOWULF=YES      # Debian  9 → Devuan Beowulf
_JESSIE_TO_BEOWULF=YES       # Debian  8 → Devuan Beowulf

These pairings match the codename map in lib/functions/system.sh.inc and the auto* drivers: Buster/Stretch/Jessie all land on Beowulf as their Devuan entry point, then chain forward from there.

Debian → Debian hops (not recommended)

BOA is no longer regularly tested on Debian. Use only with a specific reason to stay on Debian, and accept the testing gap.

_BOOKWORM_TO_TRIXIE=YES      # Debian 12 → Debian 13
_BULLSEYE_TO_BOOKWORM=YES    # Debian 11 → Debian 12
_BUSTER_TO_BULLSEYE=YES      # Debian 10 → Debian 11
_STRETCH_TO_BUSTER=YES       # Debian  9 → Debian 10
_JESSIE_TO_STRETCH=YES       # Debian  8 → Debian  9

Percona sequencing

  • Daedalus defaults to Percona 5.7. Stage forward in place with barracuda up-lts system percona-8.0 then barracuda up-lts system percona-8.4. No direct 5.7 → 8.4 jump.
  • Excalibur requires Percona 8.4. No 5.7 or 8.0 path on Excalibur — stage the DB to 8.4 on Daedalus first, then take the _DAEDALUS_TO_EXCALIBUR hop.

The staged mechanics and recovery guards are in Percona install + tuning.

After the hop

Unlike the automated chain, a classic barracuda up-<tier> system hop does not auto-deactivate unused PHP versions. The automatic cleanup (_php_if_versions_cleanup_cnf → _AUTO_PHP_CLEANUP) fires only when a run-to-*.cnf marker is present or you have set the /root/.allow-php-multi-install-cleanup.cnf marker yourself — and only on an UPGRADE pass on a host that already carries an Octopus instance (/data/u) and a healthy Ægir Master. On the classic path you drive that pruning explicitly:

barracuda php-idle disable   # deactivate every PHP version no site is using
barracuda php-idle enable    # re-install previously-disabled versions

php-idle disable is what writes the .allow-php-multi-install-cleanup.cnf marker; php-idle enable removes it and rebuilds the disabled versions.

ICU, resolvconf and the .top-* marker changes on the modern-codename path are the same as the automated path.

Classic vs automated — which to use

  • The automated drivers cover four Devuan targets — Beowulf, Chimaera, Daedalus and Excalibur (one auto* driver each) — and walk the whole chain from one trigger. There is no automated driver for a Debian → Debian hop.
  • The classic path supports every codename in the supported set, including the Debian → Debian hops the automated drivers cannot do, but you drive each step.
  • From a typical start (Buster, Bullseye, Bookworm, Beowulf, Chimaera) heading to Daedalus, prefer the automated path. Use the classic path for exotic intermediates or fine control.

Related