This document contains notes from the Varnish developers about ongoing development and past versions:
Official information about changes in releases and advise on the upgrade process can be found in the doc/sphinx/whats-new/ directory, also available in HTML format at http://varnish-cache.org/docs/trunk/whats-new/index.html and via individual releases. These documents are updated as part of the release process.
The MAIN.sess_drop counter is gone.
New configure switch: --with-unwind. Alpine linux appears to offer a libexecinfo implementation that crashes when called by Varnish, this offers the alternative of using libunwind instead.
backend none was added for "no backend".
std.rollback(bereq) is now safe to use, fixed bug 3009
Fixed varnishstat, varnishtop, varnishhist and varnishadm handling INT, TERM and HUP signals (bugs 3088 and 3229)
The hash algorithm of the hash director was changed, so backend selection will change once only when upgrading. Users of the hash director are advised to consider using the shard director, which, amongst other advantages, offers more stable backend selection through consistent hashing.
Log records can safely have empty fields or fields containing blanks if they are delimited by "double quotes". This was applied to SessError and Backend_health.
It is now possible for VMOD authors to customize the connection pooling of a dynamic backend. A hash is now computed to determine uniqueness and a backend declaration can contribute arbitrary data to influence the pool.
The option varnishtest -W is gone, the same can be achieved with varnishtest -p debug=+witness. A witness.sh script is available in the source tree to generate a graphviz dot file and detect potential lock cycles from the test logs.
The Process timestamp for vcl_synth {} was wrongly issued before the VCL subroutine, now it gets emitted after VCL returns for consistency with vcl_deliver {}.
Latencies for newly created worker threads to start work on congested systems have been improved.
VRB_Iterate() signature has changed
VRT_fail() now also works from director code
Deliberately closing backend requests through return(abandon), return(fail) or return(error) is no longer accounted as a fetch failure
Fixed a bug which could cause probes not to run
The if-range header is now handled, allowing clients to conditionally request a range based on a date or an ETag.
Introduced struct reqtop to hold information on the ESI top request and PRIV_TOP, fixed regression 3019
Allow numerical expressions in VCL to be negative / negated
Add vi-stype CTRL-f / CTRL-b for page down/up to interactive varnishstat
Fixed wrong handling of an out-of-workspae condition in the proxy vmod and in the workspace allocator, bug 3131
Raised the minimum for the vcl_cooldown parameter to 1s to fix bug 3135
Improved creation of additional threads when none are available
Fixed a race between director creation and the backend.list CLI command - see bug 3094
Added error handling to avoid panics for workspace overflows during session attribute allocation - bug 3145
Overloaded the += operator to also append to headers
Fixed set *.body commands.
Fixed status for truncated CLI responses, bug 3038
New or improved Coccinelle semantic patches that may be useful for VMOD or utilities authors.
Output VCC warnings also for VCLs loaded via the varnishd -f option, see bug 3160
Improved fetch error handling when stale objects are present in cache, see bug 3089
Added a Notice VSL tag (used for varnishlog logging)
Always refer to sub as subroutine in the documentation and error messages to avoid confusion with other terms.
New pid command in the Varnish CLI, to get the master and optionally cache process PIDs, for example from varnishadm.
Fixed a race that could result in a partial response being served in its entirety when it is also compressed with gzip.
Fixed session close reason reporting and accounting, added rx_close_idle counter for separate accounting when timeout_idle is reached. Also, send_timeout is no longer reported as "remote closed".
Fixed handling of request bodies for backend retries
Fix deadlocks when the maximum number of threads has been reached, in particular with http/2, see 2418
Add more vcl control over timeouts with sess.timeout_linger, sess.send_timeout and sess.idle_send_timeout
Fix panics due to missing EINVAL handling on MacOS, see 1853
Added VSLs() and VSLbs() functions for logging STRANDS to VSL
Fixed cases where a workspace overflow would not result in a VCL failure, see 3194
Added WS_VSB_new() / WS_VSB_finish() for VSBs on workspaces
Imported vmod_cookie from varnish_modules
The previously deprecated function cookie.filter_except() has been removed during import. It was replaced by cookie.keep()
body_status and req_body_status have been collapsed into one type. In particular, the REQ_BODY_* enums now have been replaced with BS_*.
Fixed an old regression of the Age: header for passes, see bug 3221
Added VRT_AllocStrandsWS() as a utility function to allocate STRANDS on a workspace.
Reduced compile time of vcl_init{} / vcl_fini{} with gcc, added v_dont_optimize attribute macro
Fixed a case where send_timeout would have no effect when streaming from a backend fetch, see bug 3189
NOTE Users upgrading varnish should re-check send_timeout with respect to long pass and streaming fetches and watch out for increased session close rates.
Added VSB_tofile() to libvarnishapi, see 3238
In addition to a significant number of bug fixes, these are the most important changes in 6.3:
WS_Reserve() is now deprecated and any use should trigger a compiler warning. It is to be replaced by
WS_ReserveAll() to reserve all of the remaining workspace
It will always leave the workspace reserved even if 0 bytes are available, so it must always be followed by a call to WS_Release()
WS_ReserveSize() to reserve a fixed amount.
It will only leave the workspace reserved if the reservation request could be fulfilled.
We provide a script to help automate this change in the tools/coccinelle subdirectory of the source tree.
The RST references generated by vmodtool.py have been changed to match better the VCL syntax to avoid overhead where references are used. The new scheme for a vmod called name is:
To illustrate, the old references:
:ref:`vmod_name.function` :ref:`vmod_name.obj` :ref:`vmod_name.obj.method`
now are renamed to:
:ref:`name.function()` :ref:`name.obj()` :ref:`xobj.method()`
tools/vmod_ref_rename.sh is provided to automate this task
Extend JSON support in the CLI (2783)
Improve accuracy of statistics (VSC)
In Error: out of workspace log entries, the workspace name is now reported in lowercase
Adjust code generator python tools to python 3 and prefer python 3 over python 2 where available
Added a thread pool watchdog which will restart the worker process if scheduling tasks onto worker threads appears stuck. The new parameter thread_pool_watchdog configures it. (2418)
Changed ExpKill log tags to emit microsecond-precision timestamps instead of nanoseconds (2792)
Changed the default of the thread_pool_watchdog parameter to 60 seconds to match the cli_timeout default
VSB quoted output has been unified to three-digit octal, VSB_QUOTE_ESCHEX has been added to prefer hex over octal quoting
Retired long deprecated parameters (VIP16). Replacement mapping is: shm_reclen -> vsl_reclen vcl_dir -> vcl_path vmod_dir -> vmod_path
The width of the columns of the backend.list cli command output is now dynamic.
For best forward compatibility, we recommend that scripts parse JSON output as obtained using the -j option.
See release notes for details.
The format of the backend.list -j (JSON) cli command output has changed.
See release notes for details.
The undocumented -v option to the backend.list cli command has been removed
Changed the formatting of the vcl.list command from:
status state/temperature busy name [labelinfo]
to:
status state temperature busy name [<-|->] [info]
Column width is now dynamic.
Field values remain unchanged except for the label information, see varnish-cli(7) for details.
The ban facility has been extended by bans access to obj.ttl, obj.age, obj.grace and obj.keep and additional inequality operators.
Many cache lookup optimizations.
Display the VCL syntax during a panic.
Update to the VCL diagrams to include hit-for-miss.
libvarnish: VRT_VSA_GetPtr renamed to VSA_GetPtr
Included vtree.h in the distribution for vmods and renamed the red/black tree macros from VRB_* to VRBT_* to disambiguate from the acronym for Varnish Request Body.
Changed the internal organisation of dynamic PRIVs (PRIV_TASK, PRIV_TOP from a list to a red/black tree) for performance. (2813)
Vmod developers are advised that anything returned by a vmod function/method is assumed to be immutable. In other words, a vmod must not modify any data which was previously returned.
Tolerate null IP addresses for ACL matches.
Added vstrerror() as a safe wrapper for strerror() to avoid a NULL pointer dereference under rare conditions where the latter could return NULL. (2815)
Varnish-based tools using the VUT interface should now consider using the VUT_Usage() function for consistency
The name of the event_function callback for VCL events in vmods is now prefixed by $Prefix_` if $Prefix is defined in the .vcc file, or vmod_ by default.
So, for example, with $Event foo and no $Prefix, the event function will be called vmod_foo and with $Prefix bar it will be called bar_foo.
In the vmodtool-generated ReStructuredText documentation, anchors have been renamed
repsectively. In short, the anchor is now named equal to VCL syntax for constructors and functions and similarly to VCL syntax for methods.
VRT API has been updated to 9.0
HTTP_Copy() was removed, HTTP_Dup() and HTTP_Clone() were added
Previously, VCL_BLOB was implemented as struct vmod_priv, which had the following shortcomings:
The VCL_BLOB type is now implemented as struct vrt_blob, with the blob member replacing the former priv pointer and the free pointer removed.
A type member was added for lightweight type checking similar to the miniobject magic member, but in contrast to it, type should never be asserted upon.
VRT_blob() was updated accordingly.
req->req_bodybytes was removed. Replacement code snippet:
AZ(ObjGetU64(req->wrk, req->body_oc, OA_LEN, &u));
VRT_SetHealth() has been removed and VRT_SetChanged() added. VRT_LookupDirector() (only to be called from CLI contexts) as been added.
See release notes for details
vmodtool has been changed significantly to avoid various name clashes. Rather than using literal prefixes/suffixes, vmod authors should now (and might have to for making existing code continue to compile) use the following macros
VPFX(name) to prepend the vmod prefix (vmod_ by default)
VARGS(name) as the name of a function/method's argument struct, e.g.:
VCL_VOID vmod_test(VRT_CTX, struct VARGS(test) *args) { ...
VENUM(name) to access the enum by the name name
The counters
now break down the detailed reason for session accept failures, the sum of which continues to be counted in sess_fail.
Fixed implementation of the max_restarts limit: It used to be one less than the number of allowed restarts, it now is the number of return(restart) calls per request.
The cli_buffer parameter has been removed
Added back umem storage for Solaris descendants
The new storage backend type (stevedore) default now resolves to either umem (where available) or malloc.
Since varnish 4.1, the thread workspace as configured by workspace_thread was not used as documented, delivery also used the client workspace.
We are now taking delivery IO vectors from the thread workspace, so the parameter documentation is in sync with reality again.
Users who need to minimize memory footprint might consider decreasing workspace_client by workspace_thread.
The new parameter esi_iovs configures the amount of IO vectors used during ESI delivery. It should not be tuned unless advised by a developer.
Support Unix domain sockets for the -a and -b command-line arguments, and for backend declarations. This requires VCL >= 4.1.
return (fetch) is no longer allowed in vcl_hit {}, use return (miss) instead. Note that return (fetch) has been deprecated since 4.0.
Fix behaviour of restarts to how it was originally intended: Restarts now leave all the request properties in place except for req.restarts and req.xid, which need to change by design.
req.storage, req.hash_ignore_busy and req.hash_always_miss are now accessible from all of the client side subs, not just vcl_recv{}
obj.storage is now available in vcl_hit{} and vcl_deliver{}.
Removed beresp.storage_hint for VCL 4.1 (was deprecated since Varnish 5.1)
For VCL 4.0, compatibility is preserved, but the implementation is changed slightly: beresp.storage_hint is now referring to the same internal data structure as beresp.storage.
In particular, it was previously possible to set beresp.storage_hint to an invalid storage name and later retrieve it back. Doing so will now yield the last successfully set stevedore or the undefined (NULL) string.
IP-valued elements of VCL are equivalent to 0.0.0.0:0 when the connection in question was addressed as a UDS. This is implemented with the bogo_ip in vsa.c.
beresp.backend.ip is retired as of VCL 4.1.
workspace overflows in std.log() now trigger a VCL failure.
workspace overflows in std.syslog() are ignored.
added return(restart) from vcl_recv{}.
The alg argument of the shard director .reconfigure() method has been removed - the consistent hashing ring is now always generated using the last 32 bits of a SHA256 hash of "ident%d" as with alg=SHA256 or the default.
We believe that the other algorithms did not yield sufficiently dispersed placement of backends on the consistent hashing ring and thus retire this option without replacement.
Users of .reconfigure(alg=CRC32) or .reconfigure(alg=RS) be advised that when upgrading and removing the alg argument, consistent hashing values for all backends will change once and only once.
The alg argument of the shard director .key() method has been removed - it now always hashes its arguments using SHA256 and returns the last 32 bits for use as a shard key.
Backwards compatibility is provided through vmod blobdigest with the key_blob argument of the shard director .backend() method:
for alg=CRC32, replace:
<dir>.backend(by=KEY, key=<dir>.key(<string>, CRC32))
with:
<dir>.backend(by=BLOB, key_blob=blobdigest.hash(ICRC32, blob.decode(encoded=<string>)))
Note: The vmod blobdigest hash method corresponding to the shard director CRC32 method is called ICRC32
for alg=RS, replace:
<dir>.backend(by=KEY, key=<dir>.key(<string>, RS))with:
<dir>.backend(by=BLOB, key_blob=blobdigest.hash(RS, blob.decode(encoded=<string>)))
The shard director now offers resolution at the time the actual backend connection is made, which is how all other bundled directors work as well: With the resolve=LAZY argument, other shard parameters are saved for later reference and a director object is returned.
This enables layering the shard director below other directors.
The shard director now also supports getting other parameters from a parameter set object: Rather than passing the required parameters with each .backend() call, an object can be associated with a shard director defining the parameters. The association can be changed in vcl_backend_fetch() and individual parameters can be overridden in each .backend() call.
The main use case is to segregate shard parameters from director selection: By associating a parameter object with many directors, the same load balancing decision can easily be applied independent of which set of backends is to be used.
To support parameter overriding, support for positional arguments of the shard director .backend() method had to be removed. In other words, all parameters to the shard director .backend() method now need to be named.
Integers in VCL are now 64 bits wide across all platforms (implemented as int64_t C type), but due to implementation specifics of the VCL compiler (VCC), integer literals' precision is limited to that of a VCL real (double C type, roughly 53 bits).
In effect, larger integers are not represented accurately (they get rounded) and may even have their sign changed or trigger a C compiler warning / error.
Add VMOD unix.
Add VMOD proxy.
This is the first beta release of the upcoming 5.0 release.
The list of changes are numerous and will not be expanded on in detail.
The release notes contain more background information and are highly recommended reading before using any of the new features.
Major items:
Changes since 4.1.8:
Changes since 4.1.7:
Changes since 4.1.7-beta1:
Changes since 4.1.6:
Changes between 4.0 and 4.1 are numerous. Please read the upgrade section in the documentation for a general overview.
New since 4.0.2-rc1:
New since 4.0.1:
New since 4.0.0:
New since 4.0.0-beta1:
New since TP2:
varnishsizes -----------~
Persistent storage is now experimentally supported using the persistent stevedore. It has the same command line arguments as the file stevedore.
obj.* is now called beresp.* in vcl_fetch, and obj.* is now read-only.
The regular expression engine is now PCRE instead of POSIX regular expressions.
req.* is now available in vcl_deliver.
Add saint mode where we can attempt to grace an object if we don't like the backend response for some reason.
Related, add saintmode_threshold which is the threshold for the number of objects to be added to the trouble list before the backend is considered sick.
Add a new hashing method called critbit. This autoscales and should work better on large object workloads than the classic hash. Critbit has been made the default hash algorithm.
When closing connections, we experimented with sending RST to free up load balancers and free up threads more quickly. This caused some problems with NAT routers and so has been reverted for now.
Add thread that checks objects against ban list in order to prevent ban list from growing forever. Note that this needs purges to be written so they don't depend on req.*. Enabled by setting ban_lurker_sleep to a nonzero value.
The shared memory log file format was limited to maximum 64k simultaneous connections. This is now a 32 bit field which removes this limitation.
Remove obj_workspace, this is now sized automatically.
Rename acceptors to waiters
vcl_prefetch has been removed. It was never fully implemented.
Add support for authenticating CLI connections.
Add hash director that chooses which backend to use depending on req.hash.
Add client director that chooses which backend to use depending on the client's IP address. Note that this ignores the X-Forwarded-For header.
varnishd now displays a banner by default when you connect to the CLI.
Increase performance somewhat by moving statistics gathering into a per-worker structure that is regularly flushed to the global stats.
Make sure we store the header and body of object together. This may in some cases improve performance and is needed for persistence.
Remove client-side address accounting. It was never used for anything and presented a performance problem.
Add a timestamp to bans, so you can know how old they are.
Quite a few people got confused over the warning about not being able to lock the shared memory log into RAM, so stop warning about that.
Change the default CLI timeout to 10 seconds.
We previously forced all inserts into the cache to be GET requests. This has been changed to allow POST as well in order to be able to implement purge-on-POST semantics.
The CLI command stats now only lists non-zero values.
The CLI command stats now only lists non-zero values.
Use daemon(3) from libcompat on Darwin.
Remove vcl_discard as it causes too much complexity and never actually worked particularly well.
Remove vcl_timeout as it causes too much complexity and never actually worked particularly well.
Update the documentation so it refers to sess_workspace, not http_workspace.
Document the -i switch to varnishd as well as the server.identity and server.hostname VCL variables.
purge.hash is now deprecated and no longer shown in help listings.
When processing ESI, replace the five mandatory XML entities when we encounter them.
Add string representations of time and relative time.
Add locking for n_vbe_conn to make it stop underflowing.
When ESI-processing content, check for illegal XML character entities.
Varnish can now connect its CLI to a remote instance when starting up, rather than just being connected to.
It is no longer needed to specify the maximum number of HTTP headers to allow from backends. This is now a run-time parameter.
The X-Forwarded-For header is now generated by vcl_recv rather than the C code.
It is now possible to not send all CLI traffic to syslog.
It is now possible to not send all CLI traffic to syslog.
In the case of varnish crashing, it now outputs a identifying string with the OS, OS revision, architecture and storage parameters together with the backtrace.
Use exponential backoff when we run out of file descriptors or sessions.
Allow setting backend timeouts to zero.
Count uptime in the shared memory log.
Try to detect the case of two running varnishes with the same shmlog and storage by writing the master and child process ids to the shmlog and refusing to start if they are still running.
Make sure to use EOF mode when serving ESI content to HTTP/1.0 clients.
Make sure we close the connection if it either sends Connection: close or it is a HTTP/1.0 backend that does not send Connection: keep-alive.
Increase the default session workspace to 64k on 64-bit systems.
Make the epoll waiter use level triggering, not edge triggering as edge triggering caused problems on very busy servers.
Handle unforeseen client disconnections better on Solaris.
Make session lingering apply to new sessions, not just reused sessions.
VCL Manual page --------------~
Red Hat spec file ----------------~
Build system -----------~
Build system -----------~
Build system -----------~
The request workflow has been redesigned to simplify request processing and eliminate code duplication. All codepaths which need to speak HTTP now share a single implementation of the protocol. Some new VCL hooks have been added, though they aren't much use yet. The only real user-visible change should be that Varnish now handles persistent backend connections correctly (see ticket #56).
Support for multiple listen addresses has been added.
An "include" facility has been added to VCL, allowing VCL code to pull in code fragments from multiple files.
Multiple definitions of the same VCL function are now concatenated into one in the order in which they appear in the source. This simplifies the mechanism for falling back to the built-in default for cases which aren't handled in custom code, and facilitates modularization.
The code used to format management command arguments before passing them on to the child process would underestimate the amount of space needed to hold each argument once quotes and special characters were properly escaped, resulting in a buffer overflow. This has been corrected.
The VCL compiler has been overhauled. Several memory leaks have been plugged, and error detection and reporting has been improved throughout. Parts of the compiler have been refactored to simplify future extension of the language.
A bug in the VCL compiler which resulted in incorrect parsing of the decrement (-=) operator has been fixed.
A new -C command-line option has been added which causes varnishd to compile the VCL code (either from a file specified with -f or the built-in default), print the resulting C code and exit.
When processing a backend response using chunked encoding, if a chunk header crosses a read buffer boundary, read additional bytes from the backend connection until the chunk header is complete.
A new ping_interval run-time parameter controls how often the management process checks that the worker process is alive.
A bug which would cause the worker process to dereference a NULL pointer and crash if the backend did not respond has been fixed.
In some cases, such as when they are used by AJAX applications to circumvent Internet Explorer's over-eager disk cache, it may be desirable to cache POST requests. However, the code path responsible for delivering objects from cache would only transmit the response body when replying to a GET request. This has been extended to also apply to POST.
This should be revisited at a later date to allow VCL code to control whether the body is delivered.
Varnish now respects Cache-control: s-maxage, and prefers it to Cache-control: max-age if both are present.
This should be revisited at a later date to allow VCL code to control which headers are used and how they are interpreted.
When loading a new VCL script, the management process will now load the compiled object to verify that it links correctly before instructing the worker process to load it.
A new -P command-line options has been added which causes varnishd to create a PID file.
The sendfile_threshold run-time parameter's default value has been set to infinity after a variety of sendfile()-related bugs were discovered on several platforms.
The formatting callback has been largely rewritten for clarity, robustness and efficiency.
If a request included a Host: header, construct and output an absolute URL. This makes varnishncsa output from servers which handle multiple virtual hosts far more useful.
The flag that is raised upon reception of a SIGHUP has been marked volatile so it will not be optimized away by the compiler.