blob: e7aa425d95b8cf210ea21c8070c4c0b5ce6f9059 [file] [log] [blame]
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001.. toctree::
2 :maxdepth: 2
3
4
5How Lua runs in HAProxy
6=======================
7
8HAProxy Lua running contexts
9----------------------------
10
11The Lua code executed in HAProxy can be processed in 2 main modes. The first one
12is the **initialisation mode**, and the second is the **runtime mode**.
13
14* In the **initialisation mode**, we can perform DNS solves, but we cannot
15 perform socket I/O. In this initialisation mode, HAProxy still blocked during
16 the execution of the Lua program.
17
18* In the **runtime mode**, we cannot perform DNS solves, but we can use sockets.
19 The execution of the Lua code is multiplexed with the requests processing, so
20 the Lua code seems to be run in blocking, but it is not the case.
21
22The Lua code is loaded in one or more files. These files contains main code and
23functions. Lua have 6 execution context.
24
251. The Lua file **body context**. It is executed during the load of the Lua file
26 in the HAProxy `[global]` section with the directive `lua-load`. It is
27 executed in initialisation mode. This section is use for configuring Lua
28 bindings in HAProxy.
29
David Carlier61fdf8b2015-10-02 11:59:38 +0100302. The Lua **init context**. It is a Lua function executed just after the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010031 HAProxy configuration parsing. The execution is in initialisation mode. In
32 this context the HAProxy environment are already initialized. It is useful to
33 check configuration, or initializing socket connections or tasks. These
34 functions are declared in the body context with the Lua function
35 `core.register_init()`. The prototype of the function is a simple function
36 without return value and without parameters, like this: `function fcn()`.
37
David Carlier61fdf8b2015-10-02 11:59:38 +0100383. The Lua **task context**. It is a Lua function executed after the start
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010039 of the HAProxy scheduler, and just after the declaration of the task with the
40 Lua function `core.register_task()`. This context can be concurrent with the
41 traffic processing. It is executed in runtime mode. The prototype of the
42 function is a simple function without return value and without parameters,
43 like this: `function fcn()`.
44
David Carlier61fdf8b2015-10-02 11:59:38 +0100454. The **action context**. It is a Lua function conditionally executed. These
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020046 actions are registered by the Lua directives "`core.register_action()`". The
47 prototype of the Lua called function is a function with doesn't returns
48 anything and that take an object of class TXN as entry. `function fcn(txn)`.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010049
505. The **sample-fetch context**. This function takes a TXN object as entry
51 argument and returns a string. These types of function cannot execute any
52 blocking function. They are useful to aggregate some of original HAProxy
53 sample-fetches and return the result. The prototype of the function is
54 `function string fcn(txn)`. These functions can be registered with the Lua
55 function `core.register_fetches()`. Each declared sample-fetch is prefixed by
56 the string "lua.".
57
58 **NOTE**: It is possible that this function cannot found the required data
59 in the original HAProxy sample-fetches, in this case, it cannot return the
60 result. This case is not yet supported
61
David Carlier61fdf8b2015-10-02 11:59:38 +0100626. The **converter context**. It is a Lua function that takes a string as input
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010063 and returns another string as output. These types of function are stateless,
64 it cannot access to any context. They don't execute any blocking function.
65 The call prototype is `function string fcn(string)`. This function can be
66 registered with the Lua function `core.register_converters()`. Each declared
67 converter is prefixed by the string "lua.".
68
69HAProxy Lua Hello world
70-----------------------
71
72HAProxy configuration file (`hello_world.conf`):
73
74::
75
76 global
77 lua-load hello_world.lua
78
79 listen proxy
80 bind 127.0.0.1:10001
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020081 tcp-request inspect-delay 1s
82 tcp-request content use-service lua.hello_world
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010083
84HAProxy Lua file (`hello_world.lua`):
85
86.. code-block:: lua
87
Thierry FOURNIERa2d02252015-10-01 15:00:42 +020088 core.register_service("hello_world", "tcp", function(applet)
89 applet:send("hello world\n")
90 end)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010091
92How to start HAProxy for testing this configuration:
93
94::
95
96 ./haproxy -f hello_world.conf
97
98On other terminal, you can test with telnet:
99
100::
101
102 #:~ telnet 127.0.0.1 10001
103 hello world
104
105Core class
106==========
107
108.. js:class:: core
109
110 The "core" class contains all the HAProxy core functions. These function are
111 useful for the controlling the execution flow, registering hooks, manipulating
112 global maps or ACL, ...
113
114 "core" class is basically provided with HAProxy. No `require` line is
115 required to uses these function.
116
David Carlier61fdf8b2015-10-02 11:59:38 +0100117 The "core" class is static, it is not possible to create a new object of this
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100118 type.
119
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100120.. js:attribute:: core.emerg
121
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100122 :returns: integer
123
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100124 This attribute is an integer, it contains the value of the loglevel "emergency" (0).
125
126.. js:attribute:: core.alert
127
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100128 :returns: integer
129
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100130 This attribute is an integer, it contains the value of the loglevel "alert" (1).
131
132.. js:attribute:: core.crit
133
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100134 :returns: integer
135
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100136 This attribute is an integer, it contains the value of the loglevel "critical" (2).
137
138.. js:attribute:: core.err
139
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100140 :returns: integer
141
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100142 This attribute is an integer, it contains the value of the loglevel "error" (3).
143
144.. js:attribute:: core.warning
145
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100146 :returns: integer
147
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100148 This attribute is an integer, it contains the value of the loglevel "warning" (4).
149
150.. js:attribute:: core.notice
151
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100152 :returns: integer
153
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100154 This attribute is an integer, it contains the value of the loglevel "notice" (5).
155
156.. js:attribute:: core.info
157
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100158 :returns: integer
159
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100160 This attribute is an integer, it contains the value of the loglevel "info" (6).
161
162.. js:attribute:: core.debug
163
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100164 :returns: integer
165
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100166 This attribute is an integer, it contains the value of the loglevel "debug" (7).
167
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100168.. js:attribute:: core.proxies
169
170 **context**: task, action, sample-fetch, converter
171
172 This attribute is an array of declared proxies (frontend and backends). Each
173 proxy give an access to his list of listeners and servers. Each entry is of
174 type :ref:`proxy_class`
175
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200176 Warning, if you are declared frontend and backend with the same name, only one
177 of these are listed.
178
179 :see: :js:attr:`core.backends`
180 :see: :js:attr:`core.frontends`
181
182.. js:attribute:: core.backends
183
184 **context**: task, action, sample-fetch, converter
185
186 This attribute is an array of declared proxies with backend capability. Each
187 proxy give an access to his list of listeners and servers. Each entry is of
188 type :ref:`proxy_class`
189
190 Warning, if you are declared frontend and backend with the same name, only one
191 of these are listed.
192
193 :see: :js:attr:`core.proxies`
194 :see: :js:attr:`core.frontends`
195
196.. js:attribute:: core.frontends
197
198 **context**: task, action, sample-fetch, converter
199
200 This attribute is an array of declared proxies with frontend capability. Each
201 proxy give an access to his list of listeners and servers. Each entry is of
202 type :ref:`proxy_class`
203
204 Warning, if you are declared frontend and backend with the same name, only one
205 of these are listed.
206
207 :see: :js:attr:`core.proxies`
208 :see: :js:attr:`core.backends`
209
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100210.. js:function:: core.log(loglevel, msg)
211
212 **context**: body, init, task, action, sample-fetch, converter
213
David Carlier61fdf8b2015-10-02 11:59:38 +0100214 This function sends a log. The log is sent, according with the HAProxy
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100215 configuration file, on the default syslog server if it is configured and on
216 the stderr if it is allowed.
217
218 :param integer loglevel: Is the log level asociated with the message. It is a
219 number between 0 and 7.
220 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100221 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
222 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
223 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
224 :see: :js:func:`core.Debug`
225 :see: :js:func:`core.Info`
226 :see: :js:func:`core.Warning`
227 :see: :js:func:`core.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100228
229.. js:function:: core.Debug(msg)
230
231 **context**: body, init, task, action, sample-fetch, converter
232
233 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100234 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100235
236 Does the same job than:
237
238.. code-block:: lua
239
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100240 function Debug(msg)
241 core.log(core.debug, msg)
242 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100243..
244
245.. js:function:: core.Info(msg)
246
247 **context**: body, init, task, action, sample-fetch, converter
248
249 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100250 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100251
252.. code-block:: lua
253
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100254 function Info(msg)
255 core.log(core.info, msg)
256 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100257..
258
259.. js:function:: core.Warning(msg)
260
261 **context**: body, init, task, action, sample-fetch, converter
262
263 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100264 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100265
266.. code-block:: lua
267
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100268 function Warning(msg)
269 core.log(core.warning, msg)
270 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100271..
272
273.. js:function:: core.Alert(msg)
274
275 **context**: body, init, task, action, sample-fetch, converter
276
277 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100278 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100279
280.. code-block:: lua
281
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100282 function Alert(msg)
283 core.log(core.alert, msg)
284 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100285..
286
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100287.. js:function:: core.add_acl(filename, key)
288
289 **context**: init, task, action, sample-fetch, converter
290
291 Add the ACL *key* in the ACLs list referenced by the file *filename*.
292
293 :param string filename: the filename that reference the ACL entries.
294 :param string key: the key which will be added.
295
296.. js:function:: core.del_acl(filename, key)
297
298 **context**: init, task, action, sample-fetch, converter
299
300 Delete the ACL entry referenced by the key *key* in the list of ACLs
301 referenced by *filename*.
302
303 :param string filename: the filename that reference the ACL entries.
304 :param string key: the key which will be deleted.
305
306.. js:function:: core.del_map(filename, key)
307
308 **context**: init, task, action, sample-fetch, converter
309
310 Delete the map entry indexed with the specified key in the list of maps
311 referenced by his filename.
312
313 :param string filename: the filename that reference the map entries.
314 :param string key: the key which will be deleted.
315
Thierry Fourniereea77c02016-03-18 08:47:13 +0100316.. js:function:: core.get_info()
317
318 **context**: body, init, task, action, sample-fetch, converter
319
320 Returns HAProxy core informations. We can found information like the uptime,
321 the pid, memory pool usage, tasks number, ...
322
323 These information are also returned by the management sockat via the command
324 "show info". See the management socket documentation fpor more information
325 about the content of these variables.
326
327 :returns: an array of values.
328
Thierry Fournierb1f46562016-01-21 09:46:15 +0100329.. js:function:: core.now()
330
331 **context**: body, init, task, action
332
333 This function returns the current time. The time returned is fixed by the
334 HAProxy core and assures than the hour will be monotnic and that the system
335 call 'gettimeofday' will not be called too. The time is refreshed between each
336 Lua execution or resume, so two consecutive call to the function "now" will
337 probably returns the same result.
338
339 :returns: an array which contains two entries "sec" and "usec". "sec"
340 contains the current at the epoch format, and "usec" contains the
341 current microseconds.
342
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100343.. js:function:: core.http_date(date)
344
345 **context**: body, init, task, action
346
347 This function take a string repsenting http date, and returns an integer
348 containing the corresponding date with a epoch format. A valid http date
349 me respect the format IMF, RFC850 or ASCTIME.
350
351 :param string date: a date http-date formatted
352 :returns: integer containing epoch date
353 :see: :js:func:`core.imf_date`.
354 :see: :js:func:`core.rfc850_date`.
355 :see: :js:func:`core.asctime_date`.
356 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
357
358.. js:function:: core.imf_date(date)
359
360 **context**: body, init, task, action
361
362 This function take a string repsenting IMF date, and returns an integer
363 containing the corresponding date with a epoch format.
364
365 :param string date: a date IMF formatted
366 :returns: integer containing epoch date
367 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
368
369 The IMF format is like this:
370
371.. code-block:: text
372
373 Sun, 06 Nov 1994 08:49:37 GMT
374..
375
376.. js:function:: core.rfc850_date(date)
377
378 **context**: body, init, task, action
379
380 This function take a string repsenting RFC850 date, and returns an integer
381 containing the corresponding date with a epoch format.
382
383 :param string date: a date RFC859 formatted
384 :returns: integer containing epoch date
385 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
386
387 The RFC850 format is like this:
388
389.. code-block:: text
390
391 Sunday, 06-Nov-94 08:49:37 GMT
392..
393
394.. js:function:: core.asctime_date(date)
395
396 **context**: body, init, task, action
397
398 This function take a string repsenting ASCTIME date, and returns an integer
399 containing the corresponding date with a epoch format.
400
401 :param string date: a date ASCTIME formatted
402 :returns: integer containing epoch date
403 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
404
405 The ASCTIME format is like this:
406
407.. code-block:: text
408
409 Sun Nov 6 08:49:37 1994
410..
411
412.. js:function:: core.rfc850_date(date)
413
414 **context**: body, init, task, action
415
416 This function take a string repsenting http date, and returns an integer
417 containing the corresponding date with a epoch format.
418
419 :param string date: a date http-date formatted
420
421.. js:function:: core.asctime_date(date)
422
423 **context**: body, init, task, action
424
425 This function take a string repsenting http date, and returns an integer
426 containing the corresponding date with a epoch format.
427
428 :param string date: a date http-date formatted
429
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100430.. js:function:: core.msleep(milliseconds)
431
432 **context**: body, init, task, action
433
434 The `core.msleep()` stops the Lua execution between specified milliseconds.
435
436 :param integer milliseconds: the required milliseconds.
437
Thierry Fournierf61aa632016-02-19 20:56:00 +0100438.. js:attribute:: core.proxies
439
440 **context**: body, init, task, action, sample-fetch, converter
441
442 proxies is an array containing the list of all proxies declared in the
443 configuration file. Each entry of the proxies array is an object of type
444 :ref:`proxy_class`
445
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100446.. js:function:: core.register_action(name, actions, func [, nb_args])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200447
448 **context**: body
449
David Carlier61fdf8b2015-10-02 11:59:38 +0100450 Register a Lua function executed as action. All the registered action can be
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200451 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
452 input.
453
454 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200455 :param table actions: is a table of string describing the HAProxy actions who
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200456 want to register to. The expected actions are 'tcp-req',
457 'tcp-res', 'http-req' or 'http-res'.
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100458 :param integer nb_args: is the expected number of argument for the action.
459 By default the value is 0.
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200460 :param function func: is the Lua function called to work as converter.
461
462 The prototype of the Lua function used as argument is:
463
464.. code-block:: lua
465
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100466 function(txn [, arg1 [, arg2]])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200467..
468
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100469 * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200470 current request or TCP stream.
471
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100472 * **argX**: this is argument provided throught the HAProxy configuration file.
473
Willy Tarreau61add3c2015-09-28 15:39:10 +0200474 Here, an exemple of action registration. the action juste send an 'Hello world'
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200475 in the logs.
476
477.. code-block:: lua
478
479 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
480 txn:Info("Hello world")
481 end)
482..
483
484 This example code is used in HAproxy configuration like this:
485
486::
487
488 frontend tcp_frt
489 mode tcp
490 tcp-request content lua.hello-world
491
492 frontend http_frt
493 mode http
494 http-request lua.hello-world
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100495..
496
497 A second example using aruments
498
499.. code-block:: lua
500
501 function hello_world(txn, arg)
502 txn:Info("Hello world for " .. arg)
503 end
504 core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2)
505..
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200506
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100507 This example code is used in HAproxy configuration like this:
508
509::
510
511 frontend tcp_frt
512 mode tcp
513 tcp-request content lua.hello-world everybody
514..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100515.. js:function:: core.register_converters(name, func)
516
517 **context**: body
518
David Carlier61fdf8b2015-10-02 11:59:38 +0100519 Register a Lua function executed as converter. All the registered converters
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100520 can be used in HAProxy with the prefix "lua.". An converter get a string as
521 input and return a string as output. The registered function can take up to 9
522 values as parameter. All the value are strings.
523
524 :param string name: is the name of the converter.
525 :param function func: is the Lua function called to work as converter.
526
527 The prototype of the Lua function used as argument is:
528
529.. code-block:: lua
530
531 function(str, [p1 [, p2 [, ... [, p5]]]])
532..
533
534 * **str** (*string*): this is the input value automatically converted in
535 string.
536 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
537 the haroxy configuration file. The number of arguments doesn't exceed 5.
538 The order and the nature of these is conventionally choose by the
539 developper.
540
541.. js:function:: core.register_fetches(name, func)
542
543 **context**: body
544
David Carlier61fdf8b2015-10-02 11:59:38 +0100545 Register a Lua function executed as sample fetch. All the registered sample
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100546 fetchs can be used in HAProxy with the prefix "lua.". A Lua sample fetch
547 return a string as output. The registered function can take up to 9 values as
548 parameter. All the value are strings.
549
550 :param string name: is the name of the converter.
551 :param function func: is the Lua function called to work as sample fetch.
552
553 The prototype of the Lua function used as argument is:
554
555.. code-block:: lua
556
557 string function(txn, [p1 [, p2 [, ... [, p5]]]])
558..
559
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100560 * **txn** (:ref:`txn_class`): this is the txn object associated with the current
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100561 request.
562 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
563 the haroxy configuration file. The number of arguments doesn't exceed 5.
564 The order and the nature of these is conventionally choose by the
565 developper.
566 * **Returns**: A string containing some data, ot nil if the value cannot be
567 returned now.
568
569 lua example code:
570
571.. code-block:: lua
572
573 core.register_fetches("hello", function(txn)
574 return "hello"
575 end)
576..
577
578 HAProxy example configuration:
579
580::
581
582 frontend example
583 http-request redirect location /%[lua.hello]
584
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200585.. js:function:: core.register_service(name, mode, func)
586
587 **context**: body
588
David Carlier61fdf8b2015-10-02 11:59:38 +0100589 Register a Lua function executed as a service. All the registered service can
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200590 be used in HAProxy with the prefix "lua.". A service gets an object class as
591 input according with the required mode.
592
593 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200594 :param string mode: is string describing the required mode. Only 'tcp' or
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200595 'http' are allowed.
596 :param function func: is the Lua function called to work as converter.
597
598 The prototype of the Lua function used as argument is:
599
600.. code-block:: lua
601
602 function(applet)
603..
604
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100605 * **applet** *applet* will be a :ref:`applettcp_class` or a
606 :ref:`applethttp_class`. It depends the type of registered applet. An applet
607 registered with the 'http' value for the *mode* parameter will gets a
608 :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets
609 a :ref:`applettcp_class`.
610
611 **warning**: Applets of type 'http' cannot be called from 'tcp-*'
612 rulesets. Only the 'http-*' rulesets are authorized, this means
613 that is not possible to call an HTTP applet from a proxy in tcp
614 mode. Applets of type 'tcp' can be called from anywhre.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200615
Willy Tarreau61add3c2015-09-28 15:39:10 +0200616 Here, an exemple of service registration. the service just send an 'Hello world'
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200617 as an http response.
618
619.. code-block:: lua
620
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100621 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200622 local response = "Hello World !"
623 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200624 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200625 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200626 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200627 applet:send(response)
628 end)
629..
630
631 This example code is used in HAproxy configuration like this:
632
633::
634
635 frontend example
636 http-request use-service lua.hello-world
637
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100638.. js:function:: core.register_init(func)
639
640 **context**: body
641
642 Register a function executed after the configuration parsing. This is useful
643 to check any parameters.
644
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100645 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100646
647 The prototype of the Lua function used as argument is:
648
649.. code-block:: lua
650
651 function()
652..
653
654 It takes no input, and no output is expected.
655
656.. js:function:: core.register_task(func)
657
658 **context**: body, init, task, action, sample-fetch, converter
659
660 Register and start independent task. The task is started when the HAProxy
661 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100662 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100663
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100664 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100665
666 The prototype of the Lua function used as argument is:
667
668.. code-block:: lua
669
670 function()
671..
672
673 It takes no input, and no output is expected.
674
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100675.. js:function:: core.register_cli([path], usage, func)
676
677 **context**: body
678
679 Register and start independent task. The task is started when the HAProxy
680 main scheduler starts. For example this type of tasks can be executed to
681 perform complex health checks.
682
683 :param array path: is the sequence of word for which the cli execute the Lua
684 binding.
685 :param string usage: is the usage message displayed in the help.
686 :param function func: is the Lua function called to handle the CLI commands.
687
688 The prototype of the Lua function used as argument is:
689
690.. code-block:: lua
691
692 function(AppletTCP, [arg1, [arg2, [...]]])
693..
694
695 I/O are managed with the :ref:`applettcp_class` object. Args are given as
696 paramter. The args embbed the registred path. If the path is declared like
697 this:
698
699.. code-block:: lua
700
701 core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5)
702 end)
703..
704
705 And we execute this in the prompt:
706
707.. code-block:: text
708
709 > prompt
710 > show ssl stats all
711..
712
713 Then, arg1, arg2 and arg3 will contains respectivey "show", "ssl" and "stats".
714 arg4 will contain "all". arg5 contains nil.
715
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100716.. js:function:: core.set_nice(nice)
717
718 **context**: task, action, sample-fetch, converter
719
720 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100721
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100722 :param integer nice: the nice value, it must be between -1024 and 1024.
723
724.. js:function:: core.set_map(filename, key, value)
725
726 **context**: init, task, action, sample-fetch, converter
727
728 set the value *value* associated to the key *key* in the map referenced by
729 *filename*.
730
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100731 :param string filename: the Map reference
732 :param string key: the key to set or replace
733 :param string value: the associated value
734
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100735.. js:function:: core.sleep(int seconds)
736
737 **context**: body, init, task, action
738
739 The `core.sleep()` functions stop the Lua execution between specified seconds.
740
741 :param integer seconds: the required seconds.
742
743.. js:function:: core.tcp()
744
745 **context**: init, task, action
746
747 This function returns a new object of a *socket* class.
748
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100749 :returns: A :ref:`socket_class` object.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100750
Thierry Fournier1de16592016-01-27 09:49:07 +0100751.. js:function:: core.concat()
752
753 **context**: body, init, task, action, sample-fetch, converter
754
755 This function retruns a new concat object.
756
757 :returns: A :ref:`concat_class` object.
758
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200759.. js:function:: core.done(data)
760
761 **context**: body, init, task, action, sample-fetch, converter
762
763 :param any data: Return some data for the caller. It is useful with
764 sample-fetches and sample-converters.
765
766 Immediately stops the current Lua execution and returns to the caller which
767 may be a sample fetch, a converter or an action and returns the specified
768 value (ignored for actions). It is used when the LUA process finishes its
769 work and wants to give back the control to HAProxy without executing the
770 remaining code. It can be seen as a multi-level "return".
771
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100772.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100773
774 **context**: task, action, sample-fetch, converter
775
776 Give back the hand at the HAProxy scheduler. It is used when the LUA
777 processing consumes a lot of processing time.
778
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100779.. js:function:: core.parse_addr(address)
780
781 **context**: body, init, task, action, sample-fetch, converter
782
783 :param network: is a string describing an ipv4 or ipv6 address and optionally
784 its network length, like this: "127.0.0.1/8" or "aaaa::1234/32".
785 :returns: a userdata containing network or nil if an error occurs.
786
787 Parse ipv4 or ipv6 adresses and its facultative associated network.
788
789.. js:function:: core.match_addr(addr1, addr2)
790
791 **context**: body, init, task, action, sample-fetch, converter
792
793 :param addr1: is an address created with "core.parse_addr".
794 :param addr2: is an address created with "core.parse_addr".
795 :returns: boolean, true if the network of the addresses matche, else returns
796 false.
797
798 Match two networks. For example "127.0.0.1/32" matchs "127.0.0.0/8". The order
799 of network is not important.
800
Thierry FOURNIER / OZON.IO8a1027a2016-11-24 20:48:38 +0100801.. js:function:: core.tokenize(str, separators [, noblank])
802
803 **context**: body, init, task, action, sample-fetch, converter
804
805 This function is useful for tokenizing an entry, or splitting some messages.
806 :param string str: The string which will be split.
807 :param string separators: A string containing a list of separators.
808 :param boolean noblank: Ignore empty entries.
809 :returns: an array of string.
810
811 For example:
812
813.. code-block:: lua
814
815 local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true)
816 print_r(array)
817..
818
819 Returns this array:
820
821.. code-block:: text
822
823 (table) table: 0x21c01e0 [
824 1: (string) "This"
825 2: (string) "function"
826 3: (string) "is"
827 4: (string) "useful"
828 5: (string) "for"
829 6: (string) "tokenizing"
830 7: (string) "an"
831 8: (string) "entry"
832 ]
833..
834
Thierry Fournierf61aa632016-02-19 20:56:00 +0100835.. _proxy_class:
836
837Proxy class
838============
839
840.. js:class:: Proxy
841
842 This class provides a way for manipulating proxy and retrieving information
843 like statistics.
844
Thierry FOURNIER817e7592017-07-24 14:35:04 +0200845.. js:attribute:: Proxy.name
846
847 Contain the name of the proxy.
848
Baptiste Assmann46c72552017-10-26 21:51:58 +0200849.. js:attribute:: Proxy.uuid
850
851 Contain the unique identifier of the proxy.
852
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100853.. js:attribute:: Proxy.servers
854
855 Contain an array with the attached servers. Each server entry is an object of
856 type :ref:`server_class`.
857
Thierry Fournierff480422016-02-25 08:36:46 +0100858.. js:attribute:: Proxy.listeners
859
860 Contain an array with the attached listeners. Each listeners entry is an
861 object of type :ref:`listener_class`.
862
Thierry Fournierf61aa632016-02-19 20:56:00 +0100863.. js:function:: Proxy.pause(px)
864
865 Pause the proxy. See the management socket documentation for more information.
866
867 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
868 proxy.
869
870.. js:function:: Proxy.resume(px)
871
872 Resume the proxy. See the management socket documentation for more
873 information.
874
875 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
876 proxy.
877
878.. js:function:: Proxy.stop(px)
879
880 Stop the proxy. See the management socket documentation for more information.
881
882 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
883 proxy.
884
885.. js:function:: Proxy.shut_bcksess(px)
886
887 Kill the session attached to a backup server. See the management socket
888 documentation for more information.
889
890 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
891 proxy.
892
893.. js:function:: Proxy.get_cap(px)
894
895 Returns a string describing the capabilities of the proxy.
896
897 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
898 proxy.
899 :returns: a string "frontend", "backend", "proxy" or "ruleset".
900
901.. js:function:: Proxy.get_mode(px)
902
903 Returns a string describing the mode of the current proxy.
904
905 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
906 proxy.
907 :returns: a string "tcp", "http", "health" or "unknown"
908
909.. js:function:: Proxy.get_stats(px)
910
911 Returns an array containg the proxy statistics. The statistics returned are
912 not the same if the proxy is frontend or a backend.
913
914 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
915 proxy.
916 :returns: a key/value array containing stats
917
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100918.. _server_class:
919
920Server class
921============
922
923.. js:function:: Server.is_draining(sv)
924
925 Return true if the server is currently draining stiky connections.
926
927 :param class_server sv: A :ref:`server_class` which indicates the manipulated
928 server.
929 :returns: a boolean
930
931.. js:function:: Server.set_weight(sv, weight)
932
933 Dynamically change the weight of the serveur. See the management socket
934 documentation for more information about the format of the string.
935
936 :param class_server sv: A :ref:`server_class` which indicates the manipulated
937 server.
938 :param string weight: A string describing the server weight.
939
940.. js:function:: Server.get_weight(sv)
941
942 This function returns an integer representing the serveur weight.
943
944 :param class_server sv: A :ref:`server_class` which indicates the manipulated
945 server.
946 :returns: an integer.
947
948.. js:function:: Server.set_addr(sv, addr)
949
950 Dynamically change the address of the serveur. See the management socket
951 documentation for more information about the format of the string.
952
953 :param class_server sv: A :ref:`server_class` which indicates the manipulated
954 server.
955 :param string weight: A string describing the server address.
956
957.. js:function:: Server.get_addr(sv)
958
959 Returns a string describing the address of the serveur.
960
961 :param class_server sv: A :ref:`server_class` which indicates the manipulated
962 server.
963 :returns: A string
964
965.. js:function:: Server.get_stats(sv)
966
967 Returns server statistics.
968
969 :param class_server sv: A :ref:`server_class` which indicates the manipulated
970 server.
971 :returns: a key/value array containing stats
972
973.. js:function:: Server.shut_sess(sv)
974
975 Shutdown all the sessions attached to the server. See the management socket
976 documentation for more information about this function.
977
978 :param class_server sv: A :ref:`server_class` which indicates the manipulated
979 server.
980
981.. js:function:: Server.set_drain(sv)
982
983 Drain sticky sessions. See the management socket documentation for more
984 information about this function.
985
986 :param class_server sv: A :ref:`server_class` which indicates the manipulated
987 server.
988
989.. js:function:: Server.set_maint(sv)
990
991 Set maintenance mode. See the management socket documentation for more
992 information about this function.
993
994 :param class_server sv: A :ref:`server_class` which indicates the manipulated
995 server.
996
997.. js:function:: Server.set_ready(sv)
998
999 Set normal mode. See the management socket documentation for more information
1000 about this function.
1001
1002 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1003 server.
1004
1005.. js:function:: Server.check_enable(sv)
1006
1007 Enable health checks. See the management socket documentation for more
1008 information about this function.
1009
1010 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1011 server.
1012
1013.. js:function:: Server.check_disable(sv)
1014
1015 Disable health checks. See the management socket documentation for more
1016 information about this function.
1017
1018 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1019 server.
1020
1021.. js:function:: Server.check_force_up(sv)
1022
1023 Force health-check up. See the management socket documentation for more
1024 information about this function.
1025
1026 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1027 server.
1028
1029.. js:function:: Server.check_force_nolb(sv)
1030
1031 Force health-check nolb mode. See the management socket documentation for more
1032 information about this function.
1033
1034 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1035 server.
1036
1037.. js:function:: Server.check_force_down(sv)
1038
1039 Force health-check down. See the management socket documentation for more
1040 information about this function.
1041
1042 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1043 server.
1044
1045.. js:function:: Server.agent_enable(sv)
1046
1047 Enable agent check. See the management socket documentation for more
1048 information about this function.
1049
1050 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1051 server.
1052
1053.. js:function:: Server.agent_disable(sv)
1054
1055 Disable agent check. See the management socket documentation for more
1056 information about this function.
1057
1058 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1059 server.
1060
1061.. js:function:: Server.agent_force_up(sv)
1062
1063 Force agent check up. See the management socket documentation for more
1064 information about this function.
1065
1066 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1067 server.
1068
1069.. js:function:: Server.agent_force_down(sv)
1070
1071 Force agent check down. See the management socket documentation for more
1072 information about this function.
1073
1074 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1075 server.
1076
Thierry Fournierff480422016-02-25 08:36:46 +01001077.. _listener_class:
1078
1079Listener class
1080==============
1081
1082.. js:function:: Listener.get_stats(ls)
1083
1084 Returns server statistics.
1085
1086 :param class_listener ls: A :ref:`listener_class` which indicates the
1087 manipulated listener.
1088 :returns: a key/value array containing stats
1089
Thierry Fournier1de16592016-01-27 09:49:07 +01001090.. _concat_class:
1091
1092Concat class
1093============
1094
1095.. js:class:: Concat
1096
1097 This class provides a fast way for string concatenation. The way using native
1098 Lua concatenation like the code below is slow for some reasons.
1099
1100.. code-block:: lua
1101
1102 str = "string1"
1103 str = str .. ", string2"
1104 str = str .. ", string3"
1105..
1106
1107 For each concatenation, Lua:
1108 * allocate memory for the result,
1109 * catenate the two string copying the strings in the new memory bloc,
1110 * free the old memory block containing the string whoch is no longer used.
1111 This process does many memory move, allocation and free. In addition, the
1112 memory is not really freed, it is just mark mark as unsused and wait for the
1113 garbage collector.
1114
1115 The Concat class provide an alternative way for catenating strings. It uses
1116 the internal Lua mechanism (it does not allocate memory), but it doesn't copy
1117 the data more than once.
1118
1119 On my computer, the following loops spends 0.2s for the Concat method and
1120 18.5s for the pure Lua implementation. So, the Concat class is about 1000x
1121 faster than the embedded solution.
1122
1123.. code-block:: lua
1124
1125 for j = 1, 100 do
1126 c = core.concat()
1127 for i = 1, 20000 do
1128 c:add("#####")
1129 end
1130 end
1131..
1132
1133.. code-block:: lua
1134
1135 for j = 1, 100 do
1136 c = ""
1137 for i = 1, 20000 do
1138 c = c .. "#####"
1139 end
1140 end
1141..
1142
1143.. js:function:: Concat.add(concat, string)
1144
1145 This function adds a string to the current concatenated string.
1146
1147 :param class_concat concat: A :ref:`concat_class` which contains the currently
1148 builded string.
1149 :param string string: A new string to concatenate to the current builded
1150 string.
1151
1152.. js:function:: Concat.dump(concat)
1153
1154 This function returns the concanated string.
1155
1156 :param class_concat concat: A :ref:`concat_class` which contains the currently
1157 builded string.
1158 :returns: the concatenated string
1159
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001160.. _fetches_class:
1161
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001162Fetches class
1163=============
1164
1165.. js:class:: Fetches
1166
1167 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001168 HAProxy "configuration.txt" documentation for more information about her
1169 usage. they are the chapters 7.3.2 to 7.3.6.
1170
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001171 **warning** some sample fetches are not available in some context. These
1172 limitations are specified in this documentation when theire useful.
1173
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001174 :see: :js:attr:`TXN.f`
1175 :see: :js:attr:`TXN.sf`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001176
1177 Fetches are useful for:
1178
1179 * get system time,
1180 * get environment variable,
1181 * get random numbers,
1182 * known backend status like the number of users in queue or the number of
1183 connections established,
1184 * client information like ip source or destination,
1185 * deal with stick tables,
1186 * Established SSL informations,
1187 * HTTP information like headers or method.
1188
1189.. code-block:: lua
1190
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001191 function action(txn)
1192 -- Get source IP
1193 local clientip = txn.f:src()
1194 end
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001195..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001196
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001197.. _converters_class:
1198
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001199Converters class
1200================
1201
1202.. js:class:: Converters
1203
1204 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001205 HAProxy documentation "configuration.txt" for more information about her
1206 usage. Its the chapter 7.3.1.
1207
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001208 :see: :js:attr:`TXN.c`
1209 :see: :js:attr:`TXN.sc`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001210
1211 Converters provides statefull transformation. They are useful for:
1212
1213 * converting input to base64,
1214 * applying hash on input string (djb2, crc32, sdbm, wt6),
1215 * format date,
1216 * json escape,
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001217 * extracting preferred language comparing two lists,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001218 * turn to lower or upper chars,
1219 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001220
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001221.. _channel_class:
1222
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001223Channel class
1224=============
1225
1226.. js:class:: Channel
1227
1228 HAProxy uses two buffers for the processing of the requests. The first one is
1229 used with the request data (from the client to the server) and the second is
1230 used for the response data (from the server to the client).
1231
1232 Each buffer contains two types of data. The first type is the incoming data
1233 waiting for a processing. The second part is the outgoing data already
1234 processed. Usually, the incoming data is processed, after it is tagged as
1235 outgoing data, and finally it is sent. The following functions provides tools
1236 for manipulating these data in a buffer.
1237
1238 The following diagram shows where the channel class function are applied.
1239
1240 **Warning**: It is not possible to read from the response in request action,
1241 and it is not possible to read for the request channel in response action.
1242
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001243.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001244
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001245.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001246
1247 This function returns a string that contain the entire buffer. The data is
1248 not remove from the buffer and can be reprocessed later.
1249
1250 If the buffer cant receive more data, a 'nil' value is returned.
1251
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001252 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001253 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001254
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001255.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001256
1257 This function returns a string that contain the entire buffer. The data is
1258 consumed from the buffer.
1259
1260 If the buffer cant receive more data, a 'nil' value is returned.
1261
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001262 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001263 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001264
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001265.. js:function:: Channel.getline(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001266
1267 This function returns a string that contain the first line of the buffer. The
1268 data is consumed. If the data returned doesn't contains a final '\n' its
1269 assumed than its the last available data in the buffer.
1270
1271 If the buffer cant receive more data, a 'nil' value is returned.
1272
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001273 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +02001274 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001275
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001276.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001277
1278 This function replace the content of the buffer by the string. The function
1279 returns the copied length, otherwise, it returns -1.
1280
1281 The data set with this function are not send. They wait for the end of
1282 HAProxy processing, so the buffer can be full.
1283
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001284 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001285 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001286 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001287
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001288.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001289
1290 This function append the string argument to the content of the buffer. The
1291 function returns the copied length, otherwise, it returns -1.
1292
1293 The data set with this function are not send. They wait for the end of
1294 HAProxy processing, so the buffer can be full.
1295
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001296 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001297 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001298 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001299
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001300.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001301
1302 This function required immediate send of the data. Unless if the connection
1303 is close, the buffer is regularly flushed and all the string can be sent.
1304
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001305 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001306 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001307 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001308
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001309.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001310
1311 This function returns the length of the input part of the buffer.
1312
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001313 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001314 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001315
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001316.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001317
1318 This function returns the length of the output part of the buffer.
1319
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001320 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001321 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001322
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001323.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001324
1325 This function transfer bytes from the input part of the buffer to the output
1326 part.
1327
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001328 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001329 :param integer int: The amount of data which will be forwarded.
1330
Thierry FOURNIER / OZON.IO65192f32016-11-07 15:28:40 +01001331.. js:function:: Channel.is_full(channel)
1332
1333 This function returns true if the buffer channel is full.
1334
1335 :returns: a boolean
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001336
1337.. _http_class:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001338
1339HTTP class
1340==========
1341
1342.. js:class:: HTTP
1343
1344 This class contain all the HTTP manipulation functions.
1345
Pieter Baauw386a1272015-08-16 15:26:24 +02001346.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001347
1348 Returns an array containing all the request headers.
1349
1350 :param class_http http: The related http object.
1351 :returns: array of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001352 :see: :js:func:`HTTP.res_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001353
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001354 This is the form of the returned array:
1355
1356.. code-block:: lua
1357
1358 HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1359
1360 local hdr = HTTP:req_get_headers()
1361 hdr["host"][0] = "www.test.com"
1362 hdr["accept"][0] = "audio/basic q=1"
1363 hdr["accept"][1] = "audio/*, q=0.2"
1364 hdr["accept"][2] = "*/*, q=0.1"
1365..
1366
Pieter Baauw386a1272015-08-16 15:26:24 +02001367.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001368
1369 Returns an array containing all the response headers.
1370
1371 :param class_http http: The related http object.
1372 :returns: array of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001373 :see: :js:func:`HTTP.req_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001374
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001375 This is the form of the returned array:
1376
1377.. code-block:: lua
1378
1379 HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1380
1381 local hdr = HTTP:req_get_headers()
1382 hdr["host"][0] = "www.test.com"
1383 hdr["accept"][0] = "audio/basic q=1"
1384 hdr["accept"][1] = "audio/*, q=0.2"
1385 hdr["accept"][2] = "*.*, q=0.1"
1386..
1387
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001388.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001389
1390 Appends an HTTP header field in the request whose name is
1391 specified in "name" and whose value is defined in "value".
1392
1393 :param class_http http: The related http object.
1394 :param string name: The header name.
1395 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001396 :see: :js:func:`HTTP.res_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001397
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001398.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001399
1400 appends an HTTP header field in the response whose name is
1401 specified in "name" and whose value is defined in "value".
1402
1403 :param class_http http: The related http object.
1404 :param string name: The header name.
1405 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001406 :see: :js:func:`HTTP.req_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001407
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001408.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001409
1410 Removes all HTTP header fields in the request whose name is
1411 specified in "name".
1412
1413 :param class_http http: The related http object.
1414 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001415 :see: :js:func:`HTTP.res_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001416
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001417.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001418
1419 Removes all HTTP header fields in the response whose name is
1420 specified in "name".
1421
1422 :param class_http http: The related http object.
1423 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001424 :see: :js:func:`HTTP.req_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001425
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001426.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001427
1428 This variable replace all occurence of all header "name", by only
1429 one containing the "value".
1430
1431 :param class_http http: The related http object.
1432 :param string name: The header name.
1433 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001434 :see: :js:func:`HTTP.res_set_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001435
1436 This function does the same work as the folowwing code:
1437
1438.. code-block:: lua
1439
1440 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001441 TXN.http:req_del_header("header")
1442 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001443 end
1444..
1445
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001446.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001447
1448 This variable replace all occurence of all header "name", by only
1449 one containing the "value".
1450
1451 :param class_http http: The related http object.
1452 :param string name: The header name.
1453 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001454 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001455
Pieter Baauw386a1272015-08-16 15:26:24 +02001456.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001457
1458 Matches the regular expression in all occurrences of header field "name"
1459 according to "regex", and replaces them with the "replace" argument. The
1460 replacement value can contain back references like \1, \2, ... This
1461 function works with the request.
1462
1463 :param class_http http: The related http object.
1464 :param string name: The header name.
1465 :param string regex: The match regular expression.
1466 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001467 :see: :js:func:`HTTP.res_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001468
Pieter Baauw386a1272015-08-16 15:26:24 +02001469.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001470
1471 Matches the regular expression in all occurrences of header field "name"
1472 according to "regex", and replaces them with the "replace" argument. The
1473 replacement value can contain back references like \1, \2, ... This
1474 function works with the request.
1475
1476 :param class_http http: The related http object.
1477 :param string name: The header name.
1478 :param string regex: The match regular expression.
1479 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001480 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001481
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001482.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001483
1484 Rewrites the request method with the parameter "method".
1485
1486 :param class_http http: The related http object.
1487 :param string method: The new method.
1488
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001489.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001490
1491 Rewrites the request path with the "path" parameter.
1492
1493 :param class_http http: The related http object.
1494 :param string path: The new path.
1495
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001496.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001497
1498 Rewrites the request's query string which appears after the first question
1499 mark ("?") with the parameter "query".
1500
1501 :param class_http http: The related http object.
1502 :param string query: The new query.
1503
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +02001504.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001505
1506 Rewrites the request URI with the parameter "uri".
1507
1508 :param class_http http: The related http object.
1509 :param string uri: The new uri.
1510
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001511.. js:function:: HTTP.res_set_status(http, status [, reason])
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001512
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001513 Rewrites the response status code with the parameter "code".
1514
1515 If no custom reason is provided, it will be generated from the status.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001516
1517 :param class_http http: The related http object.
1518 :param integer status: The new response status code.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001519 :param string reason: The new response reason (optional).
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001520
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001521.. _txn_class:
1522
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001523TXN class
1524=========
1525
1526.. js:class:: TXN
1527
1528 The txn class contain all the functions relative to the http or tcp
1529 transaction (Note than a tcp stream is the same than a tcp transaction, but
1530 an HTTP transaction is not the same than a tcp stream).
1531
1532 The usage of this class permits to retrieve data from the requests, alter it
1533 and forward it.
1534
1535 All the functions provided by this class are available in the context
1536 **sample-fetches** and **actions**.
1537
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001538.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001539
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001540 :returns: An :ref:`converters_class`.
1541
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001542 This attribute contains a Converters class object.
1543
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001544.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001545
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001546 :returns: An :ref:`converters_class`.
1547
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001548 This attribute contains a Converters class object. The functions of
1549 this object returns always a string.
1550
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001551.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001552
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001553 :returns: An :ref:`fetches_class`.
1554
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001555 This attribute contains a Fetches class object.
1556
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001557.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001558
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001559 :returns: An :ref:`fetches_class`.
1560
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001561 This attribute contains a Fetches class object. The functions of
1562 this object returns always a string.
1563
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001564.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001565
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001566 :returns: An :ref:`channel_class`.
1567
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001568 This attribute contains a channel class object for the request buffer.
1569
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001570.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001571
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001572 :returns: An :ref:`channel_class`.
1573
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001574 This attribute contains a channel class object for the response buffer.
1575
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001576.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001577
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001578 :returns: An :ref:`http_class`.
1579
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001580 This attribute contains an HTTP class object. It is avalaible only if the
1581 proxy has the "mode http" enabled.
1582
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001583.. js:function:: TXN.log(TXN, loglevel, msg)
1584
1585 This function sends a log. The log is sent, according with the HAProxy
1586 configuration file, on the default syslog server if it is configured and on
1587 the stderr if it is allowed.
1588
1589 :param class_txn txn: The class txn object containing the data.
1590 :param integer loglevel: Is the log level asociated with the message. It is a
1591 number between 0 and 7.
1592 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001593 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1594 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1595 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
1596 :see: :js:func:`TXN.deflog`
1597 :see: :js:func:`TXN.Debug`
1598 :see: :js:func:`TXN.Info`
1599 :see: :js:func:`TXN.Warning`
1600 :see: :js:func:`TXN.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001601
1602.. js:function:: TXN.deflog(TXN, msg)
1603
1604 Sends a log line with the default loglevel for the proxy ssociated with the
1605 transaction.
1606
1607 :param class_txn txn: The class txn object containing the data.
1608 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001609 :see: :js:func:`TXN.log
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001610
1611.. js:function:: TXN.Debug(txn, msg)
1612
1613 :param class_txn txn: The class txn object containing the data.
1614 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001615 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001616
1617 Does the same job than:
1618
1619.. code-block:: lua
1620
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001621 function Debug(txn, msg)
1622 TXN.log(txn, core.debug, msg)
1623 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001624..
1625
1626.. js:function:: TXN.Info(txn, msg)
1627
1628 :param class_txn txn: The class txn object containing the data.
1629 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001630 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001631
1632.. code-block:: lua
1633
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001634 function Debug(txn, msg)
1635 TXN.log(txn, core.info, msg)
1636 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001637..
1638
1639.. js:function:: TXN.Warning(txn, msg)
1640
1641 :param class_txn txn: The class txn object containing the data.
1642 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001643 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001644
1645.. code-block:: lua
1646
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001647 function Debug(txn, msg)
1648 TXN.log(txn, core.warning, msg)
1649 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001650..
1651
1652.. js:function:: TXN.Alert(txn, msg)
1653
1654 :param class_txn txn: The class txn object containing the data.
1655 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001656 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001657
1658.. code-block:: lua
1659
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001660 function Debug(txn, msg)
1661 TXN.log(txn, core.alert, msg)
1662 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001663..
1664
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001665.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001666
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001667 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001668 function. If no data are stored, it returns a nil value.
1669
1670 :param class_txn txn: The class txn object containing the data.
1671 :returns: the opaque data previsously stored, or nil if nothing is
1672 avalaible.
1673
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001674.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001675
1676 Store any data in the current HAProxy transaction. This action replace the
1677 old stored data.
1678
1679 :param class_txn txn: The class txn object containing the data.
1680 :param opaque data: The data which is stored in the transaction.
1681
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001682.. js:function:: TXN.set_var(TXN, var, value)
1683
David Carlier61fdf8b2015-10-02 11:59:38 +01001684 Converts a Lua type in a HAProxy type and store it in a variable <var>.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001685
1686 :param class_txn txn: The class txn object containing the data.
1687 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER / OZON.IOb210bcc2016-12-12 16:24:16 +01001688 :param type value: The value associated to the variable. The type can be string or
1689 integer.
Christopher Faulet85d79c92016-11-09 16:54:56 +01001690
1691.. js:function:: TXN.unset_var(TXN, var)
1692
1693 Unset the variable <var>.
1694
1695 :param class_txn txn: The class txn object containing the data.
1696 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001697
1698.. js:function:: TXN.get_var(TXN, var)
1699
1700 Returns data stored in the variable <var> converter in Lua type.
1701
1702 :param class_txn txn: The class txn object containing the data.
1703 :param string var: The variable name according with the HAProxy variable syntax.
1704
Willy Tarreaubc183a62015-08-28 10:39:11 +02001705.. js:function:: TXN.done(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001706
Willy Tarreaubc183a62015-08-28 10:39:11 +02001707 This function terminates processing of the transaction and the associated
1708 session. It can be used when a critical error is detected or to terminate
1709 processing after some data have been returned to the client (eg: a redirect).
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001710
Thierry FOURNIERab00df62016-07-14 11:42:37 +02001711 *Warning*: It not make sense to call this function from sample-fetches. In
1712 this case the behaviour of this one is the same than core.done(): it quit
1713 the Lua execution. The transaction is really aborted only from an action
1714 registered function.
1715
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001716 :param class_txn txn: The class txn object containing the data.
1717
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001718.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001719
1720 Is used to change the log level of the current request. The "loglevel" must
1721 be an integer between 0 and 7.
1722
1723 :param class_txn txn: The class txn object containing the data.
1724 :param integer loglevel: The required log level. This variable can be one of
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001725 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1726 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1727 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001728
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001729.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001730
1731 Is used to set the TOS or DSCP field value of packets sent to the client to
1732 the value passed in "tos" on platforms which support this.
1733
1734 :param class_txn txn: The class txn object containing the data.
1735 :param integer tos: The new TOS os DSCP.
1736
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001737.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001738
1739 Is used to set the Netfilter MARK on all packets sent to the client to the
1740 value passed in "mark" on platforms which support it.
1741
1742 :param class_txn txn: The class txn object containing the data.
1743 :param integer mark: The mark value.
1744
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001745.. _socket_class:
1746
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001747Socket class
1748============
1749
1750.. js:class:: Socket
1751
1752 This class must be compatible with the Lua Socket class. Only the 'client'
1753 functions are available. See the Lua Socket documentation:
1754
1755 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1756 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1757
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001758.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001759
1760 Closes a TCP object. The internal socket used by the object is closed and the
1761 local address to which the object was bound is made available to other
1762 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001763 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001764
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001765 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001766
1767 Note: It is important to close all used sockets once they are not needed,
1768 since, in many systems, each socket uses a file descriptor, which are limited
1769 system resources. Garbage-collected objects are automatically closed before
1770 destruction, though.
1771
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001772.. js:function:: Socket.connect(socket, address[, port])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001773
1774 Attempts to connect a socket object to a remote host.
1775
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001776
1777 In case of error, the method returns nil followed by a string describing the
1778 error. In case of success, the method returns 1.
1779
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001780 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001781 :param string address: can be an IP address or a host name. See below for more
1782 information.
1783 :param integer port: must be an integer number in the range [1..64K].
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001784 :returns: 1 or nil.
1785
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001786 an address field extension permits to use the connect() function to connect to
1787 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
1788 the basically expected format. This format requires the port.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001789
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001790 Other format accepted are a socket path like "/socket/path", it permits to
1791 connect to a socket. abstract namespaces are supported with the prefix
1792 "abns@", and finaly a filedescriotr can be passed with the prefix "fd@".
1793 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
1794 passed int the string. The syntax "127.0.0.1:1234" is valid. in this case, the
Tim Duesterhus6edab862018-01-06 19:04:45 +01001795 parameter *port* must not be set.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001796
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001797.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001798
1799 Same behavior than the function socket:connect, but uses SSL.
1800
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001801 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001802 :returns: 1 or nil.
1803
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001804.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001805
1806 Returns information about the remote side of a connected client object.
1807
1808 Returns a string with the IP address of the peer, followed by the port number
1809 that peer is using for the connection. In case of error, the method returns
1810 nil.
1811
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001812 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001813 :returns: a string containing the server information.
1814
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001815.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001816
1817 Returns the local address information associated to the object.
1818
1819 The method returns a string with local IP address and a number with the port.
1820 In case of error, the method returns nil.
1821
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001822 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001823 :returns: a string containing the client information.
1824
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001825.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001826
1827 Reads data from a client object, according to the specified read pattern.
1828 Patterns follow the Lua file I/O format, and the difference in performance
1829 between all patterns is negligible.
1830
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001831 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001832 :param string|integer pattern: Describe what is required (see below).
1833 :param string prefix: A string which will be prefix the returned data.
1834 :returns: a string containing the required data or nil.
1835
1836 Pattern can be any of the following:
1837
1838 * **`*a`**: reads from the socket until the connection is closed. No
1839 end-of-line translation is performed;
1840
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001841 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001842 LF character (ASCII 10), optionally preceded by a CR character
1843 (ASCII 13). The CR and LF characters are not included in the
1844 returned line. In fact, all CR characters are ignored by the
1845 pattern. This is the default pattern.
1846
1847 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001848 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001849 beginning of any received data before return.
1850
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001851 * **empty**: If the pattern is left empty, the default option is `*l`.
1852
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001853 If successful, the method returns the received pattern. In case of error, the
1854 method returns nil followed by an error message which can be the string
1855 'closed' in case the connection was closed before the transmission was
1856 completed or the string 'timeout' in case there was a timeout during the
1857 operation. Also, after the error message, the function returns the partial
1858 result of the transmission.
1859
1860 Important note: This function was changed severely. It used to support
1861 multiple patterns (but I have never seen this feature used) and now it
1862 doesn't anymore. Partial results used to be returned in the same way as
1863 successful results. This last feature violated the idea that all functions
1864 should return nil on error. Thus it was changed too.
1865
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001866.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001867
1868 Sends data through client object.
1869
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001870 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001871 :param string data: The data that will be sent.
1872 :param integer start: The start position in the buffer of the data which will
1873 be sent.
1874 :param integer end: The end position in the buffer of the data which will
1875 be sent.
1876 :returns: see below.
1877
1878 Data is the string to be sent. The optional arguments i and j work exactly
1879 like the standard string.sub Lua function to allow the selection of a
1880 substring to be sent.
1881
1882 If successful, the method returns the index of the last byte within [start,
1883 end] that has been sent. Notice that, if start is 1 or absent, this is
1884 effectively the total number of bytes sent. In case of error, the method
1885 returns nil, followed by an error message, followed by the index of the last
1886 byte within [start, end] that has been sent. You might want to try again from
1887 the byte following that. The error message can be 'closed' in case the
1888 connection was closed before the transmission was completed or the string
1889 'timeout' in case there was a timeout during the operation.
1890
1891 Note: Output is not buffered. For small strings, it is always better to
1892 concatenate them in Lua (with the '..' operator) and send the result in one
1893 call instead of calling the method several times.
1894
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001895.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001896
1897 Just implemented for compatibility, this cal does nothing.
1898
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001899.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001900
1901 Changes the timeout values for the object. All I/O operations are blocking.
1902 That is, any call to the methods send, receive, and accept will block
1903 indefinitely, until the operation completes. The settimeout method defines a
1904 limit on the amount of time the I/O methods can block. When a timeout time
1905 has elapsed, the affected methods give up and fail with an error code.
1906
1907 The amount of time to wait is specified as the value parameter, in seconds.
1908
1909 The timeout modes are bot implemented, the only settable timeout is the
1910 inactivity time waiting for complete the internal buffer send or waiting for
1911 receive data.
1912
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001913 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001914 :param integer value: The timeout value.
1915
Thierry FOURNIER31904272017-10-25 12:59:51 +02001916.. _regex_class:
1917
1918Regex class
1919===========
1920
1921.. js:class:: Regex
1922
1923 This class allows the usage of HAProxy regexes because classic lua doesn't
1924 provides regexes. This class inherits the HAProxy compilation options, so the
1925 regexes can be libc regex, pcre regex or pcre JIT regex.
1926
1927 The expression matching number is limited to 20 per regex. The only available
1928 option is case sensitive.
1929
1930 Because regexes compilation is a heavy process, it is better to define all
1931 your regexes in the **body context** and use it during the runtime.
1932
1933.. code-block:: lua
1934
1935 -- Create the regex
1936 st, regex = Regex.new("needle (..) (...)", true);
1937
1938 -- Check compilation errors
1939 if st == false then
1940 print "error: " .. regex
1941 end
1942
1943 -- Match the regexes
1944 print(regex:exec("Looking for a needle in the haystack")) -- true
1945 print(regex:exec("Lokking for a cat in the haystack")) -- false
1946
1947 -- Extract words
1948 st, list = regex:match("Looking for a needle in the haystack")
1949 print(st) -- true
1950 print(list[1]) -- needle in the
1951 print(list[2]) -- in
1952 print(list[3]) -- the
1953
1954.. js:function:: Regex.new(regex, case_sensitive)
1955
1956 Create and compile a regex.
1957
1958 :param string regex: The regular expression according with the libc or pcre
1959 standard
1960 :param boolean case_sensitive: Match is case sensitive or not.
1961 :returns: boolean status and :ref:`regex_class` or string containing fail reason.
1962
1963.. js:function:: Regex.exec(regex, str)
1964
1965 Execute the regex.
1966
1967 :param class_regex regex: A :ref:`regex_class` object.
1968 :param string str: The input string will be compared with the compiled regex.
1969 :returns: a boolean status according with the match result.
1970
1971.. js:function:: Regex.match(regex, str)
1972
1973 Execute the regex and return matched expressions.
1974
1975 :param class_map map: A :ref:`regex_class` object.
1976 :param string str: The input string will be compared with the compiled regex.
1977 :returns: a boolean status according with the match result, and
1978 a table containing all the string matched in order of declaration.
1979
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001980.. _map_class:
1981
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001982Map class
1983=========
1984
1985.. js:class:: Map
1986
1987 This class permits to do some lookup in HAProxy maps. The declared maps can
1988 be modified during the runtime throught the HAProxy management socket.
1989
1990.. code-block:: lua
1991
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001992 default = "usa"
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001993
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001994 -- Create and load map
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01001995 geo = Map.new("geo.map", Map._ip);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001996
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001997 -- Create new fetch that returns the user country
1998 core.register_fetches("country", function(txn)
1999 local src;
2000 local loc;
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002001
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002002 src = txn.f:fhdr("x-forwarded-for");
2003 if (src == nil) then
2004 src = txn.f:src()
2005 if (src == nil) then
2006 return default;
2007 end
2008 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002009
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002010 -- Perform lookup
2011 loc = geo:lookup(src);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002012
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002013 if (loc == nil) then
2014 return default;
2015 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002016
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002017 return loc;
2018 end);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002019
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002020.. js:attribute:: Map._int
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002021
2022 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2023 samples" ans subchapter "ACL basics" to understand this pattern matching
2024 method.
2025
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002026 Note that :js:attr:`Map.int` is also available for compatibility.
2027
2028.. js:attribute:: Map._ip
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002029
2030 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2031 samples" ans subchapter "ACL basics" to understand this pattern matching
2032 method.
2033
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002034 Note that :js:attr:`Map.ip` is also available for compatibility.
2035
2036.. js:attribute:: Map._str
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002037
2038 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2039 samples" ans subchapter "ACL basics" to understand this pattern matching
2040 method.
2041
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002042 Note that :js:attr:`Map.str` is also available for compatibility.
2043
2044.. js:attribute:: Map._beg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002045
2046 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2047 samples" ans subchapter "ACL basics" to understand this pattern matching
2048 method.
2049
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002050 Note that :js:attr:`Map.beg` is also available for compatibility.
2051
2052.. js:attribute:: Map._sub
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002053
2054 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2055 samples" ans subchapter "ACL basics" to understand this pattern matching
2056 method.
2057
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002058 Note that :js:attr:`Map.sub` is also available for compatibility.
2059
2060.. js:attribute:: Map._dir
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002061
2062 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2063 samples" ans subchapter "ACL basics" to understand this pattern matching
2064 method.
2065
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002066 Note that :js:attr:`Map.dir` is also available for compatibility.
2067
2068.. js:attribute:: Map._dom
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002069
2070 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2071 samples" ans subchapter "ACL basics" to understand this pattern matching
2072 method.
2073
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002074 Note that :js:attr:`Map.dom` is also available for compatibility.
2075
2076.. js:attribute:: Map._end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002077
2078 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2079 samples" ans subchapter "ACL basics" to understand this pattern matching
2080 method.
2081
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002082.. js:attribute:: Map._reg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002083
2084 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
2085 samples" ans subchapter "ACL basics" to understand this pattern matching
2086 method.
2087
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002088 Note that :js:attr:`Map.reg` is also available for compatibility.
2089
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002090
2091.. js:function:: Map.new(file, method)
2092
2093 Creates and load a map.
2094
2095 :param string file: Is the file containing the map.
2096 :param integer method: Is the map pattern matching method. See the attributes
2097 of the Map class.
2098 :returns: a class Map object.
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002099 :see: The Map attributes: :js:attr:`Map._int`, :js:attr:`Map._ip`,
2100 :js:attr:`Map._str`, :js:attr:`Map._beg`, :js:attr:`Map._sub`,
2101 :js:attr:`Map._dir`, :js:attr:`Map._dom`, :js:attr:`Map._end` and
2102 :js:attr:`Map._reg`.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002103
2104.. js:function:: Map.lookup(map, str)
2105
2106 Perform a lookup in a map.
2107
2108 :param class_map map: Is the class Map object.
2109 :param string str: Is the string used as key.
2110 :returns: a string containing the result or nil if no match.
2111
2112.. js:function:: Map.slookup(map, str)
2113
2114 Perform a lookup in a map.
2115
2116 :param class_map map: Is the class Map object.
2117 :param string str: Is the string used as key.
2118 :returns: a string containing the result or empty string if no match.
2119
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002120.. _applethttp_class:
2121
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002122AppletHTTP class
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002123================
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002124
2125.. js:class:: AppletHTTP
2126
2127 This class is used with applets that requires the 'http' mode. The http applet
2128 can be registered with the *core.register_service()* function. They are used
2129 for processing an http request like a server in back of HAProxy.
2130
2131 This is an hello world sample code:
2132
2133.. code-block:: lua
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002134
Pieter Baauw4d7f7662015-11-08 16:38:08 +01002135 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002136 local response = "Hello World !"
2137 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002138 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002139 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002140 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002141 applet:send(response)
2142 end)
2143
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002144.. js:attribute:: AppletHTTP.c
2145
2146 :returns: A :ref:`converters_class`
2147
2148 This attribute contains a Converters class object.
2149
2150.. js:attribute:: AppletHTTP.sc
2151
2152 :returns: A :ref:`converters_class`
2153
2154 This attribute contains a Converters class object. The
2155 functions of this object returns always a string.
2156
2157.. js:attribute:: AppletHTTP.f
2158
2159 :returns: A :ref:`fetches_class`
2160
2161 This attribute contains a Fetches class object. Note that the
2162 applet execution place cannot access to a valid HAProxy core HTTP
2163 transaction, so some sample fecthes related to the HTTP dependant
2164 values (hdr, path, ...) are not available.
2165
2166.. js:attribute:: AppletHTTP.sf
2167
2168 :returns: A :ref:`fetches_class`
2169
2170 This attribute contains a Fetches class object. The functions of
2171 this object returns always a string. Note that the applet
2172 execution place cannot access to a valid HAProxy core HTTP
2173 transaction, so some sample fecthes related to the HTTP dependant
2174 values (hdr, path, ...) are not available.
2175
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002176.. js:attribute:: AppletHTTP.method
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002177
2178 :returns: string
2179
2180 The attribute method returns a string containing the HTTP
2181 method.
2182
2183.. js:attribute:: AppletHTTP.version
2184
2185 :returns: string
2186
2187 The attribute version, returns a string containing the HTTP
2188 request version.
2189
2190.. js:attribute:: AppletHTTP.path
2191
2192 :returns: string
2193
2194 The attribute path returns a string containing the HTTP
2195 request path.
2196
2197.. js:attribute:: AppletHTTP.qs
2198
2199 :returns: string
2200
2201 The attribute qs returns a string containing the HTTP
2202 request query string.
2203
2204.. js:attribute:: AppletHTTP.length
2205
2206 :returns: integer
2207
2208 The attribute length returns an integer containing the HTTP
2209 body length.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002210
Thierry FOURNIER841475e2015-12-11 17:10:09 +01002211.. js:attribute:: AppletHTTP.headers
2212
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002213 :returns: array
2214
2215 The attribute headers returns an array containing the HTTP
2216 headers. The header names are always in lower case. As the header name can be
2217 encountered more than once in each request, the value is indexed with 0 as
2218 first index value. The array have this form:
2219
2220.. code-block:: lua
2221
2222 AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>"
2223
2224 AppletHTTP.headers["host"][0] = "www.test.com"
2225 AppletHTTP.headers["accept"][0] = "audio/basic q=1"
2226 AppletHTTP.headers["accept"][1] = "audio/*, q=0.2"
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002227 AppletHTTP.headers["accept"][2] = "*/*, q=0.1"
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002228..
2229
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002230.. js:function:: AppletHTTP.set_status(applet, code [, reason])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002231
2232 This function sets the HTTP status code for the response. The allowed code are
2233 from 100 to 599.
2234
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002235 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002236 :param integer code: the status code returned to the client.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002237 :param string reason: the status reason returned to the client (optional).
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002238
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002239.. js:function:: AppletHTTP.add_header(applet, name, value)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002240
2241 This function add an header in the response. Duplicated headers are not
2242 collapsed. The special header *content-length* is used to determinate the
2243 response length. If it not exists, a *transfer-encoding: chunked* is set, and
2244 all the write from the funcion *AppletHTTP:send()* become a chunk.
2245
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002246 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002247 :param string name: the header name
2248 :param string value: the header value
2249
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002250.. js:function:: AppletHTTP.start_response(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002251
2252 This function indicates to the HTTP engine that it can process and send the
2253 response headers. After this called we cannot add headers to the response; We
2254 cannot use the *AppletHTTP:send()* function if the
2255 *AppletHTTP:start_response()* is not called.
2256
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002257 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2258
2259.. js:function:: AppletHTTP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002260
2261 This function returns a string containing one line from the http body. If the
2262 data returned doesn't contains a final '\\n' its assumed than its the last
2263 available data before the end of stream.
2264
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002265 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002266 :returns: a string. The string can be empty if we reach the end of the stream.
2267
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002268.. js:function:: AppletHTTP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002269
2270 Reads data from the HTTP body, according to the specified read *size*. If the
2271 *size* is missing, the function tries to read all the content of the stream
2272 until the end. If the *size* is bigger than the http body, it returns the
2273 amount of data avalaible.
2274
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002275 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002276 :param integer size: the required read size.
2277 :returns: always return a string,the string can be empty is the connexion is
2278 closed.
2279
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002280.. js:function:: AppletHTTP.send(applet, msg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002281
2282 Send the message *msg* on the http request body.
2283
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002284 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002285 :param string msg: the message to send.
2286
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002287.. js:function:: AppletHTTP.get_priv(applet)
2288
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002289 Return Lua data stored in the current transaction. If no data are stored,
2290 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002291
2292 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2293 :returns: the opaque data previsously stored, or nil if nothing is
2294 avalaible.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002295 :see: :js:func:`AppletHTTP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002296
2297.. js:function:: AppletHTTP.set_priv(applet, data)
2298
2299 Store any data in the current HAProxy transaction. This action replace the
2300 old stored data.
2301
2302 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2303 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002304 :see: :js:func:`AppletHTTP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002305
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002306.. js:function:: AppletHTTP.set_var(applet, var, value)
2307
2308 Converts a Lua type in a HAProxy type and store it in a variable <var>.
2309
2310 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2311 :param string var: The variable name according with the HAProxy variable syntax.
2312 :param type value: The value associated to the variable. The type ca be string or
2313 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002314 :see: :js:func:`AppletHTTP.unset_var`
2315 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002316
2317.. js:function:: AppletHTTP.unset_var(applet, var)
2318
2319 Unset the variable <var>.
2320
2321 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2322 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002323 :see: :js:func:`AppletHTTP.set_var`
2324 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002325
2326.. js:function:: AppletHTTP.get_var(applet, var)
2327
2328 Returns data stored in the variable <var> converter in Lua type.
2329
2330 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2331 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002332 :see: :js:func:`AppletHTTP.set_var`
2333 :see: :js:func:`AppletHTTP.unset_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002334
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002335.. _applettcp_class:
2336
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002337AppletTCP class
2338===============
2339
2340.. js:class:: AppletTCP
2341
2342 This class is used with applets that requires the 'tcp' mode. The tcp applet
2343 can be registered with the *core.register_service()* function. They are used
2344 for processing a tcp stream like a server in back of HAProxy.
2345
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002346.. js:attribute:: AppletTCP.c
2347
2348 :returns: A :ref:`converters_class`
2349
2350 This attribute contains a Converters class object.
2351
2352.. js:attribute:: AppletTCP.sc
2353
2354 :returns: A :ref:`converters_class`
2355
2356 This attribute contains a Converters class object. The
2357 functions of this object returns always a string.
2358
2359.. js:attribute:: AppletTCP.f
2360
2361 :returns: A :ref:`fetches_class`
2362
2363 This attribute contains a Fetches class object.
2364
2365.. js:attribute:: AppletTCP.sf
2366
2367 :returns: A :ref:`fetches_class`
2368
2369 This attribute contains a Fetches class object.
2370
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002371.. js:function:: AppletTCP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002372
2373 This function returns a string containing one line from the stream. If the
2374 data returned doesn't contains a final '\\n' its assumed than its the last
2375 available data before the end of stream.
2376
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002377 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002378 :returns: a string. The string can be empty if we reach the end of the stream.
2379
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002380.. js:function:: AppletTCP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002381
2382 Reads data from the TCP stream, according to the specified read *size*. If the
2383 *size* is missing, the function tries to read all the content of the stream
2384 until the end.
2385
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002386 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002387 :param integer size: the required read size.
2388 :returns: always return a string,the string can be empty is the connexion is
2389 closed.
2390
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002391.. js:function:: AppletTCP.send(appletmsg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002392
2393 Send the message on the stream.
2394
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002395 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002396 :param string msg: the message to send.
2397
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002398.. js:function:: AppletTCP.get_priv(applet)
2399
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002400 Return Lua data stored in the current transaction. If no data are stored,
2401 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002402
2403 :param class_AppletTCP applet: An :ref:`applettcp_class`
2404 :returns: the opaque data previsously stored, or nil if nothing is
2405 avalaible.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002406 :see: :js:func:`AppletTCP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002407
2408.. js:function:: AppletTCP.set_priv(applet, data)
2409
2410 Store any data in the current HAProxy transaction. This action replace the
2411 old stored data.
2412
2413 :param class_AppletTCP applet: An :ref:`applettcp_class`
2414 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002415 :see: :js:func:`AppletTCP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002416
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002417.. js:function:: AppletTCP.set_var(applet, var, value)
2418
2419 Converts a Lua type in a HAProxy type and stores it in a variable <var>.
2420
2421 :param class_AppletTCP applet: An :ref:`applettcp_class`
2422 :param string var: The variable name according with the HAProxy variable syntax.
2423 :param type value: The value associated to the variable. The type can be string or
2424 integer.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002425 :see: :js:func:`AppletTCP.unset_var`
2426 :see: :js:func:`AppletTCP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002427
2428.. js:function:: AppletTCP.unset_var(applet, var)
2429
2430 Unsets the variable <var>.
2431
2432 :param class_AppletTCP applet: An :ref:`applettcp_class`
2433 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002434 :see: :js:func:`AppletTCP.unset_var`
2435 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002436
2437.. js:function:: AppletTCP.get_var(applet, var)
2438
2439 Returns data stored in the variable <var> converter in Lua type.
2440
2441 :param class_AppletTCP applet: An :ref:`applettcp_class`
2442 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002443 :see: :js:func:`AppletTCP.unset_var`
2444 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002445
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002446External Lua libraries
2447======================
2448
2449A lot of useful lua libraries can be found here:
2450
2451* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
2452
2453Redis acces:
2454
2455* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
2456
2457This is an example about the usage of the Redis library with HAProxy. Note that
2458each call of any function of this library can throw an error if the socket
2459connection fails.
2460
2461.. code-block:: lua
2462
2463 -- load the redis library
2464 local redis = require("redis");
2465
2466 function do_something(txn)
2467
2468 -- create and connect new tcp socket
2469 local tcp = core.tcp();
2470 tcp:settimeout(1);
2471 tcp:connect("127.0.0.1", 6379);
2472
2473 -- use the redis library with this new socket
2474 local client = redis.connect({socket=tcp});
2475 client:ping();
2476
2477 end
2478
2479OpenSSL:
2480
2481* `http://mkottman.github.io/luacrypto/index.html
2482 <http://mkottman.github.io/luacrypto/index.html>`_
2483
2484* `https://github.com/brunoos/luasec/wiki
2485 <https://github.com/brunoos/luasec/wiki>`_
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01002486