Operating System BSD

How to Install Vinyl Cache (formerly Varnish) with Nginx on FreeBSD 15

Set up Vinyl Cache 9, the successor to Varnish Cache, as a caching reverse proxy in front of Nginx on FreeBSD 15, with the rc.conf settings, a VCL file and the checks that prove it caches.

This guide puts a caching HTTP reverse proxy in front of Nginx on FreeBSD 15.1, the current production release (the same steps apply to FreeBSD 14). At the end, the cache answers on port 80 and Nginx serves as its backend on 127.0.0.1:8080.

One thing has changed since Varnish 5: the open source project was renamed. From version 9.0, released in March 2026, Varnish Cache is called Vinyl Cache, and the programs are named vinyld, vinyladm, vinyllog and vinylstat instead of varnishd, varnishadm, varnishlog and varnishstat. Varnish 5, 6.x (other than the 6.0 LTS branch), 7 and 8 are end-of-life upstream; the supported branch is Vinyl Cache 9.1, which FreeBSD packages as vinyl09. FreeBSD 11 itself has been unsupported since 2021.

Requirements

  • A server running FreeBSD 15.1 or 14.x with root access. The commands below are run as root; prefix them with sudo or doas if you use one of those.
  • Ports 80 free, and enough RAM for the cache size you choose (256 MB in the example).

Step 1: Update the system packages

pkg update
pkg upgrade

Step 2: Install Nginx and move it to port 8080

pkg install nginx
sysrc nginx_enable=YES

Open /usr/local/etc/nginx/nginx.conf and change the listen line of the default server so that Nginx only accepts connections from the local machine:

server {
    listen       127.0.0.1:8080;
    server_name  example.com;
    ...
}

Test the configuration and start Nginx:

nginx -t
service nginx start
fetch -qo - http://127.0.0.1:8080/ | head -n 5

You should see the beginning of the Nginx welcome page.

Step 3: Install Vinyl Cache

pkg install vinyl09

The package installs the daemon as /usr/local/sbin/vinyld, the tools in /usr/local/bin, and three rc scripts: vinyld, vinyllog and vinylncsa.

Step 4: Write a VCL file

The rc script can run without a configuration file, using only a backend address. A VCL file is the better choice because you will want to add caching rules later and reload them without a restart. The package does not install one, so create the directory and the file /usr/local/etc/vinyl-cache/default.vcl:

mkdir -p /usr/local/etc/vinyl-cache
vcl 4.1;

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

With only a backend defined, the built-in VCL applies. It caches GET and HEAD responses and does not cache requests that carry a Cookie or Authorization header or responses that set a cookie.

Step 5: Configure the service in rc.conf

sysrc vinyld_enable=YES
sysrc vinyld_listen=":80"
sysrc vinyld_config="/usr/local/etc/vinyl-cache/default.vcl"
sysrc vinyld_storage="malloc,256M"
sysrc vinyld_admin="localhost:81"
VariableMeaningDefault in the rc script
vinyld_listenAddress and port for client requests (-a):80
vinyld_configVCL file (-f). When set, vinyld_backend is ignoredunset
vinyld_backendBackend used when no VCL file is set (-b)localhost:8080
vinyld_storageCache storage (-s)file,/tmp,100M
vinyld_adminManagement interface (-T)localhost:81
vinyld_extra_flagsAnything else to pass to vinyldempty

malloc keeps cached objects in memory. The size is a limit for object storage only; the process uses additional memory per object, so leave headroom. Keep the management interface on localhost.

Check the VCL and start the service:

service vinyld configtest
service vinyld start

Step 6: Verify that requests go through the cache

sockstat -4 -l | grep -E 'vinyld|nginx'

vinyld should be listening on *:80 and Nginx on 127.0.0.1:8080. Now request the page twice and look at the headers:

fetch -qo /dev/null -v http://127.0.0.1/ 2>&1 | grep -iE '^(Age|Via|X-Vinyl)'
fetch -qo /dev/null -v http://127.0.0.1/ 2>&1 | grep -iE '^(Age|Via|X-Vinyl)'

Responses that passed through the cache carry a Via header naming Vinyl-Cache and an X-Vinyl header. On the second request X-Vinyl contains two IDs and Age is greater than zero: that is a cache hit. For live numbers use vinylstat (watch MAIN.cache_hit and MAIN.cache_miss) and vinyllog to follow individual requests.

If you run a packet filter, allow inbound TCP port 80 and keep 8080 and 81 closed to the outside.

Step 7: Log the real client address in Nginx

Nginx now sees every request coming from 127.0.0.1. The cache passes the visitor's address in the X-Forwarded-For header. If your Nginx build includes the realip module, add this to the http block and restart Nginx:

set_real_ip_from 127.0.0.1;
real_ip_header   X-Forwarded-For;
nginx -t
service nginx restart

Maintenance

After editing the VCL file, load it without dropping the cache:

service vinyld configtest
service vinyld reload

The reload compiles the file under a new name and activates it. Old versions stay loaded until you remove them:

vinyladm vcl.list
vinyladm vcl.discard reloaded_20261115120000

service vinyld restart empties a malloc cache, so use it only when you change rc.conf settings. To empty the cache for one site without restarting, ban its objects:

vinyladm "ban req.http.host == example.com"

The full reference is in the Vinyl Cache 9.1 documentation.

Frequently asked questions

Is the varnish7 package still usable?

The www/varnish7 port still exists, but upstream lists the 7.x series as end-of-life and FreeBSD flags the port as vulnerable. Its rc variables have the same names with a varnishd_ prefix, so moving to vinyl09 is mostly a rename. VCL written for Varnish 7 keeps working, with two exceptions noted in the upgrade notes: req.ttl is now req.max_age and beresp.storage_hint is gone.

What about HTTPS?

The cache speaks plain HTTP to clients in this setup. Terminate TLS in front of it, for example with a second Nginx server block on port 443 that proxies to 127.0.0.1:80, so the chain is Nginx (TLS), then the cache, then Nginx on port 8080.

Why is my application never served from the cache?

Most often because it sets cookies on every response or sends Cache-Control: no-cache or private. The built-in rules refuse to cache those. Either fix the headers in the application or write explicit VCL for the URLs that are safe to cache.

Is Varnish Cache gone?

The community project continues as Vinyl Cache. Varnish Software, the company, now publishes its own distribution under the Varnish Cache name, based on Vinyl Cache. The FreeBSD package described here is the community project.

Share story:

Continue reading other guides on How VPS.