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
sudoordoasif 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 upgradeStep 2: Install Nginx and move it to port 8080
pkg install nginx
sysrc nginx_enable=YESOpen /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 startfetch -qo - http://127.0.0.1:8080/ | head -n 5You should see the beginning of the Nginx welcome page.
Step 3: Install Vinyl Cache
pkg install vinyl09The 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-cachevcl 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"| Variable | Meaning | Default in the rc script |
|---|---|---|
vinyld_listen | Address and port for client requests (-a) | :80 |
vinyld_config | VCL file (-f). When set, vinyld_backend is ignored | unset |
vinyld_backend | Backend used when no VCL file is set (-b) | localhost:8080 |
vinyld_storage | Cache storage (-s) | file,/tmp,100M |
vinyld_admin | Management interface (-T) | localhost:81 |
vinyld_extra_flags | Anything else to pass to vinyld | empty |
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 startStep 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 restartMaintenance
After editing the VCL file, load it without dropping the cache:
service vinyld configtest
service vinyld reloadThe 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_20261115120000service 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.