# BOA Documentation

> Documentation for BOA (Barracuda / Octopus / Aegir) — installing, operating, and developing the hosting stack.

## Pages

- [BOA Documentation](https://docs.boa.io/): Documentation for the BOA (Barracuda / Octopus / Ægir) hosting stack, split into four guides by reader role: hosted customers, self-hosters, operators, and stack developers.
- [Ægir vs BOA: what the stack adds](https://docs.boa.io/aegir-vs-boa.md): Ægir is the control panel; BOA is everything underneath it — a hardened, self-watching LEMP stack installed with one command. What BOA adds on top of vanilla Ægir, point by point.
- [Discontinued features](https://docs.boa.io/discontinued.md): Features BOA no longer ships — what each was, why it was dropped, and what replaced it — so searches for old terms find an explanation instead of dead links.
- [Docs changelog](https://docs.boa.io/changelog.md): What changed in this documentation, newest first — new pages, meaningful corrections and reference additions, each with links to the affected pages.

## Using BOA

- [Using BOA](https://docs.boa.io/using.md): The hosted-customer guide: run your sites from the Ægir control panel and your own limited oN.ftp shell, without ever needing root or touching the server.
- [Welcome & your account](https://docs.boa.io/using/welcome.md): What comes with your hosted account — the Ægir control panel, your own limited shell, and the self-service tools — and where to begin once you are settled in.
- [Your account and first login](https://docs.boa.io/using/welcome/your-account-and-first-login.md): What your host handed you, where your welcome-email login details come from, logging into the Ægir control panel the first time, and a tour of your dashboard.
- [Glossary (for site owners)](https://docs.boa.io/using/welcome/glossary.md): Plain-language definitions of the BOA and Ægir words you meet as a site owner: site, platform, client, alias, the control-panel tasks, and the control files.
- [Backdrop CMS sites](https://docs.boa.io/using/backdrop.md): Backdrop CMS as a first-class citizen: the same panel tasks as your Drupal sites, automatic caching and cron, and bee — Backdrop's own CLI — next to drush.
- [Your Backdrop site day to day](https://docs.boa.io/using/backdrop/your-backdrop-site.md): The everyday jobs with bee and drush, where Backdrop keeps its configuration, and what's already handled for you: cron, caching, backups.
- [Upgrading from Drupal 7](https://docs.boa.io/using/backdrop/upgrading-from-drupal-7.md): The built-in Drupal 7 → Backdrop upgrade converts a copy while your existing site keeps serving untouched — with a per-module report before anything is created.
- [Upgrading from Drupal 6](https://docs.boa.io/using/backdrop/upgrading-from-drupal-6.md): The two-step chain for Drupal 6 sites: a built-in Drupal 6 → Drupal 7 task that carries your CCK field data, then the standard Backdrop upgrade on the copy.
- [Converting utf8 databases to utf8mb4](https://docs.boa.io/using/backdrop/converting-utf8-databases.md): The one-step task that converts 3-byte utf8 tables to utf8mb4 — it probes first, reports an honest no-op when there's nothing to do, and backs up before changing anything.
- [Adding modules to your Backdrop site](https://docs.boa.io/using/backdrop/adding-modules.md): Where contrib code goes on a Backdrop site (one folder, and it isn't sites/all), the three ways to get it there, and the short routine that fills a port gap after a Drupal 7 upgrade — kept data included.
- [Connecting to your account](https://docs.boa.io/using/connecting.md): How to reach your account over SSH and SFTP or FTPS: your login details, setting up an SSH key, what the limited shell allows, fixing a refused login, and separate limited logins for your developers.
- [Shell and SFTP access](https://docs.boa.io/using/connecting/shell-and-sftp.md): Connecting over SSH and SFTP, what the limited shell allows and blocks, tunnelling a database tool in, setting up an SSH key for passwordless logins, and rotating your password on demand.
- [When you can't connect](https://docs.boa.io/using/connecting/connection-problems.md): Fixing the two connection problems that trip people up: a host key changed warning after a server rebuild, and a password refused after the 90-day refresh.
- [Extra accounts for your developers](https://docs.boa.io/using/connecting/extra-accounts.md): Giving a developer their own limited SSH/SFTP/FTPS login that reaches only the sites you choose: create a Client, make it the site's owner, and forward the password yourself — and, when your host enables it, a second platform-level login for a developer who maintains a whole codebase.
- [Managing sites & platforms](https://docs.boa.io/using/sites-and-platforms.md): Running your own sites from the Ægir control panel — the platform-and-site model, everyday tasks, cloning, migrating and domain aliases, no server access needed.
- [Sites, platforms and clients](https://docs.boa.io/using/sites-and-platforms/concepts.md): The plain-language mental model behind the control panel: a platform is a codebase, a site is one website that runs on it, and a client is the owner who holds them.
- [Creating and managing a site](https://docs.boa.io/using/sites-and-platforms/managing-sites.md): Creating a site from the Add site form, then the everyday tasks that keep it running — Verify, Disable and Enable, Delete — and how to read a task's status log.
- [Choosing and managing platforms](https://docs.boa.io/using/sites-and-platforms/platforms.md): Choosing the platform a new site runs on, shaping your own list with platforms.info, adding your own codebase by path or makefile, and tuning a platform you own.
- [Site aliases and redirects](https://docs.boa.io/using/sites-and-platforms/aliases-and-redirects.md): Extra domains that answer for one site — adding and removing aliases, the automatic www companion, redirecting them all to your primary domain, and the DNS each one needs.
- [Cloning and moving a site](https://docs.boa.io/using/sites-and-platforms/cloning-and-migrating.md): Clone copies a site to a new domain, Migrate Site moves it to newer code or renames it — plus the safe upgrade path and the rule to change only one thing at a time.
- [Faster cloning and migration](https://docs.boa.io/using/sites-and-platforms/faster-clone-migrate.md): Two optional control-file switches for bulk clone and migrate jobs: FastTrack skips the pre-flight verifications, and MyQuick controls the fast parallel per-table database copy plus the classic-dump opt-out that lets Restore bring a site back whole.
- [Importing an existing site](https://docs.boa.io/using/sites-and-platforms/importing-a-site.md): Bringing a Drupal site from outside Ægir into your account: upload the codebase, register a platform, create a blank site, copy the files, prepare and import the database, and get hardcoded file paths right.
- [Scheduled cron for your sites](https://docs.boa.io/using/sites-and-platforms/site-cron.md): Ægir runs Drupal cron for every site on a schedule you control — the hourly default, changing or disabling it per site, how it works behind a proxy or without DNS, and running cron on demand.
- [Reading another site's database](https://docs.boa.io/using/sites-and-platforms/migration-source.md): The Migration source task gives one of your sites read-only access to another of your sites' database, so Drupal's migration tools can read the old site while you build the new one.
- [SSL for your sites](https://docs.boa.io/using/ssl.md): Serving your sites over HTTPS is a single control-panel setting — free, auto-renewing Let's Encrypt certificates, with nothing to buy, upload, or run from a shell.
- [HTTPS for your sites](https://docs.boa.io/using/ssl/ssl-for-your-sites.md): Switching Encryption on for a site, the DNS every domain and alias must satisfy first, automatic Let's Encrypt renewal, re-enabling HTTPS after a clone or rename, and why dev-named sites get a placeholder certificate.
- [Tuning your site & platform](https://docs.boa.io/using/tuning.md): The dials BOA leaves in your hands, turned from your own shell without touching the server: the INI control files, your PHP version, and the modules BOA manages.
- [Which file do I edit?](https://docs.boa.io/using/tuning/which-file-do-i-edit.md): The quick decision guide: find the thing you want to change in a table, and it points you at the one file to edit and the page with the full instructions.
- [Platform and site INI settings](https://docs.boa.io/using/tuning/platform-and-site-ini.md): The full guide to the two INI control files: how to edit them, how a site setting overrides a platform one, and every tenant-editable setting grouped by what it does.
- [Choosing your site's PHP version](https://docs.boa.io/using/tuning/php-version.md): Pick the PHP that serves your sites and the one that runs drush, composer and bee, using one-line files in your control folder, with a per-site override and an instant command-line switch that steers your Ægir backend tasks and platform builds too.
- [Modules BOA manages](https://docs.boa.io/using/tuning/modules.md): On Drupal 6 and 7 sites BOA force-enables a few performance modules and disables risky ones — the full lists of what it touches, why, and your options when its choice and yours differ. Plus the managed robots.txt (edit it in the module, and the per-domain override for Domain Access), and how to override a bundled o_contrib module with your own copy in sites/all.
- [Caching on your sites](https://docs.boa.io/using/caching.md): How the caching layers on a BOA host fit together — the Nginx front cache, Drupal's page cache, the Redis/Valkey object cache, and PHP's opcache — what each one does for your site, and which dials are yours to turn.
- [The Redis/Valkey object cache](https://docs.boa.io/using/caching/redis-valkey-object-cache.md): How every Drupal cache bin — including your own custom bins — rides the fast object cache automatically: routing, per-site key isolation, cache clearing and wildcard flushes, the Fast Redis Lock, size limits, the automatic database fallback, how to verify it all with the X-Cache headers, and what happens to a site's cache namespace when a domain name is reused.
- [The front cache & Drupal's page cache](https://docs.boa.io/using/caching/front-cache-and-page-cache.md): The two full-page layers: the Nginx Speed Booster micro-cache and Drupal's own page cache — the TTL you can tune, why the page cache stays on, the right way to exempt a single URL from caching, and the AdvAgg answer to styling that breaks after a cache clear.
- [PHP opcache & APCu](https://docs.boa.io/using/caching/php-opcache-and-apcu.md): The PHP-level caches: why code and settings changes take about a minute to appear, what the per-worker APCu tier does for Drupal 8+ sites, and the self-service graceful PHP-FPM reload that clears stale APCu.
- [Drush in your instance](https://docs.boa.io/using/drush.md): Drush comes ready to use from your own shell: the right version for each site, an alias per site, and the correct PHP already wired up — no install, no config.
- [Running Drush](https://docs.boa.io/using/drush/drush-basics.md): Your first Drush command from the shell: the everyday jobs, choosing the PHP version Drush and Composer run on, and using a modern site's own bundled Drush with vdrush after unlocking it.
- [Drush aliases and contributed commands](https://docs.boa.io/using/drush/aliases-and-contrib.md): How the per-site @alias works and how to list yours, why targeting an alias beats changing into a site folder, and what to do when a contributed command is not recognised.
- [Deploying your own code](https://docs.boa.io/using/deploying-code.md): Bring your own Composer-built or Git-tracked codebase, register it as a platform from your own shell, and run sites on it — no root, no touching the server.
- [Building your own platform](https://docs.boa.io/using/deploying-code/building-a-platform.md): Build a Drupal codebase with Composer under static/platforms, register it in the panel with Platform Path, and add sites — with Ægir auto-detecting the web docroot.
- [Developing your site](https://docs.boa.io/using/deploying-code/dev-workflow.md): Use the .dev. preview URL to see errors and skip caches, turn on Twig or Drupal 7 theme debugging, and learn which settings files are yours to edit and which BOA rewrites.
- [Ruby Gems and Node tools](https://docs.boa.io/using/deploying-code/gems-and-node-tools.md): Run Sass/Compass and — where the host enables Node — Gulp, Grunt and Bower directly in your oN.ftp shell; one control file switches the whole toolchain on for your account.
- [In-place upgrades — unlocking your codebase](https://docs.boa.io/using/deploying-code/in-place-upgrades.md): How to use the unlock.info control file to take ownership of your codebase for in-place composer or git upgrades, what the nightly codebase lock normally does, and how to hand the keys back when you are done.
- [Backing up & restoring](https://docs.boa.io/using/backups.md): Nightly database backups run automatically; add on-demand snapshots and rollbacks in the panel, encrypted offsite copies to your cloud storage, and file recovery.
- [Backing up and restoring in the UI](https://docs.boa.io/using/backups/backup-and-restore.md): The control panel Backup and Restore tasks: take an on-demand snapshot in one of three modes, roll a site back — completely or database-only or files-only, matching what the snapshot holds — and list, export, or download backups.
- [Off-site backups & mybackup](https://docs.boa.io/using/backups/mybackup-and-quota.md): The extended off-site backup subsystem for hosted and PRO accounts: basic use first — drop in provider credentials, restore with one command, control local dump retention — then the advanced detail when you want it.
- [How your site's files are stored](https://docs.boa.io/using/backups/your-files-storage.md): Why your files and private folders survive platform rebuilds and upgrades untouched, how cloning keeps each site's copies separate, what a restore or a delete does to them, and the optional file-sharing control file.
- [Exporting your site](https://docs.boa.io/using/backups/exporting-your-site.md): Taking a complete copy of a site away — database, site directory and codebase — from your own login: a one-line sql-dump over SSH, rsync with the -L flag, and the one backup-archive caveat to know.
- [Disaster-proof access to your off-site backups](https://docs.boa.io/using/backups/disaster-proof-restore.md): How to open your encrypted off-site backups with no BOA server at all: ask your host for your encryption passphrase once, install standard Duplicity on your Mac, Windows PC or any Linux machine, and let the boa-restore helper do the rest — check, list and restore straight from your own cloud bucket, plus the fire drill worth running before you ever need it.
- [Protecting your site](https://docs.boa.io/using/protecting-your-site.md): BOA's built-in access protections and the locks you add yourself: opting out of a built-in guard per site, whole-site and login/admin IP allow-lists, and the per-site AI crawler policy.
- [Restricting access to your site](https://docs.boa.io/using/protecting-your-site/access-control.md): The access controls you manage from your own files — the default admin-page protection explained in full, with pointers to the site IP lock, the login/admin IP lock, and the AI crawler policy, each on its own page.
- [Locking a whole site to your own IP addresses](https://docs.boa.io/using/protecting-your-site/site-ip-lock.md): Make an entire site reachable only from IP addresses you list — ideal for intranets, staging copies and admin-only tools — from one control file in your own account, with built-in protection against locking yourself out.
- [Locking login and admin to your IPs](https://docs.boa.io/using/protecting-your-site/login-admin-ip-lock.md): Keep a site public while its /user and /admin pages answer only to IP addresses you list — one control file in your own account, with built-in protection against locking yourself out.
- [AI crawlers and assistants on your sites](https://docs.boa.io/using/protecting-your-site/ai-crawlers.md): Which AI bots may read your sites: training crawlers are blocked by default, AI search and assistant fetchers are allowed and rate-limited, and one control file changes it per site.
- [Load testing your site](https://docs.boa.io/using/protecting-your-site/load-testing.md): Why a load test fired from a single address measures BOA's DoS protection instead of your site, the kinds of testing that do produce real numbers, and the two things to get right before a genuine pre-launch load audit.
- [Attacks that never reach your site](https://docs.boa.io/using/protecting-your-site/attacks-that-never-reach-your-site.md): What the server refuses before your Drupal or Backdrop site ever sees it — probes for other systems' admin pages, secret-file fishing, injection payloads, scrapers and floods — how offenders get blocked by behaviour, what keeps the site standing during a swarm, and what stays yours to decide.
- [Extra services](https://docs.boa.io/using/extra-services.md): The ready-made services around your sites: Solr search, the Adminer database browser, outbound mail, New Relic monitoring, and the system print/PDF binaries.
- [Search (Solr) for your site](https://docs.boa.io/using/extra-services/search.md): Give a site its own private Solr core: set one line in the site INI, add the matching Drupal search module, and BOA builds, wires up, and later removes the core.
- [Browsing your database (Adminer)](https://docs.boa.io/using/extra-services/database-gui.md): Open the built-in Adminer database browser over HTTPS, log in with a site's own credentials from its drushrc.php, and browse, query or export tables safely.
- [Sending mail from your site](https://docs.boa.io/using/extra-services/outbound-mail.md): Everyday transactional mail just works, bulk newsletters belong at an email service, and an optional SMTP module improves delivery, plus what to check when mail is missing.
- [New Relic monitoring for your sites](https://docs.boa.io/using/extra-services/new-relic.md): Point your sites at New Relic APM with two small switches — the license-key control file and the per-site INI setting — and each site reports as its own application.
- [Print & PDF tools (wkhtmltopdf and pdftk)](https://docs.boa.io/using/extra-services/print-pdf-tools.md): The system wkhtmltopdf, wkhtmltoimage and pdftk binaries are preinstalled on every BOA server — point your print/PDF modules at the system paths instead of uploading your own builds.
- [When something's wrong](https://docs.boa.io/using/when-somethings-wrong.md): A calm first stop for troubleshooting from the control panel and your shell: quick safe checks, reading task status, resetting a login, and when it's your host's job.
- [My site is broken (white screen)](https://docs.boa.io/using/when-somethings-wrong/broken-site.md): Track down a white screen from the control panel and your shell: read the hidden error in the log or the .dev. URL, undo recent changes, rebuild the cache, and run Verify.
- [When an Ægir task fails](https://docs.boa.io/using/when-somethings-wrong/task-recovery.md): Recover a failed control-panel task: read its log before retrying, re-run Verify, run the Lock and Unlock Local Drush cycle, clear the classic Clone/Migrate failures yourself, and know when a stuck queue is your host's job.
- [Password and access recovery](https://docs.boa.io/using/when-somethings-wrong/password-and-access.md): Get back into the three logins in your world: a Drupal user on your site, your control panel account, and your oN.ftp shell or SFTP password, plus using an SSH key.
- [I'm blocked, or my site is slow](https://docs.boa.io/using/when-somethings-wrong/blocked-or-slow.md): Why BOA's abuse protection may briefly block your address and lift on its own, what a short 502 under load means as BOA eases off, why a 502 after exactly three minutes is different, and the checks you can do yourself.
- [Site health tasks](https://docs.boa.io/using/when-somethings-wrong/site-health-tasks.md): The one-click Flush all caches and Rebuild registry tasks, what each does and when to run each.
- [Local development with DDEV](https://docs.boa.io/using/local-development-with-ddev.md): Using the ddev-boa add-on to pull your hosted site's database and files into a local DDEV project over your existing shell login, for developing on your own machine.
- [Drupal distributions](https://docs.boa.io/using/distributions.md): The Drupal distributions BOA carries — Drupal CMS, Commerce, Thunder, LocalGov, farmOS, Open Social, OpenCulturas and more — what each one ships as, which Drupal core and PHP version each is built for, and how to get it into your platform list.
- [Drupal CMS](https://docs.boa.io/using/distributions/drupal-cms.md): The Drupal Association's flagship product as a one-task platform install: what ships, what a fresh install looks like, and how it stays current.
- [Commerce Kickstart — three generations](https://docs.boa.io/using/distributions/commerce.md): Drupal Commerce on BOA across three generations: current Commerce Kickstart on Drupal 11, Commerce v.2 for existing Drupal 10 shops, and the Drupal 7 Kickstart kept for legacy estates.
- [Thunder](https://docs.boa.io/using/distributions/thunder.md): The professional publishing distribution from Hubert Burda Media as a one-task platform install — rebuilt from upstream each cycle, on the current Drupal core.
- [LocalGov Drupal](https://docs.boa.io/using/distributions/localgov.md): The council-built publishing platform for local government as a one-task install — built from the drupal.org-packaged 4.x line, rebuilt from upstream each cycle.
- [farmOS](https://docs.boa.io/using/distributions/farmos.md): The farm management and record-keeping platform as a one-task install — built from the latest upstream release, with one deliberate surprise: the front page is locked by design.
- [OpenCulturas](https://docs.boa.io/using/distributions/openculturas.md): The culture-sector platform for venues, events and cultural networks as a one-task install — rebuilt from upstream each cycle, with a build-level correction that makes fresh installs work first time.
- [Open Social](https://docs.boa.io/using/distributions/open-social.md): The community-platform distribution as a one-task install — rebuilt from upstream as BOA releases ship, for running your own social community on your own infrastructure.
- [OpenFed](https://docs.boa.io/using/distributions/openfed.md): The Belgian federal government's multilingual, accessibility-first distribution as a one-task install — rebuilt from upstream as BOA releases ship.
- [Opigno LMS](https://docs.boa.io/using/distributions/opigno.md): The learning-management distribution rebuilt from upstream's current release — with the install defects upstream ships corrected, so a working LMS is one task away.
- [Ubercart — Drupal 6 and 7 legacy commerce](https://docs.boa.io/using/distributions/ubercart.md): Ubercart shops on BOA's maintained Drupal 7 and Pressflow 6 legacy cores — still installable, still served, with a migration runway when you're ready.
- [EzContent](https://docs.boa.io/using/distributions/ezcontent.md): Srijan's content-and-media distribution as a one-task install — ready-made content types, layout-built landing pages and a decoupled-ready API layer, as a pinned, tested build.
- [Varbase](https://docs.boa.io/using/distributions/varbase.md): Vardot's best-practice starter-kit distribution as a one-task platform install — rebuilt from upstream each cycle, on the current Drupal core.
- [Migrating a Drupal 7 site to Drupal CMS](https://docs.boa.io/using/distributions/migrating-from-drupal-7.md): The end-to-end workflow for moving a Drupal 7 site into Drupal CMS on your own account: both ends side by side on one server, Drupal's own Migrate API doing the content work, rehearsals on disposable copies, and a rename cutover when you're ready.
- [Leaving Drupal 7: choosing your exit](https://docs.boa.io/using/distributions/leaving-drupal-7.md): Two paved exits from Drupal 7 — the Backdrop upgrade that keeps your site's structure, and the Drupal CMS migration that rebuilds around your content — and why most of the classic migration project stops existing when both ends live on one server.

## Self-Hosting

- [Self-Hosting BOA](https://docs.boa.io/self-hosting.md): Run your own BOA server without being a sysadmin: install cleanly onto a fresh box, let it keep itself current, and recover when a service won't start.
- [Is BOA for me?](https://docs.boa.io/self-hosting/start-here.md): Decide before you install: what BOA is, what it hosts (Drupal and Backdrop), the kind of server it needs, and whether to pick the free LTS or paid PRO edition.
- [Before you install](https://docs.boa.io/self-hosting/before-you-install.md): The eleven-item pre-flight checklist before installing: a clean box, supported OS, a root password for console access, root SSH key, hostname and DNS, open ports, RAM and disk, and a snapshot plan.
- [Install BOA](https://docs.boa.io/self-hosting/install-boa.md): The full install from start to finish: open a screen session, fetch the installer, run the one build command, wait out the quiet phases, reboot, and log into Ægir.
- [Debian to Devuan (autoinit)](https://docs.boa.io/self-hosting/debian-to-devuan.md): Convert a fresh Debian box to Devuan with autoinit before installing BOA: let the installer do it for you, or run autoinit by hand and confirm from its logs.
- [Essential settings](https://docs.boa.io/self-hosting/essential-settings.md): BOA ships already tuned, so only a handful of settings matter: your admin email, the auto-update switch, and HTTPS-renewal notices, plus how to edit the config safely.
- [Keeping BOA current](https://docs.boa.io/self-hosting/keeping-current.md): Most of the time you do nothing: SKYNET keeps the box patched automatically. When you do need to, this walks through running a full upgrade by hand, step by step.
- [Upgrading the operating system](https://docs.boa.io/self-hosting/os-upgrades.md): Move the whole operating system to a newer Devuan codename with the guided driver: bring BOA current, snapshot, drop a target marker file, and let it hop there safely.
- [When the box breaks](https://docs.boa.io/self-hosting/when-the-box-breaks.md): A calm, in-order recovery checklist: is it your blocked IP, is the box self-healing, has the disk filled, and the reboot-then-restore ladder when nothing else works.
- [Resizing the root disk](https://docs.boa.io/self-hosting/resize-root-disk.md): After your provider enlarges the VM disk, grow the partition and ext4 filesystem to match, live and without a reboot, with a snapshot and device-name checks first.
- [Migrating from vanilla Ægir](https://docs.boa.io/self-hosting/migrate-from-aegir.md): Adopt a vanilla Ægir 3.x estate into BOA with the drilled aegir2boa path: read-only preflight grading, staged conversion, and a reversible cutover.
- [Backdrop CMS on your server](https://docs.boa.io/self-hosting/backdrop-cms.md): Run Backdrop CMS as a first-class platform: default-on support, self-updating platforms, the bee CLI, and safe built-in upgrade paths from Drupal 7 and Drupal 6.
- [Local development install](https://docs.boa.io/self-hosting/local-development-install.md): Install the full BOA stack on a local VM or container at aegir.local, with no public IP or DNS, for development and testing — the same BOA you run in production.
- [Prebuilt stack packages](https://docs.boa.io/self-hosting/prebuilt-packages.md): Why installs and upgrades feel fast on Devuan Daedalus: BOA fetches its heavy stack components as verified, ready-made packages — and falls back to compiling from sources automatically whenever a package isn't available.
- [Security on your box](https://docs.boa.io/self-hosting/security.md): What BOA already hardens for you — firewall, abuse guard, hourly security patching, TLS — the short list that is genuinely yours to do, and when to escalate to the advanced security reference.
- [Migrating a Drupal 7 site to Drupal CMS](https://docs.boa.io/self-hosting/migrating-to-drupal-cms.md): Run the whole Drupal 7 → Drupal CMS migration on your own BOA server: build the Drupal CMS platform, install the target site next to the source, let Drupal's Migrate API move the content, rehearse on copies, and cut over by rename.
- [Grav CMS on your server](https://docs.boa.io/self-hosting/grav-cms.md): Run Grav 2 sites under the Ægir control panel: opt-in support, self-updating admin-bundle platforms, per-site full installs, the grav CLI, mirror-fed one-click upgrades, upgraded copies, Rename and Cutover.
- [Textpattern CMS on your server](https://docs.boa.io/self-hosting/textpattern-cms.md): Run Textpattern sites under the Ægir control panel: opt-in support, shared-core multisite platforms tracking the newest official release, a path-mapped admin, and enforced modern PHP.

## Operating

- [Operating BOA](https://docs.boa.io/operating.md): The complete root-operator reference for running BOA in production: architecture, control files, tuning, security, monitoring, and troubleshooting.
- [Architecture & Ægir internals](https://docs.boa.io/operating/architecture.md): The operating reference for BOA's internal model: the layered front-end and back-end split, the entity and task-queue engines, and the multi-Octopus layout.
- [Architecture overview & BOA fork model](https://docs.boa.io/operating/architecture/overview.md): The layered view of a BOA host: the Hostmaster front end and Provision back end, the Master and Satellite split, the on-disk layout, and the fork's divergence from Ægir.
- [Entity & service model](https://docs.boa.io/operating/architecture/entity-model.md): The Drupal node types Ægir runs on: server, platform, site, client and package, their real status constants, the BOA permissions matrix, and each one's provision backend.
- [Task queue engine](https://docs.boa.io/operating/architecture/task-queue.md): How BOA drains the Ægir task queue from cron rather than a daemon: the dispatch chain, fast and slow cadence, the registered queues, and the pause and failure controls.
- [Multi-Octopus model](https://docs.boa.io/operating/architecture/multi-octopus.md): One Master plus N Octopus instances per host: per-instance roots and control files, the instance-owner versus lshell identity split, the isolation boundary, and adding instances.
- [Managing Ægir from the command line](https://docs.boa.io/operating/architecture/command-line.md): Driving the Ægir back end directly: the provision and hosting-task verbs, the node-first way to stand up a platform and site, what Verify checks per context, and debugging a task.
- [Host control files & INI reference](https://docs.boa.io/operating/control-files-ini.md): The complete operator reference for BOA's four-layer config: the host .cnf files, the empty boolean marker files, the tenant-editable INI, and what wins.
- [Overview — the control-file system](https://docs.boa.io/operating/control-files-ini/overview.md): How BOA's host control files work: the master .cnf files you edit, the empty boolean toggle markers, the /root to /etc/boa relocation, and the internal state files.
- [/root/.barracuda.cnf reference](https://docs.boa.io/operating/control-files-ini/barracuda-cnf.md): The host-wide barracuda.cnf variables by family: host identity, CPU and load thresholds, Percona, Nginx build and DoS knobs, PHP, Redis or Valkey, SSH, and force-reinstall.
- [/root/.${USER}.octopus.cnf reference](https://docs.boa.io/operating/control-files-ini/octopus-cnf.md): The per-instance octopus.cnf variables: instance identity, platform tree control, PHP version and FPM sizing, SQL conversion, cleanup retention, and the plan selector.
- [INI files & precedence](https://docs.boa.io/operating/control-files-ini/ini-precedence.md): The tenant-editable platform and site INI templates, the compiled-in defaults beneath them, the four-layer override chain, refresh timing, and the SQL-convert forcing exception.
- [Drupal module support matrix](https://docs.boa.io/operating/control-files-ini/modules-matrix.md): BOA's curated contrib module set for D6 and D7 platforms: the support and enforcement flag legend, the day-gated force enable and disable lists, and how maintenance applies them.
- [_XTRAS_LIST & install modes](https://docs.boa.io/operating/control-files-ini/xtras-list.md): The _XTRAS_LIST tokens selecting which optional packages BOA installs: what each three-letter code adds, the additive never-uninstall rule, and the PUBLIC and LOCAL install modes.
- [PHP-FPM & performance](https://docs.boa.io/operating/php-fpm-performance.md): How BOA sizes and tunes the PHP execution tier: the RAM budget, master and tenant pool workers and memory_limit, the opcache/APCu shares, and the cache stack.
- [FPM capacity sizing](https://docs.boa.io/operating/php-fpm-performance/fpm-capacity.md): How BOA sizes PHP-FPM: the box-wide RAM budget from installed memory, master versus tenant pool pm.max_children, the shared and dedicated plan model, and the override knobs.
- [opcache & APCu](https://docs.boa.io/operating/php-fpm-performance/opcache-apcu.md): How BOA sizes the opcache and APCu shares from the RAM budget, what it writes into each phpNN.ini, the Valkey/Redis cache settings, and the read-only fpm_tune/fpmreport samplers.
- [Cache & cron tuning](https://docs.boa.io/operating/php-fpm-performance/cache-tuning.md): Diagnosing intermittent plugin-not-found errors on busy hosts: Valkey memory starvation, drush cache poisoning, HDD autoloader timeouts, cron tuning, and the graceful APCu flush.
- [Web tier (Nginx) internals](https://docs.boa.io/operating/nginx-internals.md): How BOA assembles the web tier from four cooperating Nginx layers, from static config templates to the per-request edge-policy guard chain.
- [Custom rewrites & location blocks](https://docs.boa.io/operating/nginx-internals/rewrites-locations.md): How to add per-site rewrites, redirects, and custom location blocks through the two operator include files that survive upgrades, and where each lands in the rendered vhost.
- [Config templates](https://docs.boa.io/operating/nginx-internals/config-templates.md): The two Nginx template surfaces: the static config set BOA copies verbatim, and the Provision-rendered master http config that holds the log format and the rate-limit zones.
- [SSL operations — LE renewal, custom certs](https://docs.boa.io/operating/nginx-internals/ssl-operations.md): How BOA issues and renews Let's Encrypt certificates from the nightly run, the daily renewal cadence and failure reporting, and how to install a custom OV/EV or wildcard cert.
- [Nginx debugging](https://docs.boa.io/operating/nginx-internals/nginx-debug.md): Diagnosing three Nginx failure modes with BOA's real socket and log paths: 502/504 against PHP-FPM, the high-load 503 reduced-feature mode, and the redirect loop to install.php.
- [Edge policy](https://docs.boa.io/operating/nginx-internals/edge-policy.md): BOA's Nginx edge machinery before PHP-FPM: Cloudflare real-client-IP recovery, the universal secret-path deny, and the shared reload lock the config generators take.
- [AI crawler policy](https://docs.boa.io/operating/nginx-internals/ai-crawler-policy.md): BOA's per-class AI bot policy at the Nginx edge: training blocked by default, search and assistant fetchers allowed and rate-limited per vendor, and the per-site policy.txt control file.
- [HTTP/3 and KTLS](https://docs.boa.io/operating/nginx-internals/http3-ktls.md): BOA's HTTP/3 (QUIC) and kernel-TLS edge tuning: the server-wide _NGINX_KTLS opt-out, wildcard-only reuseport listener placement, the HTTP/3 trusted-host fix, and picking HTTP/3 up after an upgrade.
- [SQL-admin vhosts](https://docs.boa.io/operating/nginx-internals/sql-admin-vhosts.md): BOA's SQL-admin subdomain vhosts (Adminer, sqlbuddy, CGP): how the xtras keywords gate each install, and the IP-allowlist-plus-crawler-drop model that guards them instead of basic-auth or Ægir SSO.
- [Database (Percona/MySQL)](https://docs.boa.io/operating/database.md): The shared Percona Server on a BOA host: how it is installed and tuned, the my.cnf lifecycle, the nightly mydumper dumps, the browser DB tools, and graceful restarts.
- [Percona install + tuning](https://docs.boa.io/operating/database/percona-setup-tuning.md): Supported Percona versions per Devuan codename, the staged 5.7 to 8.0 to 8.4 in-place upgrade and its recovery guards, the real memory tuner, and the high-load restart.
- [my.cnf lifecycle + mycnfup](https://docs.boa.io/operating/database/my-cnf-lifecycle.md): How BOA deploys and per-version sed-patches /etc/mysql/my.cnf, the logging-reset-first rule, the _CUSTOM_CONFIG_SQL protection, and what mycnfup actually does.
- [Dumps with mydumper](https://docs.boa.io/operating/database/dumps-mydumper.md): The nightly per-DB mydumper dump chain, the mysql system-schema mysqldump exception, where dumps land, retention, the repair and binlog helpers, and how to restore.
- [DB GUI tools](https://docs.boa.io/operating/database/db-gui-tools.md): Adminer and sqlbuddy on their own subdomain vhosts, the ADM and BDD xtras keywords, and the IP-allowlist plus app-credential access model, with no Ægir or Drupal login.
- [Graceful MySQLD control (move_sql.sh)](https://docs.boa.io/operating/database/move-database.md): move_sql.sh: the clean stop, start, and restart building block the InnoDB log-resize, Percona-upgrade, and self-heal paths drive. Despite the name it moves no databases.
- [Percona 8 upgrade readiness (codebasecheck)](https://docs.boa.io/operating/database/percona8-readiness.md): codebasecheck: which accounts, if any, block the box-wide 5.7 to 8.0 to 8.4 upgrade, the per-core compatibility thresholds, and the --deep contrib and schema analysis.
- [Orphan database cleanup (sqlclean)](https://docs.boa.io/operating/database/orphan-database-cleanup.md): The root-only sqlclean tool: find and remove databases nothing in Ægir owns any more — DRY report first, per-name confirmation or a reviewed-manifest auto mode, and the protect list that keeps your non-Ægir databases safe.
- [Backups internals & operations](https://docs.boa.io/operating/backups.md): Off-site backup on a BOA host: a Duplicity-driven subsystem with three orchestrators — multiback, mybackup, and the legacy backboa — each with its own config and gate.
- [Backup subsystem overview & architecture](https://docs.boa.io/operating/backups/overview.md): The two generations of off-site backup tooling, the Duplicity layer beneath them, what multiback actually captures, the licence gate, and the backup-binary 755 failure mode.
- [multiback operations — dcysetup, config tree, cron](https://docs.boa.io/operating/backups/multiback-operations.md): dcysetup install and setup, the /root/.remote_backups/ config tree, credential and secret files, the paths.txt variables, the interval cron, and how secrets reach Duplicity.
- [Backup retention policy](https://docs.boa.io/operating/backups/retention.md): KEEP_WITHIN and FULL_BACKUP_FREQUENCY validation, ranges, and defaults, the time-based cleanup path, the destructive purge distinction, and local-dump retention.
- [Backup regions, bucket names & target URLs](https://docs.boa.io/operating/backups/regions-and-buckets.md): How multiback builds bucket names and per-backend target URLs deterministically, which providers need a bucket created by hand, and how to test connectivity first.
- [Backup CLI reference](https://docs.boa.io/operating/backups/cli-reference.md): Exact verb dispatch and argument order for multiback, mybackup, duobackboa, and backboa, including the positional restore arguments and the per-bucket log paths.
- [Legacy backboa & duobackboa (AWS S3)](https://docs.boa.io/operating/backups/legacy-backboa.md): The inline AWS-S3 config variables for backboa and duobackboa, the single-bucket scheme, the static crontab schedule, the randomised full-backup day, and cross-host retrieve.
- [Security & isolation](https://docs.boa.io/operating/security.md): BOA's multi-tenant threat model and every layer that enforces it — SYNPROXY, CSF, the Nginx edge, AppArmor, restricted shells, SSH and admin-path hardening.
- [BOA security model — multi-Ægir architecture](https://docs.boa.io/operating/security/security-model.md): The three-tier root, aegir and tenant trust model, and the built-in protections that isolate Octopus tenants; the deep hardening knobs live on their own focused pages.
- [lshell + manage_ltd_users](https://docs.boa.io/operating/security/lshell-ltd-users.md): The per-tenant restricted shell that isolates Octopus tenants: the oN and oN.ftp two-account model, what lshell blocks, and the manage_ltd_users orchestrator.
- [CSF + LFD firewall lifecycle](https://docs.boa.io/operating/security/csf-firewall.md): CSF and the LFD login-failure daemon as BOA's host firewall: the install and upgrade lifecycle, the Abuse Guard ban loop, migration-proxy trust, and blocked-IP recovery.
- [SYNPROXY iptables-based DDoS protection](https://docs.boa.io/operating/security/synproxy-ddos.md): Linux kernel SYN-flood mitigation as the lowest DDoS layer beneath CSF: the synproxy command family, live counters, reassert after reboot, and snapshot rollback.
- [AppArmor confinement profiles](https://docs.boa.io/operating/security/apparmor.md): The 46 Mandatory Access Control profiles BOA ships for PHP and its daemons — off by default, opt-in via a control file and reboot in complain or enforce mode.
- [SSH server + SFTP hardening](https://docs.boa.io/operating/security/ssh-sftp.md): What BOA enforces in sshd_config, how the strip-and-append upgrade reconciliation decides which edits survive, and the MySecureShell and Pure-FTPd SFTP and FTPS chroot.
- [Password hashing — SHA512 → Bcrypt/Blowfish](https://docs.boa.io/operating/security/password-hashing.md): The default SHA512 account hashing and the optional pam_unix2 migration to Bcrypt, including the PAM transition and the failure mode that can lock out every account.
- [Extra SSH/SFTP/FTPS accounts per client](https://docs.boa.io/operating/security/shell-extras.md): How BOA provisions one extra SSH, SFTP and FTPS subaccount per Ægir Client, scoped to that Client's own sites, and its provisioning, key and removal lifecycle.
- [`/admin*` URL protection](https://docs.boa.io/operating/security/admin-url-protection.md): The default block on anonymous /admin access — the unconditional Nginx guard, the INI-gated 301 redirect to the homepage, and the disable_admin_dos_protection per-site opt-out.
- [Whole-site IP allow-list — `ip_access`](https://docs.boa.io/operating/security/site-ip-access.md): The ip_access generator that locks an entire site — or the master SQL-admin proxies — to a per-instance IP allow-list at Nginx, with automatic anti-lockout for loopback, the server and active SSH clients.
- [Login/admin IP allow-list — `user_admin_access`](https://docs.boa.io/operating/security/user-admin-ip-access.md): The user_admin_access generator that locks only a site's /user and /admin surface to a per-instance IP allow-list at Nginx while the rest of the site stays public, with the same anti-lockout as ip_access.
- [Mailing policy — no bulk mail from BOA hosts](https://docs.boa.io/operating/security/mailing-policy.md): Why BOA hosts send transactional mail only and not bulk, what to route through an external provider instead, and how to configure an SMTP relay for outbound mail.
- [Drush extension deny-filter (*.drush.inc)](https://docs.boa.io/operating/security/drush-extension-filter.md): The default-deny filter that stops tenant .drush.inc command files from running as a privileged backend identity, its backend-only gate, per-instance opt-ins and kill switch.
- [Shared codebase permissions — fixrepo](https://docs.boa.io/operating/security/shared-codebase-permissions.md): The root-only fixrepo tool that makes an entire codebase and its git metadata group-writable with setgid directories, so an account's oN and oN.ftp identities can work on the same tree without permission clashes.
- [The codebase lock — nightly ownership management](https://docs.boa.io/operating/security/codebase-lock.md): How BOA's nightly worker re-asserts code ownership and permissions on registered platforms, what unlock.info and skip.info flip, which barracuda.cnf and INI knobs gate the whole machinery, and how Verify interacts with it.
- [Strict binary permissions](https://docs.boa.io/operating/security/strict-bin-permissions.md): The _STRICT_BIN_PERMISSIONS hardening: group-read stripping on system binaries and the system-shell switch to dash, both running only during barracuda upgrade passes.
- [Security audit hardening & edge anti-spoofing](https://docs.boa.io/operating/security/security-audit-hardening.md): The filesystem permission baseline, the codebase-wide 5.9.5 security-audit outcomes, the 5.10.1 Cloudflare-aware anti-spoofing hardening, and the edgetest edge-stack checker.
- [Database credentials — cloaking](https://docs.boa.io/operating/security/database-credentials.md): Why a hosted site's settings.php holds no database password, where the credentials actually live, and how the web and command-line paths each obtain them.
- [Per-instance group — instgrp](https://docs.boa.io/operating/security/per-instance-group.md): Why every Octopus account now owns a private Unix group, what that closes between tenants, what deliberately stays shared, and the root-only instgrp tool that converts, reports and reverts an account.
- [Platform developer account](https://docs.boa.io/operating/security/platform-developer-account.md): Step by step for operators: giving one Client's developer a second shell login that reaches whole codebases — enabling _LTD_PLATFORM_CLIENTS, what the next pass builds, how to verify it, the Drush unlock window, retiring the account, and what to check when something is missing.
- [Abuse Guard (nginx IDS)](https://docs.boa.io/operating/abuse-guard.md): BOA's application-layer web defence: real-time nginx map and geo guards that drop hostile requests, plus a post-hoc log scorer that feeds genuine offenders into CSF.
- [scan_nginx scoring engine](https://docs.boa.io/operating/abuse-guard/scan-nginx-scoring.md): The post-hoc log analyser that scores each real client IP from recent access.log lines across six ban-issuing detectors and two alert paths, writing offenders into the ban pipeline.
- [The ban pipeline](https://docs.boa.io/operating/abuse-guard/ban-pipeline.md): The scheduled scripts that turn scored offenders into blocks: guest-fire adds temporary CSF bans, guest-water escalates repeats, nginx_deny rebuilds the ban geo, and nginx_fleet renders the crawler-fleet refusal maps.
- [Request guards](https://docs.boa.io/operating/abuse-guard/request-guards.md): The real-time half: a wall of nginx map and geo directives that classify every request by IP, URI, User-Agent, Referer and query, dropping hostile ones before PHP-FPM.
- [Abuse Guard configuration reference](https://docs.boa.io/operating/abuse-guard/configuration.md): The authoritative reference for every Abuse Guard tuning knob: each variable's built-in default, what it controls, and how barracuda.cnf overrides replace those values.
- [Operations + tuning](https://docs.boa.io/operating/abuse-guard/operations.md): The operator side of the Abuse Guard: reading live state, lifting or cycling a ban, whitelisting an IP, path or service, debug output, and the caveats before extending it.
- [Self-healing monitor stack](https://docs.boa.io/operating/monitoring.md): How each BOA box watches and repairs itself from a single root crontab of short-lived scripts: service watchdogs, load auto-pause, process guards, and nightly maintenance.
- [Service auto-healing watchdogs](https://docs.boa.io/operating/monitoring/auto-healing.md): The minute.sh fan-out of short-lived per-service watchdogs that restart nginx, php-fpm, mysql and the rest in place whenever one is found down, stuck or misconfigured.
- [Load control & auto-pause](https://docs.boa.io/operating/monitoring/load-control.md): The auto-pause safety net in second.sh: load sampled every few seconds, crawler blocking, web-stack pause and runaway kills by threshold, then automatic recovery.
- [Process guards & auth scanners](https://docs.boa.io/operating/monitoring/process-guards.md): The heavy passes of second.sh: the _proc_control service guards, the auth and shell-escape scanners, and runner.sh, the cron-driven Ægir task-queue runner.
- [Cron cadence & idle-load throttle](https://docs.boa.io/operating/monitoring/cadence-and-throttle.md): Why cron-fired watchdogs show load 3 to 4 on an idle box, and the CI, SLOW or NORMAL box-class throttle that calms small hosts while production stays unchanged.
- [loadreport — monitor resource profiler](https://docs.boa.io/operating/monitoring/loadreport.md): The read-only /proc profiler that answers which recurring BOA agents drive idle load: live and JSON views, the 30-minute logger, and throttling when fan-out is the cause.
- [Nightly maintenance (owl.sh)](https://docs.boa.io/operating/monitoring/nightly-owl.md): The nightly owl.sh orchestrator that replaced daily.sh: launch gates and lock, the frozen run context, per-account subprocess logs, and optional parallel fan-out.
- [Ghost & empty-artefact cleanup](https://docs.boa.io/operating/monitoring/ghost-cleanup.md): The nightly reapers for orphaned codebases, aliases and vhosts: dry-run by default, classified candidates, moves instead of deletes, the ghost-site client notice, and recovering a moved item.
- [XDR9000 — permanent attack & health archive](https://docs.boa.io/operating/monitoring/attack-health-archive.md): The read-only harvester that copies attack bans, auto-heal incidents, backup outcomes and metric samples into a permanent append-only archive before routine log cleanup erases them, and the root-only xdr9000 CLI that renders the whole history.
- [Solr search (operator)](https://docs.boa.io/operating/solr.md): BOA's per-host, localhost-bound Solr stack: three coexisting versions, per-site INI-driven cores, and a reconciliation daemon that creates, optimises and archives them.
- [Solr overview and tuning](https://docs.boa.io/operating/solr/overview-and-tuning.md): The per-site INI contract that drives Solr core selection, plus solr.php, core continuity across clones and migrations, GC-log diagnostics, and high-write core tuning.
- [Solr 9 modules](https://docs.boa.io/operating/solr/solr9-modules.md): The 17 module files BOA seeds into Solr 9, the five auto-enabled fleet-wide via SOLR_MODULES, the two load paths, and how to add, force-reseed or pin the module set.
- [Solr core lifecycle (manage_solr_config.sh)](https://docs.boa.io/operating/solr/core-management.md): The manage_solr_config.sh reconciliation daemon: the four-minute pass, re-registration of a core Solr stopped listing, core deletion on INI removal, three-tier orphan archival, health checks, and recovering archived cores.
- [OS lifecycle & upgrades](https://docs.boa.io/operating/os-lifecycle.md): The two independent upgrade axes of a BOA host: the barracuda and octopus software stack and the Devuan codename chain, plus the manual commands and cron-driven SELFUPGRADE.
- [Automated codename upgrades](https://docs.boa.io/operating/os-lifecycle/devuan-os-upgrades.md): The automated Devuan codename chain: the run-to-target markers, the four auto codename drivers, Percona and ICU sequencing, provider boot caveats, and post-chain PHP cleanup.
- [Classic major OS upgrade](https://docs.boa.io/operating/os-lifecycle/major-os-upgrade.md): The explicit per-hop OS upgrade path: set one FROM-TO control variable, run a system pass, and walk the full Devuan and Debian codename pairing matrix one hop at a time.
- [Manual BOA upgrade reference](https://docs.boa.io/operating/os-lifecycle/manual-boa-upgrade.md): The complete barracuda and octopus upgrade command matrix: full versus system-only, silent log mode, the lts, pro and dev tiers, and the octopus per-component modes.
- [SELFUPGRADE reference](https://docs.boa.io/operating/os-lifecycle/selfupgrade-reference.md): BOA's cron-driven upgrade scheduler: the AUTO_UP variables and default timing, the weekly system run, the ICU 7.4 intl auto-heal, the unattended kernel-reboot guard, and the service-teardown markers autoupboa honours on every pass.
- [Host OS baseline](https://docs.boa.io/operating/os-lifecycle/host-os-baseline.md): The base-OS choices a barracuda pass makes for you: the rsyslog daemon it always installs and never removes, whether BOA starts or reloads the cron service, the decorative root login banner and its packages, and which OpenSSL series BOA's own SSL toolchain (and Nginx) tracks.
- [Cross-host migration & cloning](https://docs.boa.io/operating/migration-cloning.md): Moving BOA sites and accounts: the in-host Ægir Clone and Migrate tasks, the root-side xoct, xcopy and xmass cross-host toolchain, migratefs, and site import and export.
- [Cross-host migration — xoct, xcopy, xmass](https://docs.boa.io/operating/migration-cloning/cross-host-migration.md): Overview of the root-side xoct, xcopy and xmass cross-host tools: which to reach for when, and the machinery all three share - the DRY/--live storage gate, the http-off write freeze, and the migration proxy.
- [xoct & xcopy — single-account move and copy](https://docs.boa.io/operating/migration-cloning/xoct-account-move.md): The full xoct single-account cross-host move runbook - dispatch verbs, the export dump, on-target import and renameaegirhost, DNS proxy conversion - plus xcopy, the non-destructive duplicate that leaves the source live.
- [xmass — whole-server move](https://docs.boa.io/operating/migration-cloning/xmass-server-move.md): The full xmass whole-server move runbook: xtrabackup snapshot plus MySQL GTID replication, incremental sync, the storage-planned cutover sequence, per-account proxy modes, and the state machine and recovery paths.
- [Site cloning & in-host migration](https://docs.boa.io/operating/migration-cloning/site-cloning.md): The in-host Ægir Clone and Migrate tasks: the Provision backend, the FastTrack and MyQuick accelerators and their defaults, the Restore trade-off, and Encryption auto-disable.
- [Aliases & redirects](https://docs.boa.io/operating/migration-cloning/aliases-redirects.md): The hosting_alias data model, pure-alias versus 301-redirect mode, the separate redirection vhost BOA emits per alias, SAN cert coverage, and rebuilding aliases after a rename.
- [Relocating stores to attached storage — migratefs](https://docs.boa.io/operating/migration-cloning/migratefs-storage-relocation.md): The operator-only migratefs tool that relocates account file stores and the shared arch archive onto the single attached mount and symlinks them back, with a DRY plan by default.
- [Importing & exporting sites](https://docs.boa.io/operating/migration-cloning/import-export.md): Adopting a Drupal site BOA did not create with provision-import and platform auto-import, and taking a managed site back out to standalone via its backup tarball.
- [Percona versions & verifying a migration](https://docs.boa.io/operating/migration-cloning/percona-versions-and-verification.md): How xoct and xmass behave across Percona 5.7/8.0/8.4, why the MySQL watchdog is paused during a move, and the before/after checklist that proves a migration actually succeeded.
- [Adopting vanilla Ægir into BOA — aegir2boa](https://docs.boa.io/operating/migration-cloning/aegir-to-boa.md): The operator runbook for adopting a vanilla Ægir 3.x estate into a BOA Octopus account on a separate box - the read-only preflight, the in-place Apache-to-Nginx flip, and remote per-site or whole-panel adoption behind a proxy-revert window.
- [PX0 proxies & shrinking a migrated source — xtrim](https://docs.boa.io/operating/migration-cloning/px0-proxy-shrink.md): What a migrated source box becomes when it is kept as a permanent web proxy, how its certificates stay alive, and how xtrim removes the payload it no longer serves — the reversible quiesce step, the one-way data stage, the box-wide finalize, and everything the tool refuses to touch.
- [Failover & recovery scenarios](https://docs.boa.io/operating/migration-cloning/failover-recovery-scenarios.md): Scenario-first runbook for the migration and HA topology: what to do when the proxy box or the active server goes down, how to switch to a mirror behind your own proxy or a CDN-only front, what downtime to expect, and how to bring the original server back as master.
- [Migration source wiring](https://docs.boa.io/operating/migration-cloning/migration-source.md): The migrate_source task: what it grants, the proof of possession that bounds which database may be named and the checks around it, its automatic enablement on every Octopus install and upgrade, and the reconciliation sweep.
- [Troubleshooting & recovery](https://docs.boa.io/operating/troubleshooting.md): 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.
- [Ægir task failures](https://docs.boa.io/operating/troubleshooting/task-failures.md): 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](https://docs.boa.io/operating/troubleshooting/fixme-recovery.md): 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](https://docs.boa.io/operating/troubleshooting/smtp-ssl.md): 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](https://docs.boa.io/operating/troubleshooting/firewall-blocked.md): 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](https://docs.boa.io/operating/troubleshooting/502-bad-gateway.md): 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](https://docs.boa.io/operating/troubleshooting/backup-failures.md): 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](https://docs.boa.io/operating/troubleshooting/faq.md): 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](https://docs.boa.io/operating/troubleshooting/dns-resolver.md): 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.
- [Native files symlinking](https://docs.boa.io/operating/files-symlinking.md): How BOA keeps each site's writable files and private directories in the account's static store, symlinked back into the platform, with a warn-not-fail safety model.
- [Native files symlinking — overview & safety model](https://docs.boa.io/operating/files-symlinking/overview.md): The store layout and event model for native files symlinking, plus the privilege and account scope, the warn-not-fail safety properties, kill-switches and file sharing.
- [Files-symlink tools](https://docs.boa.io/operating/files-symlinking/tools-reference.md): The three executables behind the subsystem: the autosymlink worker and its modes, the hardened sudo wrapper, and the read-only symlinkinfo history query, with logs.
- [Nightly automation — updatesymlinks](https://docs.boa.io/operating/files-symlinking/nightly-automation.md): The updatesymlinks scheduler around autosymlink: the auto-fix and orphan-report sub-modes, the nightly cron line, the task-queue pause and grace, and the heavy-task skips.
- [Files-symlinking configuration reference](https://docs.boa.io/operating/files-symlinking/configuration.md): The three barracuda.cnf variables that govern the nightly automation, how Barracuda persists them, the defaults by system class, and the full kill-switch control-file catalogue.
- [Orphan stores & the .archived archive](https://docs.boa.io/operating/files-symlinking/orphans-archiving.md): How a site's store is set aside into a dated .archived directory by the Delete task itself, by a rename and at name reuse, how the nightly sweep's strict alias-and-vhost test catches what is left, and why nothing is ever deleted and pruning is yours.
- [Backups on the static filesystem](https://docs.boa.io/operating/files-symlinking/backups-on-static-fs.md): The nightly relocation of an account's backups and backup-exports onto its static filesystem, gated on a different-device test, with its no-op default and kill-switches.
- [Why a dry run is NOT CLEAN — the EXPLAINED section](https://docs.boa.io/operating/files-symlinking/not-clean-explained.md): Why one anomaly marks a whole dry run NOT CLEAN and blocks batch conversion, and how the read-only EXPLAINED section re-probes each finding with its diagnosis and fix.

## Developing

- [Developing BOA](https://docs.boa.io/developing.md): The maintainer guide for hacking on BOA itself: the Barracuda and Octopus bash, the omega8cc Ægir forks, the fork model, release pipeline and install internals.
- [Maintainer overview & fork model](https://docs.boa.io/developing/overview.md): The entry point for changing BOA: the stack as a code reader sees it — entry scripts, sourced library sets, the deployable payload — and the omega8cc fork model.
- [Stack architecture for maintainers](https://docs.boa.io/developing/overview/architecture.md): The wiring diagram to hold before changing BOA code: which repo owns what, the call chain from an Ægir UI click to a backend verb, and where each file lands on a live box.
- [The omega8cc fork model](https://docs.boa.io/developing/overview/fork-model.md): Every Ægir-layer component BOA installs is an omega8cc fork, upstream of record: the repository set, where each fork lands on a box, and the divergence and delivery rules.
- [The original scripts (2009)](https://docs.boa.io/developing/overview/origins-2009.md): Three shell scripts dated 20 November 2009 — the direct ancestors of Barracuda and Octopus, older than the public BOA repository itself — preserved byte-for-byte, with a guided tour of what survived into today's stack.
- [Contributing & code style](https://docs.boa.io/developing/contributing.md): How a change gets into the omega8cc repos and the style contract it is reviewed against: the PR and serial-bump mechanics, bash and PHP conventions, and the 5.6 floor.
- [Contributing to BOA](https://docs.boa.io/developing/contributing/contributing.md): How to file against the single omega8cc boa tracker: the mandatory boa info Gist, where the logs live, per-repo PR targets, security disclosure, and the promotion pipeline.
- [Code style & conventions](https://docs.boa.io/developing/contributing/code-style.md): The enforceable style contract for both BOA languages: bash layout, naming, output helpers and locking, the hard PHP 5.6 floor, shell-escaping rules, and the commit checklist.
- [Release model & SKYNET pipeline](https://docs.boa.io/developing/release-model.md): How a commit you merge becomes code running on every production box: the branch and edition model that decides what ships, and the serial and fetch pipeline that lands it.
- [Branches, editions & licensing](https://docs.boa.io/developing/release-model/branches-and-editions.md): The three release trees (lts, pro, dev) as branch, mirror payload and identity stamp at once: the nine public branches, the tag-is-a-release-act rule, and the licensing model.
- [The serial & fetch pipeline (SKYNET)](https://docs.boa.io/developing/release-model/serial-pipeline.md): How a merged commit reaches every live box: the two transports, the SKYNET self-update heartbeat, the fNN serial rules, and why the update functions duplicate on purpose.
- [Install & staged-setup internals](https://docs.boa.io/developing/install-internals.md): How a BOA box builds and upgrades its Ægir layer: the four AegirSetup phases that assemble the Master and Satellite instances, plus the Hostmaster upgrade orchestrator.
- [Staged setup engine (AegirSetup*)](https://docs.boa.io/developing/install-internals/staged-setup.md): The four AegirSetup scripts that build an Ægir instance: the Satellite A/B/C chain, the Master M, their privilege boundaries, and the snapshot and marker-file contracts.
- [Hostmaster upgrade orchestrator (AegirUpgrade)](https://docs.boa.io/developing/install-internals/hostmaster-upgrade.md): The fifth staged script, upgrading the Master Ægir frontend: the barracuda-flow gates, the host_master/NNN root selection with zombie sweep, and the five-step migrate pipeline.
- [Ægir backend APIs (Provision/Hosting)](https://docs.boa.io/developing/aegir-apis.md): The PHP half of BOA: the four omega8cc Ægir forks (Hostmaster, Hosting, Provision, Drush) and how a task travels from frontend node to backend command and back.
- [Hostmaster frontend internals](https://docs.boa.io/developing/aegir-apis/hostmaster-frontend.md): The Drupal 7 install profile that is Ægir's web UI: its .info manifest, install node graph, make-file chain, the eldir theme, and how Master and Satellite frontends differ.
- [Provision backend internals](https://docs.boa.io/developing/aegir-apis/provision-backend.md): The Drush 8 command package behind every server-side action Ægir takes: the command registry, verify/install/deploy hook choreography, the context data model, and services.
- [Hosting module suite map](https://docs.boa.io/developing/aegir-apis/hosting-module-suite.md): A module-by-module map of the hosting module suite: the node types it defines, the six api.php hook files it carries, and which modules BOA enables versus which ship dormant.
- [Provision API](https://docs.boa.io/developing/aegir-apis/provision-api.md): The backend extension contract: the two dispatch channels, the provision.api.php hook surface, service-driver classes and contexts, and a working provision extension skeleton.
- [Hosting API](https://docs.boa.io/developing/aegir-apis/hosting-api.md): The frontend extension contract: the hosting.api.php hook surface and five per-module api files, dynamic queue command registration, feature toggles, and adding a feature module.
- [Extending Ægir: contexts, hooks, module pairs](https://docs.boa.io/developing/aegir-apis/extending-aegir.md): Writing the paired frontend and backend extension: the contexts model, the d() accessor, how a property travels frontend to backend and back, and which hook surface to use.
- [Drush fork internals (8-boa-micro)](https://docs.boa.io/developing/aegir-apis/drush-fork-internals.md): The omega8cc Drush 8 fork that runs every Ægir backend task: the 8-boa-micro base and version pins, the PHP 8.x startup backstop, and the drush.inc extension deny-filter.
- [Web & search stack internals](https://docs.boa.io/developing/web-search-internals.md): The web-serving half of BOA: how Provision turns an Ægir site node into an Nginx vhost and settings.php, where the edge-map wall is declared, and how Barracuda installs Solr.
- [Vhost generator (Provision templates)](https://docs.boa.io/developing/web-search-internals/vhost-generator.md): How Provision renders the per-site Nginx vhost: the Provision_Config eval cycle, the server, inc and site class split, the disabled, subdir and SSL variants, and where it lands.
- [Edge map/geo mechanics & the never-remove rule](https://docs.boa.io/developing/web-search-internals/edge-map-mechanics.md): The http-block map and geo catalogue that filters every request: the declare-here enforce-there idiom, the ban, crawler and i18n maps, and why a deployed map can never be removed.
- [How BOA wires settings.php (global.inc)](https://docs.boa.io/developing/web-search-internals/settings-php-wiring.md): How Provision generates the settings.php: the per-major template, the cloaking switch that keeps DB credentials out of the file, and the global.inc to platform to local.settings.php include cascade.
- [Solr installer internals (solr.sh.inc)](https://docs.boa.io/developing/web-search-internals/solr-installer.md): The Barracuda-side dispatcher that installs Solr 4, 7 and 9: the three version ladders, their gating tokens, the JDK-pinned env files, and why it runs only on an UPGRADE pass.
- [Build & test](https://docs.boa.io/developing/build-test.md): There is no CI: getting a fork change onto a running box and proving it holds is manual and box-shaped, from staging the delivery to running the behaviour by hand.
- [Building & testing BOA changes](https://docs.boa.io/developing/build-test/build-and-test.md): The four test gates for a BOA change, cheapest first: lint, the edgetest edge-policy harness, a disposable VM for environment-dependent breakage, and a serial-bump smoke check.
- [Verifying the drush extension filter](https://docs.boa.io/developing/build-test/drush-filter-verification.md): A runbook proving the Drush extension deny-filter holds both ways: the backend refuses a tenant command file, while a client's limited-shell CLI keeps loading its contrib commands.
- [Building the test-codebase mirror](https://docs.boa.io/developing/build-test/staticbuild-test-codebases.md): staticbuild is the maintainer tool that builds the newer Drupal core and distribution test codebases, plus the Backdrop family, and publishes them to the static mirror the fleet installs from, every version derived from the actual build.
- [Monitor & abuse-guard internals (code)](https://docs.boa.io/developing/monitor-abuse-internals.md): The runtime tier of BOA at code level: the cron-driven watchdogs, the abuse-guard ban pipeline, the nightly maintenance sweep, and the trust boundary they all sit on.
- [Monitor deploy surfaces & registration](https://docs.boa.io/developing/monitor-abuse-internals/monitor-deploy-surfaces.md): How a monitor reaches a box and runs: the wholesale copy, the launcher that spawns it, the serial-gated per-file fetch, base-package deps, and the box-class fan-out throttle.
- [Abuse Guard code internals](https://docs.boa.io/developing/monitor-abuse-internals/abuse-guard-internals.md): The maintainer's view of the Abuse Guard scorer: the detector skeleton, incremental log reading, cross-run window state, realip resolution, and how a new detector plugs in.
- [Nightly worker architecture (owl.sh + night/)](https://docs.boa.io/developing/monitor-abuse-internals/nightly-worker-internals.md): The nightly maintenance sweep at code level: an orchestrator, a per-account and per-site worker family, and the run-freeze that carries state across the subprocess boundary.
- [Security model internals](https://docs.boa.io/developing/monitor-abuse-internals/security-model-internals.md): The code contracts that keep BOA tenants isolated: the euid trust boundary, the Drush extension filter, the safe path and identifier helpers, and shell-out escaping discipline.
- [Prebuilt package builder](https://docs.boa.io/developing/prebuilt-builder-pipeline.md): How BOA produces the prebuilt stack packages the fleet installs: the stackbuild tool on dedicated per-release builder-mirror VMs that snapshot a real barracuda upgrade, the builder invariants, the daily packaging cycle, integrity and naming, and the add-a-builder runbook.
- [Glossary (for maintainers)](https://docs.boa.io/developing/glossary.md): The maintainer vocabulary in one place: the Barracuda/Octopus/Ægir trio, Satellite vs Master, trees and branches, serials and fetched tools, the staged installers, markers, and the state bus.

## Cheat Sheets

- [Cheat Sheets](https://docs.boa.io/cheat-sheets.md): One-page cheat sheets for the topics people ask about most — the quick primer and the few moves that matter, with links into the full documentation for everything else.
- [Caching — Cheat Sheet](https://docs.boa.io/cheat-sheets/caching.md): The quick caching primer: the four layers in 30 seconds, the .dev. alias that turns caching off while you debug, how to clear or restart things, and how to check it's all working — with links to the full docs.
- [INI Control Files — Cheat Sheet](https://docs.boa.io/cheat-sheets/control-files.md): The quick 'which file do I edit' primer: the two INI files you create, why the site file beats the platform file, how to apply and verify a change on a .dev. name, and why the PHP version lives in a different file — with links to the full docs.
- [Sites & platforms — Cheat Sheet](https://docs.boa.io/cheat-sheets/sites-and-platforms.md): The quick sites-and-platforms primer: the pieces in 30 seconds, Clone vs Migrate Site, the safe upgrade path, renaming and aliases, taking a whole site with you, and the settings people actually touch — with links to the full docs.
- [Shell & Drush — Cheat Sheet](https://docs.boa.io/cheat-sheets/shell-and-drush.md): The quick shell & Drush primer: the two logins and three ways in, `drush` versus `vdrush`, setting your own CLI PHP version, one-line site exports, and giving a developer their own login — with links to the full docs.
- [Backups & restore — Cheat Sheet](https://docs.boa.io/cheat-sheets/backups.md): The quick backups primer: what's protecting your site in 30 seconds, which snapshot mode holds what, exporting your data in a line, pulling an offsite copy back down, and trimming retention to free quota — with links to the full docs.
- [When something's wrong — Cheat Sheet](https://docs.boa.io/cheat-sheets/when-somethings-wrong.md): The quick triage primer: the first things to try (they fix most problems), reading a failed task before you retry, getting back into a locked-out site, and what's yours to fix versus your host's.

## Releases

- [Releases](https://docs.boa.io/releases.md): Per-release notes for every BOA version: what each release changes for your sites and your server, the operator-facing notes, and links to the code and full changelog.
- [BOA-5.88.855 — Kraken Edition](https://docs.boa.io/releases/boa-5-88-855.md): BOA-5.88.855 Kraken Edition: off-site backups restorable on your own workstation, a one-click Migration source task, a self-healing task queue, exact-name database grants with zero residual access, and a root layer that never follows a tenant-planted symlink.
- [BOA-5.88.844 — Certainty Edition](https://docs.boa.io/releases/boa-5-88-844.md): BOA-5.88.844 Certainty Edition: every backup route that does not name a mode now produces a restorable archive with the pre-restore safety copy included, imports refuse data the store cannot prove, migrations and failovers report only what they can show evidence for, and installs are interlocked against the fleet's own housekeeping.
- [BOA-5.88.833 — Candour Edition](https://docs.boa.io/releases/boa-5-88-833.md): BOA-5.88.833 Candour Edition: panel backups that hold exactly what their label says with a Restore that brings it all back, single-email installs completing with a welcome email true for the box, XDR9000 permanent attack and health history on every Ægir server, and distributed scrapers' cold fetches answered before PHP.
- [BOA-5.88.822 — Clarity Edition](https://docs.boa.io/releases/boa-5-88-822.md): BOA-5.88.822 Clarity Edition: 35 hidden control-file switches become named barracuda.cnf settings, PHP security releases installing in moments as prebuilt packages, a gated Excalibur kernel update, Backdrop packaged like the Drupal cores, and self-healing that confirms before it acts.
- [BOA-5.88.811 — Cadence Edition](https://docs.boa.io/releases/boa-5-88-811.md): BOA-5.88.811 Cadence Edition release notes: leftover management for interrupted migrate/clone/restore tasks, prebuilt stack packages reaching Devuan Excalibur, Backdrop CMS refinements, and 40 commits since 5.88.8.
- [BOA-5.88.8 — Continuity Edition](https://docs.boa.io/releases/boa-5-88-8.md): BOA-5.88.8 Continuity Edition release notes: Backdrop CMS support, the Drupal 6 → 7 → Backdrop upgrade chain, classic Ægir imports, and 422 commits since 5.10.3.
- [BOA-5.10.3 — Watchtower Edition](https://docs.boa.io/releases/boa-5-10-3.md): BOA-5.10.3 PRO/LTS release notes: a hardened abuse guard, self-healing monitors, and Drupal 8+ reliability fixes.
- [BOA-5.10.1 — AI Policy Edition](https://docs.boa.io/releases/boa-5-10-1.md): BOA-5.10.1 PRO/LTS release notes: per-class AI bot policy, edge hardening, and refreshed distributions.
- [BOA-5.9.5 — Security Audit](https://docs.boa.io/releases/boa-5-9-5.md): BOA-5.9.5 PRO/LTS release notes: the security audit and hardened foundations release.
- [BOA-5.9.3 — Active Threat Response](https://docs.boa.io/releases/boa-5-9-3.md): BOA-5.9.3 PRO/LTS release notes: active threat response and deep hardening.
- [BOA-5.9.1 — HTTP/3 and KTLS](https://docs.boa.io/releases/boa-5-9-1.md): BOA-5.9.1 PRO/LTS release notes: HTTP/3 and kernel TLS bring the fast lane to HTTPS.
- [BOA-5.8.5 — Devuan Excalibur and PHP 8.5](https://docs.boa.io/releases/boa-5-8-5.md): BOA-5.8.5 PRO/LTS release notes: Devuan Excalibur, PHP 8.5, and 1092 commits since BOA-5.7.12.
- [BOA-5.7.11 — Drupal 11 with Ægir 3](https://docs.boa.io/releases/boa-5-7-11.md): BOA-5.7.11 PRO release notes: full Drupal 11 support integrated with Ægir 3.
- [BOA-5.6.0 — New Backup System](https://docs.boa.io/releases/boa-5-6-0.md): BOA-5.6.0 PRO release notes: a new backup system, fresh tools, and over 750 updates since BOA-5.5.0.

## Reference

- [Reference appendix](https://docs.boa.io/reference.md): The BOA reference appendix: every documented configuration variable, command, and control file, indexed with links back to the page that documents each.
- [Variable reference](https://docs.boa.io/reference/variables.md): The complete index of every documented barracuda.cnf / octopus.cnf variable: type, built-in default, what it controls, and the page that documents it.
- [Command reference](https://docs.boa.io/reference/commands.md): The complete index of every documented BOA command and helper tool, with its purpose and the page that documents it.
- [Control-file reference](https://docs.boa.io/reference/control-files.md): The complete index of every documented BOA control file — the marker and one-line files whose presence or content changes behaviour — with where it lives, what it does, and the page that documents it.