Determining which steps are active during the request-response cycle
Modules
Preliminaries
This note describes how the server is modularized and how it can be configured to behave differently by enabling and disabling individual modules.
The HTTP request-response cycle can be configured to include or exclude optional processing steps. This level of configuration is like flipping a series of master switches. Disabled modules are completely ignored: their associated configuration section is not validated and their processing handler is bypassed.
This design can be beneficial during development and production, allowing the devops staff to quickly reconfigure the server to test features and troubleshoot problems.
Most of the server's optional modules are preconfigured by default to be disabled; you must enable them explicitly before their handlers will have any effect.
The optional modules perform a variety of tasks which can conceptually be grouped into: 1) security, 2) negotiation, 3) caching, 4) processing, and 5) monitoring modules.
Security
The ip-access
module can block blacklisted IP addresses from making requests to the server.
The forbidden
module prevents access to files paths that are in the public document area.
The rbac
module is a Role Based Access Control protocol allowing granular permissions to be set on resource paths.
The cross-origin
module is used to configure the CORS protocol.
Negotiation
The accept-language
module handles content language negotiation.
The content-encoding
module saves outgoing bandwidth by compressing responses.
Caching
The etag
module allows browsers to handle caching with fewer false positives.
The cache-control
module defines the browser caching instructions to be sent with each request.
Processing
The user-agent
module can recognize crawlers and selectively disable path access and/or speculative push notifications.
The resource-masks
module converts SEO-friendly URLs and microservice API calls into canonical server paths.
The push-priority
module configures the rules to use for requests that are candidates for HTTP/2 speculative push protocol.
The web-dav
module enables or disables PUT and DELETE handling of static files.
Monitoring modules
The information-headers
module provides contextual information about response status codes.
The custom-errors
module displays error messages in a natural language suitable to the website's readers, and with CSS to match the website's styling rules.
The counters
module provides real-time access to basic server usage data.
The policies
module is used to configure the security and error logging policies that browsers should enforce on text/html
documents.
Configuration
Modules are configured by adding entries to the modules
section. Each entry should be on a separate line, and contain only the name of the module and the keyword on
or off
. Modules names that are not explicitly configured, are off by default.
Placement
The modules
configuration section may appear in either the server
section or a host
section. When values occur in both the server
and host
sections, they are merged according to the standard rules defined for the merge
attribute.
EBNF
SP | ::= | U+20 |
CR | ::= | U+0D |
LEFT-CURLY-BRACKET | ::= | U+7B |
RIGHT-CURLY-BRACKET | ::= | U+7D |
module-name | ::= | ('ip-access' | 'forbidden' | 'rbac' | 'cross-origin' | 'accept-language' | 'content-encoding' | 'etag' | 'cache-control' | 'user-agent' | 'resource-masks' | 'push-priority' | 'information-headers' | 'custom-errors' | 'counters') |
named-module-entry | ::= | module-name SP ('on' | 'off') CR |
modules-section | ::= | 'modules' SP LEFT-CURLY-BRACKET CR named-module-entry* RIGHT-CURLY-BRACKET CR |
Cookbook
Example 1: Standard modules only
server {
modules {
accept-language on
content-encoding on
etag on
cache-control on
information-headers on
}
}
Example 2: Explicitly turned off
server {
modules {
ip-access off
forbidden off
rbac off
cross-origin off
accept-language on
content-encoding on
etag on
cache-control on
user-agent off
resource-masks off
push-priority off
information-headers on
custom-errors off
counters off
}
}
This example is equivalent to Example 1, but is more explicit.
Review
Key points to remember:
- The modules configuration is a master switch, and should always be checked when diagnosing why the server is not responding as expected.
- Two common mistakes are:
- having the module turned on, but forgetting to add its configuration rules;
- having a module's section correctly configured, but neglecting to turn the module on.