Adding response headers (add_header) in Nginx - Deep Dive

Overview - Adding response headers (add_header)

What is it?

Adding response headers in nginx means instructing the server to include extra information in the replies it sends to clients. These headers can control browser behavior, security settings, or caching rules. The add_header directive is the command used in nginx configuration to specify these headers. It helps customize how browsers and other clients handle the server's responses.

Why it matters

Without the ability to add response headers, websites would lack important controls for security, performance, and user experience. For example, you couldn't tell browsers to avoid caching sensitive data or to allow cross-site requests safely. This could lead to slower sites, security risks, or broken features. Adding headers lets site owners shape how their content is treated, improving safety and speed.

Where it fits

Before learning add_header, you should understand basic nginx configuration and how HTTP headers work. After mastering add_header, you can explore advanced security headers, caching strategies, and how to debug HTTP responses. This fits into the broader journey of web server management and web security.

Mental Model

Core Idea

Adding response headers with add_header is like attaching instruction notes to every package your server sends, guiding the receiver on how to handle it.

Think of it like...

Imagine sending a letter with a sticky note that says 'Handle with care' or 'Keep refrigerated.' The add_header directive sticks these notes (headers) onto your server's responses so browsers know what to do.

┌─────────────────────────────┐
│ Client Request              │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ nginx Server                │
│  add_header directive adds  │
│  extra headers to response  │
└─────────────┬───────────────┘
              │
              ▼
┌─────────────────────────────┐
│ Response with headers       │
│ (instructions for browser) │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding HTTP Response Headers

Concept: Learn what HTTP response headers are and why they matter.

HTTP response headers are pieces of information sent by a web server along with the content. They tell the browser things like content type, caching rules, or security policies. For example, a header can say 'Content-Type: text/html' to tell the browser to treat the response as a webpage.

Result

You understand that headers are extra data sent with web pages that control browser behavior.

Knowing what response headers do is essential before you can add or modify them effectively.

2

Foundation

Basic nginx Configuration Structure

Concept: Understand where and how to write configuration directives in nginx.

nginx configuration files have blocks like 'http', 'server', and 'location' where you define settings. Directives like add_header go inside these blocks to apply to all or some responses. For example, inside a 'server' block, you can add headers for all responses from that server.

Result

You know where to place add_header commands to affect responses.

Understanding nginx config structure prevents misplacement of directives that would cause errors or no effect.

3

Intermediate

Using add_header Directive Syntax

🤔Before reading on: do you think add_header can add multiple headers in one line or requires separate lines? Commit to your answer.

Concept: Learn the syntax and usage rules of the add_header directive.

The add_header directive syntax is: add_header [always]; Each header must be added with its own add_header line. The optional 'always' parameter ensures the header is added even on error responses. For example: add_header X-Frame-Options "DENY"; add_header Cache-Control "no-store" always;

Result

You can write correct add_header lines to add custom headers.

Knowing the syntax and the 'always' flag helps you control when headers appear, avoiding common mistakes.

4

Intermediate

Scope and Inheritance of add_header

🤔Before reading on: do you think add_header directives in a parent block automatically apply inside nested blocks? Commit to your answer.

Concept: Understand how add_header behaves in nested nginx blocks and inheritance rules.

add_header directives apply only in the block where they are declared and do not inherit into nested blocks. If you define add_header in 'http' block, it applies globally. But if you define it in a 'location' block, it overrides or replaces headers from parent blocks. This means you must repeat add_header in nested blocks if you want headers there.

Result

You know how to place add_header directives to cover all desired responses.

Understanding scope prevents missing headers in some responses due to block nesting.

5

Intermediate

Controlling Headers on Error Responses

🤔Before reading on: do you think add_header adds headers to error pages by default? Commit to your answer.

Concept: Learn how to ensure headers are added even when nginx returns error pages.

By default, add_header does NOT add headers to responses with status codes 4xx or 5xx. To force headers on all responses, use the 'always' parameter: add_header X-Content-Type-Options "nosniff" always; This ensures security headers are present even on error pages.

Result

You can guarantee headers appear on all responses, improving security.

Knowing this prevents security holes where error pages lack important headers.

6

Advanced

Conditional Headers with if and map

🤔Before reading on: do you think add_header supports conditions directly? Commit to your answer.

Concept: Explore how to add headers conditionally using nginx features like if and map.

add_header itself does not support conditions. To add headers only for certain requests, use 'if' blocks or 'map' variables. For example: map $http_user_agent $add_header_flag { default 0; "BadBot" 1; } server { if ($add_header_flag) { add_header X-Blocked "true"; } } This adds a header only if the user agent matches 'BadBot'.

Result

You can customize headers dynamically based on request properties.

Understanding this workaround allows flexible header control despite add_header limitations.

7

Expert

Interaction with HTTP/2 and Caching Proxies

🤔Before reading on: do you think add_header behaves identically with HTTP/1.1 and HTTP/2? Commit to your answer.

Concept: Learn how add_header works with HTTP/2 and caching proxies, and potential pitfalls.

HTTP/2 multiplexes requests, but add_header works the same way adding headers to each response. However, caching proxies may ignore or strip some headers unless properly configured. Also, some headers like 'Cache-Control' affect caching behavior and must be set carefully to avoid stale content. Understanding how add_header interacts with these layers is crucial for production.

Result

You can avoid subtle bugs with headers in modern web environments.

Knowing these interactions prevents performance and security issues in complex deployments.

Under the Hood

When nginx processes a client request, it builds the HTTP response including status, body, and headers. The add_header directive tells nginx to insert specified header lines into the response before sending it out. Internally, nginx stores these headers in a data structure linked to the response. The 'always' flag modifies the logic to include headers even on error responses, overriding default behavior that skips headers on errors.

Why designed this way?

nginx was designed for high performance and flexibility. add_header was made simple to add static headers efficiently without complex logic. The default behavior to skip headers on errors avoids sending misleading headers, but the 'always' flag was added later to meet security needs. The lack of direct conditional support keeps the core simple, pushing complex logic to other directives like 'if' and 'map'.

┌───────────────┐
│ Client sends  │
│ HTTP request  │
└──────┬────────┘
       │
       ▼
┌─────────────────────────────┐
│ nginx request processing    │
│ - Matches server/location   │
│ - Prepares response headers │
│ - Applies add_header rules  │
└──────┬──────────────────────┘
       │
       ▼
┌─────────────────────────────┐
│ Response sent with headers   │
│ including add_header entries │
└─────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does add_header add headers to all responses including errors by default? Commit yes or no.

Common Belief: add_header always adds headers to every response, no matter the status code.

Reality: By default, add_header does NOT add headers to responses with status codes 4xx or 5xx unless the 'always' parameter is used.

Why it matters: Without 'always', security headers might be missing on error pages, exposing vulnerabilities or inconsistent behavior.

Quick: If you add_header in a parent block, does it automatically apply inside nested location blocks? Commit yes or no.

Common Belief: Headers added in a parent block automatically apply to all nested blocks and locations.

Reality: add_header directives do NOT inherit into nested blocks; you must repeat them in each block where you want headers.

Why it matters: Missing headers in nested locations can cause security or caching issues that are hard to debug.

Quick: Can you add multiple headers in one add_header directive line? Commit yes or no.

Common Belief: You can add several headers in one add_header line separated by spaces.

Reality: Each add_header directive adds only one header; multiple headers require multiple add_header lines.

Why it matters: Trying to add multiple headers in one line causes configuration errors or missing headers.

Quick: Does add_header support conditional logic directly? Commit yes or no.

Common Belief: add_header supports conditions to add headers only for certain requests.

Reality: add_header does not support conditions; you must use other nginx features like 'if' or 'map' to control when headers are added.

Why it matters: Assuming direct conditions leads to failed configurations and inability to customize headers dynamically.

Expert Zone

1

add_header directives are evaluated at response time, so variables in header values can be used but require careful syntax.

2

The 'always' parameter was introduced in nginx 1.7.5; older versions do not support it, causing silent header omissions on errors.

3

Headers added by add_header can be overridden or removed by proxy servers or browsers caching policies, so testing end-to-end is essential.

When NOT to use

Avoid using add_header for dynamic or complex header logic; instead, use Lua scripts with ngx_http_lua_module or external middleware. Also, do not rely on add_header alone for security; combine with proper server and application configurations.

Production Patterns

In production, add_header is commonly used to add security headers like X-Frame-Options, Content-Security-Policy, and caching controls. It is often combined with conditional logic using map to tailor headers per client or path. Headers are tested with tools like curl or browser DevTools to ensure correct delivery.

Connections

HTTP Headers

builds-on

Understanding HTTP headers is essential to know what add_header modifies and why those headers matter for web communication.

Web Security

builds-on

Adding headers like Content-Security-Policy or X-Frame-Options directly impacts web security, making add_header a key tool in defense strategies.

Postal Service Instructions

analogy

Just like postal instructions guide how a package is handled, response headers guide browsers on handling content, showing how communication protocols rely on metadata.

Common Pitfalls

#1 Headers missing on error pages

Wrong approach:

add_header X-Content-Type-Options "nosniff";

Correct approach:

add_header X-Content-Type-Options "nosniff" always;

Root cause:

Not using the 'always' flag causes headers to be skipped on 4xx/5xx responses.

#2 Headers not applied in nested location blocks

Wrong approach:

http {
add_header X-Test "value";
server {
location / {
# no add_header here
}
}
}

Correct approach:

http {
add_header X-Test "value";
server {
location / {
add_header X-Test "value";
}
}
}

Root cause:

add_header does not inherit into nested blocks; must be repeated.

#3 Trying to add multiple headers in one line

Wrong approach:

add_header X-Frame-Options "DENY" Cache-Control "no-store";

Correct approach:

add_header X-Frame-Options "DENY";
add_header Cache-Control "no-store";

Root cause:

Each add_header directive adds only one header; multiple headers need separate lines.

Key Takeaways

The add_header directive in nginx lets you attach extra information to HTTP responses that control browser behavior and security.

Headers added with add_header do not apply to error responses unless you use the 'always' parameter.

add_header directives do not inherit into nested blocks, so you must add them explicitly where needed.

You cannot add multiple headers in one add_header line; each header requires its own directive.

For conditional header logic, use nginx features like 'if' or 'map' since add_header itself lacks condition support.