Multi-Octopus model

The Master + N-Satellites layout is BOA's defining departure from upstream Ægir. 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 Ægir 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

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:

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-Ægir security model — are in Security.

One thing the Master does not partition per instance is the Nginx domain namespace. Every Octopus instance publishes into the central Nginx vhost set, and BOA does not deduplicate domains across instances — the instances are unaware of each other. Installing a site for the same domain on two instances therefore collides, so avoiding duplicate domains across instances is the operator's responsibility.

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 [email protected] 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.

Suspending an instance

boa suspend <user> turns off web serving for one Octopus instance: every site under that account answers 503 Service Unavailable with a neutral "temporarily unavailable" page, and boa unsuspend <user> restores it. The intended use is billing enforcement — a client with an overdue invoice — but nothing about the mechanism is billing-specific. Both commands are instant and idempotent (suspending an already-suspended instance just reports the current state), affect only the named instance, and an unknown or nonexistent instance is refused with a non-zero exit.

boa suspend o3
boa unsuspend o3

The 503 carries Retry-After: 3600 and Cache-Control: no-store, so nothing downstream caches the outage page, and BOA purges the Nginx speed cache at both toggle points — the 503 appears the instant you suspend and clears the instant you unsuspend.

Suspend deliberately touches nothing else: no files, databases, vhosts or certificates change, and SSH/SFTP for the account's users keeps working. Only front-end web requests are short-circuited — Drush, Ægir tasks and cron stay fully functional, so the Ægir frontend keeps managing the account's sites while it is suspended.

The switch is a root-owned flag at /data/conf/suspended/<user>.pid (its contents are the suspension epoch, an operator breadcrumb). It lives outside the account tree on purpose — /data/conf is root-owned, so the account owner cannot remove it through shell or SFTP access. The global settings include, which every hosted site loads before bootstrap, answers a flagged account with the 503 short-circuit; boa unsuspend removes the flag and purges the speed cache.

Suspend is separate from the two mechanisms it resembles. log/CANCELLED marks an instance for cleanup/purge and arms vhost removal on the next barracuda up-* — a suspended instance never enters that machinery. static/control/http-off.pid is the migration web-off gate managed by xoct / xmass (Cross-host migration); it lives inside the account tree and serves a cacheable maintenance page. Suspend is neither: it is a reversible, cache-safe web-off toggle that leaves the instance otherwise fully managed.

Multi-server topologies

Ægir 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

• Architecture overview — the layered model and file-system layout.
• Entity & service model — the node types each instance manages.
• Task queue engine — the per-instance dispatch chain.
• Security — the isolation/jail hardening detail.
• Control files & INI — .barracuda.cnf / per-instance .octopus.cnf.
• Reference appendix — the consolidated configuration-variable and command indexes.