Varnish lua vmod to execute lua script in VCL.
C Makefile Shell
Latest commit f7a9fe1 Mar 6, 2016 @flygoast Updated README.rst.
Permalink
Failed to load latest commit information.
debian
examples
m4
src
LICENSE
Makefile.am
README.rst
autogen.sh
configure.ac

README.rst

vmod_lua

Varnish Lua Module

Author: Gu Feng
Date: 2016-03-05
Version: 0.6
Manual section:3

SYNOPSIS

vcl

import lua;

sub vcl_init {
    lua.init("/path/to/?.lua", "/path/to/?.so", "/path/to/lua/foo.lua");
    return (ok);
}

sub vcl_fini {
    lua.cleanup();
    return (ok);
}

sub vcl_deliver {
    set resp.http.x-FOO = lua.call("foobar");
}

foo.lua

function foobar()
    local resp = "X-Foo-Header-Is-" .. varnish.req.http["X-Foo"]
    return resp
end

DESCRIPTION

Varnish lua vmod is a module to let you can execute lua script in VCL. VCL variables exported as Lua global variables:

  • varnish.req.*
  • varnish.bereq.*
  • varnish.beresp.*
  • varnish.resp.*

For example, you can got user-agent header of request:

ua = varnish.req.http["User-Agent"]

These variables are read only.

STATUS

Proof of concept

FUNCTIONS

init

Prototype
init(STRING path, STRING cpath, STRING luafile)
Return value
VOID
Description
Initialize a lua state struct to be used. Param 'path' and 'cpath' used to specify Lua search paths. Param 'luafile' specified the lua script need to run. It should be called in vcl_init.
Example
lua.init("/path/to/?.lua", "/path/to/?.so", "/path/to/foo.lua");

call

Prototype
call(STRING S)
Return value
STRING
Description
Execute the lua function specified by S, and return a string or nil.
Example
set resp.http.x-lua = lua.call("foobar");

cleanup

Prototype
cleanup()
Return value
VOID
Description
Release the resource used by Lua. It should be called in vcl_fini.
Example
lua.cleanup();

DEPENDENCIES

or

INSTALLATION

The source tree is based on autotools to configure the building, and does also have the necessary bits in place to do functional unit tests using the varnishtest tool.

Usage:

export LUA_INC=/path/to/luainc
export LUA_LIB=/path/to/lualib
sh ./autogen.sh
./configure VARNISHSRC=DIR [VMODDIR=DIR]

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).

Make targets:

  • make - builds the vmod
  • make install - installs your vmod in VMODDIR

NOTE

  • Branch 3.0 is for Varnish 3.0.x
  • Branch 4.1 is for Varnish 4.1.x

If you want to load C modules compiled for Lua with require(), you need to make shure the public symbols (e.g. lua_setmetatable) are exported.

  • Link liblua or libluajit to the varnishd binary file

or

  • Link liblua or libluajitevery to every C modules

COPYRIGHT

This document is licensed under the same license as the libvmod-lua project. See LICENSE for details.