TinyKVM VMOD examples

This repository contains simple example programs for the KVM and TinyKVM VMODs.

About the VMOD

The KVM VMOD allows you to sandbox systems languages, allowing them to run natively on the CPU while Varnish is running safely. These languages are compiled down to machine code as regular Linux executables and archived. The archive is then published along with a library JSON file that describes each program and its limits. Libraries and programs may also be loaded from the local filesystem.

The VMOD focuses on data processing. That is, programs take inputs and generate HTTP response outputs with access to Varnish internals. It is also possible to do many other things like scheduling tasks at regular intervals and communicating with other non-HTTP services. The sandboxes have permission-based access to the local filesystem and Internet, allowing for things like database communication and as a programmable alternative to regular Varnish backends.

Enable hardware virtualization

If you have not enabled VMX or SVM already in your BIOS, you will need to do so in order to run things like qemu-kvm and the KVM VMOD on your own machine. Most servers already have this enabled and can skip this step.

To see if you have enabled hardware virtualization, check:

• Generally:
  • Presence of dev/kvm: stat /dev/kvm
• Specific to AMD64:
  • Intel: grep vmx /proc/cpuinfo
  • AMD: grep svm /proc/cpuinfo

If you are running Linux inside a VM, such as VMware Player or VMware Workstation, you will need to enable nested virtualization:

• Enable VT-x/EPT virtualization in the Processors tab.

Add your own user to KVM group

vmod_compute and vmod_kvm requires access to /dev/kvm. In order to give Varnish access, run this in a terminal:

sudo addgroup varnish kvm

You may need to fully log out and then in again in order for the change to take effect. It may not be enough to reopen the terminal.

Documentation

You can find the documentation here. It is still being written and may change daily.

There are several examples in the documentation, as well how to use the VMOD from VCL.

Select your language

• C: Go into the c folder and edit hello_world.c
• C++: Go into the cpp folder and edit hello_world.cpp
• Go: Go into the go folder and edit goexample.go
• Kotlin: Go into the kotlin folder and edit main.kt
• Nelua: Go into the nelua folder and edit example.nelua
• Nim: Go into the nim folder and edit hello.nim
• JavaScript: Go into the javascript folder and edit chat.js
• Rust: Go into the rust folder and edit main.rs
• Zig: Go into the zig folder and edit example.zig

You can find the C API here: kvm_api.h. It contains the complete API with some explanations and examples. The API is not necessarily intended for end-users, but it is required for those who wants to integrate other languages.

There are work-in-progress APIs for other languages as well, but they are not always fully fleshed out. The JavaScript API is for the most part written out in the beginning of the examples, which you can find here.

The APIs will be more fleshed out over time for each language, likely based on interest and demand. Each language has different pros and cons, strengths and weaknesses. For example, many programs don't require the highest possible performance and would work just fine with a scripting language.

Example: Nelua

require 'varnish'
local image = #[embed '../assets/rose.jpg']#

local function on_get(url: string, arg: string)
    varnish.set("X-Language: Nelua 0.2.0-dev")
    varnish.response(200, "image/jpeg", image)
end

varnish.set_backend_get(on_get)
varnish.wait_for_requests()

Significant demos

cpp/avif converts JPEG to AVIF, and if any error happens it will instead deliver the original JPEG.

cpp/webp converts JPEG or PNG to WebP, with support for cropping and resizing.

cpp/gbc is a self-hosting co-operative GameBoy Color emulator demo. It delivers a static website that communicates with the emulator and each viewer contributes inputs in order to create chaos. The demo has complex code in order to share the state of the emulator and the current frame with request VMs. There are two PNG frames, and the emulator employs double-buffering (rendering to one frame while presenting another). Each request VM enters storage in order to contribute inputs, while at the same time potentially scheduling new frames. New frames are generated asynchronously in storage, and read from shared memory by request VMs freeing up storage access. It uses requests to drive frame generation, resulting in no CPU usage when nobody is watching.

cpp/src/espeak.cpp generates voice audio based on input.

cpp/src/minify.cpp will minify JSON at 6GB/s.

Licensing

TinyKVM and VMOD-TinyKVM are released under a dual licensing model:

• Open Source License: GPL‑3.0 (see LICENSE).
• Commercial License: Available under terms controlled by Varnish Software.

For commercial licensing inquiries, please contact: compliance@varnish-software.com.

Contributing

We welcome contributions! By submitting a pull request or other contribution, you agree to our Contributor License Agreement and our Code of Conduct.

For details on how to contribute, please refer to this document.