H2O

the optimized HTTP/1.x, HTTP/2, HTTP/3 server

Powered by Oktavia

Configure > Headers Directives

Headers directives can be used to manipulate response headers.

This document describes the following configuration directives as well as when they are applied. All the directives accept one header field (specified by a YAML scalar), or multiple header fields (specified by a YAML sequence).

Description:

Adds a new header line to the response headers, regardless if a header with the same name already exists.

Example. Setting the Set-Cookie header
header.add: "Set-Cookie: test=1"
Level:
global, host, path, extension
Description:

Adds a new header line, or appends the value to the existing header with the same name, separated by ,.

Level:
global, host, path, extension
Description:

Adds a new header line, or merges the value to the existing header of comma-separated values.

The following example sets the must-revalidate attribute of the Cache-Control header when and only when the attribute is not yet being set.

Example. Setting the must-revalidate attribute
header.merge: "Cache-Control: must-revalidate"
Level:
global, host, path, extension
Description:

Sets a header line, removing headers with the same name if exists.

Example. Setting the X-Content-Type-Options: nosniff header
header.set: "X-Content-Type-Options: nosniff"
Level:
global, host, path, extension
Description:

Sets a header line when and only when a header with the same name does not already exist.

Level:
global, host, path, extension
Description:

Removes headers with given name.

Example. Removing the X-Powered-By header
header.unset: "X-Powered-By"
Level:
global, host, path, extension
Description:

Remove all headers but those listed.

Example. Remove all headers but If-Match and If-Modified-Since
header.unsetunless:
- "If-Match"
- "If-Modified-Since"
Level:
global, host, path, extension

Timing of Application

Starting from v2.3, it is possible to specify the timing when the headers directives is applied. All of the header directives can take either of the following two forms.

Example. Scalar Form
header.add: "X-Foo: FOO":
Example. Mapping Form
header.add:
  header: "X-Foo: FOO":
  when: final

The above two are identical.

when can be either of: final, early, all. Default is final.

If the value is final, the header directive is only applied to final (i.e. non-1xx) response. If the value is early, it's only applied to 1xx informational responses. If all is set, it's applied to both of final and 1xx responses.