.. _whatsnew_upgrading: %%%%%%%%%%%%%%%%%%%%%% Upgrading to Varnish 4 %%%%%%%%%%%%%%%%%%%%%% Changes to VCL ============== The backend fetch parts of VCL have changed in Varnish 4. We've tried to compile a list of changes needed to upgrade here. Version statement ~~~~~~~~~~~~~~~~~ To make sure that people have upgraded their VCL to the current version, Varnish now requires the first line of VCL to indicate the VCL version number:: vcl 4.0; req.request is now req.method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To align better with RFC naming, `req.request` has been renamed to `req.method`. vcl_fetch is now vcl_backend_response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Directors have been moved to the vmod_directors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To make directors (backend selection logic) easier to extend, the directors are now defined in loadable VMODs. Setting a backend for future fetches in `vcl_recv` is now done as follows:: sub vcl_init { new cluster1 = directors.round_robin(); cluster1.add_backend(b1, 1.0); cluster1.add_backend(b2, 1.0); } sub vcl_recv { set req.backend_hint = cluster1.backend(); } Note the extra `.backend()` needed after the director name. Use the hash director as a client director ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Since the client director was already a special case of the hash director, it has been removed, and you should use the hash director directly:: sub vcl_init { new h = directors.hash(); h.add_backend(b1, 1); h.add_backend(b2, 1); } sub vcl_recv { set req.backend_hint = h.backend(client.identity); } vcl_error is now vcl_backend_error ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To make a distinction between internally generated errors and VCL synthetic responses, `vcl_backend_error` will be called when varnish encounters an error when trying to fetch an object. error() is now synth() ~~~~~~~~~~~~~~~~~~~~~~ And you must explicitly return it:: return (synth(999, "Response")); Synthetic responses in vcl_synth ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Setting headers on synthetic response bodies made in vcl_synth are now done on resp.http instead of obj.http. The synthetic keyword is now a function:: if (resp.status == 799) { set resp.status = 200; set resp.http.Content-Type = "text/plain; charset=utf-8"; synthetic("You are " + client.ip); return (deliver); } obj in vcl_error replaced by beresp in vcl_backend_error ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To better represent a the context in which it is called, you should now use `beresp.*` vcl_backend_error, where you used to use `obj.*` in `vcl_error`. hit_for_pass objects are created using beresp.uncacheable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Example:: sub vcl_backend_response { if (beresp.http.X-No-Cache) { set beresp.uncacheable = true; set beresp.ttl = 120s; return (deliver); } } req.* not available in vcl_backend_response ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ req.* used to be available in `vcl_fetch`, but after the split of functionality, you only have 'bereq.*' in `vcl_backend_response`. vcl_* reserved ~~~~~~~~~~~~~~ Any custom-made subs cannot be named 'vcl_*' anymore. This namespace is reserved for builtin subs. req.backend.healthy replaced by std.healthy(req.backend_hint) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Remember to import the std module if you're not doing so already. client.port, and server.port replaced by respectively std.port(client.ip) and std.port(server.ip) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ `client.ip` and `server.ip` are now proper datatypes, which renders as an IP address by default. You need to use the `std.port()` function to get the port number. obj is now read-only ~~~~~~~~~~~~~~~~~~~~ `obj` is now read-only. `obj.hits`, if enabled in VCL, now counts per objecthead, not per object. `obj.last_use` has been retired. Note that obj.hits may not be reset in some cases where bans are in use. See bug 1492_ for details. .. _1492: https://www.varnish-cache.org/trac/ticket/1492 Some return values have been replaced ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Apart from the new `synth` return value described above, the following has changed: - `vcl_recv` must now return `hash` instead of `lookup` - `vcl_hash` must now return `lookup` instead of `hash` - `vcl_pass` must now return `fetch` instead of `pass` default/builtin VCL changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~ The VCL code that is appended to user-configured VCL automatically is now called the builtin VCL. (previously default.vcl) The builtin VCL now honors Cache-Control: no-cache (and friends) to indicate uncacheable content from the backend. The `remove` keyword is gone ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Replaced by `unset`. Changes to existing parameters ============================== session_linger ~~~~~~~~~~~~~~ `session_linger` has been renamed to `timeout_linger`. sess_timeout ~~~~~~~~~~~~ `sess_timeout` has been renamed to `timeout_idle`. sess_workspace ~~~~~~~~~~~~~~ In 3.0 it was often necessary to increase `sess_workspace` if a lot of VMODs, complex header operations or ESI were in use. This is no longer necessary, because ESI scratch space happens elsewhere in 4.0. If you are using a lot of VMODs, you may need to increase either `workspace_backend` and `workspace_client` based on where your VMOD is doing its work. New parameters since 3.0 ======================== vcc_allow_inline_c ~~~~~~~~~~~~~~~~~~ You can now completely disable inline C in your VCL, and it is disabled by default. Other changes ============= New log filtering ~~~~~~~~~~~~~~~~~ The logging framework has a new filtering language, which means that the -m switch has been replaced with a new -q switch. See :ref:`ref-vsl-query` for more information about the new query language.