Op 28-10-2015 om 9:28 schreef Thierry FOURNIER:
Hi List,

I wrote a Lua advanced documentation. This explain the Lua integration
in HAProxy, the reason of some choices. Some traps and Lua code with
advanced comments.

This doc is not terminated, but I want to release a first version. I
will fill the missing points later.

unfortunatelly I have some difficulties to write in english, if anyone
wants to correct my doc, it will be welcome.

Thank you,
Hi Thierry,

Thanks for the doc !
Ive changed a few words here and there.. Updated doc attached.
Probably there is some more to correct for the more native English speaking/writing people.

I haven't tried to check it myself, but didn't see it in either of the documents how often is a function from core.register_task called? Or should it contain a loop+sleep ? Perhaps a small example could be added?


HAProxy is a powerful load balancer. It embeds many options and many
configuration styles in order to give a solution to many load balancing
problems. However, HAProxy is not universal and some special or specific
problems doesn't have solution with the native software.

This text is not a full explanation of the Lua syntax.

This text is not a replacement of the HAProxy Lua API documentation. The API
documentation can be found at the project root, in the documentation directory. 
The goal of this text is to discover how Lua is implemented in HAProxy and using
it efficiently.

However, this can be read by Lua beginners. Some examples are detailed.

Why a scripting language in HAProxy

HAProxy 1.5 makes at possible to do many things using samples, but some people
wants to more combining results of samples fetches, programming conditions and
loops which is not possible. Sometimes people implement these functionalities
in patches which have no meaning outside their network. These people must
maintain these patches, or worse we must integrate them in the HAProxy

Their need is to have an embedded programming language in order to no longer
modify the HAProxy source code, but to write their own control code. Lua is
encountered very often in the software industry, and in some open source
projects. It is easy to understand, efficient, light without external
dependencies, and leaves the resource control to the implementation. Its design
is close to the HAProxy philosophy which uses components for what they do

The HAProxy control block allows one to take a decision based on the comparison
between samples and patterns. The samples are extracted using fetch functions
easily extensible, and are used by actions which are also extensible. It seems
natural to allow Lua to give samples, modify them, and to be an action target.
So, Lua uses the same entities as the configuration language. This is the most
natural and reliable way fir the Lua integration. So, the Lua engine allow one
to add new sample fetch functions, new converter functions and new actions.
These new entities can access the existing samples fetches and converters
allowing to extend them without rewriting them.

The writing of the first Lua functions shows that implementing complex concepts
like protocol analysers is easy and can be extended to full services. It appears
that these services are not easy to implement with the HAProxy configuration
model which is base on four steps: fetch, convert, compare and action. HAProxy
is extended with a notion of services which are a formalisation of the existing
services like stats, cli and peers. The service is an autonomous entity with a
behaviour pattern close to that of an external client or server. The Lua engine
inherits from this new service and offers new possibilities for writing

This scripting language is useful for testing new features as proof of concept.
Later, if there is general interest, the proof of concept could be integrated
with C language in the HAProxy core.

The HAProxy Lua integration also provides also a simple way for distributing Lua
packages. The final user needs only to install the Lua file, load it in HAProxy
and follow the attached documentation.

Design and technical things

Lua is integrated in the HAProxy event driven core. We want to preserve the
fast processing of HAProxy. To ensure this, we implement some technical concepts
between HAProxy and the Lua library.

The following paragraph describes also the interactions between Lua and HAProxy
with a technical point of view.


Reading the following documentation links are required to understand the
current paragraph:

   HAProxy doc: http://cbonte.github.io/haproxy-dconv/configuration-1.6.html
   Lua API:     http://www.lua.org/manual/5.3/
   HAProxy API: http://www.arpalert.org/src/haproxy-lua-api/1.6/index.html
   Lua guide:   http://www.lua.org/pil/

more about Lua choice

Lua language is very easy to extend. It is trivial to add new functions writted
in C in the core language. It not require to embbed very intrusive library, and
we do not change compilation processes.

The amount of memory consumed can be controlled, and the issues due to lack of
memory are perfectly caught. The max amount of memory allowed for the Lua
processes is configurable. If some memory miss, the current Lua action fails,
and the HAProxy processing flow continue.

Lua provides a way for implementing event driven design. When the Lua code
wants to do blocking action, the action is started, it executes non blocking
operations, and give back the hand to the HAProxy scheduler when it needs to
wait for some external event.

The Lua process can be interrupted after a number of instructions executed. The
Lua execution will resumed later. This is a useful way for controlling the
execution time. In other way this system keeps HAProxy responsive. When the Lua
execution is interrupted, HAProxy accept some connections or transfer pending
data. The Lua execution don't block the main HAProxy processing, except in some
cases which we will see later.

Lua function integration

The Lua actions, sample fetches, converters and services are integrated in
HAProxy with "register_*" functions. The register system is a choice for
providing HAProxy Lua packages easily. The register system adds new sample
fetches, converters, actions or services usable in the HAProxy configuration

The register system are defined in the "core" functions collection. This
collection is provided by HAProxy and its always available. Below, the list of
these functions:

 - core.register_action()
 - core.register_converters()
 - core.register_fetches()
 - core.register_init()
 - core.register_service()
 - core.register_task()

These functions are the execution entry points.

HTTP action must be used for manipulating HTTP request headers. This action
can not manipulates HTTP content. It is dangerous to use the channel
manipulation object with an HTTP request in an HTTP action. The Channel
manipulation can transform a valid request in an invalid request, in this case,
the action will never resumed and the processing will be frozen. HAProxy
discard the request after the reception timeout.

Non blocking design

HAProxy is an event driven software, so the blocking system calls are absolutely
forbidden. However, the Lua allow to do blocking actions. When an action blocks
HAProxy is waiting and do nothing, so the basic functionalities like accepting
connections or forwarding data are blocked while the end of the system call. In
this case HAProxy will be less responsive.

This is very insidious because when the developer tries to execute its Lua code
with only one stream, HAProxy seems to run. When the code is used with
production stream, HAProxy encounters some slow processing, and HAProxy cannot
hold the load.

However, during the initialisation state, you can obviously using blocking
functions. There are typically used for loading files.

The lists of prohibited standard Lua functions during the runtime are all that
do filesystem access:

 - os.remove()
 - os.rename()
 - os.tmpname()
 - package.*()
 - io.*()
 - file.*()

Some other functions are prohibited:

 - os.execute(), waits for the end of the required execution blocking HAProxy.

 - os.exit(), is not really dangerous for the process, but its not the good way
              for exiting the HAProxy process.

 - print(), write data on stdout. In some cases these writes are blocking, the
            best practice is reserving this call for debugging. We must prefer
            to use core.log() or TXN.log() for sending messages.

Some HAProxy functions have a blocking behaviour pattern in the Lua code, but
there are compatible with the non blocking design. These functions are:

 - All the socket class
 - core.sleep()

Responsive design

HAProxy must process connexions accept, forwarding data and processing timeouts
as soon as possible. The first thing is to believe that a Lua script with a long
execution time should impact the expected responsive behaviour.

It is not the case, the Lua script are regularly interrupted, and HAProxy can
process other things. These interruptions are exprimed in number of Lua
instructions. There are configured with the tune option:


When HAProxy interrupts the Lua processing, we have two states possibles:

 - Lua is resumable, and it give back the hand to the HAProxy scheduler,
 - Lua is not resumable, and we just check the execution timeout.

The second case occurs if it is required by the HAProxy core. It require this
state if the Lua is processed in a non resumable HAProxy part like sample
fetches or converters.

It occurs also if the Lua is non resumable. For example, if some code is called
in through the Lua pcall() function, the execution is not resumable. This is
explained later.

So, the Lua code must be fast and simple when is executed as sample fetches and
converters, it could be slow and complex when is executed as actions and

Execution time

The Lua execution time is measured and limited. Each group of functions have its
own timeout configured. The time measured is the real Lua execution time, and
not the difference between the end time and the start time. The groups are:

 - main code and init are not submitted to the timeout,
 - fetches, converters and action have a default timeout of 4s,
 - task, by default does not have timeout,
 - service have a default timeout of 4s.

The corresponding tune option are:

 - tune.lua.session-timeout (fetches, converters and action)
 - tune.lua.task-timeout    (task)
 - tune.lua.service-timeout (services)

The tasks does not have a timeout because it runs in background along the
HAProxy process life.

For example, if an Lua script is executed during 1,1s and the script executes a
sleep of 1 second, the effective measured running time is 0,1s.

This timeout is useful for preventing infinite loops. During the runtime, it
should never triggered.

The stack and the coprocess

The Lua execution is organized around a stack. Each Lua action, even out of the
effective execution, affects the stack. HAProxy integration uses one main stack,
which is common for all the process, and a secondary one used as coprocess.
After the initialization, the main stack is no longer used by HAProxy, except
for global storage. The second type of stack is used by all the Lua functions
called from different Lua actions declared in HAProxy. The main stack permits
to store coroutines pointers, and some global variables.

Do you want to see an example of how seems Lua C development around a stack ?
Some examples follows. This first one, is a simple addition:

   lua_pushnumber(L, 1)
   lua_pushnumber(L, 2)
   lua_arith(L, LUA_OPADD)

Its easy, we push 1 on the stack, after, we push 2, and finally, we perform an
addition. The two top entries of the stack are added, poped, and the result is
pushed. It is a classic way with a stack.

Now an example for constructing array and objects. Its little bit more
complicated. The difficult consist to keep in mind the state of the stack while
we write the code. The goal is to create the entity described below. Note that
the notation "*1" is a metatable reference. The metatable will be explained

   name*1 = {
      [0] = <userdata>,

   *1 = {
      "__index" = {
         "method1" = <function>,
         "method2" = <function>
      "__gc" = <function>

Let's go:

   lua_newtable()               // The "name" table
   lua_newtable()               // The metatable *1
   lua_newtable()               // The "__index" table
   lua_settable(-3)             // -3 is an index in the stack. insert method1
   lua_settable(-3)             // insert method2
   lua_settable(-3)             // insert "__index"
   lua_settable()               // insert "__gc"
   lua_setmetatable(-1)         // attach metatable to "name"

So, coding for Lua in C, is not complex, but it needs some mental gymnastic.

The object concept and the HAProxy format

The objects seems to not be a native concept. An Lua object is a table. We can
note that the table notation accept three forms:

   1. mytable["entry"](mytable, "param")
   2. mytable.entry(mytable, "param")
   3. mytable:entry("param")

These three notation have the same behaviour pattern: a function is executed
with the itself table as first parameter and string "param" as second parameter
The notation with [] is commonly used for storing data in a hash table, and the
dotted notation is used for objects. The notation with ":" indicates that the
first parameter is the element at the left of the symbol ":".

So, an object is a table and each entry of the table is a variable. A variable
can be a function. These are the first concepts of the object notation in the
Lua, but it is not the end.

With the objects, we usually expect classes and inheritance. This is the role of
the metable. A metable is a table with predefined entries. These entries modify
the default behaviour of the table. The simplest example is the "__index" entry.
If this entry exists, it is called when a value is requested in the table. The
behaviour is the following:

   1 - looks in the table if the entry exists, and if it the case, return it

   2 - looks if a metatable exists, and if the "__index" entry exists

   3 - if "__index" is a function, execute it with the key as parameter, and
       returns the result of the function.

   4 - if "__index" is a table, looks if the requested entry exists, and if
       exists, return it.

   5 - if not exists, return to step 2 

The behaviour of the point 5 represents the inheritance.

In HAProxy all the provided objects are tables, the entry "[0]" contains private
data, there are often userdata or lightuserdata. The matatable is registered in
the global part of the main Lua stack, and it is called with the case sensitive
class name. A great part of these class must not be used directly because it
requires an initialisation using the HAProxy internal structs.

The HAProxy objects uses unified conventions. An Lua object is always a table.
In most cases, an HAProxy Lua object need some private data. These are always
set in the index [0] of the array. The metatable entry "__tostring" returns the
object name.

The Lua developer can add entries to the HAProxy object. He just works carefully
and prevent to modify the index [0].

Common HAproxy objects are:

 - TXN        : manipulates the transaction between the client and the server
 - Channel    : manipulates proxified data between the client and the server
 - HTTP       : manipulates HTTP between the client and the server
 - Map        : manipulates HAProxy maps.
 - Fetches    : access to all HAProxy sample fetches
 - Converters : access to all HAProxy sample converters
 - AppletTCP  : process client request like a TCP server 
 - AppletHTTP : process client request like an HTTP server
 - Socket     : establish tcp connection to a server (ipv4/ipv6/socket/ssl/...)

The garbage collector and the memory allocation

Lua doesn't really have a global memory limit, but HAProxy implements it. This
permits to control the amount of memory dedicated to the Lua processes. It is
specially useful with embedded environments.

When the memory limit is reached, HAProxy refuses to give more memory to the Lua
scripts. The current Lua execution is terminated with an error and HAProxy
continue its processing.

The max amount of memory is configured with the option:


As many other script languages, Lua uses a garbage collector for reusing its
memory. The Lua developper can work without memory preoccupation. Usually, the
garbage collector is controlled by the Lua core, but sometimes it will be useful
to run when the user/developer requires. So the garbage collector can be called
from C part or Lua part.

Sometimes, objects using lightuserdata or userdata requires to free some memory
block or close filedescriptor not controlled by the Lua. A dedicated garbage
collection function is providedthrought the metatable. It is referenced with the
special entry "__gc".

Generally, in HAProxy, the garbage collector does this job without any
intervention. However some object uses a great amount of memory, and we want to
release as quick as possible. The problem is that only the GC knows if the 
is in use or not. The reason is simple variable containing objects can be shared
between coroutines and the main thread, so an object can used everywhere in

The only one example is the HAProxy sockets. These are explained later, just for
understanding the GC issues, a quick overview of the socket follows. The HAProxy
socket uses an internal session and stream, these sessions uses resources like
memory and file descriptor and in some cases keeps a socket open while it is no
loner used by Lua.

If the HAProxy socket is used, we forcing a garbage collector cycle after the
end of each function using HAProxy socket. The reason is simple: if the socket
is no longer used, we want to close the connection quickly.

A special flag is used in HAProxy indicating that a HAProxy socket is created.
If this flag is set, a full GC cycle is started after each Lua action. This is
not free, we loose about 10% of performances, but it is the only way for closing
sockets quickly.

The yield concept / longjmp issues

The "yield" is an action which does some Lua processing in pause and give back
the hand to the HAProxy core. This action is do when the Lua needs to wait about
data or other things. The most basically example is the sleep() function. In a
event driven software the code must not process blocking systems call, so the
sleep blocks the software between a lot of time. In HAProxy, an Lua sleep does a
yield, and ask to the scheduler to be waked up in a required sleep time.
Meanwhile, the HAProxy scheduler dos other things, like accepting new connection
or forwarding data.

A yield is also executed regularly, after a lot of Lua instruction processed.
This yield permits to control the effective execution time, and also give back
the hand to the haproxy core. When HAProxy finish to process the pending jobs,
the Lua execution continue.

This special "yield" uses the Lua "debug" functions. Lua provides a debug method
called "lua_sethook()" which permits to interrupt the execution after some
configured condition and call a function. This condition used in HAProxy is
a number of instruction processed and when a function returns. The function
called controls the effective execution time, and if it is possible send a

The yield system is based on a couple setjmp/longjmp. In brief, the setjmp()
stores a stack state, and the longjmp restores the stack in its state which had
before the last Lua execution.

Lua can immediately stop is execution if an error occurs. This system uses also
the longjmp system. In HAProxy, we try to use this sytem only for unrecoverable
errors. Maybe some trivial errors targets an exception, but we try to remove it.

It seems that Lua uses the longjmp system for having a behaviour like the java
try / catch. We can use the function pcall() to executes some code. The function
pcall() run a setjmp(). So, if any error occurs while the Lua code execution,
the flow immediately return from the pcall() with an error.

The big issue of this behaviour is that we cannot do a yield. So if some Lua 
executes a library using pcall for catching errors, HAProxy must be wait for the
end of execution without processing any accept or any stream. The cause is the
yield must be jump to the root of execution. The intermediate setjmp() avoid
this behaviour.

   HAproxy start Lua execution
     + Lua puts a setjmp()
        + Lua executes code
        + Some code is executed in a pcall()
           + pcall() puts a setjmp()
              + Lua executes code
                 + A yield is require for a sleep function
                   it cannot be jumps to the Lua root execution.

Another issue with the processing of strong errors is the manipulation of the
Lua stack outside of an Lua processing. If one of the functions called occurs a
strong error, the default behaviour is an abort(). It is not acceptable when
HAProxy is in runtime mode. The Lua documentation propose to use another
setjmp/longjmp to avoid the abort(). The goal is to puts a setjmp between
manipulating the Lua stack and using an alternative "panic" function which jumps
to the setjmp() in error case.

All of these behaviours are very dangerous for the stability, and the internal
HAProxy code must be modified with many precautions.

For preserving a good behaviour of HAProxy, the yield is mandatory.
Unfortunately, some HAProxy part are not adapted for resuming an execution after
a yield. These part are the sample fetches and the sample converters. So, the
Lua code written in these parts of HAProxy must be quickly executed, and can not
do actions which require yield like TCP connection or simple sleep.

HAproxy socket object

The HAProxy design is optimized for the data transfers between a client and a
server, and processing the many errors which can occurs during these exchanges.
HAProxy is not designed for having a third connection established to a third
party server.

The solution consist to puts the main stream in pause waiting for the end of the
exchanges with the third connection. This is completed by a signal between
internal tasks. The following graph shows the HAProxy Lua socket:

                      | Lua processing     |
 ------------------\  | creates socket     | ------------------\
  incoming request  > | and puts the       |  Outgoing request  >
 ------------------/  | current processing | ------------------/
                      | in pause waiting   |
                      | for TCP applet     |
                        ^               |
                        |               | 
                        | signal        | read / write
                        |               | data
                        |               |
          +-------------+---------+     v
          | HAProxy internal      +----------------+
          | applet send signals   |                |
          | when data is received |                | -------------------\
          | or some room is       |  Attached I/O  |  Client TCP stream  >
          | available             |  Buffers       | -------------------/
          +--------------------+--+                |
                               |                   |

A more detailed graph is available in the "doc/internals" directory.

The HAProxy Lua socket uses a full HAProxy session / stream for establishing the
connection. This mechanism provides all the facilities and HAProxy features,
like the SSL stack, many socket type, and support for namespaces.
Technically it support the proxy protocol, but there are no way to enable it.

How compiling HAProxy with Lua

HAProxy 1.6 requires Lua 5.3. Lua 5.3 offers some features which makes easy the
integration. Lua 5.3 is young, and some distros do not distribute it. Luckily,
Lua is a great product because it does not require exotic dependencies, and its
build process is really easy.

The compilation process for linux is easy:

 - download the source tarball
   wget http://www.lua.org/ftp/lua-5.3.1.tar.gz

 - untar it
   tar xf lua-5.3.1.tar.gz

 - enter the directory
   cd lua-5.3.1

 - build the library for linux
   make linux
 - install it:
   sudo make INSTALL_TOP=/opt/lua-5.3.1

HAProxy builds with your favourite options, plus the following options for
embedding the Lua script language:

 - download the source tarball
   wget http://<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

 - untar it
   tar xf haproxy-1.6.1.tar.gz

 - enter the directory
   cd haproxy-1.6.1

 - build HAProxy:
   make TARGET=linux \
        USE_DL=1 \
        USE_LUA=1 \
        LUA_LIB=/opt/lua-5.3.1/lib \

 - install it:
   sudo make PREFIX=/opt/haproxy-1.6.1 install

First steps with Lua

Now, its time to using Lua in HAProxy.

Start point

The HAProxy global directive "lua-load <file>" allow to load an lua file. This
is the entry point. This load become during the configuration parsing, and the
Lua file is immediately executed.

All the register_*() function must be called at this time because there are used
just after the processing of the global section, in the frontend/backend/listen

The most simple "Hello world !" is the following line a loaded Lua file:

   core.Alert("Hello World !");

It display a log during the HAProxy startup:

   [alert] 285/083533 (14465) : Hello World !

Default path and libraries

Lua can embed some libraries. These libraries can be included from different
paths. It seems that Lua doesn't like subdirectories. In the following example, 
try to load a compiled library, so the first line is Lua code, the second line
is an 'strace' extract proving that the library was opened. The next lines are
the associated error.


   open("./luac/concat.so", O_RDONLY|O_CLOEXEC) = 4

        [ALERT] 293/175822 (22806) : parsing [commonstats.conf:15] : lua runtime
        error: error loading module 'luac/concat' from file './luac/concat.so':
                ./luac/concat.so: undefined symbol: luaopen_luac/concat

Lua tries to load the C symbol 'luaopen_luac/concat'. When Lua tries to open a
library, it tries to execute the function associated to the symbol

The variable "<libname>" is defined using the content of the variable
"package.cpath" and/or "package.path". The default definition of the
"package.cpath" (on my computer is ) variable is:


The "<libname>" is the content which replaces the symbol "<?>". In th previous
example, its "luac/concat", and obviously the Lua core try to load the function
associated with the symbol "luaopen_luac/concat".

My conclusion is that Lua doesn't support subdirectories. So, for loading
libraries in subdirectory, it must fill the variable with the name of this
subdirectory. The extension .so must disappear, otherwise Lua try to execute the
function associated with the symbol "luaopen_concat.so". The following syntax is

   package.cpath = package.cpath .. ";./luac/?.so"

First useful example

   core.register_fetches("my-hash", function(txn, salt)
      return txn.sc:sdbm(salt .. txn.sf:req_fhdr("host") .. txn.sf:path() .. 
txn.sf:src(), 1)

You will see that these 3 line can generate a lot of explanations :)

Core.register_fetches() is executed during the processing of the global section
by the HAProxy configuration parser. A new sample fetch is declared with name
"my-hash", this name is always prefixed by "lua.". So this new declared
sample fetch will be used calling "lua.my-hash" in the HAProxy configuration

The second parameter is an inline declared anonymous function. Note the closed
parenthesis after the keyword "end" which end the function. The first parameter
of these anonymous function is "txn". It an object of class TXN. It provides
access functions. The second parameter is an arbitrary value provided by the
HAProxy configuration file. This parameter is optional, the developer must
check if its present.

The anonymous function registration is executed when the HAProxy backend or
frontend configuration references the sample fetch "lua.my-hash".

This example can writed with an other style, like below:

   function my_hash(txn, salt)
      return txn.sc:sdbm(salt .. txn.sf:req_fhdr("host") .. txn.sf:path() .. 
txn.sf:src(), 1)

   core.register_fetches("my-hash", my_hash)

This second form is clearer, but the first one is compact.

The operator ".." is a string concatenation. If one of the two operands are not 
string, an error occurs and the execution is immediately stopped. This is
important to keep in mind for the following things.

Now I write the example on more than one line. Its an easiest way for commenting
the code:

    1. function my_hash(txn, salt)
    2.    local str = ""
    3.    str = str .. salt
    4.    str = str .. txn.sf:req_fhdr("host")
    5.    str = str .. txn.sf:path()
    6.    str = str .. txn.sf:src()
    7.    local result = txn.sc:sdbm(str, 1)
    8.    return result
    9. end
   11. core.register_fetches("my-hash", my_hash)


The first keyword is "local". This is a really important keyword. You must
understand that the function "my_hash" will be called for each HAProxy request
using the declared sample fetch. So, this function can be executed many times in

By default, Lua uses global variables. so in this example, il the variable "str"
is declared without the keyword "local", it will be shared by all the parallel
executions of the function and obviously, the content of the requests will be

This warning is very important. I tried to write useful Lua code like a rewrite
of the statistics page, and its very hard to thing to declare each variable as

I guess than this behaviour will be the cause of many trouble on the mailing

str = str ..

Now a parenthesis about the form "str = str ..". This form allow to do string
concatenations. Remember that Lua uses a garbage collector, so what happens when
we do "str = str .. 'another string'" ?

   str = str .. "another string"
   ^     ^   ^  ^
   1     2   3  4

Lua execute first the concatenation operator (3), it allocates memory for the
resulting string and fill this memory with the concatenation of the operands 2
and 4. Next, it free the variable 1, now the old content of 1 can be garbage
collected. and finally, the new content of 1 is the concatenation.

what the matter ? when we do this operation many times, we consume a lot of
memory, and the string data is duplicated and move many times. So, this practice
is expensive in execution time and memory consumption.

There are easy ways to prevent this behaviour. I guess that a C binding for
concatenation with chunks will be available ASAP (it is already written). I do
some benchmarks. I compare the execution time of 1 000 times, 1 000
concatenation of 10 bytes written in pure Lua and with a C library. The result 
10 times faster in C (1s in Lua, and 0.1s in C).


txn is an HAProxy object of class TXN. The documentation is available in the
HAProxy Lua API reference. This class allow the access to the native HAProxy
sample fetches and converters. The object txn contains 2 members dedicated to
the sample fetches and 2 members dedicated to the converters.

The sample fetches members are "f" (as sample-Fetch) and "sf" (as String
sample-Fetch). These two members contains exactly the same functions. All the
HAProxy native sample fetches are available, obviously, the Lua registered 
fetches are not available. Unfortunately, HAProxy sample fetches names are not
compatible with the Lua function names, and they are renames. The rename
convention is simple, we replace all the '.', '+' and '-' by '_'. The '.' is the
object member separator, and the "-" and "+" is math operator.

Now, that I'm writing this article, I known the Lua better than I wrote the
sample-fetches wrapper. The original HAProxy sample-fetches name should be used
using alternative manner to call an object member, so the sample-fetch
"req.fhdr" (actually renamed req_fhdr") is should be used like this:

   txn.f["req.fhdr"](txn.f, ...)

However, I think that this form is not elegant.

The "s" collection return a data with a type near to the original returned type.
A string return an Lua string, an integer returns an Lua integer and an IP
address returns an Lua string. Sometime the data is not or not yet available, in
this case it returns the Lua nil value.

The "sf" collection guarantee that a string will be always returned. If the data
is not available, an empty string is returned. The main usage of these 
is to concatenate the returned sample-fetches without testing each function.

The parameters of the sample-fetches are according with the haproxy

The converters runs exactly with the same manner as the sample fetches. The
only one difference is that the fist parameter is the converter entry element.
The "c" collection returns a precise result, and the "sc" collection returns
always a string. 

The sample-fetches used in the example function are "txn.sf:req_fhdr()",
"txn.sf:path()" and "txn.sf:src()". The converter are "txn.sc:sdbm()". The same
function with the "s" collection of sample-fetches and the "c" collection of
converter should be written like this:

    1. function my_hash(txn, salt)
    2.    local str = ""
    3.    str = str .. salt
    4.    str = str .. tostring(txn.f:req_fhdr("host"))
    5.    str = str .. tostring(txn.f:path())
    6.    str = str .. tostring(txn.f:src())
    7.    local result = tostring(txn.c:sdbm(str, 1))
    8.    return result
    9. end
   11. core.register_fetches("my-hash", my_hash)


The function tostring ensure that its parameter is returned as a string. If the
parameter is a table or a thread or anything that will not have any sense as a
string, a form like the typename followed by a pointer is returned. For example:

   t = {}


   table: 0x15facc0

For objects, if the special function __tostring() is registered in the attached
metatable, it will be called with the table itself as first argument. The
HAProxy objects returns its own type.

About the converters entry point

In HAProxy, a converter is a stateless function that takes a data as entry and
returns a transformation of this data as output. In Lua it is exactly the same

So, the registered Lua function doesn't have any special parameters, juste a
variable as input which contains the value to convert, and it must return data.

The data required as input by the Lua converter is a string. So HAProxy will
always provide a string as input. If the native sample fetch is not a string it
will ne converted in best effort.

The returned value will have anything type, it will be converted as sample of
the near HAProxy type. The conversion rules from Lua variables to HAProxy
samples are:

   Lua        | HAProxy sample types
   "number"   | "sint"
   "boolean"  | "bool"
   "string"   | "str"
   "userdata" | "bool" (false)
   "nil"      | "bool" (false)
   "table"    | "bool" (false)
   "function" | "bool" (false)
   "thread"   | "bool" (false)

The function used for registering a converter is:


Storing Lua variable between function in the same session

All the functions registered as action or sample fetch can share an Lua context.
This context is a memory zone in the stack. sample fetch and action uses the
same stack, so both can access to the context.

The context is accessible via the function get_priv and set_priv provided by an
object of class TXN. The value given to set_priv replaces the current stored
value. This value can be a table, it is useful if a lot of data can be shared.

If the value stored is a table, you can add or remove entries from the table
without storing again the new table. Maybe an example will be clearer:

   local t = {}

   t["entry1"] = "foo"
   t["entry2"] = "bar"

   -- this will display "foo"

HTTP actions

Lua is fast, but my service require more execution speed

We can wrote C modules for Lua. These modules must run with HAProxy while they
are compliant with the HAProxy Lua version. A simple example is the "concat"

It is very easy to write and compile a C Lua library, however, I don't see
documentation about this process. So the current chapter is a quick howto.

The entry point

The entry point is called "luaopen_<name>", where <name> is the name of the 
file. An hello world is like this:

   #include <stdio.h>
   #include <lua.h>
   #include <lauxlib.h>

   int luaopen_mymod(lua_State *L)
      printf("Hello world\n");
      return 0;

The build

The compilation of the source file requires the Lua "include" directory. The
compilation and the link of the object file requires the -fPIC option. Thats

   cc -I/opt/lua/include -fPIC -shared  -o mymod.so mymod.c


You can load this module with the following Lua syntax:


When you start HAProxy, this module just print "Hello world" when its loaded.
Please, remember that HAProxy doesn't allow blocking method, so if you write a
function doing filesystem access or synchronous network access, all the HAProxy
process will fail.

Reply via email to