Required configuration settings for named hosts

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.

Configuration

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.

EBNF

SP ::= U+20
CR ::= U+0D
SOLIDUS ::= U+2F
ASTERISK ::= U+2A
FULL-STOP ::= U+2E
GRAVE-ACCENT ::= U+60
LEFT-CURLY-BRACKET ::= U+7B
RIGHT-CURLY-BRACKET ::= U+7D
file-system-chars ::= (ALPHA | DIGIT | )*
absolute-path ::= GRAVE-ACCENT file-system-chars* GRAVE-ACCENT
relative-path ::= GRAVE-ACCENT file-system-chars* GRAVE-ACCENT
hostname-entry ::= 'hostname' SP (ALPHA | DIGIT | FULL-STOP | HYPHEN)* CR
document-root ::= 'document-root' SP absolute-path CR
encoding-cache ::= 'encoding-cache' SP absolute-path CR
dynamic-cache ::= 'dynamic-cache' SP absolute-path CR
landing-page ::= 'landing-page' SP relative-path CR
private-key ::= 'private-key' SP absolute-path CR
certificate ::= 'certificate' SP absolute-path CR
tls-section ::= 'tls' SP LEFT-CURLY-BRACKET CR
private-key
certificate
RIGHT-CURLY-BRACKET CR
method-name ::= 'HEAD' | 'GET' | 'PUT' | 'DELETE' | 'POST' | 'PATCH' | 'OPTIONS' | 'TRACE'
methods-entry ::= 'methods' SP (method-name COMMA)* CR
accept-type-entry ::= 'mime-type' SP* MIME-type CR
accept-types-section ::= 'accept-types' SP LEFT-CURLY-BRACKET CR
accept-type-entry*
RIGHT-CURLY-BRACKET CR
request-section ::= 'request' SP LEFT-CURLY-BRACKET CR
methods-entry
accept-types-section
RIGHT-CURLY-BRACKET CR
host-section ::= 'host' SP LEFT-CURLY-BRACKET CR
hostname-entry
document-root
encoding-cache
dynamic-cache
landing-page
tls-section
request-section
RIGHT-CURLY-BRACKET CR

† Legal file system characters vary by platform

Cookbook

Example 1: Minimal host configuration
host {
hostname example.com
document-root `/srv/example.com/public`

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

request {
methods GET
accept-types {
mime-type '*/*'
}
}
}
Example 2: Minimal configuration with other common entries
host {
hostname example.com
document-root `/srv/example.com/public`
encoding-cache `/srv/example.com/encoding-cache`
dynamic-cache `/srv/example.com/dynamic-cache`
landing-page `landing-page.html`

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

request {
methods HEAD,GET,OPTIONS
accept-types {
mime-type '*/*'
}
}
}
Example 3: Configuration with additional modules enabled
host {
hostname example.com
document-root `/srv/example.com/public`
encoding-cache `/srv/example.com/encoding-cache`
dynamic-cache `/srv/example.com/dynamic-cache`
landing-page `landing-page.html`

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

modules {
accept-language on
encoding on
cache-control on
etag on
}

content-types {
html text/html
css text/css
js application/javascript
gif image/gif
png image/png
jpg image/jpeg
ico image/x-icon
}

request {
methods HEAD,GET,PUT,DELETE,POST,PATCH,OPTIONS,TRACE

accept-types {
mime-type text/html
mime-type text/css
mime-type application/javascript
mime-type image/gif
mime-type image/png
mime-type image/jpeg
mime-type image/x-icon
}

accept-language {
`*` *lang=en
}
}

response {
content-encoding {
text/html gzip
text/css gzip
application/javascript gzip
image/gif none
image/png none
image/jpeg none
image/x-icon none
}
}

cache-control {
`*.html` *instructions='no-cache, no-store, must-revalidate'
`*.css` *instructions='public, max-age=86400' // 24 hours
`*.js` *instructions='public, max-age=86400' // 24 hours
`*.gif` *instructions='public, max-age=7776000' // 3 months
`*.png` *instructions='public, max-age=7776000' // 3 months
`*.jpg` *instructions='public, max-age=7776000' // 3 months
`*.ico` *instructions='public, max-age=31536000' // 1 year
}
}
Example 4: One hostname with multiple aliases
host {
hostname example.com
alias secure.example.com
alias signin.example.com
alias www.example.com
document-root `/srv/example.com/public`

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

request {
methods GET
accept-types {
mime-type '*/*'
}
}
}

Review

Key points to remember:

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

Required configuration settings for named hosts