hwatts/libvmod-keystore

[Varnish >= 4] [BSD] VMod to interact with key/value store engines (redis and memcached)

Available drivers

• redis
• memcached

Prerequisites

• cmake >= 2.8.3
• varnish >= 4.0
• hiredis for redis driver
• libmemcached for memcached driver

How to build

With embedded drivers (statically linked)

cd /path/to/libvmod-keystore
cmake .

(if hiredis is found, redis driver will automatically be enabled ; same thing with libmemcached for memcached driver)

In top of your Varnish configuration, add:

import keystore;

With drivers as separate vmods

First build vmod_keystore alone:

cd /path/to/libvmod-keystore
cmake . -DWITH_REDIS:BOOL=OFF -DWITH_MEMCACHED:BOOL=OFF

Then build your driver(s). Example for redis:

cd /path/to/libvmod-keystore/drivers/redis
cmake .

To load redis driver, your varnish configuration should be similar to:

import keystore;
import keystore_redis; # add this line AFTER keystore

VMod methods

Instanciate a connection to your database:

new <variable name> = keystore.driver("<driver name>:host=<IP address or hostname or path to socket>;port=<port>;timeout=<timeout>");

• STRING get(STRING key): fetch current value associated to key
• BOOL add(STRING key, STRING value): add the given key if it does not already exist (returns FALSE if it already exists)
• VOID set(STRING key, STRING value): add or replace (overwrites) the value associated to key
• BOOL exists(STRING key): does key exist?
• BOOL delete(STRING key): delete key
• VOID expire(STRING key, DURATION ttl): set expiration of the given key (keys are inserted as persitent with 0 as TTL ; use 30s as value of ttl, for the key to expire in 30 seconds)
• INT increment(STRING key): return value associated to key after incrementing it (of 1)
• INT decrement(STRING key): return value associated to key after decrementing it (of 1)
• STRING name() : return current driver name
• STRING raw(STRING command) : execute an arbtrary command (redis only)

Examples

Prevent brute-force on http authentication

import std;
import keystore;
#import keystore_redis; # if compiled as a separate VMOD

sub vcl_init {
    new ipstore = keystore.driver("redis:host=localhost;port=6379");
}

sub vcl_recv {
    if (std.integer(ipstore.get("" + client.identity), 0) >= 5) {
        return(synth(403));
    }
    # ...
}

sub vcl_deliver {
    # ...
    if (401 == resp.status && req.http.Authorization) {
        if (ipstore.increment("" + client.identity) >= 5) {
            ipstore.expire("" + client.identity, 4h); # ban for 4 hours
            return(synth(429)); # return synth in vcl_deliver requires Varnish >= 4.0.2
        } else {
            ipstore.expire("" + client.identity, 1h); # reset attempts count after 1h
        }
    }
    # ...
}