Module ngx_http_headers_module

Planning your ingress-nginx migration? Start here:
kubernetes.nginx.org.

english
русский
news
about
download
security
documentation
faq
books
community
enterprise
community forum (new)
x.com
blog
njs
ingress controller
gateway fabric

Module ngx_http_headers_module

Example Configuration
Directives
add_header
add_header_inherit
add_trailer
add_trailer_inherit
expires

The ngx_http_headers_module module allows adding
the “Expires” and “Cache-Control” header
fields, and arbitrary fields, to a response header.

Example Configuration

expires 24h;
expires modified +24h;
expires @24h;
expires 0;
expires -1;
expires epoch;
expires $expires;
add_header Cache-Control private;

Directives

Syntax:

add_header
name value
[always];

Default:

—

Context:

http, server, location, if in location

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.

There could be several add_header directives.
These directives are inherited from the previous configuration level
if and only if there are no add_header directives
defined on the current level.
Inheritance rules can be redefined with the
add_header_inherit directive (1.29.3).

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

Syntax:

add_header_inherit
on |
off |
merge;

Default:

add_header_inherit on;

Context:

http, server, location, if in location

This directive appeared in version 1.29.3.

Allows altering inheritance rules for the values specified in the
add_header directives.
By default, the
standard inheritance model is used.

The merge parameter enables appending values
from the previous level to the values defined at the current level.

The off parameter cancels inheritance of the values
from the previous configuration level.

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

Syntax:

add_trailer
name value
[always];

Default:

—

Context:

http, server, location, if in location

This directive appeared in version 1.13.2.

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.

There could be several add_trailer directives.
These directives are inherited from the previous configuration level
if and only if there are no add_trailer directives
defined on the current level.
Inheritance rules can be redefined with the
add_trailer_inherit directive (1.29.3).

If the always parameter is specified
the specified field will be added regardless of the response code.

Syntax:

add_trailer_inherit
on |
off |
merge;

Default:

add_trailer_inherit on;

Context:

http, server, location, if in location

This directive appeared in version 1.29.3.

Allows altering inheritance rules for the values specified in the
add_trailer directives.
By default, the
standard inheritance model is used.

The merge parameter enables appending values
from the previous level to the values defined at the current level.

The off parameter cancels inheritance of the values
from the previous configuration level.

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

Syntax:

expires [modified] time;
expires
epoch |
max |
off;

Default:

expires off;

Context:

http, server, location, if in location

Enables or disables adding or modifying the “Expires”
and “Cache-Control” 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
time.

The time in the “Expires” field is computed as a sum of the
current time and time specified in the directive.
If the modified 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 time specified in the directive.

In addition, it is possible to specify a time of day using
the “@” prefix (0.7.9, 0.6.34):

expires @15h30m;

The contents of the “Cache-Control” field depends
on the sign of the specified time:

time is negative — “Cache-Control: no-cache”.

time is positive or zero —
“Cache-Control: max-age=t”,
where t is a time specified in the directive, in seconds.

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

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

The off parameter disables adding or modifying the
“Expires” and “Cache-Control” response
header fields.

The last parameter value can contain variables (1.7.9):

map $sent_http_content_type $expires {
default off;
application/pdf 42d;
~image/ max;
}

expires $expires;