Cache bypass conditions in Nginx - Step-by-Step Execution

Process Flow - Cache bypass conditions

Request Received

↓

Check Bypass Conditions

↓

Bypass?

↓

Fetch from

↓

Send Response

↓

End

When a request comes in, nginx checks if any bypass conditions apply. If yes, it skips cache and fetches fresh content. Otherwise, it serves cached content.

Execution Sample

Nginx

proxy_cache_bypass $http_cache_control;
proxy_no_cache $cookie_nocache;

location / {
  proxy_pass http://backend;
}

This config bypasses cache if the client sends Cache-Control header or a specific cookie.

Process Table

Step	Request Header	Cookie	Bypass Condition	Cache Used?	Action
1	Cache-Control: no-cache	nocache=0	Cache-Control triggers bypass	No	Fetch fresh content from backend
2	Cache-Control: max-age=3600	nocache=1	Cookie triggers bypass	No	Fetch fresh content from backend
3	Cache-Control: max-age=3600	nocache=0	No bypass condition met	Yes	Serve content from cache
4	No Cache-Control header	nocache=0	No bypass condition met	Yes	Serve content from cache
5	No Cache-Control header	nocache=1	Cookie triggers bypass	No	Fetch fresh content from backend

💡 Execution ends after deciding to serve from cache or fetch fresh content based on bypass conditions.

Status Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5
$http_cache_control	undefined	no-cache	max-age=3600	max-age=3600	undefined	undefined
$cookie_nocache	undefined	0	1	0	0	1
Bypass?	false	true	true	false	false	true
Cache Used?	false	false	false	true	true	false

Key Moments - 3 Insights

Why does the cache get bypassed when Cache-Control header is 'no-cache'?

Because the proxy_cache_bypass variable checks $http_cache_control header. When it contains 'no-cache', the condition is true (see execution_table step 1), so cache is bypassed.

If the cookie 'nocache' is set to 1, why does cache get bypassed even if Cache-Control header allows caching?

The proxy_no_cache directive checks the cookie. If $cookie_nocache equals 1 (step 2 and 5), it triggers bypass regardless of Cache-Control header.

What happens if neither Cache-Control header nor cookie triggers bypass?

Cache is used to serve the response (steps 3 and 4). This is the normal fast path.

Visual Quiz - 3 Questions

Look at the execution table, at which step is the cache used despite a Cache-Control header being present?

A Step 2

B Step 3

C Step 1

D Step 5

💡 Hint

Check the 'Cache Used?' column for steps with Cache-Control header.

According to the variable tracker, what is the value of $cookie_nocache at step 5?

A 1

B 0

C undefined

D no-cache

💡 Hint

Look at the $cookie_nocache row under 'After Step 5'.

If the cookie 'nocache' is removed, which steps in the execution table would change their 'Bypass Condition' to 'No bypass condition met'?

A Steps 1 and 3

B Steps 4 and 5

C Steps 2 and 5

D Steps 1 and 2

💡 Hint

Check which steps have cookie triggering bypass.

Concept Snapshot

nginx cache bypass conditions:
- Use proxy_cache_bypass and proxy_no_cache to define when to skip cache
- Common triggers: HTTP headers (e.g., Cache-Control) and cookies
- If bypass condition true, request goes to backend
- Otherwise, cached content is served
- Helps serve fresh content when needed without disabling cache globally

Full Transcript

When nginx receives a request, it checks cache bypass conditions such as specific HTTP headers or cookies. If any condition matches, nginx skips the cache and fetches fresh content from the backend server. Otherwise, it serves the cached content for faster response. For example, if the client sends a Cache-Control header with 'no-cache' or a cookie named 'nocache' with value 1, nginx bypasses the cache. This selective bypass allows fresh content delivery without disabling caching for all requests. The execution table shows different request scenarios and whether cache is used or bypassed. The variable tracker follows key variables like $http_cache_control and $cookie_nocache through each step. Understanding these conditions helps configure nginx caching effectively.

Practice

1. What is the main purpose of cache bypass conditions in nginx?

easy

A. To increase the cache size automatically

B. To compress cached content before serving

C. To delete cached files periodically

D. To tell nginx when to skip serving cached content

Solution

1. Step 1: Understand cache bypass meaning

   Cache bypass conditions define when nginx should not use cached content.

2. Step 2: Identify the main purpose

   The main goal is to skip cached content under certain conditions, like logged-in users.

3. Final Answer:

   To tell nginx when to skip serving cached content -> Option D

4. Quick Check:

   Cache bypass = skip cache [OK]

Hint: Cache bypass means skipping cache, not managing size or deletion [OK]

Common Mistakes:

• Confusing bypass with cache size management
• Thinking bypass deletes cache
• Assuming bypass compresses content

2. Which of the following is the correct syntax to bypass cache in nginx when a cookie named skip_cache is set?

easy

A. set $skip_cache 1 if ($cookie_skip_cache);

B. set $skip_cache 1 if ($cookie_skip_cache = 1);

C. set $skip_cache 1 if ($cookie_skip_cache != '');

D. set $skip_cache 1 if ($cookie_skip_cache == 'true');

Solution

1. Step 1: Understand cookie variable usage

   In nginx, $cookie_name holds the cookie value or empty if not set.

2. Step 2: Check correct condition to detect cookie presence

   Checking if $cookie_skip_cache is not empty string means cookie is set.

3. Final Answer:

   set $skip_cache 1 if ($cookie_skip_cache != ''); -> Option C

4. Quick Check:

   Check cookie not empty = bypass cache [OK]

Hint: Use != '' to check if cookie exists, not equality to 1 or 'true' [OK]

Common Mistakes:

• Using = instead of != for condition
• Comparing cookie to 1 or 'true' incorrectly
• Missing quotes around empty string

3. Given this nginx config snippet:

set $skip_cache 0;
if ($request_method = POST) {
  set $skip_cache 1;
}
if ($arg_nocache = 1) {
  set $skip_cache 1;
}

proxy_cache_bypass $skip_cache;

What happens when a POST request with ?nocache=1 is sent?

medium

A. Cache is used because $skip_cache remains 0

B. Cache is bypassed because $skip_cache is set to 1

C. Cache is bypassed only if request method is GET

D. Configuration causes syntax error and no caching

Solution

1. Step 1: Analyze conditions setting $skip_cache

   Both if blocks set $skip_cache to 1 if request method is POST or arg_nocache=1.

2. Step 2: Evaluate given request

   Request is POST and has nocache=1, so both conditions set $skip_cache=1.

3. Final Answer:

   Cache is bypassed because $skip_cache is set to 1 -> Option B

4. Quick Check:

   POST or nocache=1 sets skip_cache=1 [OK]

Hint: If any bypass condition matches, $skip_cache becomes 1 [OK]

Common Mistakes:

• Assuming POST requests use cache
• Ignoring query parameter condition
• Thinking config syntax is invalid

4. You wrote this nginx config to bypass cache for logged-in users:

set $skip_cache 0;
if ($http_cookie ~* "user_logged_in=1") {
  set $skip_cache 1;
}
proxy_cache_bypass $skip_cache;

But cache is still used for logged-in users. What is the likely error?

medium

A. The if condition does not reliably support regex matching

B. The variable $skip_cache is not initialized before if

C. The regex in if condition is incorrect syntax

D. The proxy_cache_bypass directive is missing a semicolon

Solution

1. Step 1: Understand nginx if limitations

   nginx if does not reliably support regex matching with ~ or ~* operators for cache bypass.

2. Step 2: Identify common pitfall with if in nginx

   nginx if inside server/location blocks can be tricky; better to use map for cache bypass.

3. Step 3: Recognize that if with regex may not work as expected for cache bypass

   Using if with regex in this way often fails for cache bypass.

4. Final Answer:

   The if condition does not reliably support regex matching -> Option A

5. Quick Check:

   nginx if regex often unreliable for cache bypass [OK]

Hint: Use map directive instead of if for reliable cache bypass [OK]

Common Mistakes:

• Assuming if regex always works for cache bypass
• Forgetting to initialize variables
• Missing semicolons causing errors

5. You want to bypass cache only if the request method is POST or the URL contains nocache=1, but not for logged-in users with cookie user_logged_in=1. Which nginx config snippet correctly implements this?

hard

A. set $skip_cache 0;
if ($request_method = POST) {
set $skip_cache 1;
}
if ($arg_nocache = 1) {
set $skip_cache 1;
}
if ($http_cookie ~* "user_logged_in=1") {
set $skip_cache 0;
}
proxy_cache_bypass $skip_cache;

B. map $http_cookie $skip_cache {
default 1;
~user_logged_in=1 0;
}
if ($request_method = POST) {
set $skip_cache 1;
}
if ($arg_nocache = 1) {
set $skip_cache 1;
}
proxy_cache_bypass $skip_cache;

C. map $http_cookie $skip_cache {
default 0;
~user_logged_in=1 1;
}
if ($request_method = POST) {
set $skip_cache 1;
}
if ($arg_nocache = 1) {
set $skip_cache 1;
}
proxy_cache_bypass $skip_cache;

D. map $http_cookie $skip_cache {
default 0;
~user_logged_in=1 0;
}
if ($request_method = POST) {
set $skip_cache 1;
}
if ($arg_nocache = 1) {
set $skip_cache 1;
}
proxy_cache_bypass $skip_cache;

Solution

1. Step 1: Understand the requirement

   Bypass cache if POST or nocache=1, but do NOT bypass if user_logged_in=1 cookie is present.

2. Step 2: Analyze each option

   Options A and B use map but do not reset skip_cache correctly for logged-in users. map $http_cookie $skip_cache { default 0; ~user_logged_in=1 1; } if ($request_method = POST) { set $skip_cache 1; } if ($arg_nocache = 1) { set $skip_cache 1; } proxy_cache_bypass $skip_cache; sets skip_cache=1 for logged-in users, which is opposite. set $skip_cache 0; if ($request_method = POST) { set $skip_cache 1; } if ($arg_nocache = 1) { set $skip_cache 1; } if ($http_cookie ~* "user_logged_in=1") { set $skip_cache 0; } proxy_cache_bypass $skip_cache; sets skip_cache=1 for POST or nocache=1, then resets to 0 if user_logged_in=1 cookie exists, correctly preventing bypass.

3. Final Answer:

   set $skip_cache 0; if ($request_method = POST) { set $skip_cache 1; } if ($arg_nocache = 1) { set $skip_cache 1; } if ($http_cookie ~* "user_logged_in=1") { set $skip_cache 0; } proxy_cache_bypass $skip_cache; -> Option A

4. Quick Check:

   Set bypass then reset for logged-in users [OK]

Hint: Set bypass first, then reset skip_cache to 0 for logged-in users [OK]

Common Mistakes:

• Setting skip_cache=1 for logged-in users by mistake
• Using map incorrectly without reset logic
• Not resetting skip_cache after conditions