Aliases & redirects

A site can answer on more than one URL. Aegir calls the extra URLs aliases:

  • the www. companion of a bare-domain site (www.foo.com ↔ foo.com);
  • a vanity domain over a longer canonical (acme.com ↔ acme-corp-site.com);
  • several country-code domains for one site (acme.de, acme.at, acme.ch);
  • a subdomain pointing at the same site.

Aliases are most relevant in this section because a clone or a cross-host rename changes a site's canonical machine-name, and the alias set usually has to be rebuilt to match. This page is the alias data model and the nginx output it produces. For platform-level Nginx rewrites beyond simple alias/redirect, see Web tier internals.

The hosting_alias data model

hosting_alias is the Hostmaster module that defines the alias data model and its admin UI; it ships in every Hostmaster install profile. Its parts:

  • hosting_alias.module — node-form integration on the Site node (the "Aliases" textarea) plus the automatic-alias logic.
  • hosting_alias.drush.inc — a 30-line backend integration file. It defines only drush_hosting_alias_pre_hosting_task() and hosting_alias_drush_context_import(). It registers no standalone Drush command — there is no hosting-alias-add or hosting-alias-delete verb. Aliases are edited through the Site node form (or its task arguments), not a CLI alias command.

Pure alias vs redirect

Each site is either pure-alias or redirect, set per-site:

  • Alias (no redirect) — the site answers on the alias URL with its content; the URL in the browser stays as typed.
  • Redirect — the alias issues a 301 to the canonical site URL.

The mode is a per-site toggle (the redirect default applies to all of the site's aliases — there is no per-alias override in the standard UI). The clone and migrate task arguments carry the alias set and the redirection flag through as aliases and redirection.

What nginx actually emits

When the site is verified, Provision re-renders the per-site vhost from vhost.tpl.php. The exact output depends on the redirect flag.

Pure-alias — every alias is listed in the main vhost's server_name, so one server block answers for the canonical name and all aliases:

server {
  server_name foo.example.com www.foo.example.com shop.foo.example.com;
  # ...
}

Redirect — BOA does not use an inline if ($host != ...) { return 301; } test inside the main vhost. Instead Provision emits a separate redirection virtual host per alias, each with its own server_name and an unconditional return 301, explicitly to avoid if{} in nginx:

# alias redirection virtual host
server {
  listen  *:80;
  server_name  www.foo.example.com;
  access_log off;
  log_not_found off;
  # (on a BOA/satellite host, an ACME-challenge location is also emitted here)
  return 301 $scheme://foo.example.com$request_uri;
}

One such block is generated for each alias, all redirecting to the canonical redirection target. Aliases matching *.nodns.*, *.dev.*, or *.devel.* are skipped in the redirection pass — they get their own handling. The canonical name keeps the main content vhost; every alias 301s back to it. (At the SSL layer the same separate-vhost approach drives the https:// redirect.)

DNS prerequisite

Every alias needs a DNS record (A or CNAME) pointing at the BOA host's IP. Aegir does not check DNS when you add an alias, but nginx will not usefully serve an alias until DNS resolves to the host. Under wildcard hosting (*.foo.example.com pointed at the BOA IP), individual aliases below that wildcard do not need separate DNS records.

SSL with aliases

If the site has Encryption enabled, the certificate must cover every alias:

  • Let's Encrypt — the SSL task requests a SAN certificate listing every alias. Automatic, but each alias must already resolve to this host so the ACME challenge can validate (which is why the redirection vhosts still expose the /.well-known/acme-challenge location).
  • Custom cert — supply a SAN or wildcard certificate covering every alias.

After adding an alias to an SSL site, re-run the SSL task so the certificate is re-issued with the new name included. See the SSL operations material in Web tier internals.

Add / remove cycle

Aliases are edited on the Site node (its "Aliases" textarea, one alias per line) — on the create form at install time, and on the site edit form afterwards. Saving queues an automatic Verify that re-emits the vhost with the new server_name / redirection blocks.

Removing an alias is the inverse: remove the line, save, Verify regenerates the vhost without it. A browser pointed at the removed alias then hits the nginx default 404. Aegir does not manage DNS, so the alias's DNS record is left in place — tidy it up separately.

After a clone or rename

A cloned site, or an account renamed during an xoct/xcopy/xmass move, gets a new canonical machine-name. Its alias set does not migrate meaningfully — the old aliases still point (via DNS) at the old name or old host. Rebuild the alias list on the new site to match its new canonical hostname, then Verify. If the old hostname should keep working, add it as a redirect alias on the new site so it 301s to the new canonical URL; do not add the canonical name to its own alias list (it is already the main name, and doing so under redirect mode breaks the canonical URL).

Per-alias custom behaviour

The alias model is intentionally "answer on this URL, or 301 to the main site". Anything more elaborate — a specific path on an alias going somewhere unexpected, regex rewrites — is a platform-level rewrite include, not an alias. See Web tier internals for the nginx_vhost_include.conf / nginx_force_include.conf override points.

Related