Varnish

General configuration for Varnish. At least one http or https listen endpoint must be specified, all other parameters are optional.

Example:

varnish:
  http:
  - port: 80

http

Type: List

A list of HTTP ports for Varnish to bind and listen to. Varnish needs at least one http port or one https port.

port

varnish:
  http:
  - port: 80

Type: Integer

The port number to listen to. If address is not also specified, varnish will listen on all available interfaces.

address

varnish:
  http:
  - address: 127.0.0.1:80

Type: String

The interface address to bind to. Can specify both address and port, or used in combination with port.

https

Type: List

A list of HTTPS listeners for Varnish to bind to. Each listener must have at least one certificate.

port

varnish:
  https:
  - port: 443
    certificates:
    - self_signed: example.com

Type: Integer

The port number to listen to. If address is not also specified, varnish will listen on all available interfaces.

address

varnish:
  http:
  - address: 127.0.0.1:443
    certificates:
    - self_signed: example.com

Type: String

The interface address to bind to. Can specify both address and port, or used in combination with port.

certificates

Type: List

The certificates to use for this HTTPS listener.

combined

varnish:
  https:
  - port: 443
    certificates:
    - combined: /tmp/combined.pem

Type: String

Path to a combined certificate and private key PEM file. Mutually exclusive with cert and private_key.

cert

varnish:
  https:
  - port: 443
    certificates:
    - cert: /etc/varnish-supervisor/cert.crt
      private_key: /etc/varnish-supervisor/private.key

Type: String

Path to a certificate PEM file. If specified, a private_key must be specified as well.

private_key

varnish:
  https:
  - port: 443
    certificates:
    - cert: /etc/varnish-supervisor/cert.crt
      private_key: /etc/varnish-supervisor/private.key

Type: String

Path to a private key PEM file. If specified, a cert must be specified as well.

self_signed

varnish:
  https:
  - port: 443
    certificates:
    - self_signed: "localhost"
    - self_signed: "*.localhost"
    - self_signed: "example.com"

Type: String

Generate a self-signed certificate. This is useful for testing with clients that accept non-trusted certificates. Supports wildcards for wildcard TLS certificates.

For automatic trusted TLS, see ACME.

storage

Note: Orca Premium feature

Configure a persistent cache for Varnish to use. This will generate the appropriate Massive Storage Engine (MSE) 4 configuration and initialize it with mkfs.mse4.

Changes to storage are applied when the Supervisor restarts. A reload that changes it is refused, since the files are laid out before Varnish starts and mkfs.mse4 cannot change them while it runs. Growing a store or adding one keeps the cached objects, and shrinking a store drops the objects at its tail.

stores

Type: List

A list of stores for the persisted cache. A store appears as a single large file on the file system and is used to persist chunks of cached objects.

An auxiliary file called a book is created alongside the store (or in book_path), which keeps track of where the object chunks in the store are and other metadata such as cache invalidation keys and checksums for durable storage.

Each store must have a name, path and size.

name

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

Type: String

The unique identifying name for this store.

path

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

Type: String

Path to a directory where the the store and book files will be created at Supervisor startup. The backing storage must have space to fit size bytes.

size

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G

Type: String

Size of the store to create. Available case-insensitive units are K, M, G, and T, each a power of 1024, and a number without a unit is bytes. The unit may carry a trailing B and be separated from the number by a space, and the number may have a fraction, so 20TB, 1.5T and 1 GB are all valid.

The size includes the size of the book (5G by default) and space held back for filesystem metadata, which is 3% of size with 1G as the minimum. The size of the store file can be calculated as:

overhead   = max(3% of size, 1G)
store_size = size - book_size - overhead

Must be larger than book_size + overhead. When book_path puts the book on a volume of its own, size covers the store alone: store_size = size - overhead.

Versions before 0.19.0 held back a fixed 1G, so on upgrade a store whose 3% is more than 1G is shrunk to make room for the larger reserve, which drops the objects at its tail. To keep them, raise size by the difference if the volume has room for it.

book_size

varnish:
  storage:
    stores:
    - name: disk1
      path: /etc/varnish-supervisor/storage/disk1
      size: 1000G
      book_size: 2G

Type: String

Default: 5G

Change the size of a store’s book. When the size of a book is increased, the size of the store is decreased, and vice versa, unless book_path puts the book on a volume of its own. Takes the same size formats as size.

book_path

varnish:
  storage:
    stores:
    - name: disk1
      path: /mnt/hdd1/storage
      size: 1000G
      book_path: /mnt/nvme1/books

Type: String

Default: Same as path

Directory for the store’s book. MSE4 recommends a fast device for the book, whose IO is small and random, and a large one for the store, whose IO is sequential.

Setting it changes what size means: the book is no longer carved out of size, which then covers the store alone. Give the book a volume holding book_size plus room for a resize, which builds the new book before replacing the old one. The directory has to exist already, so that a volume which failed to mount is refused rather than filled. A book_path on the same volume as path is the same as leaving it unset, and size goes on covering both.

Set on a cache that already exists, the book is moved on the next start, which copies it across and delays that start. Removing book_path again moves the book back onto the store’s volume and shrinks the store to make room for it, so that needs book_size free there.

category

varnish:
  storage:
    default_category: other
    stores:
    - name: disk1
      path: /disk1
      size: 1000G
      category: media.video
    - name: disk2
      path: /disk2
      size: 1000G
      category: media.video
    - name: icons
      path: /disk3/icons
      size: 50G
      category: media.images.icons
    - name: pictures
      path: /disk3/pictures
      size: 150G
      category: media.images.pictures
    - name: other
      path: /disk3/other
      size: 800G
      category: other

Type: String

Assign a category to the store. This reserves the store to be used exclusively for objects of the same category. Multiple stores can have the same category, in which case objects are spread evenly over the stores.

Object category can be set in VCL sub vcl_backend_response with the mse4 VMOD:

mse4.set_category("media.video");

If no category has been set in VCL, the category defined by default_category is used.

Categories are a tree structure, and each store category must be a leaf-node in that tree. This means that if one store has the category media.images.icons, another store cannot have the category media.images.

When categories are used, all stores must have a category and default_category must be set.

default_category

varnish:
  storage:
    default_category: blobs
    stores:
    - name: manifests
      path: /disk1/manifests
      size: 100G
      category: manifests
    - name: objects
      path: /disk1/objects
      size: 900G
      category: objects

Type: String

The default category to use if no category have been set in VCL.

Required if categories are used.

admin_port

varnish:
  admin_port: 1234

Type: Integer

Default: 1092

Target port for the reverse admin interface.

work_dir

varnish:
  work_dir: /var/lib/varnish

Type: String

Default: Derived from system defaults

Varnish working directory (equivalent to varnishd -n). This is the directory where Varnish stores its shared memory logs and other runtime files.

path

varnish:
  path: /path/to/varnishd

Type: String

Default: Derived from system $PATH

Path to the varnishd binary to use.

params

varnish:
  params:
    workspace_backend: 128k

Parameters for Varnish. See params.

vcls

Note: Orca Premium feature

varnish:
  vcls:
  - name: website
    path: /etc/varnish-supervisor/website/main.vcl
    routes:
    - host: "www.example.com"
    - host: "registry.example.com"
      path: "/docs/*"

Type: List

Your own VCL programs, loaded next to the ones the Virtual Registry generates. The root VCL sends each VCL the requests that match its routes, and the VCL then handles them alone, outside any registry’s pipeline.

The VCL files are copied into the generated VCL each time it is built, so an edit to one takes effect on the next reload, by SIGHUP or a change to the configuration files.

Requires the sup-vclediting addon. A configuration with vcls and no such addon is refused, since ignoring it would hand the requests that its routes claim to a registry.

name

varnish:
  vcls:
  - name: website

Type: String

Name of the VCL, which follows the same rules as a registry name and has to be unique across registries and VCLs. The VCL is loaded under the label label_<name>, so extra_root_vcl can also send requests to it. Required.

path

varnish:
  vcls:
  - name: website
    path: /etc/varnish-supervisor/website/main.vcl

Type: String

Path to the main VCL file. Required.

The .vcl files under its directory are loaded with it, so it can include them by a path relative to that directory. A file included by absolute path is read in place instead, so a reload misses an edit to it.

include_paths

varnish:
  vcls:
  - name: website
    path: /etc/varnish-supervisor/website/main.vcl
    include_paths:
    - /etc/varnish-supervisor/shared

Type: List

Directories searched in order for an included file that is not under the main file’s directory. Their .vcl files are loaded with the VCL, like those next to the main file.

The VCL shipped with Varnish, such as devicedetect.vcl, is searched last, so it can be included by name without being listed here.

routes

varnish:
  vcls:
  - name: website
    routes:
    - host: "*.example.com"
      path: "/static/*"

Type: List

Requests to send to this VCL. A route matches a host glob against the Host header, as a registry’s glob does, a path glob against the URL path without the query string, or both. A route needs at least one of the two, and one left out matches anything. In path, * also matches /, so /static/* covers everything under /static/.

The root VCL checks the routes of every VCL before it routes to a registry, in the order the VCLs and their routes are listed, and the first match wins. A VCL can therefore take a path on a registry’s host.

A VCL without routes is sent nothing unless it is the default or extra_root_vcl sends it requests, and the Supervisor warns about it.

default

varnish:
  vcls:
  - name: website
    default: true

Type: Boolean

Default: false

Send this VCL the requests that match no VCL route and no registry. Only one registry or VCL can be the default.