Hosts

Preliminaries

This note describes the required settings needed by the server to configure an HTTP/2 socket, TLS certificates, the paths to documents and caches, acceptable mime-types, and allowed methods.

The server defines a named host as a DNS domain name, port, and scheme, answering on a socket, that accepts HTTP/2 requests and sends HTTP/2 responses. Named hosts are found by DNS resolvers that convert a domain name into an IP address; they cannot be reached directly by IP address.

The server can handle more than one named host. Each is declared with a host section, containing at a minimum, these entries:

hostname which is a DNS name that resolves to the IP address of the device running the server.

document-root which uses sourceref-syntax to declare the absolute path to the root of the public documents to be served.

tls which is a section comprising:

• private-key which uses sourceref-syntax to declare the absolute path to the PEM file containing an SSL private key for the file referenced in the certificate entry.
• certificate which uses sourceref-syntax to declare the absolute path to the PEM file containing a full SSL certificate-chain, created by an accredited authority recognized by browsers, and registered for the configured hostname.

request which is a section comprising, at a minimum:

• methods which has a comma-separated list of the HTTP methods that the server will answer to.
• accept-types section which contains a list of acceptable mime-types, the simplist form being mime-type '*/*'.

Other Common Entries

These entries are commonly used, but not absolutely required:

encoding-cache which uses sourceref-syntax to declare the absolute path to the root of the cache used when the Content Encodings module is enabled.

dynamic-cache which uses sourceref-syntax to declare the absolute path to the root of the cache used when the $'BLUE- PROCESSOR' dynamic module is enabled.

landing-page which uses sourceref-syntax to declare the path — relative to the document-root — to the page to be served when no path is provided in a request.

Aliases

When DNS is configured with alternate names that point to the same IP address, you may use those alternates as aliases. A common scenario is to have a domain such as example.com and an alias such as www.example.com. Alternate names are configured using one or more alias entries.

host {
    hostname       example.com
    alias          www.example.com
    tls {
        private-key    `/etc/letsencrypt/live/example.com/privkey.pem`
        certificate    `/etc/letsencrypt/live/example.com/fullchain.pem`
    }
}
						

The use of aliases will only work if you have a "wildcard" SSL certificate, which includes both the hostname and its aliases. Examine your certificate's "Certificate Subject Alt Name" section. The above scenario should have:

DNS Name: *.example.com
DNS Name: example.com
						

Enabling Additional Modules

Additional entries are required to support modules that are not enabled by default. See the separate notes for how to configure them.

In particular, almost every configuration should enable these modules in production:

• The Accept Language module to handle content language negotiation.
• The Content Encoding module to save outgoing bandwidth by compressing responses.
• The Cache Control module to configure browser caching instructions.
• The Etag module to allow browsers to handle caching with fewer false positives.

Server section

The configuration's server section is used to provide the IP address and port to listen on. See the separate Server note for details.

† Legal file system characters vary by platform

Review

Key points to remember:

• Configuration files are written using BLUEPHRASE syntax comprising named sections and entries.
• The host section is the root section for configuring a named host.