Hostnames and sub-sites

On which hostnames a site answers, and how a request finds its site.

The hostname of a main site

A main site answers on its Hostname, set on its Identity section (/admin/sites/{site}/identity). Enter the bare hostname in lower case, like acme.example.com: no scheme, port or path.

A hostname belongs to one site. The form refuses a hostname that another site uses as its hostname, an alias or a language domain, in any environment. Changing the hostname moves every address of the site; add the old hostname as an alias to keep its links working.

Hostnames per environment

A hostname can differ per environment, like acme.ddev.site locally and acme.example.com in production. Check Environment overrides on the Hostname and Hostname aliases rows of the site type, then set the values on the Environments tab of the Identity section. An environment without a hostname of its own uses the site's. See Setting layers.

Hostname aliases

Hostname aliases on the Identity section are further hostnames of the site, like a www. variant or a former domain. A request to an alias answers with a permanent redirect (301) to the site's hostname, keeping the path and the query. Aliases can differ per environment like the hostname.

Trusted hosts

List the hub's hostname in Drupal's trusted_host_patterns in settings.php, plus the entry 'sites' => '.*'. Sites replaces that entry with every hostname, alias and language domain of every site, in every environment; see Trust the hostnames for the snippet. A site created later is trusted at once.

Without trusted_host_patterns, the status report (/admin/reports/status) shows the error Sites: trusted host patterns.

Sub-sites

Needs Sites path prefix

Part of Sites path prefix.

A sub-site answers under its main site's hostname at a path prefix, like acme.example.com/jobs. It needs no DNS entry and has no hostname or aliases of its own. Choose Sub-site under Structure when you create the site.

A path prefix:

• uses letters, digits, - and _, in one or more segments like jobs or jobs/berlin, without a leading or trailing slash;
• is unique on the platform;
• does not start with a reserved segment: admin, user, node, taxonomy, sites, system, batch, cron, install, update, api, jsonapi or preview.

A site stays a main site or a sub-site, and a sub-site stays under its main site. The prefix can change on the Identity section; nothing redirects the old addresses. A language path prefix comes first: acme.example.com/de/jobs.

How a request finds its site

Matching ignores case and port. There are no wildcards.

1. Sub-site: the host is a main site's hostname and the path starts with the prefix of one of its sub-sites. The longest matching prefix wins.
2. Main site: the host is a site's hostname, one of its aliases or one of its language domains, as set for the current environment. An alias then redirects to the hostname.
3. Hub: no site claims the host. The request runs on the hub.

A host whose only sites are disabled answers "Not Found", except to users with Access disabled sites or Administer sites. The prefix of a disabled sub-site is an ordinary path of its main site. See Disable or delete a site.