FastCGI Cache

The documentation for the FastCGI cache directives is not complete, but the directives are basically the same as the proxy directives. Here is summary of how to configure it.

fastcgi_cache_path      /var/cache/nginx levels=1:2 keys_zone=zone_one:10m inactive=5m max_size=500m;

server {
        listen   80;
        server_name www.example.com;
        root   /var/www;
        location / {
                index  index.html index.htm;
        }
        location ~ /bin/.*\.php {
                gzip off;
                fastcgi_pass   unix:/var/run/nginx/foswiki.sock;
                include fastcgi_params;
                fastcgi_cache  zone_one;
                fastcgi_cache_key      $request_uri;
                fastcgi_cache_valid    any     1h;
                fastcgi_pass_header     Set-Cookie;
        }
}

Let's go over the directives:

• fastcgi_cache_path: set up a cache store. The directives has the following options:
  • levels=n:k:... To avoid excessive number of files in a directory, nginx creates subdirectories on each level naming them by taking the first n letters from the hash for the first level, k next letters for the second and so on.
  • keys_zone=name:size The zone name, size is the size the of the keys index
  • inactive How long to save inactive files
  • max_size Maximum size of the cache store
• fastcgi_cache Use cache zone defined earlier for caching
• fastcgi_cache_key set the cache index key. This needs serious consideration, especially if the cache store is used in more then one place. Be sure to include $cookie_NAME in the key if you want to avoid giving everyone the same page regardless of cookies.
• fastcgi_cache_valid=resp_code time Cache is valid for response codes resp_code, saved for time. This allows you to define different expiry times for 404, 302, 301 responses and so on.
• fastcgi_pass_header Not really a cache directive, but very important for caching nonetheless. By default, Nginx will not pass Set-Cookie header to the client if the request is cachable. Usually that means that client will never reach the cookie-personalized version of the site. If you use this, be sure to verify that your application is issuing Cache-Control headers correctly, otherwise you might end up assigning the same cookie to everyone.

It's usually a good idea to verify that logins and cookie assignment work as expected after configuring caching. The most common mistake with caching is a greedy cache catching too much and disabling logins and dynamic content.

Dealing with session cookies

By default, if cache is active Nginx will suppress cookie headers in the response. fastcgi_pass_header Set-Cookie; will make Nginx pass the header, but it will still cache the response. There are three possible schemes for caching a site that uses cookies:

1. caching everything with index key that includes the cookie thus caching different response for each cookie.
2. caching content with the index key excluding the cookie thus caching one copy of a uri for all of the cookies - this will show the same response regardless of the cookie
3. disabling the cache when a cookie is used.

Realistically, a combination of these schemes is often used - E.G. caching the front page regardless of cookies, caching user specific banners and bars with cookie depended key index, avoiding cache for dynamic content.

Unfortunately, Nginx doesn't have an easy way of alternating between the schemes. The cache directives are not valid inside an if directive, and caching directives do not supply a way to disable the cache, so we are forced to use complex rewrites or try_files with internal locations. The fastcgi_no_cache directive now allows cache disablement based on the presence of a cookie or header.

• fastcgi_no_cache $somevar will prevent the document from being saved to cache if $somevar expands to a non-zero value
• fastcgi_cache_bypass $somever will bypass the cache (won't load from the cache) even if the documents was previously cached

The fastcgi_cache_min_uses can help reduce the amount of rarely used pages in the cache.

-- AvishaiIshShalom - 05 Apr 2010