.. Copyright (c) 2016 Varnish Software AS SPDX-License-Identifier: BSD-2-Clause See LICENSE file for full text of license .. _whatsnew_upgrading_4_0: %%%%%%%%%%%%%%%%%%%%%%%% Upgrading to Varnish 4.0 %%%%%%%%%%%%%%%%%%%%%%%% 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 data types, which renders as an IP address by default. You need to use the `std.port()` function to get the port number. Invalidation with purge ~~~~~~~~~~~~~~~~~~~~~~~ Cache invalidation with purges is now done via `return(purge)` from `vcl_recv`. The `purge;` keyword has been retired. obj is now read-only ~~~~~~~~~~~~~~~~~~~~ `obj` is now read-only. `obj.last_use` has been retired. 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` Backend restarts are now retry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In 3.0 it was possible to do `return(restart)` after noticing that the backend response was wrong, to change to a different backend. This is now called `return(retry)`, and jumps back up to `vcl_backend_fetch`. This only influences the backend fetch thread, client-side handling is not affected. 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`. X-Forwarded-For is now set before vcl_recv ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In many cases, people unintentionally removed X-Forwarded-For when implementing their own vcl_recv. Therefore it has been moved to before vcl_recv, so if you don't want an IP added to it, you should remove it in vcl_recv. Changes to existing parameters ============================== session_linger ~~~~~~~~~~~~~~ `session_linger` has been renamed to `timeout_linger` and it is in seconds now (previously was milliseconds). 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. thread_pool_purge_delay ~~~~~~~~~~~~~~~~~~~~~~~ `thread_pool_purge_delay` has been renamed to `thread_pool_destroy_delay` and it is in seconds now (previously was milliseconds). thread_pool_add_delay and thread_pool_fail_delay ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ They are in seconds now (previously were milliseconds). 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:`vsl-query(7)` for more information about the new query language.