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:

  1. Updates the BOA meta-installers (BOA.sh.txt → boa/barracuda/octopus shims in /usr/local/bin).
  2. Runs the full barracuda up-lts (system stack + Ægir Master Instance).
  3. 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 license. 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/*

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 notify@omega8.cc; 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.

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 help advertises an aegir mode ("upgrade only Ægir Master Hostmaster"), but the CLI token does not work — do not rely on it:

barracuda up-lts aegir      # does NOT do a Master-only upgrade

The argument parser only recognises log, system, disable and enable as modes; aegir is not on that list, so it is discarded and the run falls through to a plain full interactive upgrade with _AEGIR_UPGRADE_ONLY forced to NO. It never runs a Master-only pass and never emails a report. (There is a matching but unreachable handler in the dispatch, so the intent existed — the token is simply dead.)

To actually skip the host stack and upgrade only the Ægir Master Instance (Hostmaster), set the config variable by hand before a normal full run:

sed -i 's/^_AEGIR_UPGRADE_ONLY=.*/_AEGIR_UPGRADE_ONLY=YES/' /root/.barracuda.cnf
barracuda up-lts

_AEGIR_UPGRADE_ONLY=YES (with _SYSTEM_UP_ONLY=NO) is honoured by the Barracuda engine and runs the Master upgrade only. Reset it to NO afterwards so later runs upgrade the full stack again.

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.

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

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:

  1. /var/log/boa/ — high-level operational log.
  2. /var/backups/reports/up/barracuda/* — most recent barracuda upgrade log (silent + log modes write here).
  3. /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

Related