blob: 3d8282cdb3be44e9bfb39d6b90234e5cc606bba3 [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
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400172 This attribute is a table of declared proxies (frontend and backends). Each
173 proxy give an access to his list of listeners and servers. The table is
174 indexed by proxy name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100175
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
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400186 This attribute is a table of declared proxies with backend capability. Each
187 proxy give an access to his list of listeners and servers. The table is
188 indexed by the backend name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200189
190 :see: :js:attr:`core.proxies`
191 :see: :js:attr:`core.frontends`
192
193.. js:attribute:: core.frontends
194
195 **context**: task, action, sample-fetch, converter
196
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400197 This attribute is a table of declared proxies with frontend capability. Each
198 proxy give an access to his list of listeners and servers. The table is
199 indexed by the frontend name, and each entry is of type :ref:`proxy_class`.
Thierry FOURNIER9b82a582017-07-24 13:30:43 +0200200
201 :see: :js:attr:`core.proxies`
202 :see: :js:attr:`core.backends`
203
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100204.. js:function:: core.log(loglevel, msg)
205
206 **context**: body, init, task, action, sample-fetch, converter
207
David Carlier61fdf8b2015-10-02 11:59:38 +0100208 This function sends a log. The log is sent, according with the HAProxy
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100209 configuration file, on the default syslog server if it is configured and on
210 the stderr if it is allowed.
211
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100212 :param integer loglevel: Is the log level associated with the message. It is a
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100213 number between 0 and 7.
214 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100215 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
216 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
217 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
218 :see: :js:func:`core.Debug`
219 :see: :js:func:`core.Info`
220 :see: :js:func:`core.Warning`
221 :see: :js:func:`core.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100222
223.. js:function:: core.Debug(msg)
224
225 **context**: body, init, task, action, sample-fetch, converter
226
227 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100228 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100229
230 Does the same job than:
231
232.. code-block:: lua
233
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100234 function Debug(msg)
235 core.log(core.debug, msg)
236 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100237..
238
239.. js:function:: core.Info(msg)
240
241 **context**: body, init, task, action, sample-fetch, converter
242
243 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100244 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100245
246.. code-block:: lua
247
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100248 function Info(msg)
249 core.log(core.info, msg)
250 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100251..
252
253.. js:function:: core.Warning(msg)
254
255 **context**: body, init, task, action, sample-fetch, converter
256
257 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100258 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100259
260.. code-block:: lua
261
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100262 function Warning(msg)
263 core.log(core.warning, msg)
264 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100265..
266
267.. js:function:: core.Alert(msg)
268
269 **context**: body, init, task, action, sample-fetch, converter
270
271 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +0100272 :see: :js:func:`core.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100273
274.. code-block:: lua
275
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100276 function Alert(msg)
277 core.log(core.alert, msg)
278 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100279..
280
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100281.. js:function:: core.add_acl(filename, key)
282
283 **context**: init, task, action, sample-fetch, converter
284
285 Add the ACL *key* in the ACLs list referenced by the file *filename*.
286
287 :param string filename: the filename that reference the ACL entries.
288 :param string key: the key which will be added.
289
290.. js:function:: core.del_acl(filename, key)
291
292 **context**: init, task, action, sample-fetch, converter
293
294 Delete the ACL entry referenced by the key *key* in the list of ACLs
295 referenced by *filename*.
296
297 :param string filename: the filename that reference the ACL entries.
298 :param string key: the key which will be deleted.
299
300.. js:function:: core.del_map(filename, key)
301
302 **context**: init, task, action, sample-fetch, converter
303
304 Delete the map entry indexed with the specified key in the list of maps
305 referenced by his filename.
306
307 :param string filename: the filename that reference the map entries.
308 :param string key: the key which will be deleted.
309
Thierry Fourniereea77c02016-03-18 08:47:13 +0100310.. js:function:: core.get_info()
311
312 **context**: body, init, task, action, sample-fetch, converter
313
Ilya Shipitsin2075ca82020-03-06 23:22:22 +0500314 Returns HAProxy core information. We can found information like the uptime,
Thierry Fourniereea77c02016-03-18 08:47:13 +0100315 the pid, memory pool usage, tasks number, ...
316
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100317 These information are also returned by the management socket via the command
318 "show info". See the management socket documentation for more information
Thierry Fourniereea77c02016-03-18 08:47:13 +0100319 about the content of these variables.
320
321 :returns: an array of values.
322
Thierry Fournierb1f46562016-01-21 09:46:15 +0100323.. js:function:: core.now()
324
325 **context**: body, init, task, action
326
327 This function returns the current time. The time returned is fixed by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100328 HAProxy core and assures than the hour will be monotonic and that the system
Thierry Fournierb1f46562016-01-21 09:46:15 +0100329 call 'gettimeofday' will not be called too. The time is refreshed between each
330 Lua execution or resume, so two consecutive call to the function "now" will
331 probably returns the same result.
332
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400333 :returns: a table which contains two entries "sec" and "usec". "sec"
Thierry Fournierb1f46562016-01-21 09:46:15 +0100334 contains the current at the epoch format, and "usec" contains the
335 current microseconds.
336
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100337.. js:function:: core.http_date(date)
338
339 **context**: body, init, task, action
340
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100341 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100342 containing the corresponding date with a epoch format. A valid http date
343 me respect the format IMF, RFC850 or ASCTIME.
344
345 :param string date: a date http-date formatted
346 :returns: integer containing epoch date
347 :see: :js:func:`core.imf_date`.
348 :see: :js:func:`core.rfc850_date`.
349 :see: :js:func:`core.asctime_date`.
350 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
351
352.. js:function:: core.imf_date(date)
353
354 **context**: body, init, task, action
355
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100356 This function take a string representing IMF date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100357 containing the corresponding date with a epoch format.
358
359 :param string date: a date IMF formatted
360 :returns: integer containing epoch date
361 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
362
363 The IMF format is like this:
364
365.. code-block:: text
366
367 Sun, 06 Nov 1994 08:49:37 GMT
368..
369
370.. js:function:: core.rfc850_date(date)
371
372 **context**: body, init, task, action
373
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100374 This function take a string representing RFC850 date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100375 containing the corresponding date with a epoch format.
376
377 :param string date: a date RFC859 formatted
378 :returns: integer containing epoch date
379 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
380
381 The RFC850 format is like this:
382
383.. code-block:: text
384
385 Sunday, 06-Nov-94 08:49:37 GMT
386..
387
388.. js:function:: core.asctime_date(date)
389
390 **context**: body, init, task, action
391
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100392 This function take a string representing ASCTIME date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100393 containing the corresponding date with a epoch format.
394
395 :param string date: a date ASCTIME formatted
396 :returns: integer containing epoch date
397 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1
398
399 The ASCTIME format is like this:
400
401.. code-block:: text
402
403 Sun Nov 6 08:49:37 1994
404..
405
406.. js:function:: core.rfc850_date(date)
407
408 **context**: body, init, task, action
409
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100410 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100411 containing the corresponding date with a epoch format.
412
413 :param string date: a date http-date formatted
414
415.. js:function:: core.asctime_date(date)
416
417 **context**: body, init, task, action
418
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100419 This function take a string representing http date, and returns an integer
Thierry FOURNIERa78f0372016-12-14 19:04:41 +0100420 containing the corresponding date with a epoch format.
421
422 :param string date: a date http-date formatted
423
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100424.. js:function:: core.msleep(milliseconds)
425
426 **context**: body, init, task, action
427
428 The `core.msleep()` stops the Lua execution between specified milliseconds.
429
430 :param integer milliseconds: the required milliseconds.
431
Thierry Fournierf61aa632016-02-19 20:56:00 +0100432.. js:attribute:: core.proxies
433
434 **context**: body, init, task, action, sample-fetch, converter
435
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100436 Proxies is a table containing the list of all proxies declared in the
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400437 configuration file. The table is indexed by the proxy name, and each entry
438 of the proxies table is an object of type :ref:`proxy_class`.
439
440 Warning, if you have declared a frontend and backend with the same name, only
441 one of these are listed.
Thierry Fournierf61aa632016-02-19 20:56:00 +0100442
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100443.. js:function:: core.register_action(name, actions, func [, nb_args])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200444
445 **context**: body
446
David Carlier61fdf8b2015-10-02 11:59:38 +0100447 Register a Lua function executed as action. All the registered action can be
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200448 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
449 input.
450
451 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200452 :param table actions: is a table of string describing the HAProxy actions who
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200453 want to register to. The expected actions are 'tcp-req',
454 'tcp-res', 'http-req' or 'http-res'.
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100455 :param integer nb_args: is the expected number of argument for the action.
456 By default the value is 0.
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200457 :param function func: is the Lua function called to work as converter.
458
459 The prototype of the Lua function used as argument is:
460
461.. code-block:: lua
462
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100463 function(txn [, arg1 [, arg2]])
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200464..
465
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100466 * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200467 current request or TCP stream.
468
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100469 * **argX**: this is argument provided through the HAProxy configuration file.
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100470
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100471 Here, an example of action registration. The action just send an 'Hello world'
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200472 in the logs.
473
474.. code-block:: lua
475
476 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
477 txn:Info("Hello world")
478 end)
479..
480
481 This example code is used in HAproxy configuration like this:
482
483::
484
485 frontend tcp_frt
486 mode tcp
487 tcp-request content lua.hello-world
488
489 frontend http_frt
490 mode http
491 http-request lua.hello-world
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100492..
493
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100494 A second example using arguments
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100495
496.. code-block:: lua
497
498 function hello_world(txn, arg)
499 txn:Info("Hello world for " .. arg)
500 end
501 core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2)
502..
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200503
Thierry FOURNIERc5d11c62018-02-12 14:46:54 +0100504 This example code is used in HAproxy configuration like this:
505
506::
507
508 frontend tcp_frt
509 mode tcp
510 tcp-request content lua.hello-world everybody
511..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100512.. js:function:: core.register_converters(name, func)
513
514 **context**: body
515
David Carlier61fdf8b2015-10-02 11:59:38 +0100516 Register a Lua function executed as converter. All the registered converters
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100517 can be used in HAProxy with the prefix "lua.". An converter get a string as
518 input and return a string as output. The registered function can take up to 9
519 values as parameter. All the value are strings.
520
521 :param string name: is the name of the converter.
522 :param function func: is the Lua function called to work as converter.
523
524 The prototype of the Lua function used as argument is:
525
526.. code-block:: lua
527
528 function(str, [p1 [, p2 [, ... [, p5]]]])
529..
530
531 * **str** (*string*): this is the input value automatically converted in
532 string.
533 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100534 the HAProxy configuration file. The number of arguments doesn't exceed 5.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100535 The order and the nature of these is conventionally choose by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100536 developer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100537
538.. js:function:: core.register_fetches(name, func)
539
540 **context**: body
541
David Carlier61fdf8b2015-10-02 11:59:38 +0100542 Register a Lua function executed as sample fetch. All the registered sample
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100543 fetch can be used in HAProxy with the prefix "lua.". A Lua sample fetch
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100544 return a string as output. The registered function can take up to 9 values as
545 parameter. All the value are strings.
546
547 :param string name: is the name of the converter.
548 :param function func: is the Lua function called to work as sample fetch.
549
550 The prototype of the Lua function used as argument is:
551
552.. code-block:: lua
553
554 string function(txn, [p1 [, p2 [, ... [, p5]]]])
555..
556
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100557 * **txn** (:ref:`txn_class`): this is the txn object associated with the current
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100558 request.
559 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100560 the HAProxy configuration file. The number of arguments doesn't exceed 5.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100561 The order and the nature of these is conventionally choose by the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100562 developer.
563 * **Returns**: A string containing some data, or nil if the value cannot be
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100564 returned now.
565
566 lua example code:
567
568.. code-block:: lua
569
570 core.register_fetches("hello", function(txn)
571 return "hello"
572 end)
573..
574
575 HAProxy example configuration:
576
577::
578
579 frontend example
580 http-request redirect location /%[lua.hello]
581
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200582.. js:function:: core.register_service(name, mode, func)
583
584 **context**: body
585
David Carlier61fdf8b2015-10-02 11:59:38 +0100586 Register a Lua function executed as a service. All the registered service can
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200587 be used in HAProxy with the prefix "lua.". A service gets an object class as
588 input according with the required mode.
589
590 :param string name: is the name of the converter.
Willy Tarreau61add3c2015-09-28 15:39:10 +0200591 :param string mode: is string describing the required mode. Only 'tcp' or
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200592 'http' are allowed.
593 :param function func: is the Lua function called to work as converter.
594
595 The prototype of the Lua function used as argument is:
596
597.. code-block:: lua
598
599 function(applet)
600..
601
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100602 * **applet** *applet* will be a :ref:`applettcp_class` or a
603 :ref:`applethttp_class`. It depends the type of registered applet. An applet
604 registered with the 'http' value for the *mode* parameter will gets a
605 :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets
606 a :ref:`applettcp_class`.
607
608 **warning**: Applets of type 'http' cannot be called from 'tcp-*'
609 rulesets. Only the 'http-*' rulesets are authorized, this means
610 that is not possible to call an HTTP applet from a proxy in tcp
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100611 mode. Applets of type 'tcp' can be called from anywhere.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200612
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100613 Here, an example of service registration. The service just send an 'Hello world'
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200614 as an http response.
615
616.. code-block:: lua
617
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100618 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200619 local response = "Hello World !"
620 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200621 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200622 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +0200623 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +0200624 applet:send(response)
625 end)
626..
627
628 This example code is used in HAproxy configuration like this:
629
630::
631
632 frontend example
633 http-request use-service lua.hello-world
634
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100635.. js:function:: core.register_init(func)
636
637 **context**: body
638
639 Register a function executed after the configuration parsing. This is useful
640 to check any parameters.
641
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100642 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100643
644 The prototype of the Lua function used as argument is:
645
646.. code-block:: lua
647
648 function()
649..
650
651 It takes no input, and no output is expected.
652
653.. js:function:: core.register_task(func)
654
655 **context**: body, init, task, action, sample-fetch, converter
656
657 Register and start independent task. The task is started when the HAProxy
658 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100659 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100660
Pieter Baauw4d7f7662015-11-08 16:38:08 +0100661 :param function func: is the Lua function called to work as initializer.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100662
663 The prototype of the Lua function used as argument is:
664
665.. code-block:: lua
666
667 function()
668..
669
670 It takes no input, and no output is expected.
671
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100672.. js:function:: core.register_cli([path], usage, func)
673
674 **context**: body
675
676 Register and start independent task. The task is started when the HAProxy
677 main scheduler starts. For example this type of tasks can be executed to
678 perform complex health checks.
679
680 :param array path: is the sequence of word for which the cli execute the Lua
681 binding.
682 :param string usage: is the usage message displayed in the help.
683 :param function func: is the Lua function called to handle the CLI commands.
684
685 The prototype of the Lua function used as argument is:
686
687.. code-block:: lua
688
689 function(AppletTCP, [arg1, [arg2, [...]]])
690..
691
692 I/O are managed with the :ref:`applettcp_class` object. Args are given as
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100693 parameter. The args embed the registered path. If the path is declared like
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100694 this:
695
696.. code-block:: lua
697
698 core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5)
699 end)
700..
701
702 And we execute this in the prompt:
703
704.. code-block:: text
705
706 > prompt
707 > show ssl stats all
708..
709
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100710 Then, arg1, arg2 and arg3 will contains respectively "show", "ssl" and "stats".
Thierry FOURNIER / OZON.IOa44fdd92016-11-13 13:19:20 +0100711 arg4 will contain "all". arg5 contains nil.
712
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100713.. js:function:: core.set_nice(nice)
714
715 **context**: task, action, sample-fetch, converter
716
717 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100718
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100719 :param integer nice: the nice value, it must be between -1024 and 1024.
720
721.. js:function:: core.set_map(filename, key, value)
722
723 **context**: init, task, action, sample-fetch, converter
724
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100725 Set the value *value* associated to the key *key* in the map referenced by
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100726 *filename*.
727
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100728 :param string filename: the Map reference
729 :param string key: the key to set or replace
730 :param string value: the associated value
731
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100732.. js:function:: core.sleep(int seconds)
733
734 **context**: body, init, task, action
735
736 The `core.sleep()` functions stop the Lua execution between specified seconds.
737
738 :param integer seconds: the required seconds.
739
740.. js:function:: core.tcp()
741
742 **context**: init, task, action
743
744 This function returns a new object of a *socket* class.
745
Thierry FOURNIERdc595002015-12-21 11:13:52 +0100746 :returns: A :ref:`socket_class` object.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100747
Thierry Fournier1de16592016-01-27 09:49:07 +0100748.. js:function:: core.concat()
749
750 **context**: body, init, task, action, sample-fetch, converter
751
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100752 This function returns a new concat object.
Thierry Fournier1de16592016-01-27 09:49:07 +0100753
754 :returns: A :ref:`concat_class` object.
755
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200756.. js:function:: core.done(data)
757
758 **context**: body, init, task, action, sample-fetch, converter
759
760 :param any data: Return some data for the caller. It is useful with
761 sample-fetches and sample-converters.
762
763 Immediately stops the current Lua execution and returns to the caller which
764 may be a sample fetch, a converter or an action and returns the specified
765 value (ignored for actions). It is used when the LUA process finishes its
766 work and wants to give back the control to HAProxy without executing the
767 remaining code. It can be seen as a multi-level "return".
768
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100769.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100770
771 **context**: task, action, sample-fetch, converter
772
773 Give back the hand at the HAProxy scheduler. It is used when the LUA
774 processing consumes a lot of processing time.
775
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100776.. js:function:: core.parse_addr(address)
777
778 **context**: body, init, task, action, sample-fetch, converter
779
780 :param network: is a string describing an ipv4 or ipv6 address and optionally
781 its network length, like this: "127.0.0.1/8" or "aaaa::1234/32".
782 :returns: a userdata containing network or nil if an error occurs.
783
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100784 Parse ipv4 or ipv6 addresses and its facultative associated network.
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100785
786.. js:function:: core.match_addr(addr1, addr2)
787
788 **context**: body, init, task, action, sample-fetch, converter
789
790 :param addr1: is an address created with "core.parse_addr".
791 :param addr2: is an address created with "core.parse_addr".
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100792 :returns: boolean, true if the network of the addresses match, else returns
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100793 false.
794
Ilya Shipitsin2075ca82020-03-06 23:22:22 +0500795 Match two networks. For example "127.0.0.1/32" matches "127.0.0.0/8". The order
Thierry FOURNIER / OZON.IO62fec752016-11-10 20:38:11 +0100796 of network is not important.
797
Thierry FOURNIER / OZON.IO8a1027a2016-11-24 20:48:38 +0100798.. js:function:: core.tokenize(str, separators [, noblank])
799
800 **context**: body, init, task, action, sample-fetch, converter
801
802 This function is useful for tokenizing an entry, or splitting some messages.
803 :param string str: The string which will be split.
804 :param string separators: A string containing a list of separators.
805 :param boolean noblank: Ignore empty entries.
806 :returns: an array of string.
807
808 For example:
809
810.. code-block:: lua
811
812 local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true)
813 print_r(array)
814..
815
816 Returns this array:
817
818.. code-block:: text
819
820 (table) table: 0x21c01e0 [
821 1: (string) "This"
822 2: (string) "function"
823 3: (string) "is"
824 4: (string) "useful"
825 5: (string) "for"
826 6: (string) "tokenizing"
827 7: (string) "an"
828 8: (string) "entry"
829 ]
830..
831
Thierry Fournierf61aa632016-02-19 20:56:00 +0100832.. _proxy_class:
833
834Proxy class
835============
836
837.. js:class:: Proxy
838
839 This class provides a way for manipulating proxy and retrieving information
840 like statistics.
841
Thierry FOURNIER817e7592017-07-24 14:35:04 +0200842.. js:attribute:: Proxy.name
843
844 Contain the name of the proxy.
845
Baptiste Assmann46c72552017-10-26 21:51:58 +0200846.. js:attribute:: Proxy.uuid
847
848 Contain the unique identifier of the proxy.
849
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100850.. js:attribute:: Proxy.servers
851
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400852 Contain a table with the attached servers. The table is indexed by server
853 name, and each server entry is an object of type :ref:`server_class`.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100854
Adis Nezirovic8878f8e2018-07-13 12:18:33 +0200855.. js:attribute:: Proxy.stktable
856
857 Contains a stick table object attached to the proxy.
858
Thierry Fournierff480422016-02-25 08:36:46 +0100859.. js:attribute:: Proxy.listeners
860
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400861 Contain a table with the attached listeners. The table is indexed by listener
862 name, and each each listeners entry is an object of type
863 :ref:`listener_class`.
Thierry Fournierff480422016-02-25 08:36:46 +0100864
Thierry Fournierf61aa632016-02-19 20:56:00 +0100865.. js:function:: Proxy.pause(px)
866
867 Pause the proxy. See the management socket documentation for more information.
868
869 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
870 proxy.
871
872.. js:function:: Proxy.resume(px)
873
874 Resume the proxy. See the management socket documentation for more
875 information.
876
877 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
878 proxy.
879
880.. js:function:: Proxy.stop(px)
881
882 Stop the proxy. See the management socket documentation for more information.
883
884 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
885 proxy.
886
887.. js:function:: Proxy.shut_bcksess(px)
888
889 Kill the session attached to a backup server. See the management socket
890 documentation for more information.
891
892 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
893 proxy.
894
895.. js:function:: Proxy.get_cap(px)
896
897 Returns a string describing the capabilities of the proxy.
898
899 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
900 proxy.
901 :returns: a string "frontend", "backend", "proxy" or "ruleset".
902
903.. js:function:: Proxy.get_mode(px)
904
905 Returns a string describing the mode of the current proxy.
906
907 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
908 proxy.
909 :returns: a string "tcp", "http", "health" or "unknown"
910
911.. js:function:: Proxy.get_stats(px)
912
Bertrand Jacquin874a35c2018-09-10 21:26:07 +0100913 Returns a table containing the proxy statistics. The statistics returned are
Thierry Fournierf61aa632016-02-19 20:56:00 +0100914 not the same if the proxy is frontend or a backend.
915
916 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated
917 proxy.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400918 :returns: a key/value table containing stats
Thierry Fournierf61aa632016-02-19 20:56:00 +0100919
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100920.. _server_class:
921
922Server class
923============
924
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400925.. js:class:: Server
926
927 This class provides a way for manipulating servers and retrieving information.
928
Patrick Hemmera62ae7e2018-04-29 14:23:48 -0400929.. js:attribute:: Server.name
930
931 Contain the name of the server.
932
933.. js:attribute:: Server.puid
934
935 Contain the proxy unique identifier of the server.
936
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100937.. js:function:: Server.is_draining(sv)
938
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400939 Return true if the server is currently draining sticky connections.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100940
941 :param class_server sv: A :ref:`server_class` which indicates the manipulated
942 server.
943 :returns: a boolean
944
Patrick Hemmer32d539f2018-04-29 14:25:46 -0400945.. js:function:: Server.set_maxconn(sv, weight)
946
947 Dynamically change the maximum connections of the server. See the management
948 socket documentation for more information about the format of the string.
949
950 :param class_server sv: A :ref:`server_class` which indicates the manipulated
951 server.
952 :param string maxconn: A string describing the server maximum connections.
953
954.. js:function:: Server.get_maxconn(sv, weight)
955
956 This function returns an integer representing the server maximum connections.
957
958 :param class_server sv: A :ref:`server_class` which indicates the manipulated
959 server.
960 :returns: an integer.
961
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100962.. js:function:: Server.set_weight(sv, weight)
963
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400964 Dynamically change the weight of the server. See the management socket
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100965 documentation for more information about the format of the string.
966
967 :param class_server sv: A :ref:`server_class` which indicates the manipulated
968 server.
969 :param string weight: A string describing the server weight.
970
971.. js:function:: Server.get_weight(sv)
972
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400973 This function returns an integer representing the server weight.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100974
975 :param class_server sv: A :ref:`server_class` which indicates the manipulated
976 server.
977 :returns: an integer.
978
Joseph C. Sible49bbf522020-05-04 22:20:32 -0400979.. js:function:: Server.set_addr(sv, addr[, port])
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100980
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400981 Dynamically change the address of the server. See the management socket
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100982 documentation for more information about the format of the string.
983
984 :param class_server sv: A :ref:`server_class` which indicates the manipulated
985 server.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400986 :param string addr: A string describing the server address.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100987
988.. js:function:: Server.get_addr(sv)
989
Patrick Hemmerc6a1d712018-05-01 21:30:41 -0400990 Returns a string describing the address of the server.
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +0100991
992 :param class_server sv: A :ref:`server_class` which indicates the manipulated
993 server.
994 :returns: A string
995
996.. js:function:: Server.get_stats(sv)
997
998 Returns server statistics.
999
1000 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1001 server.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001002 :returns: a key/value table containing stats
Thierry Fournierf2fdc9d2016-02-22 08:21:39 +01001003
1004.. js:function:: Server.shut_sess(sv)
1005
1006 Shutdown all the sessions attached to the server. See the management socket
1007 documentation for more information about this function.
1008
1009 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1010 server.
1011
1012.. js:function:: Server.set_drain(sv)
1013
1014 Drain sticky sessions. See the management socket documentation for more
1015 information about this function.
1016
1017 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1018 server.
1019
1020.. js:function:: Server.set_maint(sv)
1021
1022 Set maintenance mode. See the management socket documentation for more
1023 information about this function.
1024
1025 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1026 server.
1027
1028.. js:function:: Server.set_ready(sv)
1029
1030 Set normal mode. See the management socket documentation for more information
1031 about this function.
1032
1033 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1034 server.
1035
1036.. js:function:: Server.check_enable(sv)
1037
1038 Enable health checks. See the management socket documentation for more
1039 information about this function.
1040
1041 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1042 server.
1043
1044.. js:function:: Server.check_disable(sv)
1045
1046 Disable health checks. See the management socket documentation for more
1047 information about this function.
1048
1049 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1050 server.
1051
1052.. js:function:: Server.check_force_up(sv)
1053
1054 Force health-check up. See the management socket documentation for more
1055 information about this function.
1056
1057 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1058 server.
1059
1060.. js:function:: Server.check_force_nolb(sv)
1061
1062 Force health-check nolb mode. See the management socket documentation for more
1063 information about this function.
1064
1065 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1066 server.
1067
1068.. js:function:: Server.check_force_down(sv)
1069
1070 Force health-check down. See the management socket documentation for more
1071 information about this function.
1072
1073 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1074 server.
1075
1076.. js:function:: Server.agent_enable(sv)
1077
1078 Enable agent check. See the management socket documentation for more
1079 information about this function.
1080
1081 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1082 server.
1083
1084.. js:function:: Server.agent_disable(sv)
1085
1086 Disable agent check. See the management socket documentation for more
1087 information about this function.
1088
1089 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1090 server.
1091
1092.. js:function:: Server.agent_force_up(sv)
1093
1094 Force agent check up. See the management socket documentation for more
1095 information about this function.
1096
1097 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1098 server.
1099
1100.. js:function:: Server.agent_force_down(sv)
1101
1102 Force agent check down. See the management socket documentation for more
1103 information about this function.
1104
1105 :param class_server sv: A :ref:`server_class` which indicates the manipulated
1106 server.
1107
Thierry Fournierff480422016-02-25 08:36:46 +01001108.. _listener_class:
1109
1110Listener class
1111==============
1112
1113.. js:function:: Listener.get_stats(ls)
1114
1115 Returns server statistics.
1116
1117 :param class_listener ls: A :ref:`listener_class` which indicates the
1118 manipulated listener.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001119 :returns: a key/value table containing stats
Thierry Fournierff480422016-02-25 08:36:46 +01001120
Thierry Fournier1de16592016-01-27 09:49:07 +01001121.. _concat_class:
1122
1123Concat class
1124============
1125
1126.. js:class:: Concat
1127
1128 This class provides a fast way for string concatenation. The way using native
1129 Lua concatenation like the code below is slow for some reasons.
1130
1131.. code-block:: lua
1132
1133 str = "string1"
1134 str = str .. ", string2"
1135 str = str .. ", string3"
1136..
1137
1138 For each concatenation, Lua:
1139 * allocate memory for the result,
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001140 * catenate the two string copying the strings in the new memory block,
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001141 * free the old memory block containing the string which is no longer used.
Thierry Fournier1de16592016-01-27 09:49:07 +01001142 This process does many memory move, allocation and free. In addition, the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001143 memory is not really freed, it is just mark mark as unused and wait for the
Thierry Fournier1de16592016-01-27 09:49:07 +01001144 garbage collector.
1145
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001146 The Concat class provide an alternative way to concatenate strings. It uses
Thierry Fournier1de16592016-01-27 09:49:07 +01001147 the internal Lua mechanism (it does not allocate memory), but it doesn't copy
1148 the data more than once.
1149
1150 On my computer, the following loops spends 0.2s for the Concat method and
1151 18.5s for the pure Lua implementation. So, the Concat class is about 1000x
1152 faster than the embedded solution.
1153
1154.. code-block:: lua
1155
1156 for j = 1, 100 do
1157 c = core.concat()
1158 for i = 1, 20000 do
1159 c:add("#####")
1160 end
1161 end
1162..
1163
1164.. code-block:: lua
1165
1166 for j = 1, 100 do
1167 c = ""
1168 for i = 1, 20000 do
1169 c = c .. "#####"
1170 end
1171 end
1172..
1173
1174.. js:function:: Concat.add(concat, string)
1175
1176 This function adds a string to the current concatenated string.
1177
1178 :param class_concat concat: A :ref:`concat_class` which contains the currently
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001179 built string.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001180 :param string string: A new string to concatenate to the current built
Thierry Fournier1de16592016-01-27 09:49:07 +01001181 string.
1182
1183.. js:function:: Concat.dump(concat)
1184
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001185 This function returns the concatenated string.
Thierry Fournier1de16592016-01-27 09:49:07 +01001186
1187 :param class_concat concat: A :ref:`concat_class` which contains the currently
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001188 built string.
Thierry Fournier1de16592016-01-27 09:49:07 +01001189 :returns: the concatenated string
1190
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001191.. _fetches_class:
1192
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001193Fetches class
1194=============
1195
1196.. js:class:: Fetches
1197
1198 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001199 HAProxy "configuration.txt" documentation for more information about her
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001200 usage. They are the chapters 7.3.2 to 7.3.6.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001201
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001202 **warning** some sample fetches are not available in some context. These
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001203 limitations are specified in this documentation when they're useful.
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001204
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001205 :see: :js:attr:`TXN.f`
1206 :see: :js:attr:`TXN.sf`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001207
1208 Fetches are useful for:
1209
1210 * get system time,
1211 * get environment variable,
1212 * get random numbers,
1213 * known backend status like the number of users in queue or the number of
1214 connections established,
1215 * client information like ip source or destination,
1216 * deal with stick tables,
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001217 * Established SSL information,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001218 * HTTP information like headers or method.
1219
1220.. code-block:: lua
1221
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001222 function action(txn)
1223 -- Get source IP
1224 local clientip = txn.f:src()
1225 end
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001226..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001227
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001228.. _converters_class:
1229
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001230Converters class
1231================
1232
1233.. js:class:: Converters
1234
1235 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001236 HAProxy documentation "configuration.txt" for more information about her
1237 usage. Its the chapter 7.3.1.
1238
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001239 :see: :js:attr:`TXN.c`
1240 :see: :js:attr:`TXN.sc`
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001241
1242 Converters provides statefull transformation. They are useful for:
1243
1244 * converting input to base64,
1245 * applying hash on input string (djb2, crc32, sdbm, wt6),
1246 * format date,
1247 * json escape,
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001248 * extracting preferred language comparing two lists,
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001249 * turn to lower or upper chars,
1250 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001251
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001252.. _channel_class:
1253
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001254Channel class
1255=============
1256
1257.. js:class:: Channel
1258
1259 HAProxy uses two buffers for the processing of the requests. The first one is
1260 used with the request data (from the client to the server) and the second is
1261 used for the response data (from the server to the client).
1262
1263 Each buffer contains two types of data. The first type is the incoming data
1264 waiting for a processing. The second part is the outgoing data already
1265 processed. Usually, the incoming data is processed, after it is tagged as
1266 outgoing data, and finally it is sent. The following functions provides tools
1267 for manipulating these data in a buffer.
1268
1269 The following diagram shows where the channel class function are applied.
1270
1271 **Warning**: It is not possible to read from the response in request action,
1272 and it is not possible to read for the request channel in response action.
1273
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001274.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001275
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001276.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001277
1278 This function returns a string that contain the entire buffer. The data is
1279 not remove from the buffer and can be reprocessed later.
1280
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001281 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001282
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001283 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001284 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001285
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001286.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001287
1288 This function returns a string that contain the entire buffer. The data is
1289 consumed from the buffer.
1290
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001291 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001292
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001293 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001294 :returns: a string containing all the available data or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001295
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001296.. js:function:: Channel.getline(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001297
1298 This function returns a string that contain the first line of the buffer. The
1299 data is consumed. If the data returned doesn't contains a final '\n' its
1300 assumed than its the last available data in the buffer.
1301
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05001302 If the buffer can't receive more data, a 'nil' value is returned.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001303
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001304 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +02001305 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001306
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001307.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001308
1309 This function replace the content of the buffer by the string. The function
1310 returns the copied length, otherwise, it returns -1.
1311
1312 The data set with this function are not send. They wait for the end of
1313 HAProxy processing, so the buffer can be full.
1314
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001315 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001316 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001317 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001318
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001319.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001320
1321 This function append the string argument to the content of the buffer. The
1322 function returns the copied length, otherwise, it returns -1.
1323
1324 The data set with this function are not send. They wait for the end of
1325 HAProxy processing, so the buffer can be full.
1326
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001327 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001328 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001329 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001330
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001331.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001332
1333 This function required immediate send of the data. Unless if the connection
1334 is close, the buffer is regularly flushed and all the string can be sent.
1335
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001336 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001337 :param string string: The data which will sent.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001338 :returns: an integer containing the amount of bytes copied or -1.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001339
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001340.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001341
1342 This function returns the length of the input part of the buffer.
1343
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001344 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001345 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001346
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001347.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001348
1349 This function returns the length of the output part of the buffer.
1350
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001351 :param class_channel channel: The manipulated Channel.
Pieter Baauw4d7f7662015-11-08 16:38:08 +01001352 :returns: an integer containing the amount of available bytes.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001353
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001354.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001355
1356 This function transfer bytes from the input part of the buffer to the output
1357 part.
1358
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001359 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001360 :param integer int: The amount of data which will be forwarded.
1361
Thierry FOURNIER / OZON.IO65192f32016-11-07 15:28:40 +01001362.. js:function:: Channel.is_full(channel)
1363
1364 This function returns true if the buffer channel is full.
1365
1366 :returns: a boolean
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001367
1368.. _http_class:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001369
1370HTTP class
1371==========
1372
1373.. js:class:: HTTP
1374
1375 This class contain all the HTTP manipulation functions.
1376
Pieter Baauw386a1272015-08-16 15:26:24 +02001377.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001378
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001379 Returns a table containing all the request headers.
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001380
1381 :param class_http http: The related http object.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001382 :returns: table of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001383 :see: :js:func:`HTTP.res_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001384
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001385 This is the form of the returned table:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001386
1387.. code-block:: lua
1388
1389 HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1390
1391 local hdr = HTTP:req_get_headers()
1392 hdr["host"][0] = "www.test.com"
1393 hdr["accept"][0] = "audio/basic q=1"
1394 hdr["accept"][1] = "audio/*, q=0.2"
1395 hdr["accept"][2] = "*/*, q=0.1"
1396..
1397
Pieter Baauw386a1272015-08-16 15:26:24 +02001398.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001399
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001400 Returns a table containing all the response headers.
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001401
1402 :param class_http http: The related http object.
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001403 :returns: table of headers.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001404 :see: :js:func:`HTTP.req_get_headers`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001405
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04001406 This is the form of the returned table:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001407
1408.. code-block:: lua
1409
1410 HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>"
1411
1412 local hdr = HTTP:req_get_headers()
1413 hdr["host"][0] = "www.test.com"
1414 hdr["accept"][0] = "audio/basic q=1"
1415 hdr["accept"][1] = "audio/*, q=0.2"
1416 hdr["accept"][2] = "*.*, q=0.1"
1417..
1418
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001419.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001420
1421 Appends an HTTP header field in the request whose name is
1422 specified in "name" and whose value is defined in "value".
1423
1424 :param class_http http: The related http object.
1425 :param string name: The header name.
1426 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001427 :see: :js:func:`HTTP.res_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001428
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001429.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001430
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001431 Appends an HTTP header field in the response whose name is
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001432 specified in "name" and whose value is defined in "value".
1433
1434 :param class_http http: The related http object.
1435 :param string name: The header name.
1436 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001437 :see: :js:func:`HTTP.req_add_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001438
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001439.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001440
1441 Removes all HTTP header fields in the request whose name is
1442 specified in "name".
1443
1444 :param class_http http: The related http object.
1445 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001446 :see: :js:func:`HTTP.res_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001447
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001448.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001449
1450 Removes all HTTP header fields in the response whose name is
1451 specified in "name".
1452
1453 :param class_http http: The related http object.
1454 :param string name: The header name.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001455 :see: :js:func:`HTTP.req_del_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001456
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001457.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001458
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001459 This variable replace all occurrence of all header "name", by only
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001460 one containing the "value".
1461
1462 :param class_http http: The related http object.
1463 :param string name: The header name.
1464 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001465 :see: :js:func:`HTTP.res_set_header`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001466
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001467 This function does the same work as the following code:
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001468
1469.. code-block:: lua
1470
1471 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001472 TXN.http:req_del_header("header")
1473 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001474 end
1475..
1476
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001477.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001478
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001479 This variable replace all occurrence of all header "name", by only
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001480 one containing the "value".
1481
1482 :param class_http http: The related http object.
1483 :param string name: The header name.
1484 :param string value: The header value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001485 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001486
Pieter Baauw386a1272015-08-16 15:26:24 +02001487.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001488
1489 Matches the regular expression in all occurrences of header field "name"
1490 according to "regex", and replaces them with the "replace" argument. The
1491 replacement value can contain back references like \1, \2, ... This
1492 function works with the request.
1493
1494 :param class_http http: The related http object.
1495 :param string name: The header name.
1496 :param string regex: The match regular expression.
1497 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001498 :see: :js:func:`HTTP.res_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001499
Pieter Baauw386a1272015-08-16 15:26:24 +02001500.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001501
1502 Matches the regular expression in all occurrences of header field "name"
1503 according to "regex", and replaces them with the "replace" argument. The
1504 replacement value can contain back references like \1, \2, ... This
1505 function works with the request.
1506
1507 :param class_http http: The related http object.
1508 :param string name: The header name.
1509 :param string regex: The match regular expression.
1510 :param string replace: The replacement value.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001511 :see: :js:func:`HTTP.req_rep_header()`
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001512
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001513.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001514
1515 Rewrites the request method with the parameter "method".
1516
1517 :param class_http http: The related http object.
1518 :param string method: The new method.
1519
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001520.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001521
1522 Rewrites the request path with the "path" parameter.
1523
1524 :param class_http http: The related http object.
1525 :param string path: The new path.
1526
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001527.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001528
1529 Rewrites the request's query string which appears after the first question
1530 mark ("?") with the parameter "query".
1531
1532 :param class_http http: The related http object.
1533 :param string query: The new query.
1534
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +02001535.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001536
1537 Rewrites the request URI with the parameter "uri".
1538
1539 :param class_http http: The related http object.
1540 :param string uri: The new uri.
1541
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001542.. js:function:: HTTP.res_set_status(http, status [, reason])
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001543
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001544 Rewrites the response status code with the parameter "code".
1545
1546 If no custom reason is provided, it will be generated from the status.
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001547
1548 :param class_http http: The related http object.
1549 :param integer status: The new response status code.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08001550 :param string reason: The new response reason (optional).
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +02001551
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001552.. _txn_class:
1553
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001554TXN class
1555=========
1556
1557.. js:class:: TXN
1558
1559 The txn class contain all the functions relative to the http or tcp
1560 transaction (Note than a tcp stream is the same than a tcp transaction, but
1561 an HTTP transaction is not the same than a tcp stream).
1562
1563 The usage of this class permits to retrieve data from the requests, alter it
1564 and forward it.
1565
1566 All the functions provided by this class are available in the context
1567 **sample-fetches** and **actions**.
1568
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001569.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001570
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001571 :returns: An :ref:`converters_class`.
1572
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001573 This attribute contains a Converters class object.
1574
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001575.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001576
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001577 :returns: An :ref:`converters_class`.
1578
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001579 This attribute contains a Converters class object. The functions of
1580 this object returns always a string.
1581
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001582.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001583
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001584 :returns: An :ref:`fetches_class`.
1585
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001586 This attribute contains a Fetches class object.
1587
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001588.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001589
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001590 :returns: An :ref:`fetches_class`.
1591
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001592 This attribute contains a Fetches class object. The functions of
1593 this object returns always a string.
1594
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001595.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001596
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001597 :returns: An :ref:`channel_class`.
1598
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001599 This attribute contains a channel class object for the request buffer.
1600
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001601.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001602
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001603 :returns: An :ref:`channel_class`.
1604
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001605 This attribute contains a channel class object for the response buffer.
1606
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001607.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001608
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001609 :returns: An :ref:`http_class`.
1610
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001611 This attribute contains an HTTP class object. It is available only if the
Thierry FOURNIER08504f42015-03-16 14:17:08 +01001612 proxy has the "mode http" enabled.
1613
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001614.. js:function:: TXN.log(TXN, loglevel, msg)
1615
1616 This function sends a log. The log is sent, according with the HAProxy
1617 configuration file, on the default syslog server if it is configured and on
1618 the stderr if it is allowed.
1619
1620 :param class_txn txn: The class txn object containing the data.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001621 :param integer loglevel: Is the log level associated with the message. It is a
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001622 number between 0 and 7.
1623 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001624 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1625 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1626 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
1627 :see: :js:func:`TXN.deflog`
1628 :see: :js:func:`TXN.Debug`
1629 :see: :js:func:`TXN.Info`
1630 :see: :js:func:`TXN.Warning`
1631 :see: :js:func:`TXN.Alert`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001632
1633.. js:function:: TXN.deflog(TXN, msg)
1634
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001635 Sends a log line with the default loglevel for the proxy associated with the
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001636 transaction.
1637
1638 :param class_txn txn: The class txn object containing the data.
1639 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001640 :see: :js:func:`TXN.log
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001641
1642.. js:function:: TXN.Debug(txn, msg)
1643
1644 :param class_txn txn: The class txn object containing the data.
1645 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001646 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001647
1648 Does the same job than:
1649
1650.. code-block:: lua
1651
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001652 function Debug(txn, msg)
1653 TXN.log(txn, core.debug, msg)
1654 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001655..
1656
1657.. js:function:: TXN.Info(txn, msg)
1658
1659 :param class_txn txn: The class txn object containing the data.
1660 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001661 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001662
1663.. code-block:: lua
1664
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001665 function Debug(txn, msg)
1666 TXN.log(txn, core.info, msg)
1667 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001668..
1669
1670.. js:function:: TXN.Warning(txn, msg)
1671
1672 :param class_txn txn: The class txn object containing the data.
1673 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001674 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001675
1676.. code-block:: lua
1677
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001678 function Debug(txn, msg)
1679 TXN.log(txn, core.warning, msg)
1680 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001681..
1682
1683.. js:function:: TXN.Alert(txn, msg)
1684
1685 :param class_txn txn: The class txn object containing the data.
1686 :param string msg: The log content.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001687 :see: :js:func:`TXN.log`
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001688
1689.. code-block:: lua
1690
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001691 function Debug(txn, msg)
1692 TXN.log(txn, core.alert, msg)
1693 end
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +01001694..
1695
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001696.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001697
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001698 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001699 function. If no data are stored, it returns a nil value.
1700
1701 :param class_txn txn: The class txn object containing the data.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001702 :returns: the opaque data previously stored, or nil if nothing is
1703 available.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001704
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001705.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001706
1707 Store any data in the current HAProxy transaction. This action replace the
1708 old stored data.
1709
1710 :param class_txn txn: The class txn object containing the data.
1711 :param opaque data: The data which is stored in the transaction.
1712
Tim Duesterhus4e172c92020-05-19 13:49:42 +02001713.. js:function:: TXN.set_var(TXN, var, value[, ifexist])
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001714
David Carlier61fdf8b2015-10-02 11:59:38 +01001715 Converts a Lua type in a HAProxy type and store it in a variable <var>.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001716
1717 :param class_txn txn: The class txn object containing the data.
1718 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER / OZON.IOb210bcc2016-12-12 16:24:16 +01001719 :param type value: The value associated to the variable. The type can be string or
1720 integer.
Tim Duesterhus4e172c92020-05-19 13:49:42 +02001721 :param boolean ifexist: If this parameter is set to a truthy value the variable
1722 will only be set if it was defined elsewhere (i.e. used
1723 within the configuration). It is highly recommended to
1724 always set this to true.
Christopher Faulet85d79c92016-11-09 16:54:56 +01001725
1726.. js:function:: TXN.unset_var(TXN, var)
1727
1728 Unset the variable <var>.
1729
1730 :param class_txn txn: The class txn object containing the data.
1731 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +02001732
1733.. js:function:: TXN.get_var(TXN, var)
1734
1735 Returns data stored in the variable <var> converter in Lua type.
1736
1737 :param class_txn txn: The class txn object containing the data.
1738 :param string var: The variable name according with the HAProxy variable syntax.
1739
Christopher Faulet700d9e82020-01-31 12:21:52 +01001740.. js:function:: TXN.reply([reply])
1741
1742 Return a new reply object
1743
1744 :param table reply: A table containing info to initialize the reply fields.
1745 :returns: A :ref:`reply_class` object.
1746
1747 The table used to initialized the reply object may contain following entries :
1748
1749 * status : The reply status code. the code 200 is used by default.
1750 * reason : The reply reason. The reason corresponding to the status code is
1751 used by default.
1752 * headers : An list of headers, indexed by header name. Empty by default. For
1753 a given name, multiple values are possible, stored in an ordered list.
1754 * body : The reply body, empty by default.
1755
1756.. code-block:: lua
1757
1758 local reply = txn:reply{
1759 status = 400,
1760 reason = "Bad request",
1761 headers = {
1762 ["content-type"] = { "text/html" },
1763 ["cache-control"] = {"no-cache", "no-store" }
1764 },
1765 body = "<html><body><h1>invalid request<h1></body></html>"
1766 }
1767..
1768 :see: :js:class:`Reply`
1769
1770.. js:function:: TXN.done(txn[, reply])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001771
Willy Tarreaubc183a62015-08-28 10:39:11 +02001772 This function terminates processing of the transaction and the associated
Christopher Faulet700d9e82020-01-31 12:21:52 +01001773 session and optionally reply to the client for HTTP sessions.
1774
1775 :param class_txn txn: The class txn object containing the data.
1776 :param class_reply reply: The class reply object to return to the client.
1777
1778 This functions can be used when a critical error is detected or to terminate
Willy Tarreaubc183a62015-08-28 10:39:11 +02001779 processing after some data have been returned to the client (eg: a redirect).
Christopher Faulet700d9e82020-01-31 12:21:52 +01001780 To do so, a reply may be provided. This object is optional and may contain a
1781 status code, a reason, a header list and a body. All these fields are
1782 optionnals. When not provided, the default values are used. By default, with
1783 an empty reply object, an empty HTTP 200 response is returned to the
1784 client. If no reply object is provided, the transaction is terminated without
1785 any reply.
1786
1787 The reply object may be fully created in lua or the class Reply may be used to
1788 create it.
1789
1790.. code-block:: lua
1791
1792 local reply = txn:reply()
1793 reply:set_status(400, "Bad request")
1794 reply:add_header("content-type", "text/html")
1795 reply:add_header("cache-control", "no-cache")
1796 reply:add_header("cache-control", "no-store")
1797 reply:set_body("<html><body><h1>invalid request<h1></body></html>")
1798 txn:done(reply)
1799..
1800
1801.. code-block:: lua
1802
1803 txn:done{
1804 status = 400,
1805 reason = "Bad request",
1806 headers = {
1807 ["content-type"] = { "text/html" },
1808 ["cache-control"] = { "no-cache", "no-store" },
1809 },
1810 body = "<html><body><h1>invalid request<h1></body></html>"
1811 }
1812..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001813
Thierry FOURNIERab00df62016-07-14 11:42:37 +02001814 *Warning*: It not make sense to call this function from sample-fetches. In
1815 this case the behaviour of this one is the same than core.done(): it quit
1816 the Lua execution. The transaction is really aborted only from an action
1817 registered function.
1818
Christopher Faulet700d9e82020-01-31 12:21:52 +01001819 :see: :js:func:`TXN.reply`, :js:class:`Reply`
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001820
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001821.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001822
1823 Is used to change the log level of the current request. The "loglevel" must
1824 be an integer between 0 and 7.
1825
1826 :param class_txn txn: The class txn object containing the data.
1827 :param integer loglevel: The required log level. This variable can be one of
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01001828 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`,
1829 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`,
1830 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001831
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001832.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001833
1834 Is used to set the TOS or DSCP field value of packets sent to the client to
1835 the value passed in "tos" on platforms which support this.
1836
1837 :param class_txn txn: The class txn object containing the data.
1838 :param integer tos: The new TOS os DSCP.
1839
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001840.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001841
1842 Is used to set the Netfilter MARK on all packets sent to the client to the
1843 value passed in "mark" on platforms which support it.
1844
1845 :param class_txn txn: The class txn object containing the data.
1846 :param integer mark: The mark value.
1847
Patrick Hemmer268a7072018-05-11 12:52:31 -04001848.. js:function:: TXN.set_priority_class(txn, prio)
1849
1850 This function adjusts the priority class of the transaction. The value should
1851 be within the range -2047..2047. Values outside this range will be
1852 truncated.
1853
1854 See the HAProxy configuration.txt file keyword "http-request" action
1855 "set-priority-class" for details.
1856
1857.. js:function:: TXN.set_priority_offset(txn, prio)
1858
1859 This function adjusts the priority offset of the transaction. The value
1860 should be within the range -524287..524287. Values outside this range will be
1861 truncated.
1862
1863 See the HAProxy configuration.txt file keyword "http-request" action
1864 "set-priority-offset" for details.
1865
Christopher Faulet700d9e82020-01-31 12:21:52 +01001866.. _reply_class:
1867
1868Reply class
1869============
1870
1871.. js:class:: Reply
1872
1873 **context**: action
1874
1875 This class represents an HTTP response message. It provides some methods to
1876 enrich it.
1877
1878.. code-block:: lua
1879
1880 local reply = txn:reply({status = 400}) -- default HTTP 400 reason-phase used
1881 reply:add_header("content-type", "text/html")
1882 reply:add_header("cache-control", "no-cache")
1883 reply:add_header("cache-control", "no-store")
1884 reply:set_body("<html><body><h1>invalid request<h1></body></html>")
1885..
1886
1887 :see: :js:func:`TXN.reply`
1888
1889.. js:attribute:: Reply.status
1890
1891 The reply status code. By default, the status code is set to 200.
1892
1893 :returns: integer
1894
1895.. js:attribute:: Reply.reason
1896
1897 The reason string describing the status code.
1898
1899 :returns: string
1900
1901.. js:attribute:: Reply.headers
1902
1903 A table indexing all reply headers by name. To each name is associated an
1904 ordered list of values.
1905
1906 :returns: Lua table
1907
1908.. code-block:: lua
1909
1910 {
1911 ["content-type"] = { "text/html" },
1912 ["cache-control"] = {"no-cache", "no-store" },
1913 x_header_name = { "value1", "value2", ... }
1914 ...
1915 }
1916..
1917
1918.. js:attribute:: Reply.body
1919
1920 The reply payload.
1921
1922 :returns: string
1923
1924.. js:function:: Reply.set_status(REPLY, status[, reason])
1925
1926 Set the reply status code and optionally the reason-phrase. If the reason is
1927 not provided, the default reason corresponding to the status code is used.
1928
1929 :param class_reply reply: The related Reply object.
1930 :param integer status: The reply status code.
1931 :param string reason: The reply status reason (optional).
1932
1933.. js:function:: Reply.add_header(REPLY, name, value)
1934
1935 Add a header to the reply object. If the header does not already exist, a new
1936 entry is created with its name as index and a one-element list containing its
1937 value as value. Otherwise, the header value is appended to the ordered list of
1938 values associated to the header name.
1939
1940 :param class_reply reply: The related Reply object.
1941 :param string name: The header field name.
1942 :param string value: The header field value.
1943
1944.. js:function:: Reply.del_header(REPLY, name)
1945
1946 Remove all occurrences of a header name from the reply object.
1947
1948 :param class_reply reply: The related Reply object.
1949 :param string name: The header field name.
1950
1951.. js:function:: Reply.set_body(REPLY, body)
1952
1953 Set the reply payload.
1954
1955 :param class_reply reply: The related Reply object.
1956 :param string body: The reply payload.
1957
Thierry FOURNIERdc595002015-12-21 11:13:52 +01001958.. _socket_class:
1959
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001960Socket class
1961============
1962
1963.. js:class:: Socket
1964
1965 This class must be compatible with the Lua Socket class. Only the 'client'
1966 functions are available. See the Lua Socket documentation:
1967
1968 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1969 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1970
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001971.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001972
1973 Closes a TCP object. The internal socket used by the object is closed and the
1974 local address to which the object was bound is made available to other
1975 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001976 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001977
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001978 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001979
1980 Note: It is important to close all used sockets once they are not needed,
1981 since, in many systems, each socket uses a file descriptor, which are limited
1982 system resources. Garbage-collected objects are automatically closed before
1983 destruction, though.
1984
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001985.. js:function:: Socket.connect(socket, address[, port])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001986
1987 Attempts to connect a socket object to a remote host.
1988
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001989
1990 In case of error, the method returns nil followed by a string describing the
1991 error. In case of success, the method returns 1.
1992
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001993 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02001994 :param string address: can be an IP address or a host name. See below for more
1995 information.
1996 :param integer port: must be an integer number in the range [1..64K].
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001997 :returns: 1 or nil.
1998
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01001999 An address field extension permits to use the connect() function to connect to
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002000 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is
2001 the basically expected format. This format requires the port.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002002
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002003 Other format accepted are a socket path like "/socket/path", it permits to
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002004 connect to a socket. Abstract namespaces are supported with the prefix
Joseph Herlant02cedc42018-11-13 19:45:17 -08002005 "abns@", and finally a file descriptor can be passed with the prefix "fd@".
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002006 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002007 passed int the string. The syntax "127.0.0.1:1234" is valid. In this case, the
Tim Duesterhus6edab862018-01-06 19:04:45 +01002008 parameter *port* must not be set.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002009
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002010.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002011
2012 Same behavior than the function socket:connect, but uses SSL.
2013
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002014 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002015 :returns: 1 or nil.
2016
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002017.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002018
2019 Returns information about the remote side of a connected client object.
2020
2021 Returns a string with the IP address of the peer, followed by the port number
2022 that peer is using for the connection. In case of error, the method returns
2023 nil.
2024
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002025 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002026 :returns: a string containing the server information.
2027
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002028.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002029
2030 Returns the local address information associated to the object.
2031
2032 The method returns a string with local IP address and a number with the port.
2033 In case of error, the method returns nil.
2034
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002035 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002036 :returns: a string containing the client information.
2037
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002038.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002039
2040 Reads data from a client object, according to the specified read pattern.
2041 Patterns follow the Lua file I/O format, and the difference in performance
2042 between all patterns is negligible.
2043
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002044 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002045 :param string|integer pattern: Describe what is required (see below).
2046 :param string prefix: A string which will be prefix the returned data.
2047 :returns: a string containing the required data or nil.
2048
2049 Pattern can be any of the following:
2050
2051 * **`*a`**: reads from the socket until the connection is closed. No
2052 end-of-line translation is performed;
2053
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002054 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002055 LF character (ASCII 10), optionally preceded by a CR character
2056 (ASCII 13). The CR and LF characters are not included in the
2057 returned line. In fact, all CR characters are ignored by the
2058 pattern. This is the default pattern.
2059
2060 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002061 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002062 beginning of any received data before return.
2063
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002064 * **empty**: If the pattern is left empty, the default option is `*l`.
2065
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002066 If successful, the method returns the received pattern. In case of error, the
2067 method returns nil followed by an error message which can be the string
2068 'closed' in case the connection was closed before the transmission was
2069 completed or the string 'timeout' in case there was a timeout during the
2070 operation. Also, after the error message, the function returns the partial
2071 result of the transmission.
2072
2073 Important note: This function was changed severely. It used to support
2074 multiple patterns (but I have never seen this feature used) and now it
2075 doesn't anymore. Partial results used to be returned in the same way as
2076 successful results. This last feature violated the idea that all functions
2077 should return nil on error. Thus it was changed too.
2078
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002079.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002080
2081 Sends data through client object.
2082
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002083 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002084 :param string data: The data that will be sent.
2085 :param integer start: The start position in the buffer of the data which will
2086 be sent.
2087 :param integer end: The end position in the buffer of the data which will
2088 be sent.
2089 :returns: see below.
2090
2091 Data is the string to be sent. The optional arguments i and j work exactly
2092 like the standard string.sub Lua function to allow the selection of a
2093 substring to be sent.
2094
2095 If successful, the method returns the index of the last byte within [start,
2096 end] that has been sent. Notice that, if start is 1 or absent, this is
2097 effectively the total number of bytes sent. In case of error, the method
2098 returns nil, followed by an error message, followed by the index of the last
2099 byte within [start, end] that has been sent. You might want to try again from
2100 the byte following that. The error message can be 'closed' in case the
2101 connection was closed before the transmission was completed or the string
2102 'timeout' in case there was a timeout during the operation.
2103
2104 Note: Output is not buffered. For small strings, it is always better to
2105 concatenate them in Lua (with the '..' operator) and send the result in one
2106 call instead of calling the method several times.
2107
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002108.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002109
2110 Just implemented for compatibility, this cal does nothing.
2111
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002112.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002113
2114 Changes the timeout values for the object. All I/O operations are blocking.
2115 That is, any call to the methods send, receive, and accept will block
2116 indefinitely, until the operation completes. The settimeout method defines a
2117 limit on the amount of time the I/O methods can block. When a timeout time
2118 has elapsed, the affected methods give up and fail with an error code.
2119
2120 The amount of time to wait is specified as the value parameter, in seconds.
2121
Mark Lakes56cc1252018-03-27 09:48:06 +02002122 The timeout modes are not implemented, the only settable timeout is the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002123 inactivity time waiting for complete the internal buffer send or waiting for
2124 receive data.
2125
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01002126 :param class_socket socket: Is the manipulated Socket.
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002127 :param float value: The timeout value. Use floating point to specify
Mark Lakes56cc1252018-03-27 09:48:06 +02002128 milliseconds.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002129
Thierry FOURNIER31904272017-10-25 12:59:51 +02002130.. _regex_class:
2131
2132Regex class
2133===========
2134
2135.. js:class:: Regex
2136
2137 This class allows the usage of HAProxy regexes because classic lua doesn't
2138 provides regexes. This class inherits the HAProxy compilation options, so the
2139 regexes can be libc regex, pcre regex or pcre JIT regex.
2140
2141 The expression matching number is limited to 20 per regex. The only available
2142 option is case sensitive.
2143
2144 Because regexes compilation is a heavy process, it is better to define all
2145 your regexes in the **body context** and use it during the runtime.
2146
2147.. code-block:: lua
2148
2149 -- Create the regex
2150 st, regex = Regex.new("needle (..) (...)", true);
2151
2152 -- Check compilation errors
2153 if st == false then
2154 print "error: " .. regex
2155 end
2156
2157 -- Match the regexes
2158 print(regex:exec("Looking for a needle in the haystack")) -- true
2159 print(regex:exec("Lokking for a cat in the haystack")) -- false
2160
2161 -- Extract words
2162 st, list = regex:match("Looking for a needle in the haystack")
2163 print(st) -- true
2164 print(list[1]) -- needle in the
2165 print(list[2]) -- in
2166 print(list[3]) -- the
2167
2168.. js:function:: Regex.new(regex, case_sensitive)
2169
2170 Create and compile a regex.
2171
2172 :param string regex: The regular expression according with the libc or pcre
2173 standard
2174 :param boolean case_sensitive: Match is case sensitive or not.
2175 :returns: boolean status and :ref:`regex_class` or string containing fail reason.
2176
2177.. js:function:: Regex.exec(regex, str)
2178
2179 Execute the regex.
2180
2181 :param class_regex regex: A :ref:`regex_class` object.
2182 :param string str: The input string will be compared with the compiled regex.
2183 :returns: a boolean status according with the match result.
2184
2185.. js:function:: Regex.match(regex, str)
2186
2187 Execute the regex and return matched expressions.
2188
2189 :param class_map map: A :ref:`regex_class` object.
2190 :param string str: The input string will be compared with the compiled regex.
2191 :returns: a boolean status according with the match result, and
2192 a table containing all the string matched in order of declaration.
2193
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002194.. _map_class:
2195
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002196Map class
2197=========
2198
2199.. js:class:: Map
2200
2201 This class permits to do some lookup in HAProxy maps. The declared maps can
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002202 be modified during the runtime through the HAProxy management socket.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002203
2204.. code-block:: lua
2205
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002206 default = "usa"
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002207
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002208 -- Create and load map
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002209 geo = Map.new("geo.map", Map._ip);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002210
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002211 -- Create new fetch that returns the user country
2212 core.register_fetches("country", function(txn)
2213 local src;
2214 local loc;
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002215
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002216 src = txn.f:fhdr("x-forwarded-for");
2217 if (src == nil) then
2218 src = txn.f:src()
2219 if (src == nil) then
2220 return default;
2221 end
2222 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002223
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002224 -- Perform lookup
2225 loc = geo:lookup(src);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002226
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002227 if (loc == nil) then
2228 return default;
2229 end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002230
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002231 return loc;
2232 end);
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002233
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002234.. js:attribute:: Map._int
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002235
2236 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002237 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002238 method.
2239
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002240 Note that :js:attr:`Map.int` is also available for compatibility.
2241
2242.. js:attribute:: Map._ip
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002243
2244 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002245 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002246 method.
2247
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002248 Note that :js:attr:`Map.ip` is also available for compatibility.
2249
2250.. js:attribute:: Map._str
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002251
2252 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002253 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002254 method.
2255
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002256 Note that :js:attr:`Map.str` is also available for compatibility.
2257
2258.. js:attribute:: Map._beg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002259
2260 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002261 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002262 method.
2263
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002264 Note that :js:attr:`Map.beg` is also available for compatibility.
2265
2266.. js:attribute:: Map._sub
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002267
2268 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002269 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002270 method.
2271
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002272 Note that :js:attr:`Map.sub` is also available for compatibility.
2273
2274.. js:attribute:: Map._dir
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002275
2276 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002277 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002278 method.
2279
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002280 Note that :js:attr:`Map.dir` is also available for compatibility.
2281
2282.. js:attribute:: Map._dom
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002283
2284 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002285 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002286 method.
2287
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002288 Note that :js:attr:`Map.dom` is also available for compatibility.
2289
2290.. js:attribute:: Map._end
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002291
2292 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002293 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002294 method.
2295
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002296.. js:attribute:: Map._reg
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002297
2298 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002299 samples" and subchapter "ACL basics" to understand this pattern matching
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002300 method.
2301
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002302 Note that :js:attr:`Map.reg` is also available for compatibility.
2303
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002304
2305.. js:function:: Map.new(file, method)
2306
2307 Creates and load a map.
2308
2309 :param string file: Is the file containing the map.
2310 :param integer method: Is the map pattern matching method. See the attributes
2311 of the Map class.
2312 :returns: a class Map object.
Thierry FOURNIER4dc71972017-01-28 08:33:08 +01002313 :see: The Map attributes: :js:attr:`Map._int`, :js:attr:`Map._ip`,
2314 :js:attr:`Map._str`, :js:attr:`Map._beg`, :js:attr:`Map._sub`,
2315 :js:attr:`Map._dir`, :js:attr:`Map._dom`, :js:attr:`Map._end` and
2316 :js:attr:`Map._reg`.
Thierry FOURNIER3def3932015-04-07 11:27:54 +02002317
2318.. js:function:: Map.lookup(map, str)
2319
2320 Perform a lookup in a map.
2321
2322 :param class_map map: Is the class Map object.
2323 :param string str: Is the string used as key.
2324 :returns: a string containing the result or nil if no match.
2325
2326.. js:function:: Map.slookup(map, str)
2327
2328 Perform a lookup in a map.
2329
2330 :param class_map map: Is the class Map object.
2331 :param string str: Is the string used as key.
2332 :returns: a string containing the result or empty string if no match.
2333
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002334.. _applethttp_class:
2335
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002336AppletHTTP class
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002337================
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002338
2339.. js:class:: AppletHTTP
2340
2341 This class is used with applets that requires the 'http' mode. The http applet
2342 can be registered with the *core.register_service()* function. They are used
2343 for processing an http request like a server in back of HAProxy.
2344
2345 This is an hello world sample code:
2346
2347.. code-block:: lua
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002348
Pieter Baauw4d7f7662015-11-08 16:38:08 +01002349 core.register_service("hello-world", "http", function(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002350 local response = "Hello World !"
2351 applet:set_status(200)
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002352 applet:add_header("content-length", string.len(response))
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002353 applet:add_header("content-type", "text/plain")
Pieter Baauw2dcb9bc2015-10-01 22:47:12 +02002354 applet:start_response()
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002355 applet:send(response)
2356 end)
2357
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002358.. js:attribute:: AppletHTTP.c
2359
2360 :returns: A :ref:`converters_class`
2361
2362 This attribute contains a Converters class object.
2363
2364.. js:attribute:: AppletHTTP.sc
2365
2366 :returns: A :ref:`converters_class`
2367
2368 This attribute contains a Converters class object. The
2369 functions of this object returns always a string.
2370
2371.. js:attribute:: AppletHTTP.f
2372
2373 :returns: A :ref:`fetches_class`
2374
2375 This attribute contains a Fetches class object. Note that the
2376 applet execution place cannot access to a valid HAProxy core HTTP
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002377 transaction, so some sample fetches related to the HTTP dependent
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002378 values (hdr, path, ...) are not available.
2379
2380.. js:attribute:: AppletHTTP.sf
2381
2382 :returns: A :ref:`fetches_class`
2383
2384 This attribute contains a Fetches class object. The functions of
2385 this object returns always a string. Note that the applet
2386 execution place cannot access to a valid HAProxy core HTTP
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002387 transaction, so some sample fetches related to the HTTP dependent
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002388 values (hdr, path, ...) are not available.
2389
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002390.. js:attribute:: AppletHTTP.method
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002391
2392 :returns: string
2393
2394 The attribute method returns a string containing the HTTP
2395 method.
2396
2397.. js:attribute:: AppletHTTP.version
2398
2399 :returns: string
2400
2401 The attribute version, returns a string containing the HTTP
2402 request version.
2403
2404.. js:attribute:: AppletHTTP.path
2405
2406 :returns: string
2407
2408 The attribute path returns a string containing the HTTP
2409 request path.
2410
2411.. js:attribute:: AppletHTTP.qs
2412
2413 :returns: string
2414
2415 The attribute qs returns a string containing the HTTP
2416 request query string.
2417
2418.. js:attribute:: AppletHTTP.length
2419
2420 :returns: integer
2421
2422 The attribute length returns an integer containing the HTTP
2423 body length.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002424
Thierry FOURNIER841475e2015-12-11 17:10:09 +01002425.. js:attribute:: AppletHTTP.headers
2426
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002427 :returns: table
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002428
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002429 The attribute headers returns a table containing the HTTP
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002430 headers. The header names are always in lower case. As the header name can be
2431 encountered more than once in each request, the value is indexed with 0 as
Patrick Hemmerc6a1d712018-05-01 21:30:41 -04002432 first index value. The table have this form:
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002433
2434.. code-block:: lua
2435
2436 AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>"
2437
2438 AppletHTTP.headers["host"][0] = "www.test.com"
2439 AppletHTTP.headers["accept"][0] = "audio/basic q=1"
2440 AppletHTTP.headers["accept"][1] = "audio/*, q=0.2"
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002441 AppletHTTP.headers["accept"][2] = "*/*, q=0.1"
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002442..
2443
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002444.. js:function:: AppletHTTP.set_status(applet, code [, reason])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002445
2446 This function sets the HTTP status code for the response. The allowed code are
2447 from 100 to 599.
2448
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002449 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002450 :param integer code: the status code returned to the client.
Robin H. Johnson52f5db22017-01-01 13:10:52 -08002451 :param string reason: the status reason returned to the client (optional).
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002452
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002453.. js:function:: AppletHTTP.add_header(applet, name, value)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002454
2455 This function add an header in the response. Duplicated headers are not
2456 collapsed. The special header *content-length* is used to determinate the
2457 response length. If it not exists, a *transfer-encoding: chunked* is set, and
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002458 all the write from the function *AppletHTTP:send()* become a chunk.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002459
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002460 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002461 :param string name: the header name
2462 :param string value: the header value
2463
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002464.. js:function:: AppletHTTP.start_response(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002465
2466 This function indicates to the HTTP engine that it can process and send the
2467 response headers. After this called we cannot add headers to the response; We
2468 cannot use the *AppletHTTP:send()* function if the
2469 *AppletHTTP:start_response()* is not called.
2470
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002471 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2472
2473.. js:function:: AppletHTTP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002474
2475 This function returns a string containing one line from the http body. If the
2476 data returned doesn't contains a final '\\n' its assumed than its the last
2477 available data before the end of stream.
2478
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002479 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002480 :returns: a string. The string can be empty if we reach the end of the stream.
2481
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002482.. js:function:: AppletHTTP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002483
2484 Reads data from the HTTP body, according to the specified read *size*. If the
2485 *size* is missing, the function tries to read all the content of the stream
2486 until the end. If the *size* is bigger than the http body, it returns the
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002487 amount of data available.
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002488
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002489 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002490 :param integer size: the required read size.
2491 :returns: always return a string,the string can be empty is the connexion is
2492 closed.
2493
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002494.. js:function:: AppletHTTP.send(applet, msg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002495
2496 Send the message *msg* on the http request body.
2497
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002498 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002499 :param string msg: the message to send.
2500
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002501.. js:function:: AppletHTTP.get_priv(applet)
2502
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002503 Return Lua data stored in the current transaction. If no data are stored,
2504 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002505
2506 :param class_AppletHTTP applet: An :ref:`applethttp_class`
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002507 :returns: the opaque data previously stored, or nil if nothing is
2508 available.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002509 :see: :js:func:`AppletHTTP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002510
2511.. js:function:: AppletHTTP.set_priv(applet, data)
2512
2513 Store any data in the current HAProxy transaction. This action replace the
2514 old stored data.
2515
2516 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2517 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002518 :see: :js:func:`AppletHTTP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002519
Tim Duesterhus4e172c92020-05-19 13:49:42 +02002520.. js:function:: AppletHTTP.set_var(applet, var, value[, ifexist])
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002521
2522 Converts a Lua type in a HAProxy type and store it in a variable <var>.
2523
2524 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2525 :param string var: The variable name according with the HAProxy variable syntax.
2526 :param type value: The value associated to the variable. The type ca be string or
2527 integer.
Tim Duesterhus4e172c92020-05-19 13:49:42 +02002528 :param boolean ifexist: If this parameter is set to a truthy value the variable
2529 will only be set if it was defined elsewhere (i.e. used
2530 within the configuration). It is highly recommended to
2531 always set this to true.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002532 :see: :js:func:`AppletHTTP.unset_var`
2533 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002534
2535.. js:function:: AppletHTTP.unset_var(applet, var)
2536
2537 Unset the variable <var>.
2538
2539 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2540 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002541 :see: :js:func:`AppletHTTP.set_var`
2542 :see: :js:func:`AppletHTTP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002543
2544.. js:function:: AppletHTTP.get_var(applet, var)
2545
2546 Returns data stored in the variable <var> converter in Lua type.
2547
2548 :param class_AppletHTTP applet: An :ref:`applethttp_class`
2549 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002550 :see: :js:func:`AppletHTTP.set_var`
2551 :see: :js:func:`AppletHTTP.unset_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002552
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002553.. _applettcp_class:
2554
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002555AppletTCP class
2556===============
2557
2558.. js:class:: AppletTCP
2559
2560 This class is used with applets that requires the 'tcp' mode. The tcp applet
2561 can be registered with the *core.register_service()* function. They are used
2562 for processing a tcp stream like a server in back of HAProxy.
2563
Thierry FOURNIERdc595002015-12-21 11:13:52 +01002564.. js:attribute:: AppletTCP.c
2565
2566 :returns: A :ref:`converters_class`
2567
2568 This attribute contains a Converters class object.
2569
2570.. js:attribute:: AppletTCP.sc
2571
2572 :returns: A :ref:`converters_class`
2573
2574 This attribute contains a Converters class object. The
2575 functions of this object returns always a string.
2576
2577.. js:attribute:: AppletTCP.f
2578
2579 :returns: A :ref:`fetches_class`
2580
2581 This attribute contains a Fetches class object.
2582
2583.. js:attribute:: AppletTCP.sf
2584
2585 :returns: A :ref:`fetches_class`
2586
2587 This attribute contains a Fetches class object.
2588
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002589.. js:function:: AppletTCP.getline(applet)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002590
2591 This function returns a string containing one line from the stream. If the
2592 data returned doesn't contains a final '\\n' its assumed than its the last
2593 available data before the end of stream.
2594
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002595 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002596 :returns: a string. The string can be empty if we reach the end of the stream.
2597
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002598.. js:function:: AppletTCP.receive(applet, [size])
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002599
2600 Reads data from the TCP stream, according to the specified read *size*. If the
2601 *size* is missing, the function tries to read all the content of the stream
2602 until the end.
2603
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002604 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002605 :param integer size: the required read size.
2606 :returns: always return a string,the string can be empty is the connexion is
2607 closed.
2608
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002609.. js:function:: AppletTCP.send(appletmsg)
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002610
2611 Send the message on the stream.
2612
Thierry FOURNIERe34a78e2015-12-25 01:31:35 +01002613 :param class_AppletTCP applet: An :ref:`applettcp_class`
Thierry FOURNIERa3bc5132015-09-25 21:43:56 +02002614 :param string msg: the message to send.
2615
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002616.. js:function:: AppletTCP.get_priv(applet)
2617
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002618 Return Lua data stored in the current transaction. If no data are stored,
2619 it returns a nil value.
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002620
2621 :param class_AppletTCP applet: An :ref:`applettcp_class`
Bertrand Jacquin874a35c2018-09-10 21:26:07 +01002622 :returns: the opaque data previously stored, or nil if nothing is
2623 available.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002624 :see: :js:func:`AppletTCP.set_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002625
2626.. js:function:: AppletTCP.set_priv(applet, data)
2627
2628 Store any data in the current HAProxy transaction. This action replace the
2629 old stored data.
2630
2631 :param class_AppletTCP applet: An :ref:`applettcp_class`
2632 :param opaque data: The data which is stored in the transaction.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002633 :see: :js:func:`AppletTCP.get_priv`
Thierry FOURNIER8db004c2015-12-25 01:33:18 +01002634
Tim Duesterhus4e172c92020-05-19 13:49:42 +02002635.. js:function:: AppletTCP.set_var(applet, var, value[, ifexist])
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002636
2637 Converts a Lua type in a HAProxy type and stores it in a variable <var>.
2638
2639 :param class_AppletTCP applet: An :ref:`applettcp_class`
2640 :param string var: The variable name according with the HAProxy variable syntax.
2641 :param type value: The value associated to the variable. The type can be string or
2642 integer.
Tim Duesterhus4e172c92020-05-19 13:49:42 +02002643 :param boolean ifexist: If this parameter is set to a truthy value the variable
2644 will only be set if it was defined elsewhere (i.e. used
2645 within the configuration). It is highly recommended to
2646 always set this to true.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002647 :see: :js:func:`AppletTCP.unset_var`
2648 :see: :js:func:`AppletTCP.get_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002649
2650.. js:function:: AppletTCP.unset_var(applet, var)
2651
2652 Unsets the variable <var>.
2653
2654 :param class_AppletTCP applet: An :ref:`applettcp_class`
2655 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002656 :see: :js:func:`AppletTCP.unset_var`
2657 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002658
2659.. js:function:: AppletTCP.get_var(applet, var)
2660
2661 Returns data stored in the variable <var> converter in Lua type.
2662
2663 :param class_AppletTCP applet: An :ref:`applettcp_class`
2664 :param string var: The variable name according with the HAProxy variable syntax.
Thierry FOURNIER12a865d2016-12-14 19:40:37 +01002665 :see: :js:func:`AppletTCP.unset_var`
2666 :see: :js:func:`AppletTCP.set_var`
Thierry FOURNIER / OZON.IOc1edafe2016-12-12 16:25:30 +01002667
Adis Nezirovic8878f8e2018-07-13 12:18:33 +02002668StickTable class
2669================
2670
2671.. js:class:: StickTable
2672
2673 **context**: task, action, sample-fetch
2674
2675 This class can be used to access the HAProxy stick tables from Lua.
2676
2677.. js:function:: StickTable.info()
2678
2679 Returns stick table attributes as a Lua table. See HAProxy documentation for
2680 "stick-table" for canonical info, or check out example bellow.
2681
2682 :returns: Lua table
2683
2684 Assume our table has IPv4 key and gpc0 and conn_rate "columns":
2685
2686.. code-block:: lua
2687
2688 {
2689 expire=<int>, # Value in ms
2690 size=<int>, # Maximum table size
2691 used=<int>, # Actual number of entries in table
2692 data={ # Data columns, with types as key, and periods as values
2693 (-1 if type is not rate counter)
2694 conn_rate=<int>,
2695 gpc0=-1
2696 },
2697 length=<int>, # max string length for string table keys, key length
2698 # otherwise
2699 nopurge=<boolean>, # purge oldest entries when table is full
2700 type="ip" # can be "ip", "ipv6", "integer", "string", "binary"
2701 }
2702
2703.. js:function:: StickTable.lookup(key)
2704
2705 Returns stick table entry for given <key>
2706
2707 :param string key: Stick table key (IP addresses and strings are supported)
2708 :returns: Lua table
2709
2710.. js:function:: StickTable.dump([filter])
2711
2712 Returns all entries in stick table. An optional filter can be used
2713 to extract entries with specific data values. Filter is a table with valid
2714 comparison operators as keys followed by data type name and value pairs.
2715 Check out the HAProxy docs for "show table" for more details. For the
2716 reference, the supported operators are:
2717 "eq", "ne", "le", "lt", "ge", "gt"
2718
2719 For large tables, execution of this function can take a long time (for
2720 HAProxy standards). That's also true when filter is used, so take care and
2721 measure the impact.
2722
2723 :param table filter: Stick table filter
2724 :returns: Stick table entries (table)
2725
2726 See below for example filter, which contains 4 entries (or comparisons).
2727 (Maximum number of filter entries is 4, defined in the source code)
2728
2729.. code-block:: lua
2730
2731 local filter = {
2732 {"gpc0", "gt", 30}, {"gpc1", "gt", 20}}, {"conn_rate", "le", 10}
2733 }
2734
Christopher Faulet0f3c8902020-01-31 18:57:12 +01002735.. _action_class:
2736
2737Action class
2738=============
2739
2740.. js:class:: Act
2741
2742 **context**: action
2743
2744 This class contains all return codes an action may return. It is the lua
2745 equivalent to HAProxy "ACT_RET_*" code.
2746
2747.. code-block:: lua
2748
2749 core.register_action("deny", { "http-req" }, function (txn)
2750 return act.DENY
2751 end)
2752..
2753.. js:attribute:: act.CONTINUE
2754
2755 This attribute is an integer (0). It instructs HAProxy to continue the current
2756 ruleset processing on the message. It is the default return code for a lua
2757 action.
2758
2759 :returns: integer
2760
2761.. js:attribute:: act.STOP
2762
2763 This attribute is an integer (1). It instructs HAProxy to stop the current
2764 ruleset processing on the message.
2765
2766.. js:attribute:: act.YIELD
2767
2768 This attribute is an integer (2). It instructs HAProxy to temporarily pause
2769 the message processing. It will be resumed later on the same rule. The
2770 corresponding lua script is re-executed for the start.
2771
2772.. js:attribute:: act.ERROR
2773
2774 This attribute is an integer (3). It triggers an internal errors The message
2775 processing is stopped and the transaction is terminated. For HTTP streams, an
2776 HTTP 500 error is returned to the client.
2777
2778 :returns: integer
2779
2780.. js:attribute:: act.DONE
2781
2782 This attribute is an integer (4). It instructs HAProxy to stop the message
2783 processing.
2784
2785 :returns: integer
2786
2787.. js:attribute:: act.DENY
2788
2789 This attribute is an integer (5). It denies the current message. The message
2790 processing is stopped and the transaction is terminated. For HTTP streams, an
2791 HTTP 403 error is returned to the client if the deny is returned during the
2792 request analysis. During the response analysis, an HTTP 502 error is returned
2793 and the server response is discarded.
2794
2795 :returns: integer
2796
2797.. js:attribute:: act.ABORT
2798
2799 This attribute is an integer (6). It aborts the current message. The message
2800 processing is stopped and the transaction is terminated. For HTTP streams,
2801 HAproxy assumes a response was already sent to the client. From the Lua
2802 actions point of view, when this code is used, the transaction is terminated
2803 with no reply.
2804
2805 :returns: integer
2806
2807.. js:attribute:: act.INVALID
2808
2809 This attribute is an integer (7). It triggers an internal errors. The message
2810 processing is stopped and the transaction is terminated. For HTTP streams, an
2811 HTTP 400 error is returned to the client if the error is returned during the
2812 request analysis. During the response analysis, an HTTP 502 error is returned
2813 and the server response is discarded.
2814
2815 :returns: integer
Adis Nezirovic8878f8e2018-07-13 12:18:33 +02002816
Christopher Faulet2c2c2e32020-01-31 19:07:52 +01002817.. js:function:: act:wake_time(milliseconds)
2818
2819 **context**: action
2820
2821 Set the script pause timeout to the specified time, defined in
2822 milliseconds.
2823
2824 :param integer milliseconds: the required milliseconds.
2825
2826 This function may be used when a lua action returns `act.YIELD`, to force its
2827 wake-up at most after the specified number of milliseconds.
2828
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002829External Lua libraries
2830======================
2831
2832A lot of useful lua libraries can be found here:
2833
2834* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
2835
Ilya Shipitsin2075ca82020-03-06 23:22:22 +05002836Redis client library:
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01002837
2838* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
2839
2840This is an example about the usage of the Redis library with HAProxy. Note that
2841each call of any function of this library can throw an error if the socket
2842connection fails.
2843
2844.. code-block:: lua
2845
2846 -- load the redis library
2847 local redis = require("redis");
2848
2849 function do_something(txn)
2850
2851 -- create and connect new tcp socket
2852 local tcp = core.tcp();
2853 tcp:settimeout(1);
2854 tcp:connect("127.0.0.1", 6379);
2855
2856 -- use the redis library with this new socket
2857 local client = redis.connect({socket=tcp});
2858 client:ping();
2859
2860 end
2861
2862OpenSSL:
2863
2864* `http://mkottman.github.io/luacrypto/index.html
2865 <http://mkottman.github.io/luacrypto/index.html>`_
2866
2867* `https://github.com/brunoos/luasec/wiki
2868 <https://github.com/brunoos/luasec/wiki>`_