Determining which steps are active during the request-response cycle



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.


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.


The accept-language module handles content language negotiation.

The content-encoding module saves outgoing bandwidth by compressing responses.


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.


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.


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.


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.


SP ::= U+20
CR ::= U+0D
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' |
named-module-entry ::= module-name SP ('on' | 'off') CR
modules-section ::= 'modules' SP LEFT-CURLY-BRACKET CR


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.


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

🔗 🔎