Enterprise extensions reference

Varnish Enterprise 6.0 is based on Varnish Cache 6.0 and extends it with additional runtime parameters, VCL variables and subroutines, CLI commands, and tools. This page is a reference for those extensions, for readers who know open source Varnish and want to see what is different. Where a feature has its own documentation page, the group heading links to it.

Items that also appear in open source Varnish releases newer than 6.0 are collected in the final section rather than listed as Enterprise extensions.

Use varnishadm param.show <name> for the full description of any parameter. Parameters marked experimental below carry that flag in param.show output.

Parameters added

Backend and timeouts

See also Timeouts.

TLS

Frontend (in-process) TLS is configured with the -A option and the tls.cert.* CLI family; see In-Process TLS and Backend TLS.

MSE, memory governor, and storage

See also Memory Governor, MSE 4 and Transit Buffer.

Networking and HTTP/2

See also HTTP/2 and NUMA.

vmod_http thread pool

These control the thread pool that services asynchronous http VMOD requests.

Scoreboard and licensing

See also Varnish Scoreboard.

Changed parameter defaults

These parameters exist in open source Varnish 6.0 but have different defaults in Varnish Enterprise:

The wait_silo feature bit is removed: the deprecated persistent silo stevedore does not exist in Varnish Enterprise.

VCL additions

Variables

The param namespace

VCL can read a set of runtime parameters directly through the read-only param.* namespace, available in all subroutines. Values are read live: a param.set through varnishadm is visible to the next use in VCL without a reload.

sub vcl_backend_fetch {
	# Give this one endpoint a longer first-byte allowance than
	# the global parameter, scaled off the configured value.
	if (bereq.url ~ "^/slow-report/") {
		set bereq.first_byte_timeout =
		    param.first_byte_timeout + 30s;
	}
}

Available: param.backend_idle_timeout, param.backend_wait_limit, param.backend_wait_timeout, param.between_bytes_timeout, param.connect_timeout, param.default_grace, param.default_keep, param.default_ttl, param.first_byte_timeout, param.idle_send_timeout, param.max_esi_depth, param.max_restarts, param.max_retries, param.pipe_timeout, param.send_timeout, param.shortlived, param.thread_pool_max, param.thread_pool_min, param.thread_pool_reserve, param.thread_pools, param.thread_queue_limit, param.timeout_idle, param.transit_buffer, param.uncacheable_ttl.

Counting parameters are INT, sizes are BYTES, and timeouts are DURATION, matching the parameter’s own type.

Subroutines and return actions

• return (connect) from vcl_recv, and the new subroutine sub vcl_connect, handle HTTP CONNECT tunneling.
• sub vcl_vha_internal exists for the Varnish High Availability replication engine. It is internal; do not use it directly.

Built-in VCL differences

The built-in VCL (appended to every loaded VCL) differs from open source 6.0 in the following ways:

• vcl_recv returns a 400 synthetic response for requests whose URL does not start with / (except OPTIONS * and CONNECT requests).
• vcl_synth short-circuits with return (deliver) when req.is_reset is true — no point rendering an error page for a client that is gone.
• The hit-for-miss TTL is set beresp.ttl = param.uncacheable_ttl; instead of a hard-coded 120 seconds.
• The Surrogate-Control and Cache-Control checks that mark responses uncacheable match case-insensitively.
• The subroutines vcl_connect and vcl_vha_internal exist (see above).

CLI and tools

Added varnishadm commands

Commands marked sensitive by Varnish Enterprise (certificate and license handling) are not logged to the Varnish log.

Socket management (graceful drain/offline):

• socket.list — list all listen sockets and their state.
• socket.close / socket.open — close or reopen all listen sockets. On close, HTTP/2 clients get GOAWAY and keep-alive clients get Connection: close.

Frontend TLS certificates (see In-Process TLS):

• tls.cert.load — load a certificate, with options for key file, ciphers, protocols, SNI filter, client certificate verification, CA file, security level, and CRL.
• tls.cert.list, tls.cert.commit, tls.cert.rollback, tls.cert.reload, tls.cert.discard, tls.cert.staple.

Backend TLS client certificates (see Backend TLS):

• backend.cert.load, backend.cert.list, backend.cert.discard.

Licensing:

• license.load, license.show, license.status.

MSE (version 3):

• mse.flush_memcache, mse.lmdb_readers, mse.lmdb_lock, plus debug commands.

MSE4 (see MSE 4):

• mse4.status — book and store states.
• mse4.fail / mse4.reset — fail a device / reinitialize an offline device (data loss on reset).
• mse4.sync, mse4.flush_memcache, mse4.purge_unreachable_objects, mse4.aio_engine, mse4.can_iouring.

VCL and general:

• vcl.load_files — compile and load multiple VCL files as one configuration.
• vcl.load -v — verbose load with timing output.
• vcl.show — the configuration name argument is now optional.
• param.set -j — JSON echo of the updated value.
• identity [-j] — show the server identity (varnishd -i).
• version, banner — JSON output variants.
• panic.clear -z — also clears the related counters.

Added varnishd options

• -A cfgfile — listen endpoint / TLS configuration file for native TLS termination.
• -z id=certfile — backend TLS client certificate (repeatable).
• -L file — Varnish Enterprise license file.
• -E secret-file — secret file for Total Encryption.
• -s mse and -s mse4 — the MSE storage engines.

Enterprise binaries

• mkfs.mse — initialize MSE (version 3) books and stores.
• mkfs.mse4 — initialize MSE4 persisted storage.
• varnishlog-json — display Varnish logs in JSON format.
• varnishscoreboard — live view of worker thread and task state (backed by the vst_space segments; see Varnish Scoreboard).
• vha-agent — the Varnish High Availability agent.

Also available in recent open source releases

The following ship in Varnish Enterprise 6.0 but were also added to open source Varnish in releases after 6.0, so they are not exclusive to Enterprise. If you administer both, check your OSS version.

Parameters: backend_wait_timeout and backend_wait_limit (queue transactions waiting for a backend connection), timeout_req (maximum time to receive request headers), h2_window_timeout, h2_rapid_reset, h2_rapid_reset_limit, h2_rapid_reset_period (HTTP/2 rapid-reset mitigation; OSS 6.0 LTS gained these in 6.0.12), h2_rxbuf_storage, shutdown_delay, startup_timeout, max_vcl, max_vcl_handling, vcc_vmod_restrict.

VCL: req.hash_ignore_vary, req.time, bereq.is_hitmiss, bereq.is_hitpass, obj.can_esi, resp.send_timeout, sess.timeout_idle, extended resp.status semantics (XXYZZ status codes where only YZZ is sent to the client), return (error) from the backend-side subroutines, and the simplified built-in vcl_hit (hit/grace decisions moved into core code).

CLI: param.reset, pid [-j].