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, join rules will be used.
- During a
joinmerge, the entities from both theserver'ssub-section and thehost'ssub-section are joined, and any duplicates are removed. - During an
overridemerge, the entities from theserver'ssub-section are discarded and thehost'ssub-section is used in its entirety. - During a
reducemerge, the entities from theserver'ssub-section are used as a basis, then any entities specified in thehost'ssub-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 diffie-hellman ciphers 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 alias 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
serversection. - Configurations may have one or more
hostsections. - Most configuration settings may appear in either the
serversection or ahostsection. - When the
mergeattribute is omitted from host sub-sections, the'join'merge procedure will apply.
