/root/.${USER}.octopus.cnf reference

One file per Octopus instance — ${USER} is the instance's Unix username (o1, o2, …). Each Octopus instance gets its own config, fully independent of other instances on the same host. A host running o1, o2, o3 has three separate files: /root/.o1.octopus.cnf, /root/.o2.octopus.cnf, /root/.o3.octopus.cnf. Editing one does not affect the others.

The editable template lives in BOA source at lib/settings/octopus.sh.cnf. It is authoritative for every operator-settable variable name, default, and condition. A few identity variables (below) are not in that template — BOA writes them into the deployed /root/.${USER}.octopus.cnf at install time. This page is the topical guide.

Variable families

Instance identity (installer-managed)

These are written into the deployed file by the octopus / boa installer, not edited from the template:

_USER                Octopus instance system account (seeded from _USER=o1 per
                       instance, e.g. o1, o2)
_MY_OCTO_EMAIL       Instance owner email — Ægir admin notifications
                       (installer-written, but operator-editable — see below)
_DOMAIN              Ægir control panel URL (e.g. o1.f-q-d-n)

_MY_OCTO_EMAIL is the exception in this family: editing it later is supported. If you skipped the admail= token at install time, the admin address was derived (root@<your-hostname>, notices landing in the local root mailbox) — and changing it afterwards is exactly one edit: set _MY_OCTO_EMAIL in /root/.<user>.octopus.cnf. The installer generates that file only when it does not exist, so your edit persists across every upgrade, and the notice senders (nightly account mailer, release notices) re-read the value on each run — no upgrade pass needed. Two boundaries: it must differ from the client-level panel account's address (the installer refuses an identical pair by design), and it does not touch the panel admin account's own email — that one you change in the control panel itself.

Once initial install sets _DOMAIN, subsequent upgrades read it back from the per-instance log snapshot (/data/disk/${USER}/log/domain.txt) rather than this file.

Platform tree control

_PLATFORMS_LIST      Platform symbols to install (default empty; ALL or an explicit
                       list of distro symbols — the full symbol map is below)
_BACKDROP_SUPPORT    YES (default) / NO — build the Backdrop CMS (BDR) platforms;
                       set NO to skip Backdrop on this instance
_GRAV_SUPPORT        YES / NO (default NO) — opt-in Grav CMS support: the GRV
                       platform, the panel module and per-instance staging of
                       official release archives; mirror the same value in
                       /root/.barracuda.cnf to enable the system layer (the
                       grav CLI wrapper) alongside
_TXP_SUPPORT         YES / NO (default NO) — opt-in Textpattern CMS support: the
                       TXP platform, the panel module and per-instance staging
                       of official release archives; mirror the same value in
                       /root/.barracuda.cnf to enable the system layer alongside
_HOT_SAUCE           YES / NO (default NO) — build a new Satellite with latest code
                       on install; YES forces a new serial on install AND upgrade
_USE_CURRENT         YES (default) / NO — when YES, reuse the current shared
                       platforms tree and avoid duplicate platforms on upgrade;
                       set NO to force a fresh set of all platforms (increased
                       serial) on upgrade. NO is useful only when a newer Drupal
                       core ships. Has no effect while _HOT_SAUCE=YES.

_PLATFORMS_LIST in this file is install-time only. Every octopus up-dev/up-pro/up-lts run rewrites the line to _PLATFORMS_LIST=none before the build stage, so editing it on an existing instance changes nothing. The standing per-instance source is the tenant control file /data/disk/<user>/static/control/platforms.info, which overrides this value on every run — the run logs NOTE! Custom Platforms List: … when it picks the file up, and falls back to the cnf value when the file is empty. That file replaces this value rather than adding to it, so pinned symbols mean the instance skips distributions added in future releases, while the keyword ALL never skips anything. The account owner can drive the same upgrade without root by touching ~/static/control/run-upgrade.pid next to it.

_USE_CURRENT=YES (the default) keeps opcache memory low by reusing existing shared platform code. Set _USE_CURRENT=NO only when you genuinely want every platform rebuilt with a new serial number.

Platform symbol map

_PLATFORMS_LIST (and a tenant's ~/static/control/platforms.info) accept these symbols, listed in a single line or one per line. The special keyword ALL installs every available platform, including ones added by future BOA releases.

Older cores and distributions need matching legacy PHP versions installed — not all supported PHP versions are present by default, since BOA deactivates versions no hosted site uses. Re-enable them with barracuda php-idle enable (or reinstall all with barracuda up-lts php-max) before installing older platforms.

Tenant + instance behaviour

_AUTOPILOT           YES / NO (default NO) — silent mode for octopus install/upgrade
_HM_ONLY             YES / NO (default NO) — upgrade Ægir Hostmaster only (skip platforms)
_PLATFORMS_ONLY      YES / NO (default NO) — rebuild platforms only (skip Hostmaster)
_DEBUG_MODE          YES / NO (default NO) — verbose (debug) install/upgrade
                       output for the whole octopus chain, incl. Drush debugging
_DL_MODE             BATCH (default) | GIT | OLD — install source mode
_MY_OWNIP            Web server IP if non-default (default empty)
_LOCAL_NETWORK_IP    Web server IP for localhost mode (default empty)
_FORCE_GIT_MIRROR    "" (default) | github | gitlab
_THIS_DB_HOST        localhost (default) | FQDN | literal name (→ remote-DB mode)
_THIS_DB_PORT        Database port (default 3306; 6033 for ProxySQL, auto-managed)
_DNS_SETUP_TEST      YES (default) / NO — skip DNS testing during this upgrade

_PLATFORMS_ONLY now persists across octopus runs the same way _HM_ONLY does: it is written into the deployed file at install and back-filled with the default on upgrade when absent, so a value set here survives every subsequent run.

Per-instance cleanup retention

_DEL_OLD_EMPTY_PLATFORMS  Delete empty verified platforms > N days old (default 0 = off)
_DEL_OLD_BACKUPS          Delete Ægir / b-migrate backups > N days old (default 0 = off)
_DEL_OLD_TMP              Delete sites temp files > N days old (default 0 = off)

Each defaults to "0" (disabled). Useful for housekeeping on hosts that accumulate artefacts.

Nightly cleanup + notification per-account overrides

Five ghost-cleanup flags gate what BOA's ghost reapers may move aside for this account. Each also exists system-wide in barracuda.cnf; YES in either file enables the move, so the per-account flag opts one account in — a per-account NO cannot veto a system-wide YES:

_GHOST_PLATFORMS_CLEANUP   YES / NO (default NO) — ghost/empty platform registrations
_GHOST_VHOSTS_CLEANUP      YES / NO (default NO) — nginx vhosts with no matching site alias
_GHOST_SITES_CLEANUP       YES / NO (default NO) — site registrations (alias + vhost)
                             whose site directory is gone
_GHOST_SITE_FILES_CLEANUP  YES / NO (default NO) — additionally move a ghost site's
                             leftover files directory
_GHOST_ALIASES_CLEANUP     YES / NO (default NO) — stale alias copies in the
                             limited-shell FTPS user tree (48h first-sighting
                             hold; front-end companions never touched)

Left at the default NO (here and in barracuda.cnf), the reapers only detect and log ghosts (dry-run) and move nothing. When enabled the move is reversible — every item lands in the account's undo/ directory, never deleted. _GHOST_SITE_FILES_CLEANUP is kept separate because it touches site data, not just registrations. The first four act in the nightly run; _GHOST_ALIASES_CLEANUP is acted on by the limited-shell user manager on its own cadence. All five are persisted per instance: written into the deployed file at install and appended with defaults on upgrade when absent. Detection rules, cadence, safeguards, and the always-on interlocks are on Ghost cleanup.

On omega8.cc-hosted servers (hostname ending in .aegir.cc) the global _GHOST_*_CLEANUP family — all six flags, the alias sweep included since it gained the 48h first-sighting hold — is seeded to YES in barracuda.cnf, and this file's five per-account flags are seeded to YES the same way (only when the line is absent, so an operator-set value is never overwritten). Note the flag test is a logical OR of the two files, so a per-account NO cannot override a global YES.

Two related overrides are deliberately not in the template or written by the installer: _LE_CLIENT_NOTIFY and _GHOST_CLIENT_NOTIFY. The nightly per-account worker sources this file after loading the global run context, so manually adding _LE_CLIENT_NOTIFY=NO here disables the client-facing Let's Encrypt renewal-failure notices for this account only, and _GHOST_CLIENT_NOTIFY=NO likewise silences the ghost-site notices for this account. Only the value NO disables (case-insensitive; quotes and whitespace are stripped), and the per-account value wins over the global barracuda.cnf setting. The LE notice pipeline is described on SSL operations; the ghost-site notice on Ghost cleanup.

PHP per instance

_PHP_FPM_VERSION             PHP-FPM version for this Satellite (default 8.4)
_PHP_CLI_VERSION             PHP-CLI version for this Satellite (default 8.4)
_PHP_FPM_WORKERS             AUTO (default) | integer override
_PHP_FPM_TIMEOUT             AUTO (default, keeps TTL 180) | a value >60 and <180
_PHP_FPM_MAX_CHILDREN_FORCE  AUTO (default) | integer — pin exact pm.max_children
                               (values below 8 are raised to 8)
_PHP_FPM_MEMORY_LIMIT_FORCE  AUTO (default) | integer MB — pin exact memory_limit
                               (minimum 64)
_PHP_FPM_RAM_PCT             AUTO (=50, default) | percent of RAM for dedicated-plan
                               workers
_PHP_FPM_CPU_FACTOR          AUTO (=8, default) | dedicated-plan max_children CPU cap
                               = cores × factor
_PHP_FPM_DENY                Per-instance disable_functions list (default empty;
                               empty denies only `passthru`, a value REPLACES it)

The four _PHP_FPM_* adaptive knobs (*_FORCE, _RAM_PCT, _CPU_FACTOR) only affect the plan-based worker and memory_limit sizing; all default to AUTO (fully dynamic). Full sizing model → PHP-FPM & performance.

Passwords + DB conversion + reserved RAM

_STRONG_PASSWORDS    YES (=64, default) | NO (=32) | integer 32-128
_SQL_CONVERT         NO (default) | innodb | YES | myisam — weekly DB conversion
_RESERVED_RAM        MB reserved for non-BOA apps on the host (default 0)

_SQL_CONVERT runs the weekly (Tuesday) sqlmagic conversion and interacts with the platform/site INI sql_conversion_mode variable. When _SQL_CONVERT=YES (or innodb), the INI variable is ignored and InnoDB conversion is forced globally on the instance — see INI files & precedence for the precedence rule. On hosted BOA systems instance-level SQL conversion is denied.

Plan selector — _CLIENT_OPTION

_CLIENT_OPTION selects the hosting plan tier for the instance and is the pivot the FPM sizing logic branches on (default POWER). The tiers split into dedicated (MONSTER/CLUSTER, ULTRA, PHANTOM) which size PHP-FPM pm.max_children and memory_limit dynamically, and shared (POWER/BUS, EDGE/AGAIN/SSD/CLASSIC, MINI/MICRO/QUIET/HEADSPACE) which keep a restricted per-plan worker and memory band. The boundary at PHANTOM is what PHP-FPM & performance refers to as "PHANTOM and above".

Octopus version pins (internal)

_AEGIR_VERSION   _AEGIR_XTS_VRN   _X_VERSION   (default AUTO)
_BRANCH_BOA      _BRANCH_PRN                   (default AUTO)
_BOA_REPO_NAME   _BOA_REPO_GIT_URL

These pin the Ægir/BOA branch and repository this instance tracks. Defaults (AUTO / the standard repo) are correct for a standard install; change only when deliberately pointing an instance at a non-default branch.

Per-instance control directory

Below the host-level .cnf, each Octopus instance has its own control directory at ~/static/control/ (e.g. /home/o1/static/control/). Tenants can edit it without root. It carries the per-version PHP switch files (fpm.info, multi-fpm.info, cli.info), platforms.info, and the tenant-triggered run-upgrade.pid. These are detailed on PHP-FPM & performance and INI files & precedence. The host-level .octopus.cnf is for variables only root can set; the ~/static/control/*.info files are for things the tenant can change themselves.

Related

• barracuda.cnf — host-wide config (this one is per-instance).
• Overview — the surrounding .cnf / marker ecosystem.
• INI files & precedence — the layers below the host level.
• Reference appendix — consolidated variable index.