Troubleshooting & recovery
Root-side diagnosis and recovery for the failure modes that recur on a busy BOA host: stuck tasks, cache faults, 502s, SMTP TLS, backups, firewall bans, and DNS drift.
Root-side diagnosis and recovery for the failure modes that actually recur on a busy BOA host:
- stuck Ægir tasks
- the APCu/Valkey/cron plugin-not-found cascade
- backup-task aborts
- 502/504 upstream failures
- SMTP TLS rejections
resolv.confdrift after DHCP lease renewals- getting yourself unblocked by the CSF/Nginx ban pipeline
Each page is a procedure against the live interface — the actual scripts, control files, log paths, and SQL — not a generic "have you tried turning it off and on again" walkthrough.
Diagnosis here assumes you are root on the box (or hold provider console access) and are fluent in the BOA layout:
- Octopus instances under
/data/disk/<USER> - the SFTP-chroot mirror under
/home/<USER>.ftp - the cron-driven task runner
- the monitor stack under
/var/xdrago - the CSF→Nginx ban chain
The tenant-facing "how do I" framing for these same symptoms lives in the Using and Self-Hosting areas; this is the operator's recovery reference.
Cross-references
The subsystem internals these procedures touch are documented in their own topics:
- the task queue in Architecture
- pool sizing in PHP-FPM performance
- the ban chain in Abuse Guard and Security
- the dump tools in Database
- the off-site engine in Backups
Ægir task failures
Why an Ægir task stalls when the queue is cron-driven, and the recovery paths for spinning tasks, failed deletes, stale state, and pulling a task log off disk.
Recovery cycles & cache faults
Telling apart platform state drift from the APCu, Valkey and cron plugin-discovery cascade, with the Verify/Unlock/Verify cycle and the sizing fixes for each.
SMTP TLS rejection
Diagnosing a certificate verify failed SMTP error from the shell down: the cert chain, CA bundle, SECLEVEL, SNI and IPv6, not a Drupal module bug.
IP-blocked recovery
Getting your own IP unblocked from BOA's CSF and Nginx ban layers: detection, removal, console-only recovery, allowlisting, and the successful-login exemption.
502 / 504 upstream failures
Why 502 and 504 are Nginx-reported but downstream-caused: PHP-FPM pool state, the shared-pool saturation model, the read timeout, and the firewall-block look-alike.
Backup-task failures
The six root causes behind Could not back up sites directory, a source-site fault that also aborts Clone and Migrate: ownership drift, disk-full, cruft, symlinks, and more.
Operator FAQ
Recurring operator questions that fit no single page: hosting non-Ægir vhosts, surviving-upgrade package pins, log locations, instance enumeration, and version markers.
DNS & resolver recovery
Stopping /etc/resolv.conf from flipping after DHCP lease renewals: how BOA owns the file, the two self-healing tiers, the toggles, and the safe dhcpfix recovery tool.