ngx_http_headers_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_headers_module"
        link="/en/docs/http/ngx_http_headers_module.html"
        lang="en"
        rev="14">

<section id="summary">

<para>
The <literal>ngx_http_headers_module</literal> module allows adding
the <header>Expires</header> and <header>Cache-Control</header> header
fields, and arbitrary fields, to a response header.
</para>

</section>


<section id="example" name="Example Configuration">

<para>
<example>
expires    24h;
expires    modified +24h;
expires    @24h;
expires    0;
expires    -1;
expires    epoch;
expires    $expires;
add_header Cache-Control private;
</example>
</para>

</section>


<section id="directives" name="Directives">

<directive name="add_header">
<syntax>
<value>name</value> <value>value</value>
[<literal>always</literal>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Adds the specified field to a response header provided that
the response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304,
307 (1.1.16, 1.0.13), or 308 (1.13.0).
Parameter value can contain variables.
</para>

<para id="add_header_default_inherit">
There could be several <literal>add_header</literal> directives.
These directives are inherited from the previous configuration level
if and only if there are no <literal>add_header</literal> directives
defined on the current level.
Inheritance rules can be redefined with the
<link id="add_header_inherit"/> directive (1.29.3).
</para>

<para>
If the <literal>always</literal> parameter is specified (1.7.5),
the header field will be added regardless of the response code.
</para>

</directive>


<directive name="add_header_inherit">
<syntax>
    <literal>on</literal> |
    <literal>off</literal> |
    <literal>merge</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>
<appeared-in>1.29.3</appeared-in>

<para>
Allows altering inheritance rules for the values specified in the
<link id="add_header"/> directives.
By default, the
<link id="add_header_default_inherit">standard</link> inheritance model is used.
</para>

<para>
The <literal>merge</literal> parameter enables appending values
from the previous level to the values defined at the current level.
</para>

<para>
The <literal>off</literal> parameter cancels inheritance of the values
from the previous configuration level.
</para>

<para>
The inheritance rules themselves are inherited in a standard way.
For example, <literal>add_header_inherit merge;</literal>
specified at the top level will
be inherited in all nested levels recursively unless redefined later.
</para>

</directive>


<directive name="add_trailer">
<syntax>
<value>name</value> <value>value</value>
[<literal>always</literal>]</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>
<appeared-in>1.13.2</appeared-in>

<para>
Adds the specified field to the end of a response provided that
the response code equals 200, 201, 206, 301, 302, 303, 307, or 308.
Parameter value can contain variables.
</para>

<para id="add_trailer_default_inherit">
There could be several <literal>add_trailer</literal> directives.
These directives are inherited from the previous configuration level
if and only if there are no <literal>add_trailer</literal> directives
defined on the current level.
Inheritance rules can be redefined with the
<link id="add_trailer_inherit"/> directive (1.29.3).
</para>

<para>
If the <literal>always</literal> parameter is specified
the specified field will be added regardless of the response code.
</para>

</directive>


<directive name="add_trailer_inherit">
<syntax>
    <literal>on</literal> |
    <literal>off</literal> |
    <literal>merge</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>
<appeared-in>1.29.3</appeared-in>

<para>
Allows altering inheritance rules for the values specified in the
<link id="add_trailer"/> directives.
By default, the
<link id="add_trailer_default_inherit">standard</link> inheritance model is used.
</para>

<para>
The <literal>merge</literal> parameter enables appending values
from the previous level to the values defined at the current level.
</para>

<para>
The <literal>off</literal> parameter cancels inheritance of the values
from the previous configuration level.
</para>

<para>
The inheritance rules themselves are inherited in a standard way.
For example, <literal>add_trailer_inherit merge;</literal>
specified at the top level will
be inherited in all nested levels recursively unless redefined later.
</para>

</directive>


<directive name="expires">
<syntax>[<literal>modified</literal>] <value>time</value></syntax>
<syntax>
    <literal>epoch</literal> |
    <literal>max</literal> |
    <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if in location</context>

<para>
Enables or disables adding or modifying the <header>Expires</header>
and <header>Cache-Control</header> response header fields provided that
the response code equals 200, 201 (1.3.10), 204, 206, 301, 302, 303, 304,
307 (1.1.16, 1.0.13), or 308 (1.13.0).
The parameter can be a positive or negative
<link doc="../syntax.xml">time</link>.
</para>

<para>
The time in the <header>Expires</header> field is computed as a sum of the
current time and <value>time</value> specified in the directive.
If the <literal>modified</literal> parameter is used (0.7.0, 0.6.32)
then the time is computed as a sum of the file’s modification time and
the <value>time</value> specified in the directive.
</para>

<para>
In addition, it is possible to specify a time of day using
the “<literal>@</literal>” prefix (0.7.9, 0.6.34):
<example>
expires @15h30m;
</example>
</para>

<para>
The contents of the <header>Cache-Control</header> field depends
on the sign of the specified time:
<list type="bullet">

<listitem>
time is negative — <header>Cache-Control: no-cache</header>.
</listitem>

<listitem>
time is positive or zero —
<header>Cache-Control: max-age=<value>t</value></header>,
where <value>t</value> is a time specified in the directive, in seconds.
</listitem>

</list>
</para>

<para>
The <literal>epoch</literal> parameter sets <header>Expires</header>
to the value “<literal>Thu, 01 Jan 1970 00:00:01 GMT</literal>”,
and <header>Cache-Control</header> to “<literal>no-cache</literal>”.
</para>

<para>
The <literal>max</literal> parameter sets <header>Expires</header>
to the value “<literal>Thu, 31 Dec 2037 23:55:55 GMT</literal>”,
and <header>Cache-Control</header> to 10 years.
</para>

<para>
The <literal>off</literal> parameter disables adding or modifying the
<header>Expires</header> and <header>Cache-Control</header> response
header fields.
</para>

<para>
The last parameter value can contain variables (1.7.9):
<example>
map $sent_http_content_type $expires {
    default         off;
    application/pdf 42d;
    ~image/         max;
}

expires $expires;
</example>
</para>

</directive>

</section>

</module>