Ægir backend APIs (Provision/Hosting)

The PHP half of BOA: the four omega8cc Ægir-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 Ægir 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.

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 Ægir-layer pieces land there; check it before documenting anything found only in old trees.