/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
_DOMAIN              Ægir control panel URL (e.g. o1.f-q-d-n)

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 — see the template for the symbol map)
_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.

_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.

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) — 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

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.

One related override is deliberately not in the template or written by the installer: _LE_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. 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 notice pipeline is described on SSL operations.

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