Aegir backend APIs (Provision/Hosting)

The PHP half of BOA: the four omega8cc Aegir-layer forks and how they talk to each other. Everything in this topic is Drupal 7 / Drush 8 PHP that runs as an unprivileged system user, and all of it must stay parse- and runtime-safe on PHP 5.6 — that floor is a hard contract for every patch in this layer, not a style preference.

The layer in one paragraph, verified at source: Hostmaster is a D7 install profile (hostmaster.info, core = 7.x, 40 active dependencies[] lines) whose make chain bundles the eldir theme and the hosting_* modules under subdir "aegir" (drupal-org.make:12-25); on a BOA build, hostmaster.make includes drupal-org.make (hostmaster.make:7) and pins the ten Aegir projects to copy downloads from the /opt/tmp/make_local/* staging clones (hostmaster.make:11-63; the D7 contrib set is pinned the same way inside drupal-org.make itself), staged by _master_download_for_local_build (master.sh.inc:547). Hosting is that module suite — 26 *.module files in the core repo (three of them example/ scaffolds) plus BOA's satellite repos (aegir_objects, hosting_civicrm, hosting_custom_settings, hosting_tasks_extra, …) — which models servers/platforms/sites as nodes and queues work as task nodes. Provision is the Drush-command backend that does the actual filesystem/DB/vhost work; it is cloned into the backend's .drush/sys/provision at ${_BRANCH_PRN} by _provision_backend_up (master.sh.inc:656,688), while hostmaster, hosting and eldir clone at 5.x-${_tRee} into the platform build (master.sh.inc:576-578). Both halves run under the omega8cc Drush 8 fork (pin _DRUSH_EIGHT_VRN=8.5.4, BARRACUDA.sh.txt:50), which bootstraps BOA's own extension deny-filter on every run (includes/preflight.inc:129 → includes/boa_extension_filter.inc). Two hook surfaces, one per half: provision.api.php backend-side, hosting.api.php (plus five per-module *.api.php files) frontend-side. An extension is therefore usually a pair of modules — one per surface.

The task round-trip

The bridge between the two API surfaces is one Drush process chain:

Hostmaster frontend (D7, hosting_* modules) — surface: hosting.api.php
   task node saved (hosting_task); queues declared via hook_hosting_queues()
                                                      (hosting.api.php:138)
   ↓  drush @hostmaster hosting-dispatch → hosting-<queue>
      per-queue commands registered dynamically from hosting_get_queues()
                                                      (hosting.drush.inc:19,40-54)
   ↓  drush @hostmaster hosting-task <nid>
drush_hosting_task()                                  (task.hosting.inc:189)
   provision-save — re-export the node as a backend context/alias
     with hook_hosting_TASK_OBJECT_context_options() applied
                                                      (task.hosting.inc:208)
   provision_backend_invoke($alias, $task->task_command, …)
                                                      (task.hosting.inc:226)
   ↓
Provision backend (Drush 8, aegir/oN user) — surface: provision.api.php
   provision-* command from provision_drush_command() (provision.drush.inc:91)
     provision-save:92 · provision-install:108 · provision-verify:207
     · provision-deploy:239
   contexts via d()                                   (provision.context.inc:23)
   service orchestrators: db/ http/ platform/*.provision.inc
   classes: Provision_Context, Provision_Service extends Provision_ChainedState
     (Provision/Service.php:10; PSR-0 "Provision_" → Provision/,
      composer.json:28-31)
   ↓  backend log/result rides the Drush backend channel back
post_hosting_<task_type>_task() hooks fire frontend-side
                                                      (task.hosting.inc:259-262)

Hold that picture and every leaf below is a zoom into one box.

Pages in this topic

• Hostmaster frontend internals — install-profile composition: hostmaster.info / hostmaster.install / hostmaster.profile and the make files (hostmaster.make and build-hostmaster.make both include drupal-org.make; the local-copy override onto /opt/tmp/make_local), module bundling under subdir "aegir", the eldir theme, per-host and per-Octopus hostmaster instances, and how BOA's hostmaster differs structurally from a plain Drupal 7 site.
• Provision backend internals — the Drush-command registry (provision_drush_command(), provision.drush.inc:91), the procedural framework core (provision.inc, provision.file.inc, provision.service.inc), the PSR-0 Provision_* class hierarchy, the per-service/backend .inc orchestrators under db/, http/ and platform/, and where provision hooks into verify/install/deploy tasks.
• Hosting module suite map — module-by-module map of the hosting_* suite with the per-module *.api.php hook references (hosting.api.php plus hosting_alias, hosting_quota, hosting_server, hosting_site, hosting_task), which modules BOA enables by default, and which are BOA-specific forks or satellite additions; the task-queue modules are mapped here with their API detail on the two API leaves below.
• Provision API — the backend hook surface (provision.api.php: services, config/template alter chain, per-server drush_hook_provision_nginx_* render hooks), service-driver classes, declaring provision-* commands via hook_drush_command(), context types and the d() accessor from the backend side, and a working skeleton for a provision extension.
• Hosting API — the frontend hook surface (hosting.api.php: hook_hosting_feature():110, hook_hosting_queues():138, hook_hosting_TASK_OBJECT_context_options():218, hook_hosting_TASK_TYPE_task_rollback():246, hook_post_hosting_TASK_TYPE_task():325), dynamic hosting-<queue> command registration, feature toggles, and adding a hosting_* feature module — the companion to the Provision API leaf.
• Extending Aegir: contexts, hooks, module pairs — writing the paired frontend+backend extension, the contexts data model and its persistence as Drush aliases written by provision-save, the d() accessor, which hook surface to use for which job, and the pitfalls: the backend runs under the instance user, not root, and the PHP 5.6 floor is non-negotiable.
• Drush fork internals (8-boa-micro) — the omega8cc Drush 8 fork: the 8-boa-micro base and version pinning (_DRUSH_EIGHT_VRN, BARRACUDA.sh.txt:50), classic 8.5.x version bumps, the PHP 8.x startup backstop, and the *.drush.inc extension deny-filter code in includes/boa_extension_filter.inc: discovery-time filtering, the realpath-before-match lesson, the backend identity gate, the deny set with its allow carve-outs, per-instance opt-in files and the global kill switch.

Boundaries

How this layer is built and shipped — the /opt/tmp/make_local staging clone set (_mL, master.sh.inc:551), AegirSetup{A,B,C,M} and the platform build — belongs to the Install & staged-setup internals topic; the Provision *.tpl.php template set and Nginx render pipeline belong to Web & search stack internals; both are indexed from the guide front page. Day-to-day queue operation (dispatch cadence, semaphore clearing, forcing runs) is operator material and deliberately not covered in this guide.

Reference

• Variables and Commands — the auto-generated consolidated _VAR and CLI reference tables.
• Discontinued features — retired Aegir-layer pieces land there; check it before documenting anything found only in old trees.