INI files & precedence

Below the host-level .cnf files sit two INI templates a tenant can edit without root: the per-platform boa_platform_control.ini and the per-site boa_site_control.ini. They are parsed Drupal-side by the global PHP includes, not sourced as bash. This page is the precedence reference — who wins when more than one layer sets the same value.

Where the INI files live

sites/all/modules/boa_platform_control.ini   (per Drupal platform)
sites/<domain>/modules/boa_site_control.ini  (per site)

Copy the shipped template into place and uncomment the lines you want to change:

cp boa-private/aegir/conf/ini/default.boa_platform_control.ini \
   sites/all/modules/boa_platform_control.ini

The templates are self-documenting — each settable variable is listed commented out, with its system default shown, so you see what you are overriding before you commit. The platform template exposes 34 settable variables and the site template 33 (the templates are authoritative; read them for the exact current set).

The four layers, narrowest to broadest

1. boa_site_control.ini       (per site)
       overrides
2. boa_platform_control.ini   (per Drupal platform)
       overrides
3. /root/.${USER}.octopus.cnf (per Octopus instance)
       overrides
4. /root/.barracuda.cnf       (host-wide)

Site INI is the narrowest scope (one site) and wins over everything. barracuda.cnf is the broadest scope and the bedrock — every default ultimately comes from here, by way of the compiled-in defaults below.

Layer File Who can edit
Site INI sites/<domain>/modules/boa_site_control.ini Tenant + operator
Platform INI sites/all/modules/boa_platform_control.ini Platform owner + operator
Octopus cnf /root/.o1.octopus.cnf etc. Root operator only
Barracuda cnf /root/.barracuda.cnf Root operator only

A tenant logged into their Octopus shell can edit site + platform INI for sites they own; they cannot touch the host-level .cnf files.

Where defaults come from

BOA's compiled-in defaults live in aegir/conf/global/global.inc and global-ini.inc. For example session_cookie_ttl defaults to 86400 seconds (24 h) in both global.inc and global-ini.inc; the INI template shows that default in a comment so you see "the system default is 86400" before deciding whether to override.

global.inc / global-ini.inc (BOA compiled-in default)
   overridden by, if set:
barracuda.cnf / octopus.cnf (host + instance)
   overridden by, if set:
boa_platform_control.ini
   overridden by, if set:
boa_site_control.ini

Each layer is optional — if boa_platform_control.ini does not exist, the chain skips it.

Effective compiled-in default vs template comment. A handful of template entries (auto_detect_domain_access_integration, auto_detect_facebook_integration) show FALSE in the template but ship a compiled-in runtime default of TRUE in global-ini.inc for backward compatibility, annotated there as slated to flip to FALSE in a later release. The template comment documents the intended default; the live default is what global-ini.inc sets. Where they differ, the compiled-in value wins until you set the variable explicitly.

Refresh timing

Layer Effect picks up
barracuda.cnf On next barracuda upgrade (plus a few read by per-minute cron)
octopus.cnf On next octopus upgrade for this instance
Platform INI ~60 s (opcache TTL), or immediately for .dev. URLs
Site INI ~60 s (opcache TTL), or immediately for .dev. URLs

INI changes are deliberately fast — they are the layer tenants use for quick adjustments. .cnf changes need a full upgrade cycle because they affect host-level behaviour BOA validates holistically.

The _SQL_CONVERT=YES forcing exception

Most of the chain is a plain default-override: the narrower layer supplies a value only if it is set, otherwise the broader layer's value stands. The DB-conversion control is the exception. When _SQL_CONVERT=YES (or innodb) is set on the Octopus instance, the per-platform / per-site sql_conversion_mode INI variable is ignored entirely and InnoDB conversion is forced regardless. Here the host-level setting is a forcing override rather than a default — see octopus.cnf.

Notable INI variables

The templates group their variables into families. A few worth calling out, with their template-documented behaviour:

Variable Default Behaviour
session_cookie_ttl 86400 session.cookie_lifetime in seconds (24 h).
session_gc_eol 86400 session.gc_maxlifetime in seconds; keep at or below the session_expire module's TTL.
redis_flush_forced_mode TRUE Aggressive cache flush mode; Drupal 6/7 only — the runtime gates it on $drupal_core < 8 and applies it via $conf (D8+ ignores it, invalidating by cache tags instead, so no $settings are emitted). When active it caps each cache entry at a 24 h TTL (redis_perm_ttl = 86400). Disable with FALSE if a D6/7 module relying on CACHE_PERMANENT entries WSODs on the shortened TTL.
redis_exclude_bins FALSE Comma-separated cache bins to keep in MySQL instead of Redis (the template ships FALSE; set a comma-separated bin list to override).
sql_conversion_mode NO innodb or myisam weekly (Tuesday) auto-conversion target; ignored when _SQL_CONVERT=YES on the Octopus.
fix_files_permissions_daily TRUE Honour the host _PERMISSIONS_FIX=YES; set FALSE to skip permission reset on Git-managed monolithic platforms.
disable_admin_dos_protection FALSE At the default FALSE, anonymous requests to /admin* are redirected to the site homepage — admin URLs are never cached and always hit Drupal directly, which blunts DoS attempts. Set TRUE to allow anonymous access to /admin* (showing only the 403 Access Denied page); use this if an expired session/cookie keeps redirecting logged-in users to the homepage.
allow_anon_node_add FALSE Allow anonymous access to node/add (also opens node edit); the default FALSE redirects to the homepage.

The Redis/Valkey cache family is the largest — the platform template carries 15 redis_* variables, including the resilience knobs redis_connect_timeout, redis_read_timeout, redis_backoff_ttl, redis_probe_retry, redis_flush_apcu_on_recovery, redis_debug, and redis_debug_header. Even when the host runs Valkey, all cache-control variables keep the stable redis_ namespace by design — the Valkey/Redis distinction exists only at the service-binary level.

Related