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 once this returns 3 or more:

boa info | grep -c Percona

It is a convenience marker for "all phases completed, including the cron-triggered background phase". Every completed Barracuda pass appends one line to /var/log/barracuda_log.txt naming the database server, and boa info prints the last five of those lines — so the count is how many passes have completed, capped at five. A freshly installed server reaches 3 when the background phase has run; a server that has been upgraded a few times since sits at 5 and stays there. BOA applies the same test internally, treating fewer than 3 as "not finished yet", so this is BOA's own signal rather than a separate convention.

What if it stops at 2?

A count that never moves past 2 means the cron-triggered background phase never launched, so the box is short of its final system pass. CSF and the DNS cache are the usual casualties. Confirm the shortfall, then run the missing pass by hand:

boa info | grep -c Percona
ls -la /usr/sbin/csf
barracuda up-lts system noscreen

Re-check the count afterwards; it should now be 3. On a PRO server use barracuda up-pro system noscreen instead.

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.