Upgrading from Varnish 2.1 to 3.0

This is a compilation of items you need to pay attention to when upgrading from Varnish 2.1 to 3.0

Changes to VCL

In most cases you need to update your VCL since there has been some changes to the syntax.

string concatenation operator

String concatenation did not have an operator previously, but this has now been changed to +.

no more %-escapes in strings

To simplify strings, the %-encoding has been removed. If you need non-printable characters, you need to use inline C.

log moved to the std vmod

log has moved to the std vmod:

log "log something";

becomes:

import std;
std.log("log something");

You only need to import std once.

purges are now called bans

purge() and purge_url() are now respectively ban() and ban_url(), so you should replace all occurences:

purge("req.url = " req.url);

becomes:

ban("req.url = " + req.url);

purge does not take any arguments anymore, but can be used in vcl_hit or vcl_miss to purge the item from the cache, where you would reduce ttl to 0 in Varnish 2.1:

sub vcl_hit {
  if (req.request == "PURGE") {
    set obj.ttl = 0s;
    error 200 "Purged.";
  }
}

becomes:

sub vcl_hit {
  if (req.request == "PURGE") {
    purge;
    error 200 "Purged.";
  }
}

beresp.cacheable and obj.cacheable are gone

beresp.cacheable is gone, and can be replaced with beresp.ttl > 0s. Similarly obj.cacheable can be replaced with obj.ttl > 0s.

returns are now done with the return() function

pass, pipe, lookup, deliver, fetch, hash, pipe and restart are no longer keywords, but arguments to return(), so:

sub vcl_pass {
  pass;
}

becomes:

sub vcl_pass {
  return(pass);
}

req.hash is replaced with hash_data()

You no longer append to the hash with +=, so:

set req.hash += req.url;

becomes:

hash_data(req.url);

esi is replaced with beresp.do_esi

You no longer enable ESI with esi, so:

esi;

in vcl_fetch becomes:

set beresp.do_esi = true;

pass in vcl_fetch renamed to hit_for_pass

The difference in behaviour of pass in vcl_recv and vcl_fetch confused people, so to make it clearer that they are different, you must now do return(hit_for_pass) when doing a pass in vcl_fetch.

Changes to runtime parameters

Deleted parameters

cache_vbe_conns and err_ttl has been removed.

New parameters

The following parameters have been added, see man varnishd for reference:

• default_keep
• expiry_sleep
• fetch_maxchunksize
• gzip_level
• gzip_memlevel
• gzip_stack_buffer
• gzip_tmp_space
• gzip_window
• http_gzip_support
• http_req_hdr_len
• http_req_size
• http_resp_hdr_len
• http_resp_size
• shortlived
• thread_pool_workspace
• vcc_err_unref
• vcl_dir
• vmod_dir

Changed default values

The following parameters have new defaults:

• ban_lurker_sleep changed from 0 to 0.01 seconds, enabling the ban lurker by default.
• connect_timeout changed from 0.4 to 0.7 seconds.
• log_hashstring changed from off to on.
• send_timeout changed from 600 to 60 seconds.
• thread_pool_add_delay changed from 20 to 2 ms.

Changed parameter names

The following parameters have new names:

• http_headers has been renamed to http_max_hdr.
• max_esi_includes has been renamed to max_esi_depth.
• overflow_max has been renamed to queue_max.
• purge_dups has been renamed to ban_dups.

Changes to behaviour

Varnish will return an error when headers are too large instead of just ignoring them. If the limits are too low, Varnish will return HTTP 413. You can change the limits by increasing http_req_hdr_len and http_req_size.

thread_pool_max is now per thread pool, while it was a total across all pools in 2.1. If you had this set in 2.1, you should adjust it for 3.0.