Crate varnish

source ·
Expand description

§Varnish bindings

This module provides access to various Varnish facilities, notably those needed to create pure-rust vmods (check out examples here). Note that it doesn’t aim to be a 1-to-1 mirror of the C API, as Rust allows for better ergonomics than what the C code can provide (notably around strings and buffer handling).

WARNING: This crate is pre-1.0 and under active development so expect things to move around. There’s also a lot of unsafe code and a few “shortcuts” that will be cleaned later on. In short: see this as a tech-preview, and don’t run it in production.

§Building a VMOD

The main idea for this crate is to make the building framework as light as possible for the vmod writer, here’s a checklist, but you can also just check the source code.

The general structure of your code should look like this:

├── Cargo.lock
├── Cargo.toml
├── src
│   └──
├── tests
│   └── test01.vtc
└── vmod.vcc


You will need at least varnish-rs (this crate), and maybe varnish-sys if you use Varnish internals directly.

varnish = "0.0.19"

varnish = "0.0.19"


You will need a vmod.vcc alongside your Cargo.toml. This file describes your vmod’s API and how it’ll be accessible from VCL.

The good news is that the syntax is exactly the same as for a C vmod. The bad news is that we don’t support all types and niceties just yet. Check out the crate::vcl::convert page for more information.

# we need a comment at the top, possibly describing the license
$Module example 3 "An example vmod"

$Function BOOL is_even(INT)


The vmod.vcc file needs to be processed into rust-code so the module is loadable by Varnish. This steps is currently done via a python script triggered by the file (also alongside Cargo.toml). The nitty-gritty details have been hidden away and you can have a fairly simple file:

fn main() {


Here’s the actual code that you can write to implement your API. Basically, you need to implement public functions that mirror what you described in vmod.vcc, and the first argument needs to be a reference to crate::vcl::ctx::Ctx:


use varnish::vcl::ctx::Ctx;

pub fn is_even(_: &Ctx, n: i64) -> bool {
    return n % 2 == 0;

The various type translations are described in detail in crate::vcl::convert.


  • Access Varnish statistics


  • Convenience macro to include the generate boilerplate code.
  • Automate VTC testing