From b162b93559360092170b687d3cf3ed36267b2999 Mon Sep 17 00:00:00 2001 From: Graham Leggett Date: Wed, 21 Dec 2011 10:47:19 +0000 Subject: [PATCH] Update transformations. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1221671 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/compliance.html | 5 + docs/manual/compliance.html.en | 466 ++++++++++++ docs/manual/compliance.xml.meta | 12 + docs/manual/filter.html.en | 2 +- docs/manual/filter.xml.es | 2 +- docs/manual/filter.xml.ja | 2 +- docs/manual/filter.xml.ko | 2 +- docs/manual/filter.xml.tr | 2 +- .../images/compliance-reverse-proxy.png | Bin 0 -> 49600 bytes docs/manual/images/compliance-static.png | Bin 0 -> 41134 bytes docs/manual/index.html.en | 1 + docs/manual/index.xml.da | 2 +- docs/manual/index.xml.de | 2 +- docs/manual/index.xml.es | 2 +- docs/manual/index.xml.ja | 2 +- docs/manual/index.xml.ko | 2 +- docs/manual/index.xml.pt-br | 2 +- docs/manual/index.xml.tr | 2 +- docs/manual/mod/allmodules.xml.de | 1 + docs/manual/mod/allmodules.xml.es | 1 + docs/manual/mod/allmodules.xml.fr | 1 + docs/manual/mod/allmodules.xml.ja | 1 + docs/manual/mod/allmodules.xml.ko | 1 + docs/manual/mod/allmodules.xml.tr | 1 + docs/manual/mod/allmodules.xml.zh-cn | 1 + docs/manual/mod/directives.html.en | 20 + docs/manual/mod/index.html.en | 3 +- docs/manual/mod/mod_policy.html | 5 + docs/manual/mod/mod_policy.html.en | 685 ++++++++++++++++++ docs/manual/mod/mod_policy.xml.meta | 12 + docs/manual/mod/quickreference.html.en | 20 + docs/manual/sitemap.html.en | 1 + 32 files changed, 1248 insertions(+), 13 deletions(-) create mode 100644 docs/manual/compliance.html create mode 100644 docs/manual/compliance.html.en create mode 100644 docs/manual/compliance.xml.meta create mode 100644 docs/manual/images/compliance-reverse-proxy.png create mode 100644 docs/manual/images/compliance-static.png create mode 100644 docs/manual/mod/mod_policy.html create mode 100644 docs/manual/mod/mod_policy.html.en create mode 100644 docs/manual/mod/mod_policy.xml.meta diff --git a/docs/manual/compliance.html b/docs/manual/compliance.html new file mode 100644 index 0000000000..7d2dcccbf1 --- /dev/null +++ b/docs/manual/compliance.html @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: compliance.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 diff --git a/docs/manual/compliance.html.en b/docs/manual/compliance.html.en new file mode 100644 index 0000000000..212c869c2f --- /dev/null +++ b/docs/manual/compliance.html.en @@ -0,0 +1,466 @@ + + + +HTTP Protocol Compliance - Apache HTTP Server + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.5

+
+
<-
+
+Apache > HTTP Server > Documentation > Version 2.5

HTTP Protocol Compliance

+
+

Available Languages:  en 

+
+ +

This document describes the mechanism to set a policy for HTTP + protocol compliance for a given URL space by the origin servers or + applications behind that URL space.

+ +

For those who may have received an error message from a rejected + policy, and need to know what the policy rejection means and what + they might do to fix the error, each policy is described below.

+
+ +
top
+
+

Enforcing HTTP Protocol Compliance in Apache 2

+ +
Related ModulesRelated Directives
+ +

The HTTP protocol follows the robustness principle + as described in RFC1122, + which states "Be liberal in what you accept, and conservative in + what you send". As a result of this principle, HTTP clients will + compensate for and recover from incorrect or misconfigured responses, or + responses that are uncacheable.

+ +

As a website is scaled up to face greater and greater traffic loads, + suboptimal or misconfigured applications or server configurations can + threaten both the stability and scalability of the website, as well as + the hosting costs associated with it. A website can also scale up to face + greater configuration complexity, and it can be increasingly difficult to + detect and keep track of suboptimally configured URL spaces on a given + server.

+ +

Eventually a point is reached where the principle "conservative in + what you send" needs to be enforced by the server administrator.

+ +

The mod_policy module provides a set of filters + which can be applied to a server, allowing key features of the HTTP + protocol to be explicitly tested, and non compliant responses logged as + warnings, or rejected outright as an error. Each filter can be applied + separately, allowing the administrator to pick and choose which policies + should be enforced depending on the circumstances of their environment. +

+ +

The filters might be placed in testing and staging environments for + the benefit of application and website developers, or may be applied + to production servers to protect infrastructure from systems outside + the administrator's direct control.

+ +

+ Enforcing HTTP protocol compliance for an application server +

+ +

In the above example, an Apache httpd server has been placed between + the application server and the internet at large, and configured to cache + responses from the application server. The mod_policy + filters have been added to enforce support for cacheable content and + conditional requests, ensuring that both mod_cache and + public caches on the internet are fully able to cache content created + by the restful application server efficiently.

+ +

+ Enforcing HTTP protocol compliance in a static server +

+ +

In the above simpler example, a static server serving highly cacheable + content has a set of policies applied to ensure that the server configuration + conforms to a minimum level of compliance.

+ +
top
+
+

Conditional Request Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server does not correctly respond + to a conditional request with the appropriate status code.

+ +

Conditional requests form the mechanism by which an HTTP cache makes + stale content fresh again, and particularly for content with short freshness + lifetimes, lack of support for conditional requests can add avoidable load + to the server.

+ +

Most specifically, the existence of any of following headers in the + request makes the request conditional:

+ +
+
If-Match
+
If the provided ETag in the If-Match header does not match + the ETag of the response, the server should return + 412 Precondition Failed. Full details of how to handle an + If-Match header can be found in + + RFC2616 section 14.24.
+ +
If-None-Match
+
If the provided ETag in the If-None-Match header matches + the ETag of the response, the server should return either + 304 Not Modified for GET/HEAD requests, or + 412 Precondition Failed for other methods. Full details of how + to handle an If-None-Match header can be found in + + RFC2616 section 14.26.
+ +
If-Modified-Since
+
If the provided date in the If-Modified-Since header is + older than the Last-Modified header of the response, the server + should return 304 Not Modified. Full details of how to handle an + If-Modified-Since header can be found in + + RFC2616 section 14.25.
+ +
If-Unmodified-Since
+
If the provided date in the If-Modified-Since header is + newer than the Last-Modified header of the response, the server + should return 412 Precondition Failed. Full details of how to + handle an If-Unmodified-Since header can be found in + + RFC2616 section 14.28.
+ +
If-Range
+
If the provided ETag or date in the If-Range header matches + the ETag or Last-Modified of the response, and a valid Range + is present, the server should return + 206 Partial Response. Full details of how to handle an + If-Range header can be found in + + RFC2616 section 14.27.
+ +
+ +

If the response is detected to have been successful (a 2xx response), + but was conditional and one of the responses above was expected instead, + this policy will be rejected. Responses that indicate a redirect or a + failure of some kind (3xx, 4xx, 5xx) will be ignored by this policy.

+ +

This policy is implemented by the POLICY_CONDITIONAL + filter.

+ +
top
+
+

Content-Length Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response does not contain + an explicit Content-Length header.

+ +

There are a number of ways of determining the length of a response + body, described in full in + + RFC2616 section 4.4 Message Length.

+ +

When the Content-Length header is present, the size of + the body is declared at the start of the response. If this information + is missing, an HTTP cache might choose to ignore the response, as it + does not know in advance whether the response will fit within the + cache's defined limits.

+ +

HTTP/1.1 defines the Transfer-Encoding header as an + alternative to Content-Length, allowing the end of the + response to be indicated to the client without the client having to + know the length beforehand. However, when HTTP/1.0 requests are + processed, and no Content-Length is specified, the only + mechanism available to the server to indicate the end of the request + is to drop the connection. In an environment containing load + balancers, this can cause the keepalive mechanism to be bypassed. +

+ +

If the response is detected to have been successful (a 2xx response), + and has a response body (this excludes 204 No Content), and + the Content-Length header is missing, this policy will be + rejected. Responses that indicate a redirect or a failure of some kind + (3xx, 4xx, 5xx) will be ignored by this policy.

+ +
It should be noted that some modules, such as + mod_proxy, add their own Content-Length + header should the response be small enough for it to have been possible + to read the response lacking such a header in one go. This may cause + small responses to pass this policy, while larger responses may + fail for the same URL.
+ +

This policy is implemented by the POLICY_LENGTH + filter.

+ +
top
+
+

Content-Type Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response does not contain + an explicit and syntactically correct Content-Type header + that matches the server defined pattern.

+ +

The media type of the body is placed in the Content-Type + header, and the format of the header is described in full in + + RFC2616 section 3.7 Media Types.

+ +

A syntactically valid content type might look as follows:

+ +

+ Content-Type: text/html; charset=iso-8859-1 +

+ +

Invalid content types might include:

+ +

+ # invalid
+ Content-Type: foo
+ # blank
+ Content-Type: +

+ +

The server administrator has the option to restrict the policy to one + or more specific types, or could specify a general wildcard type such as + */*.

+ +

This policy is implemented by the POLICY_TYPE + filter.

+ +
top
+
+

Keepalive Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response does not contain + an explicit Content-Length header, or a + Transfer-Encoding of chunked.

+ +

There are a number of ways of determining the length of a response + body, described in full in + + RFC2616 section 4.4 Message Length.

+ +

When the Content-Length header is present, the size of + the body is declared at the start of the response. HTTP/1.1 defines the + Transfer-Encoding header as an alternative to + Content-Length, allowing the end of the response to be + indicated to the client without the client having to know the length + beforehand. In the absence of these two mechanisms, the only way for + a server to indicate the end of the request is to drop the connection. + In an environment containing load balancers, this can cause the keepalive + mechanism to be bypassed. +

+ +

Most specifically, we follow these rules:

+ +
+
IF
+
we have not marked this connection as errored;
+ +
and
+
the client isn't expecting 100-continue
+ +
and
+
the response status does not require a close;
+ +
and
+
the response body has a defined length due to the status code + being 304 or 204, the request method being HEAD, already having defined + Content-Length or Transfer-Encoding: chunked, or the request version + being HTTP/1.1 and thus capable of being set as chunked
+ +
THEN
+
we support keepalive.
+
+ +
The server may choose to turn off keepalive for + various reasons, such as an imminent shutdown, or a Connection: close from + the client, or an HTTP/1.0 client request with a response with no + Content-Length, but for our purposes we only care that + keepalive was possible from the application, not that keepalive actually + took place.
+ +

It should also be noted that the Apache httpd server includes a filter + that adds chunked encoding to responses without an explicit content + length. This policy catches those cases where this filter is bypassed or + not in effect.

+ +

This policy is implemented by the POLICY_KEEPALIVE + filter.

+ +
top
+
+

Freshness Lifetime / Maxage Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response does not have + an explicit freshness lifetime at least as long + as the server defined limit, or if the freshness lifetime is + calculated based on a heuristic.

+ +

Full details of how a freshness lifetime is calculated is described in + full in + + RFC2616 section 13.2 Expiration Model.

+ +

During the freshness lifetime, a cache does not need to contact the + origin server at all, it can simply pass the cached content as is back + to the client.

+ +

When the freshness lifetime is reached, the cache should contact the + origin server in an effort to check whether the content is still fresh, + and if not, replace the content.

+ +

When the freshness lifetime is too short, it can result in excessive + load on the server. In addition, should an outage occur that is as long + or longer than the freshness lifetime, all cached content will become + stale, which could cause a thundering herd of traffic when the + server or network returns.

+ +

This policy is implemented by the POLICY_MAXAGE + filter.

+ +
top
+
+

No Cache Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response declares itself + uncacheable using either the Cache-Control or + Pragma headers.

+ +

Full details of how content may be declared uncacheable is described in + full in + + RFC2616 section 14.9.1 What is Cacheable, and within the definition + for the Pragma header in + + RFC2616 section 14.32 Pragma.

+ +

Most specifically, should any of the following header combinations + exist in the response headers, the response will be rejected:

+ +
    +
  • Cache-Control: no-cache
    • +
  • Cache-Control: no-store
    • +
  • Cache-Control: private
    • +
  • Pragma: no-cache
    • +
+ +

When unexpected, uncacheable content may produce unacceptable levels + of server load, or may incur significant cost. When this policy is enabled, + all server defined uncacheable content will be rejected.

+ +

This policy is implemented by the POLICY_NOCACHE + filter.

+ +
top
+
+

Validation Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response does not contain + either a syntactically correct ETag or + Last-Modified header.

+ +

The ETag header is described in full in + + RFC2616 section 14.19 Etag, and the Last-Modified header + is described in full in + + RFC2616 section 14.29 Last-Modified.

+ +

In addition to being checked present, the headers are checked for + syntax.

+ +

An ETag that is not surrounded with quotes, or is not + declared "weak" by prefixing it with a "W/" will cause the policy to be + rejected. A Last-Modified that is not parsed as a valid date + will cause the policy to be rejected.

+ +

This policy is implemented by the POLICY_VALIDATION + filter.

+ +
top
+
+

Vary Header Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the server response contains a + Vary header, and that header in turn contains a header + blacklisted by the administrator.

+ +

The Vary header is described in full in + + RFC2616 section 14.44 Vary.

+ +

Some client provided headers, such as User-Agent, + can contain thousands or millions of combinations of values over a period + of time, and if the response is declared cacheable, a cache might attempt + to cache each of these responses separately, filling up the cache and + crowding out other entries in the cache. In this scenario, if so + configured, the policy will reject the response.

+ +

This policy is implemented by the POLICY_VARY + filter.

+ +
top
+
+

Protocol Version Policy

+ +
Related ModulesRelated Directives
+ +

This policy will be rejected if the client request was made with a + version number lower than the version of HTTP specified.

+ +

This policy is typically used with restful applications where + control over the type of client is desired. This policy can be used + alongside the POLICY_KEEPALIVE filter to ensure that + HTTP/1.0 clients don't cause keepalive connections to be dropped.

+ +

Possible minimum versions that could be specified are:

+ +
  • HTTP/1.1
    • +
  • HTTP/1.0
    • +
  • HTTP/0.9
    • +
+ +

This policy is implemented by the POLICY_VERSON + filter.

+ +
+
+

Available Languages:  en 

+
+ \ No newline at end of file diff --git a/docs/manual/compliance.xml.meta b/docs/manual/compliance.xml.meta new file mode 100644 index 0000000000..896b4812ff --- /dev/null +++ b/docs/manual/compliance.xml.meta @@ -0,0 +1,12 @@ + + + + + compliance + / + . + + + en + + diff --git a/docs/manual/filter.html.en b/docs/manual/filter.html.en index c3fcccc635..077f7a1ab0 100644 --- a/docs/manual/filter.html.en +++ b/docs/manual/filter.html.en @@ -37,7 +37,7 @@

Filtering in Apache 2

-
Related ModulesRelated Directives
+
Related ModulesRelated Directives

The Filter Chain is available in Apache 2.0 and higher, and enables applications to process incoming and outgoing data diff --git a/docs/manual/filter.xml.es b/docs/manual/filter.xml.es index 15c98cc461..316e7ccaf6 100644 --- a/docs/manual/filter.xml.es +++ b/docs/manual/filter.xml.es @@ -1,7 +1,7 @@ - + + + + + + + + + + + +mod_policy - Apache HTTP Server + + + + + +

+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.5

+
+
<-
+ +
+

Apache Module mod_policy

+
+

Available Languages:  en 

+
+ + + +
Description:HTTP protocol compliance enforcement.
Status:Extension
Module Identifier:policy_module
Source File:mod_policy.c
+

Summary

+ +

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.

+ +
+ +
top
+
+

Actions

+ + +

If a policy is violated, one of the following actions can be + taken:

+ +
+
ignore
+
The policy check will be ignored for the given URL space, even + if the filter is present.
+ +
log
+
The policy check will be executed, and if a violation is detected + a warning will be logged to the server error_log, and a + Warning header added to the response for the benefit of + the client.
+ +
enforce
+
The policy check will be executed, and if a violation is detected + an error will be logged to the server error_log, a + 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.

+ +
top
+
+

Policy Tests

+ + +

The following policy filters are available:

+ +
+
POLICY_TYPE + : Enforce valid content types
+
Content types that are syntactically invalid or blank can be detected + and the request rejected. Types can be restricted to a specific list + containing optional wildcards ? and *.
+ +
POLICY_LENGTH + : Enforce the presence of a Content-Length
+
The length of responses can be specified in one of three ways, by + specifying an explicit length in advance, using chunked encoding to set + the length, or by setting no length at all and terminating the request + when complete. The absence of a specific content length can affect the + cacheability of the response, and prevents the use of keepalive during + HTTP/1.0 requests. This policy enforces the presence of an explicit + content length on the response.
+ +
POLICY_KEEPALIVE + : Enforce the option to keepalive
+
Less restrictive than the POLICY_LENGTH test, this policy enforces the + possibility that the response can be kept alive. If the response doesn't + have a protocol defined zero length, and the response isn't already an + error, and the response has neither a Content-Length or is declared + HTTP/1.1 and lacks Content-Encoding: chunked, then this response will be + rejected.
+ +
POLICY_VARY + : Enforce the absence of certain headers within Vary headers
+
If the Vary header contains any of the headers specified, this policy + will reject the request. The typical case is the presence of the User-Agent + within Vary, which is likely to cause a denial of service condition to a + cache.
+ +
+ POLICY_VALIDATION: Enforce the presence of Etag and/or + Last-Modified
+
The ability for a cache to determine whether a cached entity can be + refreshed is dependent on whether a valid Etag and/or Last-Modified header + is present to revalidate against. The absence of both headers, or the + invalid syntax of a header will cause this policy to be rejected.
+ +
+ POLICY_CONDITIONAL: Enforce correct operation of conditional + requests
+
When conditional headers are present in the request, a server should + respond with a 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.
+ +
POLICY_NOCACHE + : Enforce cacheable responses
+
When a response is encountered that declares itself explicitly + uncacheable, the request is rejected. A response is considered + uncacheable if it specifies any of the following: +
  • Cache-Control: no-cache
    • +
  • Pragma: no-cache
    • +
  • Cache-Control: no-store
    • +
  • Cache-Control: private
    • +
+ +
POLICY_MAXAGE + : Enforce a minimum maxage
+
When a response is encountered where the freshness lifetime is less + than the given value, or the freshness lifetime is heuristic, the request + is rejected. A response is checked in the following order: +
  • If s-maxage is present but too small; or
    • +
  • If max-age is present but too small; or
    • +
  • If Expires is present and invalid; or
    • +
  • Date is present and invalid; or
    • +
  • Expires minus Date is too small; or
    • +
  • No s-maxage, maxage, or + Expires/Date declared at all
    • +
+ +
POLICY_VERSION + : Enforce a minimum HTTP version within a request
+
When a request is encountered with an HTTP version number less than + the required minimum version, the request is rejected. The following + version numbers are recognised: +
  • HTTP/1.1
    • +
  • HTTP/1.0
    • +
  • HTTP/0.9
    • +
+ +
+ +
top
+
+

Example Configuration

+ + +

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>
+

+ +
+
top
+

PolicyConditional Directive

+ + + + + + + + +
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.

+ +

Example

+ # non-functional conditional responses should be rejected
+ PolicyConditional enforce
+

+ +
+
top
+

PolicyConditionalURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyEnvironment Directive

+ + + + + + + + +
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.

+ +

Example

+ # downgrade if POLICY_CONTROL was present
+ PolicyEnvironment POLICY_CONTROL log ignore
+

+ +
+
top
+

PolicyFilter Directive

+ + + + + + + + +
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.

+ +

Example

+ # enabled by default
+ <Location />
+ + PolicyFilter on
+ + </Location>
+
+ # suppress policy protection for server-status
+ <Location /server-status>
+ + PolicyFilter off
+ + </Location>
+

+ +
+
top
+

PolicyKeepalive Directive

+ + + + + + + + +
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.

+ +

Example

+ # missing Content-Length or Transfer-Encoding should be rejected
+ PolicyKeepalive enforce
+

+ +
+
top
+

PolicyKeepaliveURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyLength Directive

+ + + + + + + + +
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.

+ +

Example

+ # missing Content-Length header should be rejected
+ PolicyLength enforce
+

+ +
+
top
+

PolicyLengthURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyMaxage Directive

+ + + + + + + + +
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.

+ +

Example

+ # reject responses with a freshness lifetime shorter than a day
+ PolicyMaxage enforce 86400
+

+ + +
+
top
+

PolicyMaxageURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyNocache Directive

+ + + + + + + + +
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.

+ +

Example

+ # Cache-Control: no-cache will be rejected
+ PolicyNocache enforce
+

+ + +
+
top
+

PolicyNocacheURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyType Directive

+ + + + + + + + +
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.

+ +

Example

+ # enforce json or XML
+ PolicyType enforce application/json text/xml
+

+ +

Example

+ # malformed content type should be rejected
+ PolicyType enforce */*
+

+ + +
+
top
+

PolicyTypeURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyValidation Directive

+ + + + + + + + +
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.

+ +

Example

+ # no ETag or Last-Modified will be rejected
+ PolicyValidation enforce
+

+ + +
+
top
+

PolicyValidationURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyVary Directive

+ + + + + + + + +
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.

+ +

Example

+ # reject reponses with "User-Agent" listed in the Vary header
+ PolicyVary enforce User-Agent
+

+ + +
+
top
+

PolicyVaryURL Directive

+ + + + + + + + +
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.

+ +
+
top
+

PolicyVersion Directive

+ + + + + + + + +
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.

+ +

Example

+ # reject requests with an HTTP version older than HTTP/1.1
+ PolicyVersion enforce HTTP/1.1
+

+ + +
+
top
+

PolicyVersionURL Directive

+ + + + + + + + +
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.

+ +
+
+
+

Available Languages:  en 

+
+ \ No newline at end of file diff --git a/docs/manual/mod/mod_policy.xml.meta b/docs/manual/mod/mod_policy.xml.meta new file mode 100644 index 0000000000..4198cf4ed1 --- /dev/null +++ b/docs/manual/mod/mod_policy.xml.meta @@ -0,0 +1,12 @@ + + + + + mod_policy + /mod/ + .. + + + en + + diff --git a/docs/manual/mod/quickreference.html.en b/docs/manual/mod/quickreference.html.en index f963fc0d20..ddea74570e 100644 --- a/docs/manual/mod/quickreference.html.en +++ b/docs/manual/mod/quickreference.html.en @@ -625,6 +625,26 @@ evaluated. ...svdhBPasses environment variables from the shell PidFile filename logs/httpd.pid sMFile where the server records the process ID of the daemon +PolicyConditional ignore|log|enforcesvdEEnable the conditional request policy. +PolicyConditionalURL urlsvdEURL describing the conditional request policy. +PolicyEnvironment variable log-value ignore-valuesvdEOverride policies based on an environment variable. +PolicyFilter on|offsvdEEnable or disable policies for the given URL space. +PolicyKeepalive ignore|log|enforcesvdEEnable the keepalive policy. +PolicyKeepaliveURL urlsvdEURL describing the keepalive policy. +PolicyLength ignore|log|enforcesvdEEnable the content length policy. +PolicyLengthURL urlsvdEURL describing the content length policy. +PolicyMaxage ignore|log|enforce agesvdEEnable the caching minimum max-age policy. +PolicyMaxageURL urlsvdEURL describing the caching minimum freshness lifetime policy. +PolicyNocache ignore|log|enforcesvdEEnable the caching no-cache policy. +PolicyNocacheURL urlsvdEURL describing the caching no-cache policy. +PolicyType ignore|log|enforce type [ type [ ... ]]svdEEnable the content type policy. +PolicyTypeURL urlsvdEURL describing the content type policy. +PolicyValidation ignore|log|enforcesvdEEnable the validation policy. +PolicyValidationURL urlsvdEURL describing the content type policy. +PolicyVary ignore|log|enforce header [ header [ ... ]]svdEEnable the Vary policy. +PolicyVaryURL urlsvdEURL describing the content type policy. +PolicyVersion ignore|log|enforce HTTP/0.9|HTTP/1.0|HTTP/1.1svdEEnable the version policy. +PolicyVersionURL urlsvdEURL describing the minimum request HTTP version policy. PrivilegesMode FAST|SECURE|SELECTIVEsvdXTrade off processing speed and efficiency vs security against malicious privileges-aware code. Protocol protocolsvCProtocol for a listening socket diff --git a/docs/manual/sitemap.html.en b/docs/manual/sitemap.html.en index 78dc40fb71..e82a033e2c 100644 --- a/docs/manual/sitemap.html.en +++ b/docs/manual/sitemap.html.en @@ -239,6 +239,7 @@ Server on HPUX
  • Apache Module mod_mime_magic
  • Apache Module mod_negotiation
  • Apache Module mod_nw_ssl
    • +
  • Apache Module mod_policy
  • Apache Module mod_privileges
  • Apache Module mod_proxy
  • Apache Module mod_proxy_ajp
    • -- 2.50.1