vmod_memcached

Varnish Memcached Module

Author

Aaron Stone

Date

2012-01-25

Version

0.1

Manual section

3

SYNOPSIS

import memcached;

DESCRIPTION

Varnish vmod using libmemcached to access memcached servers

Implements the basic memcached operations of get, set, incr, decr.

FUNCTIONS

servers

Prototype

servers(STRING servers)

Return value

NONE

Description

Set the list of memcached servers available for requests handled by this VCL. The syntax is a whitespace or comma

separated list of one or more "hostname[:port]" items.

If you have libmemcached > 0.49 you can use the new syntax, specified in http://docs.libmemcached.org/libmemcached_configuration.html#description , which uses "--SERVER=ip:port" to specify a server. Warning: There is no error checking for this string, if it's wrong you won't get an error but memcached won't work as well. Check first if the connection string is valid.

Example

memcached.servers("localhost,anotherhost:12345");

memcached.servers("--SERVER=localhost --SERVER=anotherhost:12345");

// with consistent hashing enabled
memcached.servers("--SERVER=localhost --SERVER=anotherhost:12345 --DISTRIBUTION=consistent");

// with consistent hashing enabled and namespace
memcached.servers({"--SERVER=web1.gloople:11211 --SERVER=web2.gloople:11211 --DISTRIBUTION=consistent --NAMESPACE="memc.sess.key.""});

behavior_set

Prototype

behavior_set(STRING memcached_behavior_flag, STRING memcached_behavior_value)

Return value

NONE

Description

Change the value for particular options of the memcached client. This is not an exhaustive implementation and not all flags/values are available. See memcached_behavior(3) for more detail on behaviors. Only that shown in the example below is available.

Example

memcached.behavior_set("MEMCACHED_BEHAVIOR_DISTRIBUTION", "MEMCACHED_DISTRIBUTION_CONSISTENT");

get

Prototype

STRING get(STRING key)

Return value

STRING V

Description

Retrieve key from memcached, returns string value.

Example

memcached.servers("localhost");

set resp.http.hello = memcached.get("your_memcached_key");

set

Prototype

set(STRING key, STRING value, INT expiration, INT flags)

Return value

NONE

Description

Set key to value, with an expiration time and flags.

Example

memcached.servers("localhost");

memcached.set("your_memcached_key", "Hello, World", 100, 0);

set resp.http.hello = memcached.get("your_memcached_key");

incr

Prototype

INT incr(STRING key, INT offset)

Return value

INT

Description

Increment key by offset, unless key is not set. Return value is 0 if not set.

Example

memcached.servers("localhost");

memcached.set("your_counter", "1", 100, 0);

memcached.incr("your_counter", 10);

set resp.http.count = memcached.incr("your_counter", 1);

// Header value is Count: 12

decr

Prototype

INT decr(STRING key, INT offset)

Return value

INT

Description

Decrement key by offset, unless key is not set. Return value is 0 if not set.

Example

memcached.servers("localhost");

memcached.set("your_counter", "10", 100, 0);

memcached.decr("your_counter", 8);

set resp.http.count = memcached.decr("your_counter", 1);

// Header value is Count: 1

INSTALLATION

If you received this packge without a pre-generated configure script, you must have the GNU Autotools installed, and can then run the 'autogen.sh' script. If you received this package with a configure script, skip to the second command-line under Usage to configure.

Usage:

# Generate configure script
./autogen.sh

# Execute configure script
./configure VARNISHSRC=DIR [VMODDIR=DIR] [PKG_CONFIG=PATH] [LIBMEMCACHED_CFLAGS=COMPILE] [LIBMEMCACHED_LIBS=LINK]

VARNISHSRC is the directory of the Varnish source tree for which to compile your vmod. Both the VARNISHSRC and VARNISHSRC/include will be added to the include search paths for your module.

Optionally you can also set the vmod install directory by adding VMODDIR=DIR (defaults to the pkg-config discovered directory from your Varnish installation).

The configure script uses pkg-config to find the libmemcached library. You may specify the pkg-config binary by setting the PKG_CONFIG option. If you do not wish to use pkg-config, you may set LIBMEMCACHED_CFLAGS and LIBMEMCACHED_LIBS as necessary to compile and link with libmemcached.

Make targets:

• make - builds the vmod
• make install - installs your vmod in VMODDIR
• make check - runs the unit tests in src/tests/*.vtc

SEE ALSO

• http://memcached.org/
• http://libmemcached.org/

HISTORY

The first revision of this document sketches out a rough plan for approaching a general purpose memcached client module for Varnish. More features are sure to be added as we go along.

This manual page is based on the template man page from libvmod-example.

COPYRIGHT

• Copyright (c) 2012 Aaron Stone
• See COPYING for copyright holders and descriptions.
• See LICENSE for full copyright terms.