Architecture overview & BOA fork model

A BOA host runs an omega8cc fork of the Aegir hosting stack on Devuan, Nginx-only, Percona-only, with a Master/Satellite multi-instance layout that upstream Aegir does not have. This page fixes the mental model in place — what the layers are, where they live on disk, and exactly where BOA's fork diverges from upstream — so the rest of this section can stay concrete.

Layered view

┌──────────────────────────────────────────────────────────────┐
│ Operator (root)            Tenant (o1, o2, … via o1.ftp lshell)│
│   barracuda / boa /          Aegir UI (Satellite frontend)    │
│   octopus CLI                Restricted SFTP (o1.ftp)         │
├──────────────────────────────────────────────────────────────┤
│ Aegir Master (Barracuda)                                     │
│   /var/aegir/  aegir/distro/NNN  (one frontend per host)     │
│   central Nginx config + master/db server nodes              │
├──────────────────────────────────────────────────────────────┤
│ Aegir Satellite (Octopus)    Aegir Satellite    …            │
│   /data/disk/o1/            /data/disk/o2/                   │
│     aegir/distro/NNN          aegir/distro/NNN               │
│     platforms/  static/       platforms/  static/           │
│     sites under each platform                                │
├──────────────────────────────────────────────────────────────┤
│ Provision (Drush backend)   .drush/sys/provision             │
│   hostmaster-install / provision-verify / -install /         │
│   -migrate / -backup / -clone                                │
├──────────────────────────────────────────────────────────────┤
│ Services (host-side, managed by Barracuda)                   │
│   Nginx · PHP-FPM (multi-version) · Percona MySQL ·          │
│   Redis/Valkey · Solr (opt.) · CSF · AppArmor · Postfix      │
├──────────────────────────────────────────────────────────────┤
│ OS: Devuan (no systemd)                                      │
└──────────────────────────────────────────────────────────────┘

Two halves of Aegir: front-end and back-end

Hostmaster (front-end) is a Drupal 7 install profile (the omega8cc fork of upstream Aegir Hostmaster). Operators and tenants drive it as a web UI. Every UI action — creating a site, migrating a platform, scheduling a backup — generates a task node.

Provision (back-end) is a Drush extension that turns those task nodes into server-side actions: creating databases, writing Nginx vhosts, running drush site-install, taking dumps, copying files. Provision is installed under .drush/sys/provision — /var/aegir/.drush/sys/provision on the Master and /data/disk/<user>/.drush/sys/provision for each Octopus instance. BOA actively removes the bare upstream .drush/provision path on both Master and every Octopus user (master.sh.inc and satellite.sh.inc rm -rf .../.drush/{provision,drush_make}), so the legacy .drush/provision location never persists.

Hosting (Drupal modules) is the suite of sub-modules that provide the Drupal node types (site, platform, server, client, task, alias, package, …) and the admin UI for them. The entity model is in Entity & service model; the task plumbing is in Task queue engine.

Master + Satellite

The Master/Satellite split is a BOA-specific layering upstream Aegir does not have. Both halves are full Aegir frontends; they differ in who owns them and what they host.

A fresh BOA install creates one Master plus one Satellite (o1). More Satellites are added with boa in-octopus my@email o2 lts. The full multi-instance model — instance roots, the o1 instance-owner vs the o1.ftp lshell account, and the isolation boundary — is detailed in Multi-Octopus model.

File-system layout

The canonical paths an operator works with. The Master's instance root is /var/aegir; an Octopus instance's root is /data/disk/<user> (_ROOT="/data/disk/${_USER}", set in both OCTOPUS.sh.txt and satellite.sh.inc). The Hostmaster codebase for either root lives under <root>/aegir/distro/NNN, where NNN is a zero-padded numeric counter (_nextnum), not an upstream-style hostmaster-7.x-3.x directory.

The o1 instance owner owns /data/disk/o1/; the lshell-restricted SFTP account is the separate o1.ftp user homed at /home/o1.ftp/ (there is a matching o1.web web-runtime user). Do not conflate the instance owner with the .ftp shell account — they are distinct identities with distinct homes.

What runs continuously after install

second.sh and minute.sh are each their own per-minute cron entry (neither is launched from the other); each self-loops with sleep between passes to cover the whole minute at roughly 5-second granularity, so the effective cadence is ~5 s, not literal one-second. second.sh loops a fixed 10 passes × 5 s. minute.sh fans out the per-service auto-healing watchdogs in _ITER passes spaced _SLEEP seconds apart, box-class dependent (NORMAL = 9 × 5 s; CI = 1 × 5 s; SLOW = 3 × 18 s; overridable via _MONITOR_FANOUT_ITER / _MONITOR_FANOUT_SLEEP). The nightly owl.sh is the former daily.sh, reworked into an orchestrator that runs per-account, per-site, and global workers under aegir/tools/system/night/ (shared library night.inc.sh; workers 10-account.sh, 20-sites.sh, 90-global-post.sh); log archiving/rotation and the INI control-file conversion remain, while the old daily Drupalgeddon hacked-core check is retired post-5.10.3 — its control files /root/.force.drupalgeddon.cnf and static/control/drupalgeddon.info are auto-purged fleet-wide by BOA self-update, and the drush extension remains a manual user-space tool. The Aegir task queue is processed from cron by runner.sh — there is no resident queue daemon (see Task queue engine). The monitor stack is documented in Monitoring; the full nightly run is covered in Nightly owl.

Install & upgrade flow (high level)

A fresh install from a vanilla Devuan/Debian VPS chains, from one operator command:

1. autoinit — on a Debian base, removes systemd and migrates to the matching Devuan release. The target is version-aware, not a single universal release: trixie → excalibur, bookworm → daedalus, chimaera → daedalus, bullseye → chimaera, buster → beowulf. Skipped if already on the current Devuan. Logs to /root/.autoinit.log and /root/.autoinit-verbose.log.
2. barracuda install / upgrade — installs the host stack (Nginx, Percona, PHP-FPM, Redis/Valkey, CSF, AppArmor, …) and builds the Master Aegir frontend.
3. octopus install / upgrade — creates the first Octopus instance (o1) with its own Satellite frontend and enables Let's Encrypt.

Upgrades thereafter run via SKYNET (tags on 5.x-pro / 5.x-lts trigger automatic self-upgrade across enrolled hosts) or manually with barracuda up-lts / up-pro (the only accepted upgrade verbs are up-dev / up-pro / up-lts). The Master Hostmaster move during upgrade is handled by AegirUpgrade.sh.txt, which runs a fixed five-function pipeline (_hostmaster_mv_up, _hostmaster_dr_up, _hostmaster_go_up, _hostmaster_dr_tt, _hostmaster_mi_up) inside a settings.php-presence guard — the actual drush hostmaster-migrate runs in _hostmaster_mi_up.

Where this diverges from upstream Aegir

The omega8cc fork is authoritative for BOA behaviour: there is no meaningful upstream to rebase from, and any upstream doc that contradicts the table above is wrong on a BOA host.

Related

• Entity & service model — server / service / site / platform / client node types and the corrected permissions matrix.
• Task queue engine — the cron-driven dispatch chain.
• Multi-Octopus model — the multi-instance layout and isolation boundary.
• Control files & INI — .barracuda.cnf / .octopus.cnf and the per-instance control tree.
• Reference appendix — consolidated variable and path tables.