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 (custom Drupal, WordPress, anything) 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.

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

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.

Where do install / upgrade logs go?

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.

Update Status says "No available releases found" on a cloned/migrated/restored D8+ site — how do I fix it?

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.