LOG IN SIGN UP
Documentation

Manipulating the cache key

Redefining the cache key

Explicitly setting the cache key

You can set the cache key explicitly (including attaching conditions) by adding a request setting via the Settings tab on the Configure page of your service and including a comma-separated list of cache keys. The values of the cache keys listed are combined to make a single hash, and each unique hash is considered a unique object.

For example, if you don't want the query string to be part of the cache key, but you don't want to change req.url so that the query string still ends up in your logs, you could use the following text for the hash keys:

regsub(req.url, "\?.*$", ""), req.http.host

In the user interface, the text would appear in the Cache keys field:

the advanced options of a new request setting page showing the contents of the cache keys field

As a general rule, you should always have req.url as one of your cache keys or as part of one. The example above includes req.url inside the regsub() therefore passing this requirement.

Purging adjustments when making additions to cache keys

Because purging works on individual hashes, additions to cache keys can complicate purging URLs. However, it can also be simplified.

For example, if you were to change your cache key to just req.url and not the default req.url, req.http.host, then purging http://foo.example.com/file.html would also purge http://bar.example.com/file.html. Keep in mind this is because they're actually the same object in the cache!

On the other hand, if you were to change your cache key req.url, req.http.host, req.http.Fastly-SSL, you would have to purge http://example.com/ and https://example.com/ individually.

In the latter case, if you were to use the Vary header instead of changing the cache key, you could still have different content on the two URLs, yet purge them with a single purge. In this case you would add a new Cache Header, use http.Vary as the Destination, and use the following as the Source:

if(beresp.http.Vary, beresp.http.Vary ",", "") "Fastly-SSL"

Using a POST request body as a cache key

As long as the body of a POST request is less than 2K in size and the content type is application/x-www-form-urlencoded, then we allow you to use it as part of the cache key. Your VCL should look something like:

sub vcl_hash {
  set req.hash += req.url;
  set req.hash += req.http.host;
  if (req.request == "POST" && req.postbody) {
    set req.hash += req.postbody;
  }
  return(hash);
}

You'll also need to force a cache lookup, but only for requests that can be cached, by doing something like this in vcl_recv:

  if (req.request == "POST" && req.postbody ~ "(^|&)action=list(&|$)") {
    return(lookup);
  }

You can use a cookie as a cache key or just check for the presence of a cookie set to a specific value by controlling its request conditions. Both methods are simple and shown in the steps below.

Using a cookie as a cache key looks complicated but it's actually quite simple. Let's say your cookie is called "MyCookie" and it looks like mycookie=

Create new headers

  1. Log in to the Fastly web interface and click the Configure link.
  2. From the service menu, select the appropriate service.
  3. Click the Edit configuration button and then select Clone active. The service version page appears.
  4. Click the Content tab. The Content page appears.

    the Content tab on the Configuration page

  5. Click the Create header button. The Create a new header page appears.

    the create new header page

  6. Fill out the Create a new header fields as follows:

    • From the Type menu, select Request, and from the Action menu select Set.
    • In the Destination field, type http.X-MyCookie.
    • In the Source field, type "0" (with quotes).
    • Leave the Ignore if set menu set to the default, No.
    • In the Priority field, type a number representing the order in which the header rule should execute. The default is set to 10 for new headers.
    • In the Description field, type Set MyCookie Header Default.
  7. Click the Create button. The new header appears in the Headers area of the Content tab.

  8. Click the Create header button again and create a second new header by filling out the fields as follows:

    • From the Type menu, select Request, and from the Action menu select Set.
    • In the Destination field, type http.X-MyCookie.
    • In the Source field, type regsub(req.http.cookie, ".*mycookie =([^;]+);.*", "\1").
    • Leave the Ignore if set menu set to the default, No.
    • In the Priority field, type a larger number than the priority of previous header you just created. For example, if you left the default priority set to 10, type 20.
    • In the Description field, type Set MyCookie Header from Cookie.
  9. Click the Create button. The second header appears in the Headers area of the Content tab.

    example set myCookie headers in the headers area

Attach conditions to the new headers

  1. Click the Attach a condition link next to the Set MyCookie Header from Cookie header. The add a condition window appears.
  2. Click the Create a new request condition button. The Create a new request condition window appears.

    the create a new request condition window

  3. Fill out the fields of the Create a new request condition window as follows:

    • Leave the Type menu set to Request.
    • In the Name field, type Has MyCookie cookie.
    • In the Apply if field, type req.http.cookie ~ "mycookie=".
  4. Click the Save and apply to button. The Headers area now displays the condition that must be met in order for your header to begin being used.

    example mycookie headers with conditions

  5. Click the Settings tab. The Settings page appears.

  6. Click the Create request setting button. The Create a new request setting page appears.

  7. Fill out the Create a new request setting fields as follows:

    • In the Description field type Set Hash from Cookie.
    • In the Cache keys field, type req.url, req.http.host, req.http.X-MyCookie
  8. Click the Create button. The new request appears in the Request settings area.

  9. Click the Attach a condition link next to the new request. The Add a condition window appears.

    add a condition to the set hash from cookie request

  10. From the Select a condition menu, select Has MyCookie cookie. The Request settings area now displays the condition that must be met in order for your request to begin being used.

    example has mycookie cookie request with condition

  11. Click the Activate button to deploy your configuration changes.

An alternative way if you're just checking for the presence of the cookie set to some specific value (e.g., 1):

  1. Add a new Request setting where the Cache key field is set to req.url, req.http.host, "Has mycookie".
  2. Add a condition to that Request setting where the Apply if field contains req.http.cookie ~ ".*mycookie =1;.*".

Back to Top