Cache bypass conditions in Nginx - Commands & Configuration

Introduction

Sometimes you want your web server to skip using cached content and get fresh data instead. Cache bypass conditions let you tell the server when to ignore the cache and fetch new content.

When you want to show updated content after a user logs in without waiting for cache expiration

When certain cookies indicate personalized content that should not be cached

When a specific URL parameter means the content must be fresh

When you want to bypass cache for POST requests that change data

When debugging and you want to see live changes without cache interference

Config File - nginx.conf

nginx.conf

http {
    proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m use_temp_path=off;

    server {
        listen 80;

        location / {
            proxy_cache my_cache;
            proxy_pass http://backend_server;

            # Bypass cache if cookie "nocache" is set
            proxy_cache_bypass $cookie_nocache;

            # Bypass cache if URL has ?nocache=1
            set $bypass 0;
            if ($arg_nocache = 1) {
                set $bypass 1;
            }

            # Bypass cache if $bypass is 1
            proxy_cache_bypass $bypass;

            # Bypass cache for POST requests
            proxy_cache_bypass $request_method;
            proxy_cache_methods GET HEAD;
        }
    }
}

This configuration sets up a cache named my_cache stored in /tmp/nginx_cache. Inside the server block, the proxy_cache_bypass directives tell Nginx when to skip the cache:

• If the cookie named nocache exists, cache is bypassed.
• If the URL has the query parameter nocache=1, cache is bypassed.
• Cache is bypassed for POST requests because they usually change data.

The proxy_cache_methods limits caching to GET and HEAD requests only.

Commands

Check the Nginx configuration file for syntax errors before reloading.

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

Reload Nginx to apply the new cache bypass configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a simple GET request to check if the response is served from cache or bypassed.

Terminal

curl -I http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

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

Content-Type: text/html

X-Cache-Status: MISS

Send a GET request with the nocache parameter to test cache bypass.

Terminal

curl -I http://localhost/?nocache=1

Expected Output

HTTP/1.1 200 OK

Server: nginx

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

Content-Type: text/html

X-Cache-Status: BYPASS

Send a POST request to verify that cache is bypassed for methods that change data.

Terminal

curl -I -X POST http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Thu, 01 Jun 2023 12:00:02 GMT

Content-Type: text/html

X-Cache-Status: BYPASS

Key Concept

If you remember nothing else from this pattern, remember: cache bypass conditions tell Nginx exactly when to skip cached content and fetch fresh data.

Common Mistakes

Not testing the configuration with 'nginx -t' before reloading

This can cause Nginx to fail reloading and disrupt your web service.

Always run 'nginx -t' to verify syntax before reloading Nginx.

Using 'proxy_cache_bypass' without setting proper variables for conditions

Nginx may not bypass cache as expected, serving stale content instead.

Use variables like $cookie_nocache or custom variables set by 'if' to control bypass precisely.

Caching POST requests by mistake

POST requests usually change data and should not be cached, or users see outdated results.

Limit caching to GET and HEAD methods using 'proxy_cache_methods' and bypass cache for POST.

Summary

Configure 'proxy_cache_bypass' with variables to control when cache is skipped.

Test Nginx configuration syntax with 'nginx -t' before reloading.

Use curl commands with different conditions to verify cache bypass works as expected.

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