Migrating from vanilla Ægir

If you run a vanilla Ægir 3.x server — the classic community Ægir, usually on Apache, with everything under /var/aegir — BOA ships a dedicated, drilled migration path that adopts your whole estate into a BOA server without a leap of faith. Every step is reversible until the final DNS cutover, and nothing acts on your sites before a read-only check has graded the box.

This page is the orientation. The full operator runbook (every command, gate, and failure mode) is the Aegir-to-BOA runbook page in the Operating guide's migration section.

What you need

• Your existing Ægir server, exactly as it is. Debian or Ubuntu, on whichever release the estate survived — both families the Ægir 3 installers supported are supported here, and the tools detect the differences between releases on their own. Nothing is installed on the server and nothing is changed until you choose to run the first acting step. The discovery step that comes before it only reads.
• A second server running BOA — that is where your estate lands. BOA is this project's hosting stack: it takes a clean Debian or Devuan server and builds the whole platform on it, Nginx, PHP, the database and an Ægir control panel included. If you have not got one yet, install it first (see the installation pages in this section) or ask your host to provide one. The migration expects a finished, healthy BOA server waiting for you, not one built along the way.
• Root SSH access on both machines, and the ability to change DNS for your domains when you are ready to switch traffic over.

You do not need to install anything on your Ægir box to look: run the discovery step first and read its report before deciding anything.

Get the tools

Three scripts do the work. They are not fetched or updated automatically by any server, so you download them yourself. Your Ægir box needs no BOA installation, no account and no credentials to get them:

cd /usr/local/bin
for t in aegir2boa-preflight aegir2boa-stage1 aegir2boa-stage2; do
  wget https://files.boa.io/versions/lts/boa/aegir/tools/bin/$t
  chmod 755 $t
done

aegir2boa-preflight and aegir2boa-stage1 run on your Ægir box. aegir2boa-stage2 goes on both machines — it is the same script, and it refuses to perform a source action on the BOA server or a target action on the Ægir box, so it cannot act on the wrong side.

One caution: use the short tree name in that URL. A path like versions/5.x-lts/… does not return "not found" — it returns a small "Under Construction" page with a success code, so a mistyped URL leaves you with a file that looks downloaded but is not a script. Check with head -1 aegir2boa-preflight, which must print #!/bin/bash.

Why not convert in place?

Because there is no safe way back from a half-converted box. BOA's layout, users, and automation differ from vanilla Ægir everywhere, so the migration works the same way BOA moves its own instances between servers: your sites are adopted remotely onto a separate BOA server, and your old server is demoted to a thin proxy that forwards visitors to the new one. Undoing any single site is a one-file move on the old box — your original configuration stays on disk untouched until you retire the machine.

The shape of the migration

1. Discovery (read-only). aegir2boa-preflight inventories the box and grades it PASS / WARN / FAIL for each stage. WARN means "proceed with named caveats"; FAIL means stop. It writes a human report and a machine contract the later tools trust — nothing else re-discovers your box.
2. Apache to Nginx, in place. Vanilla Ægir supports Nginx natively, and the whole adoption machinery is nginx-based, so the first real step flips your box to Nginx with aegir2boa-stage1. Apache stays installed and configured throughout — the revert is flipping back. Your sites are verified one by one and compared against their pre-flip responses before anything is handed over.
3. Remote adoption. aegir2boa-stage2 moves the estate onto the BOA server: each site is paused behind a clean 503, dumped with its own database credentials, shipped across, registered and verified on the new server, and only then — once the new server demonstrably answers for it — cut over to a proxy on the old box. Sites move one at a time; a problem with one never blocks the rest.
4. DNS cutover and retirement. With everything serving through the proxy, you lower DNS TTLs, repoint domains at the new server at your own pace, watch the old box's traffic drain to zero, and retire it.

Two adoption routes

The tooling picks the route from discovery output — it is never a guess:

• Per-site adoption (the default). Each site is registered natively on the BOA server, one at a time. This is the route for mixed, aged, or unusual estates. Your sites and their content move fully; the old control panel's bookkeeping (client records, task history) starts fresh.
• Whole-panel import (for uniform, current estates). If discovery shows a homogeneous, up-to-date Ægir 3.x estate, the entire control panel database can be imported and reconciled instead — preserving clients, users, and task history. The tool checks the strict preconditions itself and refuses the route if any are not met.

What to expect

• Downtime per site is the gap between its export (visitors see a clean 503 with a retry hint) and its proxy cutover — typically the time it takes to copy the site and verify it on the new server.
• Every acting command runs twice: first as a dry run that prints its plan and checks its gates, then — only if that came back clean — with --live. A failed live run always demands a fresh dry run.
• Your control panel URL changes. The adopted panel lives on the BOA server (an oN. subdomain — o1, o2, … — of the new server's hostname); the old panel URL goes dark at cutover.
• HTTPS keeps working during the move, but the new server needs its own certificate before you repoint DNS. Through the proxy window your visitors are served your existing certificates from the old box, so nothing breaks while you test. Your adopted sites arrive with Encryption switched off, though — deliberately, so a half-migrated site cannot start emailing or renewing on its own — which means the new server holds no certificate for them yet. Switch Encryption on for each HTTPS site in the new panel and let Let's Encrypt issue before you change DNS; certificate requests reach the new server through the proxy, so this works while DNS still points at the old box. The migration tool checks this and refuses to report success while any proxied HTTPS site still has no certificate on the new server.
• Client SSH sub-accounts are not carried over. The welcome email delivers the main account's new credentials; any per-client SSH sub-accounts must be recreated manually on the new server — they are not part of the automated flow.

Before you start

A few things need to be in place on both boxes before the first command:

• Let the peer command arrange reachability — before any key exchange. The target's lfd reads the first-contact key-scan burst as an attack and briefly blocks port 22, so the firewall must open before the key travels. Run aegir2boa-stage2 peer --target <ip> on the old server (it mints a dedicated, revocable key and prints the exact command to run next), run that printed peer --source command on the new server (it opens the firewall in both lists, clears any tripped block and authorises the key), then repeat the first command to confirm the connection. Each step runs dry first, --live to act.
• Keep a fresh preflight report. It is written under /tmp, which is memory-backed on many boxes and lost on reboot — re-run the preflight after any reboot and copy the .txt / .env pair somewhere durable, because the later steps refuse a report from a different host.
• Give the target a PHP pool for every version your estate needs. A Drupal 6 site needs a php56 pool; a site whose pool is missing is flagged and skipped, not migrated.
• Leave disk headroom. Roughly twice each site's database size free under /var/aegir on the source for its dump, and the whole estate plus about 500 MB free under /data/disk on the target.
• On a shared target, don't assume the next free oN account name. If billing automation or another operator already took it, the dry run fails cleanly and tells you.

Current limits

Honest edges of the path as it stands:

• The proven surface is Drupal 6 through 9: Drupal 6 (d6lts) and Drupal 7 estates — HTTPS sites included — and Drupal 8+ composer-built platforms. A Drupal 6 site does need a php56 pool on the target (see the checklist above).
• Pre-3.x Ægir servers are recognised and refused — no supported path yet.
• Both source OS families are supported and drilled, Debian and Ubuntu — the tools detect each release's differences (init system, Apache layout, Nginx and OpenSSH versions, database flavour) at run time, and the check step refuses a database pairing the target could not import: a MySQL 8.0 source (Ubuntu 20.04 and later) needs a current-generation target, and check says so before anything moves. Debian and Ubuntu estates have both been taken through the whole path end to end; only the very oldest servers (Ubuntu 12.04/14.04-era init, Apache 2.2) rely on detection that has not run against a real estate — there, read the discovery report closely and let every dry run come back clean before --live.

Where to go next

• The complete operator runbook — prerequisites, every command, the safety model, reverts, and the decommission checklist — lives in the Operating guide's migration section (the Aegir-to-BOA runbook page).
• Moving between two BOA servers instead? That is xoct — see the server migration pages in this section's Operating counterpart.