Varnish Developer Portal

Quick start

This quick start guide offers quick installation instructions for Linux distributions, such as Ubuntu, Debian, CentOS and Red Hat Enterprise Linux.

If you want more detailed instructions for a specific Linux distribution, you can use one of the following links:

1. Select the right Varnish version

Currently Varnish 6 is the active major version of Varnish. The following versions are maintained:

  • Varnish Cache 6.0 LTS
  • Varnish Enterprise 6
  • Varnish Cache 6.6
  • Varnish Cache 7.0

We advise you to install Varnish Cache 6.0 LTS, which is a stable and supported version. It is maintained by Varnish Software and receives frequent updates, including backported features.

The Varnish Cache community does two releases per year, which are considered fresh releases. These releases are primarily feature-based and do not guarantee backward compatibility. Varnish Cache 6.6 and Varnish Cache 7.0 are the current community-managed releases.

The packages for these versions are available on Packagecloud. This quick start guide will use Varnish Cache 6.0 LTS.

View the packages for Varnish Cache 6.0 LTS on Packagecloud →

2. Register the package repository

Preparing the packages and registering the package repository depends on your Linux distribution, the version of your distribution, the package manager you wish to use and the Varnish version you want to install.

Ubuntu & Debian

If you’re running Ubuntu or Debian, use the following commands to register the package repository.

Update the package list:

sudo apt-get update

Install the dependencies:

sudo apt-get install debian-archive-keyring curl gnupg apt-transport-https

Register the GPG key:

curl -s -L https://packagecloud.io/varnishcache/varnish60lts/gpgkey | sudo apt-key add -

Register the package repository:

. /etc/os-release
sudo tee /etc/apt/sources.list.d/varnishcache_varnish60lts.list > /dev/null <<-EOF
deb https://packagecloud.io/varnishcache/varnish60lts/$ID/ $VERSION_CODENAME main
EOF
sudo tee /etc/apt/preferences.d/varnishcache > /dev/null <<-EOF
Package: varnish varnish-* hitch
Pin: release o=packagecloud.io/varnishcache/*
Pin-Priority: 1000
EOF

Update the package list:

sudo apt-get update

CentOS

The following commands will register the package repository on your CentOS system for both CentOS 7 and CentOS 8.

Install the epel-release package:

sudo yum install epel-release

Register the package repository:

. /etc/os-release
sudo tee /etc/yum.repos.d/varnishcache_varnish60lts.repo > /dev/null <<-EOF
[varnishcache_varnish60lts]
name=varnishcache_varnish60lts
baseurl=https://packagecloud.io/varnishcache/varnish60lts/el/${VERSION_ID%%.*}/$(arch)
repo_gpgcheck=0
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/varnishcache/varnish60lts/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300
EOF

Red Hat Enterprise Linux

The following commands will register the package repository on your Red Hat system for both RHEL 7 and RHEL 8.

Install the epel-release package:

. /etc/os-release
sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-${VERSION_ID%%.*}.noarch.rpm

Register the package repository:

sudo tee /etc/yum.repos.d/varnishcache_varnish60lts.repo > /dev/null <<-EOF
[varnishcache_varnish60lts]
name=varnishcache_varnish60lts
baseurl=https://packagecloud.io/varnishcache/varnish60lts/el/${VERSION_ID%%.*}/$(arch)
repo_gpgcheck=0
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/varnishcache/varnish60lts/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300
EOF

3. Install Varnish

Depending on the type of package manager your Linux distribution supports, you’ll either use apt-get or yum to install Varnish from the package repository that was registered in the previous step.

Ubuntu and Debian

Both Ubuntu and Debian use the apt-get package manager, which means you can run the following command to install Varnish:

sudo apt-get install varnish

CentOS and Red Hat Enterprise Linux

Both CentOS and Red Hat Enterprise Linux use the yum package manager, which means you can run the following command to install Varnish:

sudo yum install varnish

4. Configure Varnish runtime parameters

The varnishd program is managed by Systemd on the various Linux distributions. The default varnishd runtime parameters are stored in /usr/lib/systemd/system/varnish.service or /lib/systemd/system/varnish.service, depending on your Linux distribution.

This is the standard configuration:

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

[Service]
Type=forking
KillMode=process

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

# Locked shared memory - should suffice to lock the shared memory log
# (varnishd -l argument)
# Default log size is 80MB vsl + 1M vsm + header -> 82MB
# unit is bytes
LimitMEMLOCK=85983232

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

# Maximum size of the corefile.
LimitCORE=infinity

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

[Install]
WantedBy=multi-user.target

The two parameters you are most likely to edit are:

  • Setting the listen port from -a :6081 to -a :80
  • Upgrading the size of the cache by changing -s malloc,256m

You can either do this automatically through the systemctl edit command, or manually as described below.

Before you continue, make sure the Varnish service is enabled:

sudo systemctl enable varnish

This command will ensure that the Varnish service will be automatically started when the server reboots.

Through the systemctl edit command

Run the following command to edit the varnishd runtime parameters:

sudo systemctl edit --full varnish

An editor will open that includes the content from /usr/lib/systemd/system/varnish.service or /lib/systemd/system/varnish.service, depending on your Linux distribution. Modify the runtime parameters, save your changes and close the editor. As a result the modified content will be stored in /etc/systemd/system/varnish.service.

Manually

If you don’t want to use sudo systemctl edit --full varnish and you prefer to edit the varnish.service file manually, follow these instructions.

First you have to copy the varnish.service file into the /etc/systemd/sytem folder:

On Ubuntu and Debian systems you will run the following command:

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

On CentOS and Red Hat Enterprise Linux systems you will run the following command:

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

Edit /etc/systemd/system/varnish.service, save your changes and run the following command to reload the System configuration:

sudo systemctl daemon-reload

5. Reconfigure the web server

If Varnish is installed on the same server as the origin web server, Varnish will be listening on port 80. This means that the listening port of your web server will need to be modified. A good alternative HTTP port number for your web server is port 8080.

The commands below describe to how to change the port number for Apache and Nginx web servers on Ubuntu, Debian, CentOS and Red Hat Enterprise Linux.

Apache on Debian and Ubuntu

On Debian and Ubuntu Apache’s listening port values are in /etc/apache2/ports.conf. The individual virtual hosts are also mapped to these ports and need to be changed as well.

The following command will replace the occurrences of port 80 with 8080 for all relevant files:

sudo find /etc/apache2 -name '*.conf' -exec sed -r -i 's/\bListen 80\b/Listen 8080/g; s/<VirtualHost ([^:]+):80>/<VirtualHost \1:8080>/g' {} ';'

Apache on CentOS and Red Hat Enterprise Linux

On CentOS and Red Hat Enterprise Linux the Apache’s listening port values are in /etc/httpd/conf/httpd.conf and in the individual virtual hosts.

The following command will replace the occurrences of port 80 with 8080 for all relevant files:

sudo find /etc/httpd -name '*.conf' -exec sed -r -i 's/\bListen 80\b/Listen 8080/g; s/<VirtualHost ([^:]+):80>/<VirtualHost \1:8080>/g' {} ';'

Nginx

The following command will recursively replace listen 80; with listen 8080; in all the relevant .conf files in the /etc/nginx folder:

sudo find /etc/nginx -name '*.conf' -exec sed -r -i 's/\blisten ([^:]+:)?80\b([^;]*);/listen \18080\2;/g' {} ';'

This command works on Ubuntu, Debian, CentOS and Red Hat Enterprise Linux.

6. VCL backend configuration

As you’ve seen in the section about configuring runtime parameters, the varnishd program uses a -f parameter that refers to the VCL file that is loaded.

The standard VCL file location is /etc/varnish/default.vcl and contains some VCL code. It allows you to extend Varnish’s standard behavior.

The first change we need to make is to define the backend connection information that Varnish uses to connect to the origin web server.

This is the standard value that you’ll find in /etc/varnish/default.vcl:

vcl 4.1;

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

If your web server is configured on another port or if Varnish runs on another machine, please change the .host and .port properties accordingly.

7. Custom caching policies

Unless your website or application is completely static, the initial hit rate of Varnish won’t be that great. Writing custom caching policies in VCL will be necessary to improve that hit rate.

Standard caching behavior

Out-of-the box Varnish will not serve objects from the cache if the request contains a Cookie header or if a request method other than GET or HEAD is used.

Varnish will not store responses from the origin web server in the cache if the Cache-Control header contains private, no-cache or no-store. The same thing happens if the Cache-Control headers have a max-age or s-maxage value of zero, or if the Expires header contains a timestamp from the past. When Set-Cookie headers are returned, Varnish also decides not to store the response in the cache.

Write some VCL code

It’s clear that Varnish is extremely cautious when it comes to caching personalized content. In real-world situations you will encounter cookies, and you’ll have to deal with applications that send out the wrong Cache-Control headers.

The Varnish Configuration Language allows us to define custom caching policies and override the standard behavior. This allows you to tailor the behavior of Varnish to your exact needs.

Edit /etc/varnish/default.vcl, add some custom VCL code and run the varnishreload command to load your updated VCL configuration into Varnish.

VCL templates

We also have some VCL templates that can accelerate the customization process for you.

Have a look at our sample VCL template, which is a good starting point for any kind of website or web application.

We also offer specific VCL templates for frameworks like WordPress, Magento and Drupal:

8. Restart the services

Now that we modified the varnishd runtime parameters, the contents of the VCL file and listening port of the origin web server, we need to restart these services.

The commands that you’ll run will depend on the type of web server you use and the Linux distribution on which these services run.

Apache on Debian and Ubuntu

On Debian and Ubuntu, you can restart Apache and Varnish using the following command:

sudo systemctl restart apache2 varnish

Apache on CentOS and Red Hat Enterprise Linux

On CentOS and Red Hat Enterprise Linux, you can restart Apache and Varnish using the following command:

sudo systemctl restart httpd varnish

Nginx

Run the following command if you’re using Nginx instead of Apache:

sudo systemctl restart nginx varnish