Debian and Ubuntu install guide

This install guide explains how to install Varnish Cache on DEB-based Linux distributions like Debian and Ubuntu.

Register the package repository

Before we can install Varnish, we need to register the right package repository, otherwise Debian will install its own version of Varnish.

First update your packages:

sudo apt-get install -y apt-transport-https curl gpg

Import Varnish Repo Signing keys

sudo mkdir -p /etc/apt/keyrings/
curl -Ls https://packages.varnish-software.com/varnish/varnish.pub.asc | gpg --dearmor | sudo tee /etc/apt/keyrings/varnish.gpg > /dev/null

Add the correct source list based on /etc/os-release

source /etc/os-release
echo "deb [signed-by=/etc/apt/keyrings/varnish.gpg] https://packages.varnish-software.com/varnish/$ID $VERSION_CODENAME main" | sudo tee -a /etc/apt/sources.list.d/varnish.list

Install Varnish

Now that the repository is registered, you can install Varnish by running the following command:

sudo apt-get update
sudo apt-get install varnish

Configure Varnish

After installing Varnish, you will need to configure some varnishd runtime parameters, and possibly edit your VCL configuration.

Systemd configuration.

The varnishd process is managed by systemd and has its unit file in /lib/systemd/system/varnish.service. You can see this in the example below:

[Unit]
Description=Varnish Cache, a high-performance HTTP accelerator
After=network-online.target nss-lookup.target

[Service]
Type=forking
KillMode=mixed

# Maximum number of open files (for ulimit -n)
LimitNOFILE=131072

# Shared memory (VSM) segments are tentatively locked in memory. The
# default value for vsl_space (or shorthand varnishd -l option) is 80MB.
# There are other types of segments that would benefit from allowing
# more memory to be locked.
LimitMEMLOCK=100M

# Enable this to avoid "fork failed" on reload.
TasksMax=infinity

# Maximum size of the corefile.
LimitCORE=infinity

# A PID file makes the main process selection deterministic.
RuntimeDirectory=%N
PIDFile=%t/%N/varnishd.pid

ExecStart=/usr/sbin/varnishd \
          -a :6081 \
          -a localhost:8443,PROXY \
          -f /etc/varnish/default.vcl \
          -P %t/%N/varnishd.pid \
          -p feature=+http2 \
          -s malloc,256m
ExecReload=/usr/sbin/varnishreload

[Install]
WantedBy=multi-user.target

If you want to override some of the runtime parameters in the varnish.service file, you can run the following command:

sudo systemctl edit --full varnish

An editor will open in which you can edit the unit file. The content in the file comes from /lib/systemd/system/varnish.service.

After peforming the changes, make sure you save the file and exit the editor. As a result the /etc/systemd/system/varnish.service file will be created containing the modified unit file.

It is also possible to directly write the changes to /etc/systemd/system/varnish.service.

First you need to copy the original varnish.service file to the /etc/systemd/system/ folder:

sudo cp /lib/systemd/system/varnish.service /etc/systemd/system/

After modifying /etc/systemd/system/varnish.service, you have ro reload the Systemd daemon by running the following command:

sudo systemctl daemon-reload

Modifying the listening port and cache size

The varnish.service unit file above shows that the default Varnish runtime configuration is very conservative: the standard listening port is set to 6081 to avoid any clashes with other systems that might use port 80.

However, we will change the listening port to 80 because Varnish will sit in front of the web server and accept incoming HTTP connections. We’ll also increase the size of the cache to two gigabytes.

After having applied the configuration changes, the ExecStart statement now looks like this:

ExecStart=/usr/sbin/varnishd \
          -a :80 \
          -a localhost:8443,PROXY \
          -f /etc/varnish/default.vcl \
          -P %t/%N/varnishd.pid \
          -p feature=+http2 \
          -s malloc,2g

Don’t forget to run sudo systemctl daemon-reload when manually changing the unit file.

VCL backend configuration

The standard VCL file that comes with Varnish has a default backend definition that points to 127.0.0.1 on port 8080. This is the web server that Varnish will send requests to in case of cache misses, cache bypasses, and revalidation.

The default VCL file is located in /etc/varnish/default.vcl on your system and contains the following backend definition:

vcl 4.1;

backend default {
    .host = "127.0.0.1";
    .port = "8080";
}

Unless your web server is hosted locally and listens for incoming requests on port 8080, you’ll need to adjust the backend hostname and port in your VCL file.

DNS resolution of hostnames in the VCL file only happens once when the VCL file is compiled. Any DNS changes to that hostname will not be noticed by Varnish until the VCL is reloaded. Keep this in mind when using a hostname as the backend .host value.

Restart Varnish

A restart of the Varnish service is required to enable the varnishd parameter changes that were made through systemd. While the VCL changes can be done through others means, a Varnish restart will also reload the VCL configuration.

Run the following command to restart the Varnish service:

sudo systemctl restart varnish

Debian and Ubuntu install guide

Register the package repository#

Install Varnish#

Configure Varnish#

Systemd configuration.#

Modifying the listening port and cache size#

VCL backend configuration#

Restart Varnish#