Operator FAQ

Recurring operator questions that don't fit cleanly into one of the other troubleshooting pages. Everything here assumes root on the box.

Can I host non-Ægir vhosts on BOA?

Yes, but unsupported, and you own the breakage on the next upgrade. Custom master-level vhosts must live in:

/var/aegir/config/server_master/nginx/vhost.d/

That path is exempt from BOA's daily GHOST vhost detection + auto-cleanup, which scopes to /data/disk/* Octopus-instance vhosts only — master-level vhosts are never auto-removed. Do not expect a barracuda upgrade to preserve any non-Drupal config you add.

The mechanism is not Drupal-specific: a hand-built Drupal site, WordPress, or any other application can be served from a master-level vhost this way.

Can I install non-BOA services and packages?

It depends. The upgrade procedure is aggressive: if it does not know about extra services, apt autoclean may uninstall them. Tactics:

1. Pin packages via _EXTRA_PACKAGES in /root/.barracuda.cnf (default empty); listed packages survive barracuda upgrade:
   INICopy

   _EXTRA_PACKAGES="mosh tmux htop"
   

2. Watch closely the first barracuda upgrade after adding anything new.
3. Keep a checklist of additions so you can re-install after upgrades.

Can I call Drush from PHP-FPM (web requests)?

Don't. PHP-CLI and PHP-FPM are separate runtimes with separate privilege contexts, limits, and lifecycle assumptions. If you need Drupal logic from a web request, use the Drupal API (custom module, hook, controller) — do not shell out to Drush.

How do I raise PHP memory_limit or execution-time limits?

Both are auto-configured from detected RAM and CPU. To override manually, edit the FPM common pool files:

/opt/etc/fpm/fpm-pool-common.conf
/opt/etc/fpm/fpm-pool-common-legacy.conf      # PHP 7.x pools
/opt/etc/fpm/fpm-pool-common-modern.conf      # PHP 8.x pools

The relevant directives (BOA defaults shown — memory_limit is auto-tuned per box):

php_admin_value[memory_limit]            = 395M
php_admin_value[max_execution_time]      = 180
php_admin_value[max_input_time]          = 180
php_admin_value[default_socket_timeout]  = 180

Keep the bracketed form. These are FPM pool files, so only the php_admin_value[...] directives above are honoured. A bare, un-prefixed line such as max_execution_time = 180 (without the php_admin_value[...] wrapper) is not honoured — the value simply won't take effect — so wrap every directive you add.

Then reload every running PHP version:

service php74-fpm reload
service php83-fpm reload
service php84-fpm reload
# …per installed version

These files are overwritten on every barracuda upgrade. Re-apply your changes afterwards.

Where do logs live?

There is a single /var/log/php directory holding phpNN-fpm-error.log for each version — no per-version /var/log/phpNN/ directory and no php-fpm.log.

The MySQL error destination is series-dependent: BOA's per-version my.cnf pass enables log_error (pointing at /var/log/mysql/error.log) on 8.x and log_syslog on 5.7, so on a 5.7 box the reason a refused start gives is in the syslog family. See my.cnf lifecycle for the full per-series directive set.

Where do install / upgrade logs go?

How do I get verbose install / upgrade output (debug mode)?

By default the installers run quiet: many command groups discard their console output outright, so when a step fails there is often nothing to read after the fact — the logs above hold far less than the run actually printed. If a problem is reproducible, enable verbose output (debug mode) first, then re-run the install or upgrade:

touch /root/.debug-boa-installer.cnf

This is the safe debug marker: it makes the Barracuda and Octopus install chains verbose and changes nothing else. Two narrower markers exist — and one of them is a trap:

• /root/.debug-octopus-installer.cnf — verbose Octopus chain only. Safe.
• /root/.debug-barracuda-installer.cnf — verbose Barracuda chain, and the only marker that also makes the BOA.sh.txt bootstrap (the wget … | bash step) verbose. But it also skips the whole Drush toolchain — Drush, the /usr/bin/drush symlinks, CiviCRM cv, Backdrop bee — and the Master Ægir upgrade, on fresh installs and upgrades alike. Use it for short debugging windows only, and never leave it behind on a production box.

Two quirks worth knowing:

• The Barracuda chain ignores the combined marker on a plain upgrade run (a bare barracuda up-lts / up-pro). The marker propagates on the Barracuda chain only when the command line carries an extra key token (a php-* choice, nodns, or a New Relic key). For a bare barracuda up-lts, edit /root/.barracuda.cnf and set _DEBUG_MODE=YES instead — that variable is the supported switch either way (for a tenant chain, the same line in /root/.<user>.octopus.cnf). Fresh boa in-* installs and every Octopus run honour the marker unconditionally. An exported environment variable does not work — the sourced settings file reassigns _DEBUG_MODE — and no CLI argument enables it.
• Verbosity outlives the marker. A marker-enabled run writes _DEBUG_MODE=YES into the persistent cnf files, and nothing in BOA ever writes it back. When you are done, remove the marker and set _DEBUG_MODE=NO in /root/.barracuda.cnf (and in the instance's octopus cnf if a tenant run was involved).

On the dev tree the two safe markers are created automatically on every run. The staged run's tracing internals are on Staged setup engine; the full marker index is in the control-file reference.

How do I list every Octopus instance?

ls -d /home/o* 2>/dev/null | sed 's|/home/||'
# or
grep -E '^o[0-9]+:' /etc/passwd

How do I disable a noisy module without a Verify re-enabling it?

Module enable/disable lives in Drupal config, not in boa_site_control.ini. Use drush to disable cleanly:

drush @site-alias -y pmu noisy_module

If BOA's weekly maintenance keeps re-enabling it (the modules-fix feature, gated by _MODULES_FIX=YES), either add the module to _MODULES_SKIP in /root/.barracuda.cnf or disable the whole feature with _MODULES_FIX=NO.

How do I fix "No available releases found" on a cloned site?

On current BOA (5.10.3+) you don't — the deploy path clears the orphaned {key_value} update_fetch_task collection automatically right after updatedb on every Clone, Migrate, platform Migrate, Rename, and Restore (_provision_drupal_clear_update_fetch_tasks; via the site-local Drush on D10+, via Ægir's Drush 8 backend invoke on D8/D9; non-fatal on every path), so update.module can fetch release data again without manual SQL.

The manual workaround

DELETE FROM key_value WHERE collection = 'update_fetch_task';

is needed only on the degraded D10+ path where the site-local Drush is not executable — the automatic clear logs and skips there; see the degraded-path notes in Ægir task failures. D7 was never affected: its fetch tracker lived in {cache_update}, already wiped on import.

Historical cause: the re-imported site DB carried non-expirable update_fetch_task tracker rows whose matching queue was lost, so UpdateProcessor refused to enqueue and update.module wedged with no UI recovery (drupal.org #2920285).

How do I add a custom Nginx rewrite that survives upgrades?

Use the per-site custom-include mechanism: drop your config in the site's post.d/ include dir and Ægir's Verify folds it into the per-site vhost. See Rewrites & locations.

How do I check the running BOA version?

boa info
boa info | grep -i version

Why does boa info need to return 3 lines for "Percona"?

After install or upgrade, the post-install chain has finished when this returns exactly 3:

boa info | grep -c Percona

It is a convenience marker for "all phases completed, including the cron-triggered background phase".

Related

• Ægir task failures — task-level recovery.
• Recovery & cache faults — Ægir/Drush state recovery and the cache fault classes.
• PHP-FPM capacity — FPM tuning and the common pool files.
• Rewrites & locations — the custom-include mechanism.