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.

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

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.
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.
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.
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 for your sites continues through the proxy window: the new server obtains and renews Let's Encrypt certificates even while DNS still points at the old box, and the old box mirrors them weekly (this path is implemented but not yet drilled end-to-end — see Current limits).
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:

Whitelist the source IP in CSF on the target — before any key exchange. The target's lfd reads the first-contact key-scan burst as an attack and briefly blocks port 22. Add the source IP to both /etc/csf/csf.allow and /etc/csf/csf.ignore, run csf -ra, and if a block already tripped clear it with csf -tr <source-ip>. Use a dedicated, commented root SSH key so it is easy to revoke when you retire the old box.
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:

Estates with HTTPS sites: the certificate-continuity machinery is implemented but has not yet been drilled end-to-end on a live https estate — rehearse on a disposable copy first, or plan the migration with your host.
Drupal 6 and Drupal 8+ composer platforms take the per-site route and have not been exercised yet; Drupal 7 estates are the proven surface.
Pre-3.x Ægir servers are recognised and refused — no supported path yet.

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.