Upgrading the operating system

Underneath BOA is an operating system: Devuan. Every so often Devuan puts out a whole new release, with a new codename — Beowulf, Chimaera, Daedalus, Excalibur, in that order, oldest to newest. Moving your box from one codename to the next is a big, whole-system change, and it is the one upgrade BOA does not do quietly in the background. You start it on purpose, when you decide the time is right.

The good news: BOA does the hard part for you. There's a guided, automated path that walks the operating system forward one codename at a time, running the normal upgrade and rebooting between each step, until you land on the release you asked for. You point it at a target, start it, and wait.

This page is the safe, one-path way to do that. Follow it in order and don't skip any step.

First, bring BOA fully up to date

Start from a current box. Refresh the BOA installers and run one ordinary system upgrade so the codename move starts from a clean, up-to-date base:

screen
wget -qO- https://files.boa.io/BOA.sh.txt | bash
barracuda up-lts system

Let that finish before you go on. (screen keeps it running if your SSH connection drops.) This is a normal, safe BOA upgrade — the small kind BOA does all the time — not the codename move itself. It just makes sure nothing stale gets dragged across.

Before the codename move: take a snapshot

This is the one rule with no exceptions.

A codename upgrade rewrites the operating system out from under a running server, across several reboots. It almost always works. But if it doesn't, there is no in-place rescue — the only way back is to restore the whole machine from a backup you took beforehand. So take that backup first, and prove it works:

  1. From your hosting provider's control panel, take a full snapshot of the VM (the whole disk, not just some files).
  2. Test the snapshot. Restore it into a fresh throwaway VM and confirm that VM boots and your BOA host comes back to life. A backup you haven't tested is a hope, not a safety net.
  3. Only once the restored copy works, come back here and continue.

If taking and testing a snapshot isn't something you can do on your host, stop here. Don't run a codename upgrade on a box you can't restore.

Give the box a clean reboot first

Before the big move, make sure the machine reboots cleanly on its own today. Use BOA's own reboot, which shuts the stack down gracefully first:

boa reboot

Wait for it to come back, then log in again. If that plain reboot has any trouble — it doesn't come back, services don't start, the network is unreachable — fix that first. A machine that already struggles to reboot will not survive a chain of reboots. Don't proceed until a simple reboot is boringly reliable.

Point BOA at a target and start it

The whole upgrade is driven by a tiny marker file you create. There is one driver for each Devuan target, and each one watches for its own marker:

Target codename Marker file you create When to pick it
Daedalus /root/.run-to-daedalus.cnf The recommended target. Where almost everyone should land.
Excalibur (newest) /root/.run-to-excalibur.cnf Newest, still bleeding-edge for production — and needs Percona 8.4 first (see below).
Chimaera /root/.run-to-chimaera.cnf The entry point for a very old box (Debian Jessie or Stretch), which can't reach Daedalus in one go.
Beowulf (oldest) /root/.run-to-beowulf.cnf An older intermediate — rarely chosen as a final target on its own.

You create exactly one marker — the codename you want to end up on — and then start the process. For most boxes that's Daedalus:

touch /root/.run-to-daedalus.cnf
service clean-boa-env start

That's the whole trigger. The moment the service starts, BOA takes over.

Create only the one marker you want. If more than one .run-to-*.cnf marker is present, BOA doesn't stop to ask — it silently picks the newest codename among them and ignores the rest (the order it checks is Excalibur, then Daedalus, then Chimaera, then Beowulf). So an old, forgotten marker for a newer target could quietly send the box somewhere you didn't mean. If you're unsure, delete any stray .run-to-*.cnf files first and leave just the one.

Not sure which target to pick? Pick Daedalus. It's the recommended target for production, and the driver will carry you there from wherever you are now — even across several codenames — one hop at a time. Excalibur is newer but still too new to lean on in production, and it has an extra prerequisite (below); leave it until you have a specific reason.

Choosing Excalibur? Move your database to Percona 8.4 first. Excalibur runs only on Percona 8.4, and the driver will refuse to start until your database is there. You can't jump straight from the default 5.7 to 8.4 — go through 8.0 on the way, one step at a time, on your current system before you begin:

barracuda up-lts system percona-8.0
barracuda up-lts system percona-8.4

Do this while still on Daedalus (or your current codename), confirm the database is healthy, then create the .run-to-excalibur.cnf marker. Aiming for Daedalus instead? You can ignore all of this — Daedalus is happy on the default Percona 5.7.

What happens next, and how long it takes

Once started, the driver does the work in a loop:

  • It looks at which codename you're on now and figures out the next codename on the road to your target.
  • It runs the standard BOA upgrade for your edition — you don't have to tell it whether you're on the free or licensed edition; it already knows and runs the right one for you.
  • It reboots.
  • Then it does it again for the next codename, and the next, until you arrive at the target you asked for.

So a single marker can carry you across several codenames automatically, with a reboot between each one.

This part is slow, and the quiet is normal. How long it takes depends on how many codenames you're crossing and how fast your disk is — anywhere from roughly half an hour for a single hop to a couple of hours for a long chain. During it you'll see:

  • Long stretches where the terminal sits still and nothing seems to be happening. That is the installer working, not a hang — leave it alone.
  • The machine rebooting more than once. That's expected; each reboot is one codename done.
  • Your SSH session dropping when it reboots. Wait a minute or two and reconnect.

Do not interrupt it, power-cycle the box, or start typing commands to "help." The only time to step in is if a reboot never comes back after several minutes — and even then, the answer is the snapshot from step one, not improvising on a half-upgraded box.

Confirm you arrived

When you can log back in and things are quiet, check which codename you're on:

cat /etc/devuan_version

If it names your target codename (for example daedalus or excalibur), you're done — the operating system has moved and BOA has rebuilt itself on top of it.

It's also worth glancing at your sites in a browser to confirm everything is serving normally. If BOA is still settling right after the final reboot, give it a few minutes and check again before worrying.

What this path does not cover

The guided path above handles the normal case: an existing BOA box moving forward to a newer Devuan codename. It also copes with a BOA box that's still on a recent Debian release under the hood — the driver treats that as one more step and carries it onto Devuan for you, so you don't need to do anything special for that.

A couple of situations, though, fall outside this path and need a more experienced hand:

  • Staying on Debian — a Debian-to-Debian move that doesn't end up on Devuan. This path always lands you on Devuan; it isn't the tool for keeping a box on Debian.
  • Old or unusual starting points — a box too old (or on a release too new) for the driver to place on the codename ladder. If the box is outside the supported range, the driver won't guess: it stops with a message naming the oldest and newest systems it handles, and changes nothing. That's the safe outcome, not a failure — but sorting out where such a box goes next is a job for the advanced path below.

(Setting up a brand-new, empty Debian VPS to run BOA for the first time is a different job entirely — that's covered in Debian to Devuan in this area, not here.)

If you're in one of the two cases above, don't force this path. Hand it off:

Advanced (root required): Operating → Codename upgrades — the full operating-system upgrade reference: supported starting points and ranges, database sequencing across the chain, hosting-provider reboot caveats, and the onward pointer to the classic per-hop path for cases this page deliberately leaves out.

Related