`/root/.barracuda.cnf` reference

/root/.barracuda.cnf is the master host-level BOA configuration file. Every variable here applies system-wide — it affects every Octopus instance on the host unless overridden per-instance in octopus.cnf.

The functional defaults live in BOA source at lib/settings/barracuda.sh.cnf, which BOA sources on every barracuda pass. That file is authoritative for every variable name, default, and the condition under which each default applies. This page is the topical guide by family.

Two categories

Install-time-only — set once at initial install, NOT overridden on barracuda upgrade. Examples: _EASY_HOSTNAME, _MY_OWNIP, _THIS_DB_HOST. Changing these after install requires manual care.

Upgrade-honoured — re-read on every barracuda upgrade. Most operational variables fall here. Override is straightforward: edit the file, run barracuda up-lts.

Variable families

Host identity (install-time-only)

_EASY_HOSTNAME       FQDN, DNS-wildcard-enabled hostname (default placeholder
                       "wildcard-enabled-hostname")
_EASY_SETUP          PUBLIC (default) | LOCAL — install mode selector
_LOCAL_NETWORK_HN    Hostname for localhost mode (default empty)
_LOCAL_NETWORK_IP    Web server IP for localhost mode (default empty)
_MY_FRONT            Ægir frontend web address (default empty = use FQDN)
_MY_HOSTN            Server FQDN hostname (default empty = auto-detect)
_MY_OWNIP            Web server IP (default empty = auto-detect)
_SMTP_RELAY_HOST     SMTP relay host, no auth (default empty)
_SMTP_RELAY_TEST     YES (default) / NO — skip SMTP availability tests
_THIS_DB_HOST        localhost (default) | FQDN | literal name (→ remote-DB mode)

_THIS_DB_HOST is sensitive: localhost/FQDN are keywords, but any literal hostname switches on the experimental Remote DB Server Mode.

Operator identity + behaviour

_MY_EMAIL            System-admin email (default "notify@omega8.cc") —
                       install/upgrade notifications
_AUTOPILOT           YES / NO (default NO) — answer Y to every prompt (silent mode)
_DEBUG_MODE          YES / NO (default NO) — verbose Drush backend report
_DL_MODE             BATCH (default) | GIT | OLD — installer source preference
_INCIDENT_REPORT     OFF | ALL | MINI (default) | CRIT — monitor incident
                       notification depth (legacy NO→OFF, YES→MINI)
_XTRAS_LIST          Optional add-on packages (default empty) — see XTRAS list page

_XTRAS_LIST is the master add-on selector; its tokens and install modes are documented on _XTRAS_LIST & install modes.

CPU + load thresholds

_CPU_CRIT_RATIO      Per-core max 1-min load before killing PHP/Drush/Wget/Curl
                       (default 6.1)
_CPU_MAX_RATIO       Per-core max load before disabling Nginx (default 4.1)
_CPU_TASK_RATIO      Per-core max load to launch the task queue (default 3.1)
_CPU_SPIDER_RATIO    Per-core max load before blocking spiders (default 2.1)

These thresholds drive the host-level load-shedding in the monitor agent — see Monitoring & self-healing.

Database (Percona)

_DB_SERVER             Percona (default) | MySQL Server (from Trixie)
_DB_SERIES             5.7 (default) | 8.0 | 8.4
_DB_BINARY_LOG         YES / NO (default NO — disabled so CiviCRM tasks work;
                         ignored when _CUSTOM_CONFIG_SQL=YES)
_CUSTOM_COLLATION_SQL  Server-level collation override (default empty → the DB
                         server's utf8mb4_unicode_ci is used)
_SQL_LOW_MAX_TTL       Max TTL (seconds) per "problematic user" mysql process
                         listed in /etc/boa/.sql.problematic.users.cnf — the live
                         reader checks /etc/boa, this marker is in the migrated set
                         (default 60)
_SQL_MAX_TTL           Max TTL per user mysql process (default 3600; auto-lowered
                         to 1800 or 300 depending on .high_load.cnf / .big_db.cnf)
_USE_MYSQLTUNER        YES / NO (default NO) — use MySQLTuner to size limits

Full DB topic → Database.

Install behaviour

_DNS_SETUP_TEST      YES (default) / NO — skip DNS testing
_EXTRA_PACKAGES      Extra apt packages to install (default empty)
_FORCE_GIT_MIRROR    "" (default) | github | gitlab — pin a preferred git mirror
_LOCAL_DEBIAN_MIRROR Force non-default Debian mirror (default empty)
_LOCAL_DEVUAN_MIRROR Force non-default Devuan mirror (default empty)
_NEWRELIC_KEY        New Relic license (default empty; presence enables agent)
_MAGICK_FROM_SOURCES YES / NO (default NO) — build ImageMagick from source (webp)
_ENABLE_GOACCESS     YES / NO (default NO) — generate stats with GoAccess

Nginx DoS protection

_NGINX_DOS_LINES        access.log lines to check (default 1999)
_NGINX_DOS_LIMIT        Per-IP page-views limit out of the last 1999; on hit the
                          IP is denied for 1 h via /etc/csf/csf.deny (default 399)
_NGINX_DOS_MODE         1 | 2 — DoS-counter algorithm (default 2; mode 1 adds an
                          extra +5 to the per-IP counter for POST to /user
                          (register/pass/login) or /node/add, and +5 for GET to
                          /node/add or /search)
_NGINX_DOS_LOG          SILENT (default) | NORMAL | VERBOSE — detector verbosity
_NGINX_DOS_IGNORE       Regex; a matching access.log line is ignored
                          (default "doccomment")

autoupboa normalises _NGINX_DOS_LIMIT back to the current default of 399 on each pass (it hard-sets the line to 399).

scan_nginx IDS knobs

These tune the scan_nginx.sh intrusion-detection scoring. The script defines its own defaults and also reads /root/.barracuda.cnf, so they are overridable here; autoupboa seeds the increment knobs into the .cnf on upgrade. Full explanation on the Abuse guard topic.

_NGINX_DOS_DIV_INC_NR           Divisor used to derive the per-request increment
                                  from _NGINX_DOS_LIMIT (default 40 in scan_nginx.sh)
_NGINX_DOS_INC_MIN              Floor for the computed increment; scan_nginx.sh
                                  re-defaults an invalid value to 3 (default 3)
_NGINX_DOS_IGNORE_PATHS         Space-separated webhook/API endpoints exempt from
                                  IDS banning. Ships defaults
                                  (/shopify/webhook /quickbooks/webhook
                                  /stripe/webhook /paypal/webhook /github/webhook
                                  /gitlab/webhook /graphql /public-api /oauth2).
                                  Setting here REPLACES the default list.
_NGINX_PHP_PROBE_WEIGHT         Webshell *.php-probe fast-ban weight
                                  (default _NGINX_DOS_LIMIT / 3)
_NGINX_PATH_FLOOD_IP_THRESHOLD  Distinct IPs hitting one path prefix (200 and 444
                                  responses) in the scan window before a path
                                  flood is declared (default 30; declaration alone
                                  never bans — a per-IP gate decides who is blocked)
_NGINX_DOS_STOP      SQL-injection-keyword regex matched by scan_nginx.sh against
                       each access.log line; on match it adds a full
                       _NGINX_DOS_LIMIT to the per-IP counter (an immediate ban),
                       not the small per-request increment. Default catches
                       blind-timing and encoded SQLi probes
                       (`WAITFOR.DELAY|DECLARE.*@x|/**/|%27.*%29.*%3B|0x[0-9a-f]{6}`).

Full Nginx topic → Nginx internals.

PHP version management

_PHP_MULTI_INSTALL   Space-separated PHP versions to install (default "8.3 8.4 8.5")
_PHP_SINGLE_INSTALL  Single version; if set, overrides _PHP_MULTI_INSTALL,
                       _PHP_FPM_VERSION, _PHP_CLI_VERSION (default empty)
_PHP_CLI_VERSION     Default PHP-CLI version (default 8.4)
_PHP_FPM_VERSION     Default PHP-FPM version (default 8.4)
_PHP_FPM_DENY        Per-host disable_functions list; empty denies only `passthru`,
                       a non-empty value REPLACES that default (default empty)

Full PHP-FPM topic → PHP-FPM & performance.

Nginx + PHP build options

_NGINX_EXTRA_CONF    Custom configure-flags appended to Nginx build (default empty)
_NGINX_FORWARD_SECRECY  YES (default) / NO — PFS support (also forces OpenSSL+cURL)
_NGINX_HEADERS       YES / NO (default NO) — install Headers More module
_NGINX_LDAP          YES / NO (default NO) — install LDAP support
_NGINX_NAXSI         YES / NO (default NO) — install NAXSI WAF (experimental)
_NGINX_SPDY          YES (default) / NO — SPDY (also forces OpenSSL+cURL)
_NGINX_WORKERS       AUTO (default) | <integer> — override worker_processes
_PHP_EXTRA_CONF      Custom configure-flags appended to PHP build (default empty)
_PHP_FPM_WORKERS     AUTO (default) | <integer> — override pm.max_children
_PHP_IONCUBE         YES / NO (default NO) — install ionCube loader for all PHP
_PHP_MONGODB         YES / NO (default NO) — build MongoDB driver for all PHP
                       (equivalent to the MNG xtras token)

_PHP_GEOS is not a current control variable — the GEOS extension (php-geos 1.0.0) is built unconditionally for every PHP version except 5.6, and the old _PHP_GEOS=YES gate is read nowhere in the live code.

ICU / intl pin (`_ICU_FORCE_VRN`)

Off by default — the template ships no value; the var is read from /root/.barracuda.cnf by system.sh.inc. Advanced; for single-tenant dedicated boxes only. When set (dashed form, e.g. 73-1), BOA builds/links ICU at this version on all PHP versions and rebuilds the PHP intl extension against it, via apply / precheck / retire phases. It is a holding pattern to keep a legacy Drupal 7 site running after a system ICU bump without forcing a client codebase upgrade. Unset = per-OS default, no behaviour change. The pin is global per box, has a shelf life, and is NOT auto-carried on migration. Full procedure → OS lifecycle.

Auto-upgrade scheduling

These variables are not read by barracuda itself — they are consumed by autoupboa, which renders the /etc/crontab auto-upgrade lines. On a hosted BOA system autoupboa overrides them with fixed values, so they apply only on self-managed hosts.

_AUTO_VER            lts | pro | dev — release tier; maps to barracuda/octopus
                       up-<tier>. When empty, defaults to the build tier (${_tRee})
_AUTO_PHP            php-min | php-all | php-max — which PHP versions the
                       auto-upgrade rebuilds (otherwise no php argument is added)
_AUTO_UP_WEEKLY      Weekday (1-7) for the weekly system-only upgrade
_AUTO_UP_MONTH       Month (1-12) for the one-time full upgrade
_AUTO_UP_DAY         Day (1-31) for the one-time full upgrade
_AUTO_UP_HOUR        Hour (0-23) for the barracuda upgrade (default 0 when the
                       weekly/month/day trio is set)
_AUTO_UP_MINUTE      Minute (0-59) for the barracuda upgrade (default 15)
_AUTO_OCT_UP_HOUR    Hour for the octopus upgrade (default 1)
_AUTO_OCT_UP_MINUTE  Minute for the octopus upgrade (default 15)

The weekly system upgrade is scheduled only when _AUTO_UP_WEEKLY, _AUTO_UP_MONTH, and _AUTO_UP_DAY are all set; the hour/minute defaults above fill in only then.

Redis / Valkey (cache backend)

_REDIS_LISTEN_MODE     SOCKET (default, recommended) | PORT | remote IP
_REDIS_MAJOR_RELEASE   5 | 6 | 7 (default 7)
_VALKEY_LISTEN_MODE    SOCKET (default, recommended) | PORT | remote IP
_VALKEY_MAJOR_RELEASE  7 | 8 | 9 (default 9)

A non-default IP in either *_LISTEN_MODE switches all instances to a remote cache server and permanently disables the local one.

Runtime defaults applied by BOA (not operator variables): the cache instance runs as a cache, not a datastore. Persistence is disabled — no RDB snapshots (save "") — and the eviction policy is maxmemory-policy volatile-lfu. BOA enforces both on Valkey (/etc/valkey/valkey.conf) and Redis (/etc/redis/redis.conf) on each upgrade pass, restarting the service only when a value changed. To keep BOA from re-writing either file, set _CUSTOM_CONFIG_VALKEY=YES / _CUSTOM_CONFIG_REDIS=YES (below).

SSH

_SSH_ARMOUR        YES / NO (default NO) — stricter OpenSSH hardening (needs
                     _SSH_FROM_SOURCES=YES)
_SSH_FROM_SOURCES  YES (default) / NO — build OpenSSH from source (Debian only)
_SSH_PORT          22 (default) or any other valid port (also rewrites CSF)

Security + maintenance

_SKYNET_MODE             ON (default) / OFF — gates autoupboa self-update
_PERMISSIONS_FIX         YES (default) / NO — daily site file-permission re-fix
_MODULES_FIX             YES (default) / NO — the modules enable/disable enforcement
_MODULES_SKIP            Modules never auto-disabled (default empty; safelist)
_CLEAR_BOOST             YES (default) / NO — clear boost caches daily
_STRICT_BIN_PERMISSIONS  YES (default) / NO — aggressively protect /usr/local/bin
                           and other root-group binaries
_STRONG_PASSWORDS        YES (=64, default) | NO (=32) | integer 32-128
_RESERVED_RAM            MB reserved for non-BOA apps when sizing memory (default 0;
                           if unset BOA auto-reserves 1/4 of RAM)
_SPEED_VALID_MAX         Speed Booster max cache TTL in seconds (default 3600)

The _MODULES_* variables feed the enforcement detailed on the Drupal module support matrix.

Nightly maintenance (owl.sh)

_NIGHT_PARALLEL      YES / NO (default NO) — process Octopus accounts in
                       parallel during the nightly owl.sh run instead of serially
_NIGHT_MAX_PARALLEL  Max accounts processed concurrently when _NIGHT_PARALLEL=YES
                       (default empty = CPU core count; a non-numeric value is
                       sanitised to 1)
_LE_CLIENT_NOTIFY    YES (default) / NO — client-facing Let's Encrypt
                       renewal-failure notices from the nightly per-account run

With _NIGHT_PARALLEL=YES, each parallel launch waits for both a free slot and load headroom under the per-core ceiling _CPU_TASK_RATIO (owl.sh compares the current load against _O_LOAD_MAX = _CPU_TASK_RATIO × 100) — designed to wait for an overloaded account rather than skip it — and each account logs to its own file.

_LE_CLIENT_NOTIFY gates the notices sent to the affected account's client when a site's certificate renewal fails, throttled to once per 7 days per failing site. Only the value NO disables (case-insensitive, quotes/whitespace stripped — any other value including empty leaves notices ON); a per-account _LE_CLIENT_NOTIFY line in /root/.<user>.octopus.cnf overrides the global for that account.

These three, plus _CLEAR_BOOST above, are persistent cnf lines (post-5.10.3): written into a fresh /root/.barracuda.cnf at install and appended with their defaults on upgrade when the line is absent, so existing servers pick up no-op default lines automatically. The nightly run itself is documented on Nightly owl run.

Files-symlinking nightly automation

_AUTOSYMLINK_NIGHTLY      YES / NO (default NO) — nightly
                            `updatesymlinks --auto-fix` run
_ORPHAN_FILES_REPORT      YES / NO (default NO) — read-only daily orphaned-files
                            report emailed to _MY_EMAIL, only when orphaned
                            static/files entries are found
_AUTOSYMLINK_PAUSE_GRACE  Seconds updatesymlinks holds after pausing the Aegir
                            task queue before draining in-flight provision tasks
                            (runtime default 240; 0 = skip the wait)

The auto-fix run converts not-yet-symlinked site files/private dirs into the per-account static store and self-heals partly-symlinked sites. It is served by the root cron line 47 0-5,22,23 * * * — retried hourly through the night, scheduled clear of the 6-hourly duplicity backups; the first unblocked hour does the work and stamps the night done. The run is skipped while backups, provision tasks, or high load are active. The orphan report rides the same cron line and never converts or deletes; with only _ORPHAN_FILES_REPORT set, the run does the report alone.

Unlike the two toggles, _AUTOSYMLINK_PAUSE_GRACE is NOT persisted or templated anywhere — add the line to /root/.barracuda.cnf manually to override (updatesymlinks sources that file).

Seeding rule: on hosts whose hostname ends in .aegir.cc (the omega8.cc-hosted fleet) BOTH toggles are seeded to YES — but only when the line is not already present in the cnf, so an operator-set NO sticks and is never forced back. The switch keys on the hostname only, never on /root/.host8.cnf, so remotely-managed boxes are not swept in. Both toggles are persistent: written at install and appended with defaults on upgrade when absent. Mode semantics → Nightly automation and Configuration.

Nightly ghost-cleanup flags (dry-run by default)

Seven persistent host-wide flags, all default NO = detect-and-log only (dry-run). YES lets the nightly run move the item aside reversibly — the nightly cleanup itself never deletes anything.

_SHARED_CODEBASES_CLEANUP  Move unused legacy D6/D7 shared codebases under
                             /data/all into a codebases-cleanup backup dir
                             (/var/backups/codebases-cleanup, or
                             /data/disk/codebases-cleanup when /data/all is a
                             symlink)
_GHOST_CODEBASES_CLEANUP   Move orphaned trees under distro/ with no detectable
                             Drupal docroot at root or web/, docroot/, html/
                             into /var/backups/ghost-codebases-cleanup
_GHOST_PLATFORMS_CLEANUP   Move ghost/empty platform Drush aliases into the
                             undo/ dir
_GHOST_VHOSTS_CLEANUP      Move nginx vhosts with no matching site alias into
                             undo/
_GHOST_SITES_CLEANUP       Move a ghost site registration — alias + vhost —
                             whose site dir is gone
_GHOST_SITE_FILES_CLEANUP  ALSO move that ghost site's leftover files directory
                             (kept separate and default NO because it touches
                             data)
_GHOST_ALIASES_CLEANUP     Move stale per-site alias copies in the
                             limited-shell FTPS user tree

Caveat: on omega8.cc-hosted systems the moved-aside codebases-cleanup dir is pruned after 7 days, so recover promptly there; elsewhere pruning is manual.

The last five have per-account overrides in /root/.<user>.octopus.cnf; the first two are system-wide only. All seven are seeded idempotently into the live cnf on install and upgrade without clobbering operator-set values. Detection logic and safeguards — the always-on _provision_running interlock, consecutive-run confirmation, dry-run log line format — live on Ghost cleanup.

Custom-config protection flags

Tell the BOA upgrade tooling not to overwrite the named service's config when the operator has made manual edits. Set to YES after customising the config; all default to NO.

_CUSTOM_CONFIG_CSF       YES / NO — protect custom CSF config
_CUSTOM_CONFIG_LSHELL    YES / NO — protect custom Limited Shell config
_CUSTOM_CONFIG_VALKEY    YES / NO — protect custom Valkey config
_CUSTOM_CONFIG_REDIS     YES / NO — protect custom Redis config
_CUSTOM_CONFIG_SQL       YES / NO — protect custom SQL config (also makes
                           _DB_BINARY_LOG a no-op)

Force-reinstall flags

One-shot flags that force the named subsystem to reinstall from scratch on next barracuda upgrade. All default to NO.

_NGX_FORCE_REINSTALL     YES / NO — reinstall Nginx
_PHP_FORCE_REINSTALL     YES / NO — reinstall all PHP versions
_SQL_FORCE_REINSTALL     YES / NO — reinstall Percona / MySQL
_SSL_FORCE_REINSTALL     YES / NO — reinstall OpenSSL/cURL; when YES it also
                           forces _NGX_FORCE_REINSTALL, _PHP_FORCE_REINSTALL and
                           OpenSSH (sets them to YES internally; the same
                           cascade fires for _FULL_FORCE_REINSTALL=YES)
_FULL_FORCE_REINSTALL    YES / NO — reinstall everything from sources

All force-reinstall flags are transient one-shots at the file level: the config-cleanup pass scrubs EVERY *_FORCE_REINSTALL line — _NGX, _PHP, _SQL, _SSL, _SSH, _GIT and _FULL — from the live /root/.barracuda.cnf during each run (the values already sourced into memory still act during that run). Set the line to YES, run barracuda, and the flag is consumed and the line removed — it never persists across runs, which is why the cnf writers deliberately never persist any *_FORCE_REINSTALL line. _SSH_FORCE_REINSTALL is honoured and scrubbed the same way even though the settings template lists only _NGX/_PHP/_SQL/_SSL/_FULL; _GIT_FORCE_REINSTALL (reinstall Git tooling) is normally only added programmatically, so you do not set it by hand.

Aegir / system upgrade scope

_AEGIR_UPGRADE_ONLY   YES / NO (default NO) — run only the Ægir-side upgrade steps
_SYSTEM_UP_ONLY       YES / NO (default NO) — run only the system-side upgrade steps

Internal OS-version transition markers

Set by hand (or by the OS-upgrade tooling) to trigger a major dist-upgrade between release codenames; all default to NO. Flip exactly one to YES for the intended jump.

_JESSIE_TO_STRETCH       _STRETCH_TO_BUSTER       _BUSTER_TO_BULLSEYE
_BULLSEYE_TO_BOOKWORM    _BOOKWORM_TO_TRIXIE
_JESSIE_TO_BEOWULF       _STRETCH_TO_BEOWULF      _BUSTER_TO_BEOWULF
_BEOWULF_TO_CHIMAERA     _BULLSEYE_TO_CHIMAERA
_CHIMAERA_TO_DAEDALUS    _BOOKWORM_TO_DAEDALUS
_DAEDALUS_TO_EXCALIBUR   _TRIXIE_TO_EXCALIBUR

See OS lifecycle for the OS-upgrade lifecycle these markers drive.

Editing tips

Make a backup before editing:

cp /root/.barracuda.cnf /root/.barracuda.cnf.bak

Variables are bash assignments — no quotes on simple values unless they contain whitespace.
Lines starting with # are comments.
Variables take effect on the next barracuda upgrade (or immediately for the few read by per-minute cron tasks).
CLI arguments to barracuda up-lts override the config file — useful for one-off changes.

octopus.cnf — per-instance config (similar shape, different scope).
Overview — the surrounding .cnf / marker ecosystem.
INI files & precedence — finer-grained config below the host level.
Reference appendix — consolidated variable index.

/root/.barracuda.cnf reference