Moving servers & adopting Ægir — Cheat Sheet

For operators: this sheet is for people with root on their own BOA servers; hosted customers never run these tools.

Moving is two different jobs. Inside one box, the panel's Clone and Migrate tasks do it and nothing leaves the host. Across boxes, the root-side xoct, xcopy and xmass tools do it, and aegir2boa brings a vanilla Ægir 3.x server over. This page is the quick map: which tool moves what, the two rules that keep a move safe, what visitors see, and what to do when a box goes down. Everything here links to the full runbooks.

Moving in 30 seconds

1. One site, same box — the panel's Clone task (a copy under a new name) or Migrate task (onto another platform, or a rename). No root tools, and nothing leaves the box. → Site cloning & in-host migration
2. One account to another BOA box — xoct. The old box relays that account's visitors to the new one until DNS moves. → xoct & xcopy
3. A copy of one account, original still serving — xcopy. A point-in-time duplicate; the source is never frozen or proxied. → xcopy
4. The whole box — xmass: every account, database and Solr index. Live replication keeps the target current for days or weeks, so the final switch stays short. → xmass — whole-server move
5. A classic Ægir 3.x server — aegir2boa: a read-only survey, an in-place Apache-to-Nginx flip, then site-by-site adoption behind a proxy. DNS moves at your own pace. → Migrating from vanilla Ægir

Same BOA release on both ends, first

Before any cross-host move, bring both boxes to the same complete BOA release: a full barracuda and octopus run on the older one, never system alone. A target missing an nginx variable that a newer release introduced fails the box-wide config test and takes down every migrated site. xmass refuses a mismatch outright, with no override, and checks again just before the cutover touches the source, since a release can drift during weeks of syncing. xoct and xcopy leave the check to you, so do it anyway.

boa info                   # on both boxes: compare the release
wget -qO- https://files.boa.io/BOA.sh.txt | bash
barracuda up-lts
octopus up-lts all force   # on the older box; up-pro on PRO

The trees may differ (LTS at one end, PRO at the other); the release must not. xmass checks Percona too: the same series and patch level at both ends. A newer target is accepted only with _XMASS_ALLOW_PATCH_SKEW=YES, and an older one is refused with no override. xoct tolerates a difference: its logical dump lands a Percona 5.7 account cleanly on an 8.4 box when you move it there.

Changing Percona version is not a move. A box upgrades from 5.7 to 8.0 and 8.4 in place with barracuda, after codebasecheck says every codebase on it is ready — see Keeping BOA current.

→ xmass requirements · Keeping BOA current · Moving across Percona versions & verifying a migration

Dry run first, --live second

The steps that move files (transfer and pretransfer on xoct and xcopy, sync and cutover on xmass) default to a read-only dry run. It prints a [DRY-PLAN] line per store, pre-checks disk space and ends with [DRY] CLEAN or [DRY] NOT CLEAN. --live is accepted only after a clean dry run for the same account and target, and it spends that clean result, so one rehearsal never arms two live runs:

xmass sync <target-ip>          # dry run: the plan, ends CLEAN or NOT CLEAN
xmass sync <target-ip> --live   # the real transfer

The gate covers the file transfers only. Most other steps run live when you run them, and xoct export starts the account's 503 at once. aegir2boa works the same way: every acting step is a dry run until you add --live. Run xmass cutover --live inside screen or tmux; it refuses otherwise, since a dropped session would strand the source on its 503.

→ The DRY/--live gate · aegir2boa safety model

What visitors see during a move

• xcopy — nothing: the source keeps serving throughout.
• xoct — the account answers 503 from export until proxy turns the old box into its relay; the warm-up copy runs while the sites still serve. The window grows with the account's databases and number of sites, not with its files. No single-account window has been timed from the visitor's side, so there is no figure to quote.
• xmass — the data crosses before the window opens, so the window does not grow with it. Measured on test rigs, a 3-root estate came back in 2 min 10 s and an 8-root estate in 3 min 25 s; two full rehearsals on 44 sites came back in 2 min 40 s and 2 min 31 s. No production move has been timed under this order yet (the older order took 15 to 20 minutes).
• aegir2boa — each site is down only between its own export (a clean 503 with a retry hint) and its proxy cutover.

Those xmass figures are the relay-first order. On a box whose sites reach their database by anything but localhost (_THIS_DB_HOST set to the FQDN, for example), xmass keeps the older order: every site stays on 503 until the last root is renamed. The dry plan's cutover order: line says which you get.

Under the relay-first order, two things stay on 503 through the renames, minutes per root: sites whose own names carry the old box hostname, and the control panels. DNS itself is not a downtime event: the old box keeps relaying stragglers.

→ xmass: how long visitors see the 503 · The xoct window · What downtime to expect

Moving one account, or the whole box

xoct runs almost every step on the source, pointing at the target's IP; the preparation runs on both boxes, and the import on the new one. The broad order: prepare both boxes, create the account on the target and warm-copy its files while the sites still serve, export (the 503 starts), final transfer, import, then turn the old box into the relay and repoint the DNS A records. Clients keep their panel login, SSH/SFTP and SQL passwords and SSH keys. xcopy has the same shape but finishes without a relay.

xmass moves the whole box: prepare the target (one seeded account per source account), take a snapshot and start database replication, sync as often as you like for days or weeks, then cut over. It is also the clean road to a new OS: install BOA fresh at the same release on a new host, move the estate across, and switch. Afterwards xmass verify <target-ip>, run on the source, sweeps every site, symlink, certificate and panel, read-only.

The new host must run the same Percona series: when it runs Excalibur, which runs only 8.4, a Daedalus source on 5.7 is upgraded in place first.

A 200 on the home page proves little: judge a move by marker content and row counts, fetched straight from the target.

→ xoct & xcopy runbook · xmass runbook · Verifying a migration

Adopting a vanilla Ægir 3.x server

Your BOA server already has the three aegir2boa tools and keeps them current. The Ægir box needs its own copies, fetched with no BOA install, account or credentials. Set _TREE to the tree your BOA server runs:

cd /usr/local/bin
_TREE=lts   # dev, lts or pro: the tree of the BOA server the sites move to
for t in aegir2boa-preflight aegir2boa-stage1 aegir2boa-stage2; do
  wget "https://files.boa.io/versions/${_TREE}/boa/aegir/tools/bin/$t"
  chmod 755 $t
done

Use the short tree name: a path like versions/5.x-lts/… returns a success code and an "Under Construction" page, so check that head -1 aegir2boa-preflight prints #!/bin/bash. Then three stages, each reversible until DNS moves:

1. Survey — aegir2boa-preflight is read-only, writes only under /tmp, and grades each stage PASS, WARN or FAIL. Re-run it after any reboot and after the flip.
2. Flip — aegir2boa-stage1 --flip (the dry run), then aegir2boa-stage1 --flip --live: Apache to Nginx in place. Apache stays installed, so --revert is the way back; don't prune it yet.
3. Adopt — aegir2boa-stage2, site by site behind a proxy on the old box: peer, check, pre-mig, create, export, transfer, import, proxy, then the certificate sync. Until DNS moves, undoing one site is one file move on the old box.

Adopted sites arrive with Encryption off: turn it on in the new panel and let Let's Encrypt issue before you repoint DNS. The panel moves to an oN. subdomain of the new server, and client SSH sub-accounts are not carried over. The proven surface is Drupal 6 through 9 and Drupal 8+ composer platforms, from Debian or Ubuntu.

→ Migrating from vanilla Ægir · aegir2boa runbook · Reverts

When a box goes down

Read the state before acting. On the active server, xmass status shows the phase, peers, last sync and replication lag, and xoct proxy-mode --all shows each account's mode, deadline and peer.

• The proxy (old) box is down — only names still pointing at its address go dark, and no data is at risk. A rebooted proxy comes back serving on its own; if it can't be revived soon, move DNS or the CDN origin straight to the active server.
• The active server is down, with no mirror — that is a restore, not a failover: revive it, or rebuild at the same BOA release and restore from the remote backups. Budget hours to days.
• The active server is down, with a mirror — decide first: revive or promote. The emergency promotion is a by-hand checklist with sharp edges, so follow the page, and fence the failed box before it returns: its data is stale from the moment of promotion.

After any switch, run xmass verify on the relaying box and pass the current active server's IP explicitly; without it, it checks the box you just switched away from.

xmass verify <active-ip>   # relayed and direct fetch per account, plus a cron check
xoct proxy-mode --all      # each account's mode, deadline and peer

→ Failover & recovery scenarios

Which tool moves what

The Migration & cloning chapter has 12 pages in all, from these runbooks to aliases, storage relocation, import and export, proxies and failover.

If something's weird

• --live is refused with "requires a prior CLEAN dry run" → the last run for that account and target (the target alone, for xmass) was not a clean dry run, or a live run already spent it. Run the same command without --live, clear every DENY line it prints, then run --live once. The DRY/--live gate.
• xmass refuses the pair before anything moves → if it names two BOA releases, run a full barracuda and octopus upgrade on the older box and retry; if the Percona series differ, upgrade the older box's Percona in place (after codebasecheck) and retry, or move account by account with xoct; if the patch levels differ, align both ends from the same repo snapshot (a newer target can be accepted deliberately with _XMASS_ALLOW_PATCH_SKEW=YES). xmass requirements.
• Gateway errors (502/504) from the old box's address → the relay works but the active server behind it is down. Names that simply go dark mean the proxy box itself is down: no data risk, so revive it or move DNS to the active. Failover & recovery scenarios.

Going deeper

• The whole topic: Migration & cloning — the overview, the xoct/xcopy and xmass runbooks, in-host cloning, aliases, migratefs, import and export, moving across Percona versions, aegir2boa, PX0 proxies and failover.
• What the old box becomes, and retiring it in stages: PX0 proxies & xtrim.
• Moving file stores onto attached storage first: migratefs.
• Upgrading the OS in place instead of fresh install plus xmass: OS lifecycle.
• Clone and Migrate from the panel side: Sites & platforms cheat sheet.
• Setting up the box itself: Running your own BOA box cheat sheet.