Common settings for multiple named hosts

Merged Configurations

Preliminaries

This note describes how the server and host sections can be configured with merged settings to avoid repetition when configuring multiple hosts.

Merging host and server settings

Oftentimes portions of each host setup will be configured in an identical or very similar fashion. When this is the case, the configuration's server section can be used to make common declarations. This is referred to as a merged configuration.

During server startup, configurations are merged such that entities from the server section are copied, in memory, into each host section. When a configuration sub-section occurs in the server section only, and not in the host section, entries are simply copied en masse from server to host.

On the other hand, when a configuration sub-section occurs in both the server section and the host section, a more sophisticated copy procedure is needed. The rules for this may be specified by adding a *merge attribute to the host's sub-section. The merge attribute can have a value of join, override or reduce. If not specified, override rules will be used.

  • During a join merge, the entities from both the server's sub-section and the host's sub-section are joined, and any duplicates are removed.
  • During an override merge, the entities from the server's sub-section are discarded and the host's sub-section is used in its entirety.
  • During a reduce merge, the entities from the server's sub-section are used as a basis, then any entities specified in the host's sub-section are found and removed, leaving a reduced subset of the original.

Some configuration sections do not allow the *merge attribute to be used. For example, all of the sections that use file path-patterns to match request paths to configuration options are ineligible for merging. Those sections must be specified in full, in either the server section or the host section. Refer to each of the separate notes to learn whether or not merging is allowed.

EBNF

Entities that may occur in the host section only, or in the server section only, are shown in boldface type.

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
server-section ::= 'server' SP LEFT-CURLY-BRACKET CR
ip-address
port
cluster-size
registration
request-section
response-section
content-types-section
logging-section
modules-section
rbac-section
restrictions-section
accept-language-section
accept-types-section
cross-origin-section
forbidden-section
ip-access-section
methods-section
resource-masks-section
user-agent-section
cache-control-section
charset-section
content-encoding-section
push-priority-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
response-section
content-types-section
logging-section
modules-section
rbac-section
restrictions-section
accept-language-section
accept-types-section
cross-origin-section
forbidden-section
ip-access-section
methods-section
resource-masks-section
user-agent-section
cache-control-section
charset-section
content-encoding-section
push-priority-section
RIGHT-CURLY-BRACKET CR
configuration-file ::= server-section
host-section*

Cookbook

Example 1: Server with two hosts and a common server section
host {
hostname example.com
document-root `/var/www/example.com/public`
encoding-cache `/var/www/example.com/encoding-cache`
dynamic-cache `/var/www/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`
}
}

host {
hostname example.org
document-root `/var/www/example.org/public`
encoding-cache `/var/www/example.org/encoding-cache`
dynamic-cache `/var/www/example.org/dynamic-cache`
landing-page `landing-page.html`

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

server {
ip-address 10.20.30.40
port 443
cluster-size 4
registration {
customer-number 1234567890
access-key ABCDEFGHIJ
}

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
}
}

Review

Key points to remember:

  • Configuration must have exactly one server section.
  • Configurations may have one or more host sections.
  • Most configuration settings may appear in either the server section or a host section.
  • When the merge attribute is omitted from host sub-sections, the 'override' merge procedure will apply.

Common settings for multiple named hosts