Headers Directives - Configure - H2O - the optimized HTTP server

# 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).

- `header.add`
- `header.append`
- `header.merge`
- `header.set`
- `header.setifempty`
- `header.unset`
- `header.unsetunless`

### `"header.add"`

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

### `"header.append"`

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

### `"header.merge"`

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

### `"header.set"`

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

### `"header.setifempty"`

Description:

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

Level:
  global, host, path, extension

### `"header.unset"`

Description:

  Removes headers with given name.

  Example. Removing the `X-Powered-By` header

      header.unset: "X-Powered-By"

Level:
  global, host, path, extension

### `"header.unsetunless"`

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.