Using the Nginx add_header Directive

What is the Nginx add_header directive?

The Nginx add_header directive allows you to define an arbitrary response header and value to be included in all response codes, which are equal to 200, 201, 204, 206, 301, 302, 303, 304, or 307. This can be defined from within your nginx.conf file by using the following snippet.

add_header Custom-Header Value;

The Custom-Header portion corresponds to the name of your response header while the Value portion corresponds to what value you want the header to return. This directive can be defined either in an HTTP, server, or location block.

How to check if the header is active

Once you have specified a custom header in your Nginx configuration file, save your changes and reload the Nginx configuration with the following command.

service nginx reload

Your custom header should now be active and delivered as a response header. There are a couple of ways to verify that the Nginx add_header has been properly set. The first method is to check your response headers using Chrome DevTools. To do this, simply open the Chrome DevTools and navigate to the Network panel. Select your HTML document and check the Response Headers section to verify that your custom header was set.

Additionally, you can also use curl to check wether the custom header is being returned. Check out some popular curl examples for a list of ways to use curl. To check a particular URL's headers use the following command.

curl -I https://www.keycdn.com
HTTP/2 200
server: keycdn-engine
date: Sun, 15 Mar 2020 18:53:48 GMT
content-type: text/html
vary: Accept-Encoding
last-modified: Thu, 05 Mar 2020 11:41:26 GMT
etag: W/"5e60e566-13e3b"
expires: Sun, 22 Mar 2020 18:53:48 GMT
cache-control: max-age=604800
strict-transport-security: max-age=31536000; includeSubdomains; preload
content-security-policy: default-src 'self' 'unsafe-inline' 'unsafe-eval' https: data:
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
referrer-policy: no-referrer-when-downgrade
x-cache: HIT
x-edge-location: ussf
access-control-allow-origin: *

Purpose of setting custom headers

Now that you know how to set a custom response header using the Nginx add_header method, you may be asking yourself, "What the purpose is of doing this?" Custom headers can be used for informational/debugging purposes. For example, WordPress includes a header such as X-Powered-By: PHP/5.5.9-1ubuntu4.17 to identify which version of PHP and Ubuntu your server is running.

Additionally, if you are using a CDN, you may have noticed a response header such as X-Cache: HIT or X-Cache: MISS. These custom headers are used for informational purposes so that the client knows wether the asset was delivered by the cache or not.

You can also define specific headers to be used solely for certain files or folders. For example, if you do not want to cache a particular file, you can use a location block to define the file's location and use the following add_header snippet.

add_header Cache-Control no-cache;

This will tell the browser not to cache the particular asset(s) stored at the location defined. To learn more about caching headers read our complete HTTP Cache Headers guide.

What to be aware of when using Nginx add_header

It is important to be aware of how exactly the Nginx add_header works in terms of hierarchical Nginx configuration structure. From the Nginx HTTP Headers Module documentation, it says:

There could be several add_header directives. These directives are inherited from the previous level if and only if there are no add_header directives defined on the current level.

Therefore, let's say you have an http block and have specified the add_header directive within that block. Then, within the http block you have two server blocks - one for HTTP and one for HTTPS.

Let's say we don't include an add_header directive within the HTTP server block, however we do include an additional add_header within the HTTPS server block. In this scenario, the add_header directive defined in the http block will only be inherited by the HTTP server block as it does not have any add_header directive defined on the current level. On the other hand, the HTTPS server block will not inherit the add_header directive defined in the http block.

Server administrators should be aware of this when modifying their Nginx configuration. There are solutions to this such as using an alternative module such as ngx_headers_more or defining a common config snippet. To learn more about this Nginx add_headers limitation, read more here.