Using the Nginx add_header Directive
What is 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
307. This can be defined from within your
nginx.conf file by using the following snippet.
add_header Custom-Header Value;
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 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
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_headerdirectives 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.