How to register your VMOD

To get your VMOD listed on the Varnish Project homepage you need to create a small JSON file which describes it and submit a pull request to our homepage github repos

There are a lot of JSON files there already, but they are machine generated based on older registrations, so they are not indicative of what we would like them to look like.

There are some examples at the bottom of this page.

At some point in the future we would like to be able to offer some continuous integration facilities to help VMOD authors maintain their code. (A volunteer to implement this would be more than welcome)

The JSON file should have a single object (“dictionary”) and it should have members as described below.


All VMODs MUST have these members:


This is the name in the “import FOOBAR;” VCL statement.


Format “YYYY-MM-DD”, date entry was last revised.


Description, compact one-line description of what the VMOD does. (Don’t repeat the VMOD name here, it looks silly in the table.)


We prefer “FreeBSD”, “Apache2”, “GPLv2” in that order, but we are not going to pass judgement, it’s your choice.


Allowed values:

  • “included” – those included in the varnish distro

  • “prototype” – Just playing around here…

  • “development” – API still subject to change

  • “mature” – We’re trying to be serious here

Additionally the following optional members are possible:


Email address of VMOD maintainer


List of companies which will support this VMOD on commercial terms.


URL to product description web-page for commercial offerings

Github projects

Since the majority of VMODs are github projects, we have tried to make that very easy.

In the toplevel object add a object member called “github” with these members:


Github username


Github project name


Relative path to the VCC file for the VMOD


Relative path of the file documenting the VMOD (default: the VCC file)


An object mapping Varnish version to github branches.

If your github project has multiple branches corresponding to varnish versions, it could look like this:

"branches": {
    "3.0": "3.0",
    "4.0": "4.0",
    "4.1": "master"

If your VMOD only supports Varnish 3.0 from the github projects master branch:

"branches": {
    "3.0": "master"

Non Github projects

You must these two members:


URL of the repository


An object mapping Varnish version to URL where the VCC and documentation files can be found.

For instance:

"rev": {
    "3.0": {
        "url_vcc": "",
        "url_doc": ""
    "4.1": {
        "url_vcc": "",
        "url_doc": ""


A github project:

    "date": "2016-04-14",
    "desc": "Murphy Field Calibrator",
    "github": {
        "branches": {
            "3.0": "3.0"
            "4.1": "master"
        "project": "libvmod-murphy-cal",
        "user": "ACME engineering",
        "vcc_path": "src/vmod_murphy.vcc"
        "doc_path": "doc/vmod_murphy.rst"
    "license": "FreeBSD",
    "name": "murphy",
    "status": "prototype",
    "support": [ "ACME VMODs and Explosives Inc." ],
    "maintainer": ""

A VMOD not on github:

    "date": "1999-12-31",
    "desc": "Y2K fixer",
    "license": "BeerWare",
    "name": "Y2K",
    "repos": "",
    "url_doc": "",
    "rev": {
        "4.1": {
            "url_vcc": "",
            "url_doc": ""
    "status": "prototype"