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.

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:
    1. having the module turned on, but forgetting to add its configuration rules;
    2. having a module's section correctly configured, but neglecting to turn the module on.

Determining which steps are active during the request-response cycle