Adding response headers (add_header) in Nginx - Commands & Configuration

Introduction

Sometimes websites need to send extra information to browsers or clients. Adding response headers lets you include this extra info in the server's reply. This helps with security, caching, or telling browsers how to behave.

When you want to improve security by adding headers like Content-Security-Policy or X-Frame-Options.

When you want to control browser caching by adding Cache-Control headers.

When you want to add custom headers to track or identify responses.

When you want to enable CORS by adding Access-Control-Allow-Origin headers.

When you want to add headers that tell browsers to upgrade insecure requests.

Config File - nginx.conf

nginx.conf

events {}

http {
    server {
        listen 8080;
        server_name localhost;

        location / {
            root /usr/share/nginx/html;
            index index.html;

            add_header X-Content-Type-Options "nosniff";
            add_header X-Frame-Options "DENY";
            add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0";
        }
    }
}

This configuration sets up a simple server listening on port 8080.

The add_header directives inside the location / block add three response headers:

• X-Content-Type-Options nosniff: prevents browsers from guessing the content type.
• X-Frame-Options DENY: stops the page from being shown in frames to prevent clickjacking.
• Cache-Control: disables caching to always get fresh content.

Commands

This command tests the nginx configuration file for syntax errors before applying changes.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

This command reloads nginx to apply the new configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

This command requests only the headers from the server to verify the added response headers.

Terminal

curl -I http://localhost:8080

Expected Output

HTTP/1.1 200 OK

Server: nginx/1.24.0

Date: Thu, 01 Jun 2024 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Last-Modified: Wed, 31 May 2024 10:00:00 GMT

Connection: keep-alive

X-Content-Type-Options: nosniff

X-Frame-Options: DENY

Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0

Key Concept

If you remember nothing else from this pattern, remember: add_header lets you send extra info in server replies to control browser behavior and improve security.

Common Mistakes

Placing add_header directives outside the http, server, or location blocks.

Nginx ignores add_header if it is not inside a valid context, so headers won't be added.

Always put add_header inside http, server, or location blocks where it applies.

Not reloading nginx after changing the configuration.

Changes won't take effect until nginx reloads or restarts.

Run 'systemctl reload nginx' or 'nginx -s reload' after editing config.

Using add_header with variables or conditions without proper syntax.

Older nginx versions ignore add_header with variables; headers won't appear.

Use nginx 1.7.5 or newer and proper syntax for conditional headers.

Summary

Use add_header inside server or location blocks to add custom response headers.

Test your nginx config with 'nginx -t' before reloading to avoid errors.

Reload nginx to apply changes and verify headers with 'curl -I'.