Headers#

Allows adding the Expires and Cache-Control header fields, and arbitrary fields, to a response header.

Configuration Example#

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

Directives#

add_header#

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, or 308. 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.

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

If the field value, after variable substitution, is an empty string, the field is not added. This allows adding the field conditionally:

map $request_uri $robots_tag {
    ~^/private/  "noindex, nofollow";
    default      "";
}

add_header X-Robots-Tag $robots_tag;

For the ETag and Last-Modified fields, the directive does not add a second field: if the response already has such a field (for example, set when serving a static file or received from a proxied server), the directive replaces it. If the value is an empty string, the directive removes the field from the response. Replacing and removing, like adding, depend on the response code and the always parameter.

The directive handles the Content-Type field the same way. If the field received from a proxied, FastCGI, uwsgi, SCGI, or gRPC server has a charset parameter and the new value has none, the directive keeps that charset: for example, text/html; charset=utf-8 replaced with application/json becomes application/json; charset=utf-8.

add_trailer#

Syntax	`add_trailer` name value [`always`];
Default	—
Context	http, server, location, if in location

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.

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

If the field value, after variable substitution, is an empty string, the field is not added.

expires#

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, 204, 206, 301, 302, 303, 304, 307, or 308. 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, 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:

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.

`epoch`	sets `Expires` to the value "Thu, 01 Jan 1970 00:00:01 GMT", and `Cache-Control` to "no-cache".
`max`	sets `Expires` to the value "Thu, 31 Dec 2037 23:55:55 GMT", and `Cache-Control` to 10 years.
`off`	disables adding or modifying the `Expires` and `Cache-Control` response header fields.

The last parameter value can contain variables:

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

expires $expires;