Apache HTTP Server Version 2.5
Description: | HTTP protocol compliance enforcement. |
---|---|
Status: | Extension |
Module Identifier: | policy_module |
Source File: | mod_policy.c |
The HTTP protocol recommends that clients should be "liberal in what they accept", and servers "strict with what they send". In some cases it can be difficult to detect when a server or an application has been misconfigured, is serving uncacheable content or is behaving suboptimally, as an HTTP client might be compensating for the server. These problems can potentially lead to excessive bandwidth consumption, or a server outage under load.
The mod_policy
module consists of a set of
filters that test servers for HTTP protocol compliance. These
tests allow the server administrator to log violations of, or
outright reject responses where certain defined conditions exist.
This could be used as a way to set minimum HTTP protocol compliance criteria for a restful application. Alternatively, a reverse proxy or cache could be configured to protect itself from misconfigured origin servers or unexpectedly uncacheable content, or as a mechanism to detect configuration mistakes within the server itself.
If a policy is violated, one of the following actions can be taken:
Warning
header added to the response for the benefit of
the client.Warning
header added to the response, and a 502
Bad Gateway
will be returned to the client. Optional links to
explanatory documentation can be added to each error message,
detailing the origin of each policy.It is also possible to selectively disable all policies for a
given URL space, should the need arise, using the
PolicyFilter
directive.
Alternatively, the
PolicyEnvironment
directive can be used to specify an environment variable, which if
present, will cause the policies to be selectively downgraded or
bypassed.
The following policy filters are available:
304 Not Modified
or 412 Precondition
Failed
response where appropriate. A server may ignore conditional
headers, and this affects the efficiency of the HTTP caching mechanism.
This policy rejects requests where a conditional header is present, and
a 304 or 412 response code was expected, but a 2xx response was seen
instead.Cache-Control: no-cache
Pragma: no-cache
Cache-Control: no-store
Cache-Control: private
s-maxage
is present but too small; ormax-age
is present but too small; orExpires
is present and invalid; orDate
is present and invalid; orExpires
minus Date is too small; ors-maxage
, maxage
, or
Expires
/Date
declared at allHTTP/1.1
HTTP/1.0
HTTP/0.9
A typical configuration protecting a server serving static content might be as follows:
<Location "/"> SetOutputFilter POLICY_TYPE;POLICY_LENGTH;POLICY_KEEPALIVE;POLICY_VARY;POLICY_VALIDATION; \ POLICY_CONDITIONAL;POLICY_NOCACHE;POLICY_MAXAGE;POLICY_VERSION # content type must be present and valid, but can be anything PolicyType enforce */* # reject if no explicitly declared content length PolicyLength enforce # covered by the policy length filter PolicyKeepalive ignore # reject if User-Agent appears within Vary headers PolicyVary enforce User-Agent # we want to enforce validation PolicyValidation enforce # non-functional conditional responses should be rejected PolicyConditional enforce # no-cache responses should be rejected PolicyNocache enforce # maxage must be at least a day PolicyMaxage enforce 86400 # request version can be anything PolicyVersion ignore HTTP/1.1 </Location> # suppress policy protection for server-status <Location "/server-status"> PolicyFilter off </Location>
Description: | Enable the conditional request policy. |
---|---|
Syntax: | PolicyConditional ignore|log|enforce |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyConditional is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that should have been conditional but wasn't will be rejected.
# non-functional conditional responses should be rejected PolicyConditional enforce
Description: | URL describing the conditional request policy. |
---|---|
Syntax: | PolicyConditionalURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyConditionalURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the conditional request policy, to appear within error messages.
Description: | Override policies based on an environment variable. |
---|---|
Syntax: | PolicyEnvironment variable log-value ignore-value |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyEnvironment is only available in Apache 2.5.0 and later. |
Downgrade policies to logging only or ignored based on the presence of an environment variable. If the given variable is present and equal to the log-value, enforced policies will be logged instead. If the given variable is present and equal to the ignore-value, all policies will be ignored.
# downgrade if POLICY_CONTROL was present PolicyEnvironment POLICY_CONTROL log ignore
Description: | Enable or disable policies for the given URL space. |
---|---|
Syntax: | PolicyFilter on|off |
Default: | on |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyFilter is only available in Apache 2.5.0 and later. |
Master switch to enable or disable policies for a given URL space.
# enabled by default <Location "/"> PolicyFilter on </Location> # suppress policy protection for server-status <Location "/server-status"> PolicyFilter off </Location>
Description: | Enable the keepalive policy. |
---|---|
Syntax: | PolicyKeepalive ignore|log|enforce |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyKeepalive is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that lacks both an explicit
Content-Length
header and a Transfer-Encoding
of chunked
will be rejected.
# missing Content-Length or Transfer-Encoding should be rejected PolicyKeepalive enforce
Description: | URL describing the keepalive policy. |
---|---|
Syntax: | PolicyKeepaliveURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyKeepaliveURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the keepalive policy, to appear within error messages.
Description: | Enable the content length policy. |
---|---|
Syntax: | PolicyLength ignore|log|enforce |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyLength is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that lacks an explicit
Content-Length
header will be rejected.
# missing Content-Length header should be rejected PolicyLength enforce
Description: | URL describing the content length policy. |
---|---|
Syntax: | PolicyLengthURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyLengthURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the content length policy, to appear within error messages.
Description: | Enable the caching minimum max-age policy. |
---|---|
Syntax: | PolicyMaxage ignore|log|enforce age |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyMaxage is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that lacks an explicit freshness
lifetime defined with max-age
, s-maxage
or an
Expires
header, or where the explicit freshness lifetime is
smaller than the given value, will be rejected.
# reject responses with a freshness lifetime shorter than a day PolicyMaxage enforce 86400
Description: | URL describing the caching minimum freshness lifetime policy. |
---|---|
Syntax: | PolicyMaxageURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyMaxageURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the caching minimum freshness lifetime policy, to appear within error messages.
Description: | Enable the caching no-cache policy. |
---|---|
Syntax: | PolicyNocache ignore|log|enforce |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyNocache is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that defines itself uncacheable
using the Cache-Control
or Pragma
headers will
be rejected.
# Cache-Control: no-cache will be rejected PolicyNocache enforce
Description: | URL describing the caching no-cache policy. |
---|---|
Syntax: | PolicyNocacheURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyNocacheURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the caching no-cache policy, to appear within error messages.
Description: | Enable the content type policy. |
---|---|
Syntax: | PolicyType ignore|log|enforce type [ type [ ... ]] |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyType is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that lacks a Content-Type
header, where the Content-Type
header is malformed, or where the
header does not match the given pattern or patterns will be rejected.
# enforce json or XML PolicyType enforce application/json text/xml
# malformed content type should be rejected PolicyType enforce */*
Description: | URL describing the content type policy. |
---|---|
Syntax: | PolicyTypeURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyTypeURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the content type policy, to appear within error messages.
Description: | Enable the validation policy. |
---|---|
Syntax: | PolicyValidation ignore|log|enforce |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyValidation is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that lacks either a valid
ETag
header or a Last-Modified
header, or where
either header is syntactically incorrect, will be rejected.
# no ETag or Last-Modified will be rejected PolicyValidation enforce
Description: | URL describing the content type policy. |
---|---|
Syntax: | PolicyValidationURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyValidationURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the validation policy, to appear within error messages.
Description: | Enable the Vary policy. |
---|---|
Syntax: | PolicyVary ignore|log|enforce header [ header [ ... ]] |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyVary is only available in Apache 2.5.0 and later. |
When logged or enforced, a response that contains a Vary
header which in turn contains one of the headers listed, will be
rejected.
# reject reponses with "User-Agent" listed in the Vary header PolicyVary enforce User-Agent
Description: | URL describing the content type policy. |
---|---|
Syntax: | PolicyVaryURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyVaryURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the vary policy, to appear within error messages.
Description: | Enable the version policy. |
---|---|
Syntax: | PolicyVersion ignore|log|enforce HTTP/0.9|HTTP/1.0|HTTP/1.1 |
Default: | ignore |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyVersion is only available in Apache 2.5.0 and later. |
When logged or enforced, a request with a version lower than specified will be rejected.
# reject requests with an HTTP version older than HTTP/1.1 PolicyVersion enforce HTTP/1.1
Description: | URL describing the minimum request HTTP version policy. |
---|---|
Syntax: | PolicyVersionURL url |
Default: | none |
Context: | server config, virtual host, directory |
Status: | Extension |
Module: | mod_policy |
Compatibility: | PolicyVersionURL is only available in Apache 2.5.0 and later. |
Specify the URL of the documentation describing the minimum request HTTP version policy, to appear within error messages.