Manual BOA upgrade reference

The complete reference for barracuda up-* and octopus up-* — every mode, every argument, and the per-mode semantics as the dispatch actually implements them. Use this for finer control than the scheduled SELFUPGRADE path provides.

The minimum complete upgrade

If the host has not been upgraded in a long time, or this is the first upgrade after a fresh install, the only correct first run is a full upgrade — not any of the partial modes below:

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

In order, this:

Updates the BOA meta-installers (BOA.sh.txt → boa/barracuda/octopus shims in /usr/local/bin).
Runs the full barracuda up-lts (system stack + Ægir Master Instance).
Upgrades every Octopus Satellite Instance and its Drupal platforms.

Only after that completes cleanly should you use the partial modes for follow-on work.

Re-running the wget -qO- https://files.boa.io/BOA.sh.txt | bash one-liner is idempotent and safe to repeat. Since BOA-5.10.3 it fetches each tool per-file through a serial-gated helper (_fetch_versioned) that skips files already current, refuses to overwrite a tool that is currently running, and restores the previous copy if a download comes back empty — a zero-byte download can never destroy a working barracuda or octopus, and a failed fetch simply retries on the next run. The binaries land in /opt/local/bin, with the /usr/local/bin entries maintained as symlinks. The full self-update mechanism is in the SELFUPGRADE reference.

Always start in screen. An SSH drop mid-upgrade leaves a half-upgraded host that is painful to recover. Be logged in as root (or sudo -i first) — do not run these under sudo.

Tier token: `up-lts` / `up-pro` / `up-dev`

The tier token is validated by both meta-installers. barracuda and octopus accept only up-lts, up-pro and up-dev; anything else is rejected with Sorry, you are trying not supported command... up-lts is the free release; up-pro and up-dev require a licence. Substitute the token your host runs into every command on this page.

Silent / logged mode

The same upgrade with no terminal progress — it logs to file and emails on completion:

screen
wget -qO- https://files.boa.io/BOA.sh.txt | bash
barracuda up-lts log
octopus up-lts all force log

Silent mode answers Y to every prompt; use it when driving the upgrade from cron or a timer. Logs land in:

/var/backups/reports/up/barracuda/*
/var/backups/reports/up/octopus/*

Read the last line, not just its prefix. In silent and log modes the launcher checks the upgrade log before it exits and states the outcome on its final line: BARRACUDA upgrade completed when nothing raised an alert, or BARRACUDA upgrade completed WITH ERRORS -- review <log>, naming the log to open, when something did. octopus prints the same two forms with an OCTOPUS prefix. The ... upgrade completed prefix is deliberately unchanged in both, so a watcher — or an operator following the tool's own tail -f advice — waiting on that string still terminates on a failed run: seeing it end is not by itself a clean result. The same distinction drives the mail, a success report on the clean path and a failure alert on the other.

A deeper backend log for the barracuda pass is under /var/backups/. The completion report is emailed to _MY_EMAIL from /root/.barracuda.cnf (default [email protected]; on a BOA-hosted box the recipient is forced to <tool>@omega8.cc). There is no _EMAIL_USER_ADM variable — setting one has no effect.

By default that report is the upgrade log plus a short boa info summary. Create /etc/boa/.send-extended-report.cnf and every barracuda report — the success report and the failure alert — carries a much fuller picture: the most recent automated-codename-hop log (/root/.autoexcalibur.log, .autodaedalus.log, .autochimaera.log or .autobeowulf.log, whichever ranks highest; only one is attached, even on a box that has hopped more than once), a full ls -ltcra /root, a ps auxf process tree, aureport, the AppArmor aa-status loaded/enforce/complain counts and aa-unconfined, and boa info full in place of the short summary. The same switch applies to the installation reports boa sends after in-barracuda and in-octopus, with one difference: those carry no boa info summary by default, so there the extended block only adds boa info full — it replaces nothing.

The marker is one of five triggers, not the only one. Each of the four /root/.run-to-<codename>.cnf markers an automated OS upgrade sets produces the extended report on its own, so the /etc/boa file is really how you get that detail on an ordinary upgrade. Two things to weigh before leaving it in place — on barracuda the extended block is appended after that tool's own scrub of _NEWRELIC_KEY and _AWS_ lines from the upgrade log, and ls -ltcra /root lists every control-file marker on the box, so an extended report is a more sensitive mail than the default one. The boa installation report has no such scrub at all — nothing is stripped from it before it is sent, extended or not.

`barracuda` modes

Full upgrade (default, interactive)

barracuda up-lts

Upgrades the system stack plus the Ægir Master Instance.

System-only

barracuda up-lts system

Upgrades only the host stack (Nginx, Percona, PHP, Redis/Valkey, …) and skips the Master Ægir Instance. Runs silently (writes /var/backups/reports/up/barracuda/*, emails on completion). This is also the per-pass workhorse of the OS-codename chains. Use it to land system updates without touching the Ægir frontend.

Ægir-Master-only

barracuda up-lts aegir

Upgrades only the Ægir Master Instance (Hostmaster) and skips the host stack — the mirror of system. Like system and log it runs silently: it writes /var/backups/reports/up/barracuda/* and emails the report on completion.

Internally the mode sets _AEGIR_UPGRADE_ONLY=YES with _SYSTEM_UP_ONLY=NO in both /root/.barracuda.cnf and /var/backups/barracuda.sh.cnf, so there is nothing to set by hand. There is nothing to reset afterwards either: a later system or log run, or a plain full up-<tier>, writes _AEGIR_UPGRADE_ONLY=NO back into the same two files before it starts. For the same reason, setting _AEGIR_UPGRADE_ONLY=YES in /root/.barracuda.cnf by hand and then running a plain barracuda up-lts does not produce a Master-only pass — the mode token is the only way to ask for one.

The Master-only pass is skipped while heavy rebuilds are disarmed (mid-OS-migration, _ALLOW_HEAVY_REBUILDS=NO); on such a box the run continues as an ordinary pass instead.

On a box holding the replication-standby role marker (/root/.standby.cnf) the mode is refused outright — see On a replication standby below.

Silent full upgrade

barracuda up-lts log

Full upgrade, silent. Same log and email behaviour as system.

Percona version upgrades

In the barracuda up-lts slot:

barracuda up-lts percona-8.0       # 5.7 -> 8.0
barracuda up-lts percona-8.4       # 8.0 -> 8.4

No direct 5.7 → 8.4 jump — stage through 8.0. The full DB-version story, recovery guards and soname ladder are in Percona install + tuning.

PHP set management

barracuda php-idle disable    # disable every PHP version no site is using
barracuda php-idle enable     # re-install + re-enable previously-disabled versions
barracuda up-lts php-8.5      # force the host to a single PHP version (brief downtime)
barracuda up-lts php-max      # install all supported PHP versions
barracuda up-lts php-min      # install the recommended set (8.5, 8.4, 8.3; 8.4 default)

To persist a custom set, edit /root/.barracuda.cnf (_PHP_MULTI_INSTALL, _PHP_CLI_VERSION, _PHP_FPM_VERSION) and leave _PHP_SINGLE_INSTALL empty so the multi-install variables apply. The per-site PHP-version mechanics and the removal-protection trick are in PHP-FPM performance.

php-idle disable also rebuilds _PHP_MULTI_INSTALL in /root/.barracuda.cnf from the versions your sites actually declare (the multi-fpm.info, fpm.info and cli.info files under each instance's static/control/), so a version nothing declares is dropped from the set. Create /root/.include-php-latest.cnf to keep PHP 8.4 in that recomputed set even when no site declares it. The marker's name says "latest", but the version it adds is 8.4 specifically — not whatever the newest supported PHP happens to be — and BOA-hosted boxes get 8.4 added with or without the file.

The knob is narrower than it looks. The recompute only happens on an upgrade pass with /root/.allow-php-multi-install-cleanup.cnf present (which is what php-idle disable writes), with _PHP_SINGLE_INSTALL left empty and both /data/u and a healthy Ægir Master alias in place; the 8.4 addition is skipped on hosts still built against the legacy or EOL OpenSSL series; and during an automated codename hop the /root/.run-to-<codename>.cnf marker pins the set to versions in use, which disarms this marker even though it is also one of the things that opens the cleanup gate. Nothing in BOA creates or removes the file — it is yours to add and remove.

On a replication standby

A box holding the standby role marker (/root/.standby.cnf — see Failover and recovery) is a working BOA box: system, stack, Percona and kernel upgrades all run on it. What stands down is only the half that writes into a replicated database, where a local change becomes an errant transaction. So while the marker is present:

barracuda up-lts (and up-pro, up-dev, up-distro) runs its system flavour whatever you typed. Any flavour token other than system — including log, and including a bare command with no token at all — is rewritten, and three NOTE: lines say so. Because the system flavour is the silent one, an interactive full run becomes a silent, logged, emailed run: watch the log under /var/backups/reports/up/barracuda/ rather than the console.
barracuda up-lts aegir is refused outright.
Option tokens are not lost to the rewrite: barracuda up-lts percona-8.4 still selects the 8.4 series, and the php-* tokens still apply — they are read from their own argument slots, so such a run proceeds as a silent system-only pass that does what the option asked.
octopus refuses every run. Only octopus help and octopus info still answer.

The Ægir-master and platform halves are not skipped, they arrive from the source by replication. Both tools return to normal at promotion, when the cutover removes the marker.

Two practical consequences. The check sits before the screen spawn, so a refusal costs no session and leaves nothing to clean up. And it applies to the unattended SELFUPGRADE entries as well, which invoke these same two launchers from /etc/crontab: the scheduled full barracuda pass is steered to system, and the scheduled octopus pass is refused, with no operator action needed either way.

`octopus` modes

Single instance

octopus up-lts o1 force

Upgrades just instance o1. The force argument bypasses the already-upgraded skip (_satellite_check_if_already_upgraded), which is why it is the recommended form for manual upgrades where you want the work to run unconditionally.

All instances

octopus up-lts all force

Iterates every Octopus instance on the host.

Silent variants

Append log:

octopus up-lts o1 force log
octopus up-lts all force log

The already-up-to-date skip, and silencing it

When an instance's ~/log/octopus_log.txt already records the release and tier this octopus build carries, the run prints a notice and skips that instance:

TXT

This Ægir Instance o1 is already up to date!

That check is bypassed by the force token, which never reaches it.

/etc/boa/.silent-octopus-upgrade.cnf changes it, and it changes two things, not the one its name advertises:

The notice is suppressed — nothing is printed for an already-current instance.
The skip becomes a re-run — the skip flag is set in the same branch that prints the notice, so with the marker in place it is never set, and the run carries on and upgrades the instance again.

One consequence is worth knowing before you set this fleet-wide. On an already-current instance the mode token has been cleared by the time the upgrade proceeds, so the re-run takes the catch-all branch of _up_mode and upgrades frontend and platforms whatever token you typed — octopus up-lts o1 aegir on a current instance does the same work as both. And octopus up-lts all stops being a cheap no-op on a fully current host and becomes a complete re-upgrade of every instance. Set the marker where that is what you want (an unattended re-run that must not print a prompt-shaped notice), and remove it to get the skip back.

Per-component: `aegir` / `platforms` / `both` / `force`

The trailing mode token selects what part of the Octopus upgrade runs. The behaviour is set by octopus's _up_mode, and it is worth getting exact because the modes are not symmetric:

Mode	`_HM_ONLY`	`_PLATFORMS_ONLY`	Effect
`aegir`	set to `YES`	set to `NO`	Ægir frontend only
`platforms`	set to `NO`	set to `YES`	Drupal platforms only
`both`	set to `NO`	set to `NO`	frontend and platforms
`force`	set to `NO`	set to `NO`	identical to `both`
(any other / omitted)	reset to `NO`	reset to `NO`	frontend and platforms

octopus up-lts o1 aegir          # frontend only (sets _HM_ONLY=YES)
octopus up-lts o1 platforms      # platforms only
octopus up-lts o1 both           # both
octopus up-lts o1 force          # both (plus the already-upgraded-skip bypass)

Two things to be clear about, because the obvious-sounding reading is wrong:

force is identical to both in _up_mode — both share one branch that sets _HM_ONLY=NO and _PLATFORMS_ONLY=NO. force does not "honour the cnf"; its only distinct effect is bypassing the already-upgraded skip.
The catch-all branch resets _HM_ONLY=NO — it does not preserve a cnf _HM_ONLY=YES. The only mode that sets _HM_ONLY=YES is the explicit aegir branch. There is no none mode token; to upgrade the frontend only, use aegir.

Combine any mode with log:

octopus up-lts all aegir log
octopus up-lts o1 platforms log

Config-file vs. CLI precedence

Every command reads:

/root/.barracuda.cnf
/root/.${USER}.octopus.cnf

CLI arguments win over config-file values. Use the config files for persistent defaults and CLI tokens for one-off overrides — with the octopus mode caveat above firmly in mind (force/both and the catch-all reset _HM_ONLY).

Octopus platforms reminder

BOA no longer installs every bundled platform on Octopus install or upgrade. To add platforms, edit ~/static/control/platforms.info in the instance and run octopus up-lts o1 platforms.

When the manual path fails

If barracuda up-lts hangs or errors, check, in order:

/var/log/boa/ — high-level operational log.
/var/backups/reports/up/barracuda/* — most recent barracuda upgrade log (silent + log modes write here).
/var/backups/ — deeper backend log for barracuda.

Common upgrade-time failure modes (APCu/Drush/cron, SMTP/SSL, the SQL tunnel) are in Troubleshooting.

Built-in help

The CLIs carry the live argument list — trust them over any page when they disagree, since they update with the binary:

barracuda help
octopus help

SELFUPGRADE reference — scheduling these commands via _AUTO_UP_*.
Automated codename upgrades — where barracuda up-<tier> system (the host's own tier) is the per-pass engine of the OS chain.
Percona install + tuning — the percona-* upgrade tokens in depth.
Reference appendix — consolidated command and _VAR tables.