How to add your own custom Nginx headers (or reset existing headers)

4 min read

To add a custom header to your websites you can use the more_set_headers directive.
https://github.com/openresty/headers-more-nginx-module

This article will walk you through how to: –

  1. Add a custom header to either an individual website
  2. Add a custom header to all of the websites on your server
  3. Reset existing headers
  4. Use custom headers for debugging

Adding headers to individual websites

If you want to add the header on a site by site basis, add the following Nginx directive and value in a file on this file path: /var/www/site.url/nginx/*-main-context.conf

This uses the *-main-context.conf. You can replace the * with your own custom name. This is an example how the above code would look if we added a custom header to GridPane and called it “gpheader”:

/var/www/gridpane.com/gpheader-main-context.conf

Create the file with nano (switching out “site.url” for your domain name):

nano /var/www/site.url/nginx/yourchosenname-main-context.conf

Add your custom header, for example:

more_set_headers {your header code};

Hit CTRL+O and then Enter to save the file. CTRL+X to exit nano.

Check and reload Nginx

We now need to test our Nginx syntax with:

nginx -t

If there are no errors present, reload Nginx with the following command:

gp ngx reload

Add a custom header to all websites on your server

If you’d like to to add this header to all your sites, then you can add it to the extra.d main context configuration located here: /etc/nginx/extra.d/main-context.conf

First, navigate to the following directory:

cd /etc/nginx/extra.d/

Edit the main-context.conf with:

nano main-context.conf

Add your custom header, for example:

more_set_headers {your header code};

Hit CTRL+O and then Enter to save the file. CTRL+X to exit nano.

We’ll now copy the file into the _custom directory to ensure the changes persist:

cp main-context.conf _custom/main-context.conf 

Or, alternatively, you can copy the file with:

cp /etc/nginx/extra.d/main-context.conf /etc/nginx/extra.d/_custom/main-context.conf

Check and reload Nginx

We now need to test our Nginx syntax with:

nginx -t

If there are no errors present, reload Nginx with the following command:

gp ngx reload

Resetting existing headers

The GridPane stack sets numerous headers and while these are set to a common-sense default, they can be reset and reconfigured for different use cases on an as per your requirements.

To reset a header we need first to clear the existing header, and then afterwards we can set it again as a new header.

This can be accomplished by using the more_clear_headers directive to first clear the header you want to reset, and then use the more_set_headers to set the new header. For example:

more_clear_headers "Cache-Control";
more_set_headers "Cache-Control: public, no-transform";

This is probably best done on a site by site basis, and we’ll use the *-main-context.conf include to place our code. To get started, create file called cache-control-main-context.conf with the following command, switching out “site.url” with your domain name:

nano /var/www/site.url/nginx/cache-control-main-context.conf

Enter your code for clearing and reseting your header, and then hit CTRL+O and then Enter to save the file. CTRL+X to exit nano.

Check and reload Nginx

We now need to test our Nginx syntax with:

nginx -t

If there are no errors present, reload Nginx with the following command:

gp ngx reload

Examples of using custom headers for debugging

Custom headers can also be helpful when debugging. The following are a couple of examples of different use cases.

Example 1. Show Real IP addresses from Cloudflare

The following will show the real IP address of a visitor when you’re using Cloudflare.

Create a site-specific config using the *-main-context.conf include (switching out “site.url” with your domain name):

nano /var/www/site.url/nginx/showrealip-main-context.conf

Add the following header to the file:

more_set_headers "realip-remote-address: $realip_remote_addr";

Hit CTRL+O and then Enter to save the file. CTRL+X to exit nano. You’ll then need to check your Nginx syntax and reload Nginx.

Example 2. Show the stages of key processing for the cache key

The following would show the structure of the cache key as being processed:

more_set_headers "key-variables: $scheme$request_method$host$request_uri";
more_set_headers "escaped-key: $escaped_key";
more_set_headers "cache-key: $key";

Create a config for the above code block with the following command (switching out “site.url” with your domain name):

nano /var/www/site.url/nginx/keys-php-context.conf

Paste the code block above, and then hit CTRL+O and then Enter to save the file. CTRL+X to exit nano. Check and reload Nginx as outlined below.

Check and reload Nginx

Test our Nginx syntax with:

nginx -t

If there are no errors present, reload Nginx with the following command:

gp ngx reload
Free Trial