Multi-Octopus model

The Master + N-Satellites layout is BOA's defining departure from upstream Aegir. Upstream is single-instance per host (or multi-server distributed); BOA runs one Master plus any number of independent Octopus instances on a single Devuan box, each a self-contained Aegir Satellite with its own frontend, Drush, platforms, and database namespace. This page is the operator reference for that model — the instance roots, the identity split between the instance owner and its lshell account, the isolation boundary, and how to add and configure instances.

Master vs Octopus instance

Master (Barracuda) Octopus instance (Satellite)
System owner aegir o1, o2, … (one per instance)
Managed by barracuda CLI octopus CLI
Instance root (_ROOT) /var/aegir /data/disk/<user>
Hostmaster codebase /var/aegir/aegir/distro/NNN /data/disk/<user>/aegir/distro/NNN
Master Drush alias hm.alias.drushrc.php hostmaster.alias.drushrc.php
Hosts tenant sites? No Yes
Count per host exactly 1 1..N

The Master holds the central Nginx vhost set and the master/db server nodes; Octopus instances attach to those and host the actual Drupal sites. A fresh install builds the Master plus o1.

Instance identities — the three users per instance

Each Octopus instance involves up to three distinct system identities. Do not conflate them — they have different homes and different roles:

Identity Example Home Role
Instance owner o1 /data/disk/o1/ Owns the Aegir Satellite, platforms, sites, DB user namespace. Runs the per-instance Drush + dispatch.
lshell SFTP sub-user o1.ftp /home/o1.ftp/ Restricted SFTP/shell account for the tenant (lshell / mysecureshell, member of lshellg). static/ symlinks back into the instance root.
web-runtime user o1.web — Identity used for per-site web runtime separation.

The tenant's restricted shell is the o1.ftp account at /home/o1.ftp/, not the o1 instance owner at /data/disk/o1/. The o1.ftp home's static/ is a symlink back to /data/disk/o1/static, which is why a tenant browsing their SFTP home sees their platforms — but the privileged instance owner and the jailed SFTP user remain separate identities.

Per-instance layout

Under each /data/disk/<user>/:

/data/disk/o1/
  aegir/distro/NNN/        ← Satellite Hostmaster Drupal codebase
  .drush/                  ← per-instance Drush aliases
    sys/provision/         ← per-instance Provision backend
    hostmaster.alias.drushrc.php
  platforms/               ← BOA-bundled platform codebases
  static/                  ← custom platforms + control tree
    control/               ← per-instance .info toggles
    <platform>/            ← custom platform roots
  config/                  ← generated Nginx config for this instance
  backups/                 ← per-site backup tarballs (flat <uri>-<ts>.tar.gz)
  aegir.sh                 ← the dispatch entry point (drush hosting-dispatch)

Each instance's Provision is under .drush/sys/provision (the bare .drush/provision path is actively removed). Each instance has its own generated Nginx config under config/, its own platform set, and its own aegir.sh dispatch script (see Task queue engine).

Isolation boundary

The Master/Satellite split is the BOA security boundary. Because each instance runs under its own system user with its own /data/disk/<user> home and its own DB-user namespace, a Satellite user cannot touch another Satellite's sites, files, databases, or backups. Combined with the o1.ftp lshell jail for tenant SFTP, this is what lets a single host carry many mutually-distrusting tenants. The hardening details — jail config, per-instance DB grants, the multi-Aegir security model — are in Security.

Per-instance control & dispatch

Each instance is configured by its own control file and runs its own dispatch pass:

  • Control file — /root/.${USER}.octopus.cnf (_octCnf), e.g. /root/.o1.octopus.cnf. Per-instance overrides (plan tier, platform list, PHP version, queue cadence) live here, layered over the host-wide /root/.barracuda.cnf. The full variable set is in Control files & INI.
  • Per-instance .info toggles — under /data/disk/<user>/static/control/, e.g. run-aegir-queue.info to opt a CI-class instance into automatic queue processing.
  • Dispatch — runner.sh iterates /var/xdrago/run-<USER> for every instance, pausing a random 2–10 s between instances; each run-<USER> ends in that instance's aegir.sh → drush @hostmaster hosting-dispatch. The queue is therefore drained per instance, independently.

Adding an Octopus instance

A new instance is created with boa in-octopus (alias in-oct):

boa in-octopus you@example.com o2 lts

This provisions the o2 instance owner, the o2.ftp lshell sub-user, the o2 Satellite frontend at /data/disk/o2/aegir/distro/NNN, its Drush + Provision, its platforms from the plan's platform list, and its /root/.o2.octopus.cnf control file. The instance's queue cadence (.fast.cron.cnf / .slow.cron.cnf) is set from its plan tier — boxes with ≤ 4096 MB RAM force every instance Slow regardless.

Multi-server topologies

Aegir also supports topologies BOA does not typically deploy — a separate remote Percona DB host shared by several web nodes, or distributed web servers serving the same platform (the hosting_web_cluster / hosting_web_pack modules, N-graded in BOA). The node types exist and work, but the dominant BOA pattern is single-host: web + db on one Devuan VM, with the task queue dispatched per-instance by cron on the Master. A non-standard distributed topology may surprise SKYNET and the monitor stack — deploy with care.

Related