Proxy cache key in Nginx - Commands & Configuration

Introduction

When using a proxy server to speed up web content delivery, it saves copies of responses in a cache. The proxy cache key decides how the server identifies each unique cached item. This helps avoid sending the same request to the backend repeatedly.

When you want to speed up your website by caching responses from a backend server.

When you want to reduce load on your backend by serving repeated requests from cache.

When you want to customize which parts of a request determine the cached content, like ignoring cookies or query strings.

When you want to cache different versions of a page based on user language or device type.

When you want to troubleshoot or optimize cache hits by controlling the cache key.

Config File - nginx.conf

nginx.conf

http {
    proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=1g inactive=60m use_temp_path=off;

    server {
        listen 80;

        location / {
            proxy_cache my_cache;
            proxy_cache_key "$scheme://$host$request_uri";
            proxy_pass http://backend_server;
        }
    }
}

proxy_cache_path defines where and how cache is stored.

proxy_cache enables caching for the location.

proxy_cache_key sets the unique key for each cached response, here combining scheme, host, and full request URI.

This setup caches responses separately for http/https, different hosts, and request URIs.

Commands

Check the nginx configuration file for syntax errors before reloading.

Terminal

sudo 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 configuration without downtime.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request to the nginx server to check response headers and confirm caching behavior.

Terminal

curl -I http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Tue, 27 Jun 2024 12:00:00 GMT

Content-Type: text/html

Content-Length: 612

Last-Modified: Tue, 27 Jun 2024 11:50:00 GMT

Connection: keep-alive

X-Cache-Status: MISS

Send the same request again to verify the response is served from cache this time.

Terminal

curl -I http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Tue, 27 Jun 2024 12:00:05 GMT

Content-Type: text/html

Content-Length: 612

Last-Modified: Tue, 27 Jun 2024 11:50:00 GMT

Connection: keep-alive

X-Cache-Status: HIT

Key Concept

If you remember nothing else from this pattern, remember: the proxy cache key defines how nginx identifies unique cached responses, so it controls cache hits and misses.

Common Mistakes

Not setting proxy_cache_key explicitly and relying on default.

The default key may include unwanted parts like cookies, causing cache misses or storing too many copies.

Define proxy_cache_key to include only the parts of the request that should differentiate cached content.

Including variables that change every request, like $request_time, in proxy_cache_key.

This causes every request to be treated as unique, preventing caching.

Use stable variables like $scheme, $host, and $request_uri for the cache key.

Not testing nginx configuration with nginx -t before reload.

Syntax errors can cause nginx to fail to reload, leading to downtime.

Always run sudo nginx -t to verify config before reloading.

Summary

Define proxy_cache_key in nginx.conf to control how cached responses are identified.

Test nginx configuration syntax with nginx -t before reloading to avoid errors.

Reload nginx to apply changes and verify caching behavior with repeated curl requests.

Practice

1. What is the main purpose of the proxy_cache_key directive in nginx?

easy

A. To define how nginx identifies and stores cached content

B. To set the maximum size of the cache

C. To specify the cache expiration time

D. To enable SSL for proxy connections

Solution

1. Step 1: Understand the role of proxy_cache_key

   The proxy_cache_key tells nginx how to uniquely identify cached content by combining variables like scheme, host, and URI.

2. Step 2: Differentiate from other cache settings

   Other directives control cache size or expiration, but proxy_cache_key specifically defines the cache lookup key.

3. Final Answer:

   To define how nginx identifies and stores cached content -> Option A

4. Quick Check:

   proxy_cache_key = cache identifier [OK]

Hint: proxy_cache_key sets cache identity, not size or time [OK]

Common Mistakes:

• Confusing cache key with cache size or expiration
• Thinking it enables SSL
• Assuming it controls cache storage location

2. Which of the following is the correct syntax to set a proxy cache key using scheme, host, and request URI in nginx?

easy

A. proxy_cache_key $scheme$host$request_uri;

B. proxy_cache_key $scheme://$host$request_uri;

C. proxy_cache_key $scheme://host$request_uri;

D. proxy_cache_key "$scheme://$host$request_uri";

Solution

1. Step 1: Check syntax for proxy_cache_key

   The value must be a string, so it should be enclosed in double quotes if it contains special characters like ://.

2. Step 2: Verify variable usage

   Variables like $scheme, $host, and $request_uri must be concatenated properly inside quotes.

3. Final Answer:

   proxy_cache_key "$scheme://$host$request_uri"; -> Option D

4. Quick Check:

   Quotes needed for complex keys = proxy_cache_key "$scheme://$host$request_uri"; [OK]

Hint: Use quotes when combining variables with symbols like :// [OK]

Common Mistakes:

• Omitting quotes around the key string
• Missing $ before variables
• Incorrect concatenation without quotes

3. Given this nginx config snippet:

proxy_cache_key "$scheme://$host$request_uri";

What will be the cache key for a request to https://example.com/path/page?query=1?

medium

A. example.com/path/page?query=1

B. https://example.com/path/page?query=1

C. https://example.com/path/page

D. http://example.com/path/page?query=1

Solution

1. Step 1: Substitute variables with request values

   $scheme is 'https', $host is 'example.com', and $request_uri includes path and query: '/path/page?query=1'.

2. Step 2: Combine variables as per the key format

   Joining them gives 'https://example.com/path/page?query=1'.

3. Final Answer:

   https://example.com/path/page?query=1 -> Option B

4. Quick Check:

   Variables combined exactly = https://example.com/path/page?query=1 [OK]

Hint: Remember $request_uri includes query string [OK]

Common Mistakes:

• Ignoring the query string in $request_uri
• Using http instead of https for scheme
• Leaving out the scheme or host

4. You set proxy_cache_key "$scheme://$host$uri"; but nginx caches different query strings as the same content. What is the likely cause?

medium

A. You did not enable proxy_cache_path

B. You used $request_uri which already includes query string

C. You forgot to include $args in the cache key

D. You used double quotes instead of single quotes

Solution

1. Step 1: Understand $uri vs $request_uri

   $uri contains only the path (normalized), excluding the query string. $request_uri includes the query.

2. Step 2: Analyze the symptom

   Different query strings yield the same $uri, hence same cache key, causing shared cache content.

3. Final Answer:

   You forgot to include $args in the cache key -> Option C

4. Quick Check:

   $uri excludes query; add $args [OK]

Hint: $uri lacks query string; add $args [OK]

Common Mistakes:

• Confusing cache key with cache size or expiration
• Thinking it enables SSL
• Assuming it controls cache storage location

5. You want to cache content separately for mobile and desktop users. Which proxy cache key configuration achieves this if user agent contains 'Mobile' for mobile devices?

hard

A. proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map

B. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent ~* Mobile";

C. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent";

D. proxy_cache_key "$scheme://$host$request_uri";

Solution

1. Step 1: Understand the need for conditional cache key

   We want to separate cache for mobile and desktop, so the key must include a variable indicating device type.

2. Step 2: Use a map to set $is_mobile variable

   nginx can use map to set $is_mobile to 'mobile' or 'desktop' based on $http_user_agent matching 'Mobile'. Including $is_mobile in cache key separates caches.

3. Step 3: Evaluate options

   proxy_cache_key "$scheme://$host$request_uri:$http_user_agent"; uses full user agent, which is too specific and causes cache fragmentation. proxy_cache_key "$scheme://$host$request_uri:$http_user_agent ~* Mobile"; is invalid syntax. proxy_cache_key "$scheme://$host$request_uri"; ignores device type. proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map correctly uses $is_mobile set by map.

4. Final Answer:

   proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map -> Option A

5. Quick Check:

   Use map variable for device type in cache key = proxy_cache_key "$scheme://$host$request_uri:$is_mobile"; # where $is_mobile is set by map [OK]

Hint: Use map to create $is_mobile variable for cache key [OK]

Common Mistakes:

• Using full user agent causing too many cache entries
• Trying regex inside proxy_cache_key (invalid)
• Ignoring device type in cache key