header

Manipulates HTTP header fields on the response. It can set, add, and delete header values, or perform replacements using regular expressions.

By default, header operations are performed immediately unless any of the headers are being deleted (- prefix) or setting a default value (? prefix). In those cases, the header operations are automatically deferred until the time they are being written to the client.

Syntax

header [<matcher>] [[+|-|?]<field> [<value>|<find>] [<replace>]] {
	# Replace
	<field> <find> <replace>

	# Add or Set
	[+]<field> <value>

	# Delete
	-<field>

	# Default
	?<field> <value>

	[defer]
}

• <field> is the name of the header field. By default, will overwrite any existing field of the same name.

  Prefix with + to add the field instead of overwriting (setting) the field if it already exists; header fields can appear more than once in a request.

  Prefix with - to delete the field. The field may use prefix or suffix * wildcards to delete all matching fields.

  Prefix with ? to set a default value for the field. The field is only written if it doesn't yet exist.

• <value> is the header field value, if adding or setting a field.

• <find> is the substring or regular expression to search for.

• <replace> is the replacement value; required if performing a search-and-replace.

• defer will force the header operations to be deferred until the response is being written out to the client. This is automatically enabled if any of the header fields are being deleted with -, or when setting a default value with ?.

For multiple header manipulations, you can open a block and specify one manipulation per line in the same way.

When using the ? prefix to set a default header value, it is recommended to separate this into its own header directive. Under the hood, using ? configures a response matcher which applies to the directive's entire handler which only applies the header operations if the field is not yet set. For example, if in the same directive, you have these two manipulations: -Hidden and ?Foo default, then the Hidden header is only removed if Foo is empty, which is typically not the intended effect.

Examples

Set a custom header field on all requests:

header Custom-Header "My value"

Strip the "Hidden" header field:

header -Hidden

Replace http:// with https:// in any Location header:

header Location http:// https://

Set security and privacy headers on all pages: (WARNING: only use if you understand the implications!)

header {
	# disable FLoC tracking
	Permissions-Policy interest-cohort=()

	# enable HSTS
	Strict-Transport-Security max-age=31536000;

	# disable clients from sniffing the media type
	X-Content-Type-Options nosniff

	# clickjacking protection
	X-Frame-Options DENY

	# keep referrer data off of HTTP connections
	Referrer-Policy no-referrer-when-downgrade
}

Multiple header directives that are intended to be mutually-exclusive:

route {
	header           Cache-Control max-age=3600
	header /static/* Cache-Control max-age=31536000
}

Set a default cache expiration if upstream doesn't define one:

header ?Cache-Control "max-age=3600"
reverse_proxy upstream:443