blob: bbefa84cdf3ce3b70a411e7ab1f9e9d402e4c9b1 [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
302. The Lua **init context**. It is an Lua function executed just after the
31 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
383. The Lua **task context**. It is an Lua function executed after the start
39 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
454. The **action context**. It is an Lua function conditionally executed. These
46 actions are declared by the HAProxy directives "`tcp-request content lua
47 <function>`", "`tcp-response content lua <function>`", "`http-request lua
48 <function>`" and "`http-response lua <function>`". The prototype of the
49 Lua called function is a function with doesn't returns anything and that take
50 an object of class TXN as entry. `function fcn(txn)`
51
525. The **sample-fetch context**. This function takes a TXN object as entry
53 argument and returns a string. These types of function cannot execute any
54 blocking function. They are useful to aggregate some of original HAProxy
55 sample-fetches and return the result. The prototype of the function is
56 `function string fcn(txn)`. These functions can be registered with the Lua
57 function `core.register_fetches()`. Each declared sample-fetch is prefixed by
58 the string "lua.".
59
60 **NOTE**: It is possible that this function cannot found the required data
61 in the original HAProxy sample-fetches, in this case, it cannot return the
62 result. This case is not yet supported
63
646. The **converter context**. It is an Lua function that takes a string as input
65 and returns another string as output. These types of function are stateless,
66 it cannot access to any context. They don't execute any blocking function.
67 The call prototype is `function string fcn(string)`. This function can be
68 registered with the Lua function `core.register_converters()`. Each declared
69 converter is prefixed by the string "lua.".
70
71HAProxy Lua Hello world
72-----------------------
73
74HAProxy configuration file (`hello_world.conf`):
75
76::
77
78 global
79 lua-load hello_world.lua
80
81 listen proxy
82 bind 127.0.0.1:10001
83 tcp-request content lua hello_world
84
85HAProxy Lua file (`hello_world.lua`):
86
87.. code-block:: lua
88
89 function hello_world(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +010090 txn.res:send("hello world\n")
Willy Tarreau99a36dd2015-08-27 14:57:04 +020091 txn:done()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +010092 end
93
94How to start HAProxy for testing this configuration:
95
96::
97
98 ./haproxy -f hello_world.conf
99
100On other terminal, you can test with telnet:
101
102::
103
104 #:~ telnet 127.0.0.1 10001
105 hello world
106
107Core class
108==========
109
110.. js:class:: core
111
112 The "core" class contains all the HAProxy core functions. These function are
113 useful for the controlling the execution flow, registering hooks, manipulating
114 global maps or ACL, ...
115
116 "core" class is basically provided with HAProxy. No `require` line is
117 required to uses these function.
118
119 The "core" class is static, t is not possible to create a new object of this
120 type.
121
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100122.. js:attribute:: core.emerg
123
124 This attribute is an integer, it contains the value of the loglevel "emergency" (0).
125
126.. js:attribute:: core.alert
127
128 This attribute is an integer, it contains the value of the loglevel "alert" (1).
129
130.. js:attribute:: core.crit
131
132 This attribute is an integer, it contains the value of the loglevel "critical" (2).
133
134.. js:attribute:: core.err
135
136 This attribute is an integer, it contains the value of the loglevel "error" (3).
137
138.. js:attribute:: core.warning
139
140 This attribute is an integer, it contains the value of the loglevel "warning" (4).
141
142.. js:attribute:: core.notice
143
144 This attribute is an integer, it contains the value of the loglevel "notice" (5).
145
146.. js:attribute:: core.info
147
148 This attribute is an integer, it contains the value of the loglevel "info" (6).
149
150.. js:attribute:: core.debug
151
152 This attribute is an integer, it contains the value of the loglevel "debug" (7).
153
154.. js:function:: core.log(loglevel, msg)
155
156 **context**: body, init, task, action, sample-fetch, converter
157
158 This fucntion sends a log. The log is sent, according with the HAProxy
159 configuration file, on the default syslog server if it is configured and on
160 the stderr if it is allowed.
161
162 :param integer loglevel: Is the log level asociated with the message. It is a
163 number between 0 and 7.
164 :param string msg: The log content.
165 :see: core.emerg, core.alert, core.crit, core.err, core.warning, core.notice,
166 core.info, core.debug (log level definitions)
167 :see: code.Debug
168 :see: core.Info
169 :see: core.Warning
170 :see: core.Alert
171
172.. js:function:: core.Debug(msg)
173
174 **context**: body, init, task, action, sample-fetch, converter
175
176 :param string msg: The log content.
177 :see: log
178
179 Does the same job than:
180
181.. code-block:: lua
182
183 function Debug(msg)
184 core.log(core.debug, msg)
185 end
186..
187
188.. js:function:: core.Info(msg)
189
190 **context**: body, init, task, action, sample-fetch, converter
191
192 :param string msg: The log content.
193 :see: log
194
195.. code-block:: lua
196
197 function Info(msg)
198 core.log(core.info, msg)
199 end
200..
201
202.. js:function:: core.Warning(msg)
203
204 **context**: body, init, task, action, sample-fetch, converter
205
206 :param string msg: The log content.
207 :see: log
208
209.. code-block:: lua
210
211 function Warning(msg)
212 core.log(core.warning, msg)
213 end
214..
215
216.. js:function:: core.Alert(msg)
217
218 **context**: body, init, task, action, sample-fetch, converter
219
220 :param string msg: The log content.
221 :see: log
222
223.. code-block:: lua
224
225 function Alert(msg)
226 core.log(core.alert, msg)
227 end
228..
229
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100230.. js:function:: core.add_acl(filename, key)
231
232 **context**: init, task, action, sample-fetch, converter
233
234 Add the ACL *key* in the ACLs list referenced by the file *filename*.
235
236 :param string filename: the filename that reference the ACL entries.
237 :param string key: the key which will be added.
238
239.. js:function:: core.del_acl(filename, key)
240
241 **context**: init, task, action, sample-fetch, converter
242
243 Delete the ACL entry referenced by the key *key* in the list of ACLs
244 referenced by *filename*.
245
246 :param string filename: the filename that reference the ACL entries.
247 :param string key: the key which will be deleted.
248
249.. js:function:: core.del_map(filename, key)
250
251 **context**: init, task, action, sample-fetch, converter
252
253 Delete the map entry indexed with the specified key in the list of maps
254 referenced by his filename.
255
256 :param string filename: the filename that reference the map entries.
257 :param string key: the key which will be deleted.
258
259.. js:function:: core.msleep(milliseconds)
260
261 **context**: body, init, task, action
262
263 The `core.msleep()` stops the Lua execution between specified milliseconds.
264
265 :param integer milliseconds: the required milliseconds.
266
Thierry FOURNIER8255a752015-09-23 21:03:35 +0200267.. js:function:: core.register_action(name, actions, func)
268
269 **context**: body
270
271 Register an Lua function executed as action. All the registered action can be
272 used in HAProxy with the prefix "lua.". An action gets a TXN object class as
273 input.
274
275 :param string name: is the name of the converter.
276 :param table actions: is a table of string describing the HAProxy actions who
277 want to register to. The expected actions are 'tcp-req',
278 'tcp-res', 'http-req' or 'http-res'.
279 :param function func: is the Lua function called to work as converter.
280
281 The prototype of the Lua function used as argument is:
282
283.. code-block:: lua
284
285 function(txn)
286..
287
288 * **txn** (*class TXN*): this is a TXN object used for manipulating the
289 current request or TCP stream.
290
291 Here, an exemple of action registration. the action juste send à 'Hello world'
292 in the logs.
293
294.. code-block:: lua
295
296 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn)
297 txn:Info("Hello world")
298 end)
299..
300
301 This example code is used in HAproxy configuration like this:
302
303::
304
305 frontend tcp_frt
306 mode tcp
307 tcp-request content lua.hello-world
308
309 frontend http_frt
310 mode http
311 http-request lua.hello-world
312
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100313.. js:function:: core.register_converters(name, func)
314
315 **context**: body
316
317 Register an Lua function executed as converter. All the registered converters
318 can be used in HAProxy with the prefix "lua.". An converter get a string as
319 input and return a string as output. The registered function can take up to 9
320 values as parameter. All the value are strings.
321
322 :param string name: is the name of the converter.
323 :param function func: is the Lua function called to work as converter.
324
325 The prototype of the Lua function used as argument is:
326
327.. code-block:: lua
328
329 function(str, [p1 [, p2 [, ... [, p5]]]])
330..
331
332 * **str** (*string*): this is the input value automatically converted in
333 string.
334 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
335 the haroxy configuration file. The number of arguments doesn't exceed 5.
336 The order and the nature of these is conventionally choose by the
337 developper.
338
339.. js:function:: core.register_fetches(name, func)
340
341 **context**: body
342
343 Register an Lua function executed as sample fetch. All the registered sample
344 fetchs can be used in HAProxy with the prefix "lua.". A Lua sample fetch
345 return a string as output. The registered function can take up to 9 values as
346 parameter. All the value are strings.
347
348 :param string name: is the name of the converter.
349 :param function func: is the Lua function called to work as sample fetch.
350
351 The prototype of the Lua function used as argument is:
352
353.. code-block:: lua
354
355 string function(txn, [p1 [, p2 [, ... [, p5]]]])
356..
357
358 * **txn** (*class txn*): this is the txn object associated with the current
359 request.
360 * **p1** .. **p5** (*string*): this is a list of string arguments declared in
361 the haroxy configuration file. The number of arguments doesn't exceed 5.
362 The order and the nature of these is conventionally choose by the
363 developper.
364 * **Returns**: A string containing some data, ot nil if the value cannot be
365 returned now.
366
367 lua example code:
368
369.. code-block:: lua
370
371 core.register_fetches("hello", function(txn)
372 return "hello"
373 end)
374..
375
376 HAProxy example configuration:
377
378::
379
380 frontend example
381 http-request redirect location /%[lua.hello]
382
383.. js:function:: core.register_init(func)
384
385 **context**: body
386
387 Register a function executed after the configuration parsing. This is useful
388 to check any parameters.
389
390 :param fuction func: is the Lua function called to work as initializer.
391
392 The prototype of the Lua function used as argument is:
393
394.. code-block:: lua
395
396 function()
397..
398
399 It takes no input, and no output is expected.
400
401.. js:function:: core.register_task(func)
402
403 **context**: body, init, task, action, sample-fetch, converter
404
405 Register and start independent task. The task is started when the HAProxy
406 main scheduler starts. For example this type of tasks can be executed to
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100407 perform complex health checks.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100408
409 :param fuction func: is the Lua function called to work as initializer.
410
411 The prototype of the Lua function used as argument is:
412
413.. code-block:: lua
414
415 function()
416..
417
418 It takes no input, and no output is expected.
419
420.. js:function:: core.set_nice(nice)
421
422 **context**: task, action, sample-fetch, converter
423
424 Change the nice of the current task or current session.
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100425
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100426 :param integer nice: the nice value, it must be between -1024 and 1024.
427
428.. js:function:: core.set_map(filename, key, value)
429
430 **context**: init, task, action, sample-fetch, converter
431
432 set the value *value* associated to the key *key* in the map referenced by
433 *filename*.
434
435.. js:function:: core.sleep(int seconds)
436
437 **context**: body, init, task, action
438
439 The `core.sleep()` functions stop the Lua execution between specified seconds.
440
441 :param integer seconds: the required seconds.
442
443.. js:function:: core.tcp()
444
445 **context**: init, task, action
446
447 This function returns a new object of a *socket* class.
448
449 :returns: A socket class object.
450
Thierry FOURNIER0a99b892015-08-26 00:14:17 +0200451.. js:function:: core.done(data)
452
453 **context**: body, init, task, action, sample-fetch, converter
454
455 :param any data: Return some data for the caller. It is useful with
456 sample-fetches and sample-converters.
457
458 Immediately stops the current Lua execution and returns to the caller which
459 may be a sample fetch, a converter or an action and returns the specified
460 value (ignored for actions). It is used when the LUA process finishes its
461 work and wants to give back the control to HAProxy without executing the
462 remaining code. It can be seen as a multi-level "return".
463
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100464.. js:function:: core.yield()
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100465
466 **context**: task, action, sample-fetch, converter
467
468 Give back the hand at the HAProxy scheduler. It is used when the LUA
469 processing consumes a lot of processing time.
470
471Fetches class
472=============
473
474.. js:class:: Fetches
475
476 This class contains a lot of internal HAProxy sample fetches. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100477 HAProxy "configuration.txt" documentation for more information about her
478 usage. they are the chapters 7.3.2 to 7.3.6.
479
480 :see: TXN.f
481 :see: TXN.sf
482
483 Fetches are useful for:
484
485 * get system time,
486 * get environment variable,
487 * get random numbers,
488 * known backend status like the number of users in queue or the number of
489 connections established,
490 * client information like ip source or destination,
491 * deal with stick tables,
492 * Established SSL informations,
493 * HTTP information like headers or method.
494
495.. code-block:: lua
496
497 function action(txn)
498 -- Get source IP
499 local clientip = txn.f:src()
500 end
501..
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100502
503Converters class
504================
505
506.. js:class:: Converters
507
508 This class contains a lot of internal HAProxy sample converters. See the
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100509 HAProxy documentation "configuration.txt" for more information about her
510 usage. Its the chapter 7.3.1.
511
512 :see: TXN.c
513 :see: TXN.sc
514
515 Converters provides statefull transformation. They are useful for:
516
517 * converting input to base64,
518 * applying hash on input string (djb2, crc32, sdbm, wt6),
519 * format date,
520 * json escape,
521 * extracting prefered language comparing two lists,
522 * turn to lower or upper chars,
523 * deal with stick tables.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100524
525Channel class
526=============
527
528.. js:class:: Channel
529
530 HAProxy uses two buffers for the processing of the requests. The first one is
531 used with the request data (from the client to the server) and the second is
532 used for the response data (from the server to the client).
533
534 Each buffer contains two types of data. The first type is the incoming data
535 waiting for a processing. The second part is the outgoing data already
536 processed. Usually, the incoming data is processed, after it is tagged as
537 outgoing data, and finally it is sent. The following functions provides tools
538 for manipulating these data in a buffer.
539
540 The following diagram shows where the channel class function are applied.
541
542 **Warning**: It is not possible to read from the response in request action,
543 and it is not possible to read for the request channel in response action.
544
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +0100545.. image:: _static/channel.png
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100546
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100547.. js:function:: Channel.dup(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100548
549 This function returns a string that contain the entire buffer. The data is
550 not remove from the buffer and can be reprocessed later.
551
552 If the buffer cant receive more data, a 'nil' value is returned.
553
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100554 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100555 :returns: a string containig all the avalaible data or nil.
556
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100557.. js:function:: Channel.get(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100558
559 This function returns a string that contain the entire buffer. The data is
560 consumed from the buffer.
561
562 If the buffer cant receive more data, a 'nil' value is returned.
563
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100564 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100565 :returns: a string containig all the avalaible data or nil.
566
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100567.. js:function:: Channel.get_line(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100568
569 This function returns a string that contain the first line of the buffer. The
570 data is consumed. If the data returned doesn't contains a final '\n' its
571 assumed than its the last available data in the buffer.
572
573 If the buffer cant receive more data, a 'nil' value is returned.
574
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100575 :param class_channel channel: The manipulated Channel.
Pieter Baauw386a1272015-08-16 15:26:24 +0200576 :returns: a string containing the available line or nil.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100577
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100578.. js:function:: Channel.set(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100579
580 This function replace the content of the buffer by the string. The function
581 returns the copied length, otherwise, it returns -1.
582
583 The data set with this function are not send. They wait for the end of
584 HAProxy processing, so the buffer can be full.
585
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100586 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100587 :param string string: The data which will sent.
588 :returns: an integer containing the amount of butes copyed or -1.
589
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100590.. js:function:: Channel.append(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100591
592 This function append the string argument to the content of the buffer. The
593 function returns the copied length, otherwise, it returns -1.
594
595 The data set with this function are not send. They wait for the end of
596 HAProxy processing, so the buffer can be full.
597
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100598 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100599 :param string string: The data which will sent.
600 :returns: an integer containing the amount of butes copyed or -1.
601
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100602.. js:function:: Channel.send(channel, string)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100603
604 This function required immediate send of the data. Unless if the connection
605 is close, the buffer is regularly flushed and all the string can be sent.
606
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100607 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100608 :param string string: The data which will sent.
609 :returns: an integer containing the amount of butes copyed or -1.
610
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100611.. js:function:: Channel.get_in_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100612
613 This function returns the length of the input part of the buffer.
614
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100615 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100616 :returns: an integer containing the amount of avalaible bytes.
617
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100618.. js:function:: Channel.get_out_length(channel)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100619
620 This function returns the length of the output part of the buffer.
621
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100622 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100623 :returns: an integer containing the amount of avalaible bytes.
624
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100625.. js:function:: Channel.forward(channel, int)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100626
627 This function transfer bytes from the input part of the buffer to the output
628 part.
629
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100630 :param class_channel channel: The manipulated Channel.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100631 :param integer int: The amount of data which will be forwarded.
632
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100633
634HTTP class
635==========
636
637.. js:class:: HTTP
638
639 This class contain all the HTTP manipulation functions.
640
Pieter Baauw386a1272015-08-16 15:26:24 +0200641.. js:function:: HTTP.req_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100642
643 Returns an array containing all the request headers.
644
645 :param class_http http: The related http object.
646 :returns: array of headers.
Pieter Baauw386a1272015-08-16 15:26:24 +0200647 :see: HTTP.res_get_headers()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100648
Pieter Baauw386a1272015-08-16 15:26:24 +0200649.. js:function:: HTTP.res_get_headers(http)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100650
651 Returns an array containing all the response headers.
652
653 :param class_http http: The related http object.
654 :returns: array of headers.
Pieter Baauw386a1272015-08-16 15:26:24 +0200655 :see: HTTP.req_get_headers()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100656
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100657.. js:function:: HTTP.req_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100658
659 Appends an HTTP header field in the request whose name is
660 specified in "name" and whose value is defined in "value".
661
662 :param class_http http: The related http object.
663 :param string name: The header name.
664 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100665 :see: HTTP.res_add_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100666
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100667.. js:function:: HTTP.res_add_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100668
669 appends an HTTP header field in the response whose name is
670 specified in "name" and whose value is defined in "value".
671
672 :param class_http http: The related http object.
673 :param string name: The header name.
674 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100675 :see: HTTP.req_add_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100676
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100677.. js:function:: HTTP.req_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100678
679 Removes all HTTP header fields in the request whose name is
680 specified in "name".
681
682 :param class_http http: The related http object.
683 :param string name: The header name.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100684 :see: HTTP.res_del_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100685
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100686.. js:function:: HTTP.res_del_header(http, name)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100687
688 Removes all HTTP header fields in the response whose name is
689 specified in "name".
690
691 :param class_http http: The related http object.
692 :param string name: The header name.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100693 :see: HTTP.req_del_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100694
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100695.. js:function:: HTTP.req_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100696
697 This variable replace all occurence of all header "name", by only
698 one containing the "value".
699
700 :param class_http http: The related http object.
701 :param string name: The header name.
702 :param string value: The header value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100703 :see: HTTP.res_set_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100704
705 This function does the same work as the folowwing code:
706
707.. code-block:: lua
708
709 function fcn(txn)
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100710 TXN.http:req_del_header("header")
711 TXN.http:req_add_header("header", "value")
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100712 end
713..
714
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100715.. js:function:: HTTP.res_set_header(http, name, value)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100716
717 This variable replace all occurence of all header "name", by only
718 one containing the "value".
719
720 :param class_http http: The related http object.
721 :param string name: The header name.
722 :param string value: The header value.
Pieter Baauw386a1272015-08-16 15:26:24 +0200723 :see: HTTP.req_rep_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100724
Pieter Baauw386a1272015-08-16 15:26:24 +0200725.. js:function:: HTTP.req_rep_header(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100726
727 Matches the regular expression in all occurrences of header field "name"
728 according to "regex", and replaces them with the "replace" argument. The
729 replacement value can contain back references like \1, \2, ... This
730 function works with the request.
731
732 :param class_http http: The related http object.
733 :param string name: The header name.
734 :param string regex: The match regular expression.
735 :param string replace: The replacement value.
Pieter Baauw386a1272015-08-16 15:26:24 +0200736 :see: HTTP.res_rep_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100737
Pieter Baauw386a1272015-08-16 15:26:24 +0200738.. js:function:: HTTP.res_rep_header(http, name, regex, string)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100739
740 Matches the regular expression in all occurrences of header field "name"
741 according to "regex", and replaces them with the "replace" argument. The
742 replacement value can contain back references like \1, \2, ... This
743 function works with the request.
744
745 :param class_http http: The related http object.
746 :param string name: The header name.
747 :param string regex: The match regular expression.
748 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100749 :see: HTTP.req_replace_header()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100750
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100751.. js:function:: HTTP.req_replace_value(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100752
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100753 Works like "HTTP.req_replace_header()" except that it matches the regex
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100754 against every comma-delimited value of the header field "name" instead of the
755 entire header.
756
757 :param class_http http: The related http object.
758 :param string name: The header name.
759 :param string regex: The match regular expression.
760 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100761 :see: HTTP.req_replace_header()
762 :see: HTTP.res_replace_value()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100763
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100764.. js:function:: HTTP.res_replace_value(http, name, regex, replace)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100765
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100766 Works like "HTTP.res_replace_header()" except that it matches the regex
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100767 against every comma-delimited value of the header field "name" instead of the
768 entire header.
769
770 :param class_http http: The related http object.
771 :param string name: The header name.
772 :param string regex: The match regular expression.
773 :param string replace: The replacement value.
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100774 :see: HTTP.res_replace_header()
775 :see: HTTP.req_replace_value()
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100776
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100777.. js:function:: HTTP.req_set_method(http, method)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100778
779 Rewrites the request method with the parameter "method".
780
781 :param class_http http: The related http object.
782 :param string method: The new method.
783
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100784.. js:function:: HTTP.req_set_path(http, path)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100785
786 Rewrites the request path with the "path" parameter.
787
788 :param class_http http: The related http object.
789 :param string path: The new path.
790
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100791.. js:function:: HTTP.req_set_query(http, query)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100792
793 Rewrites the request's query string which appears after the first question
794 mark ("?") with the parameter "query".
795
796 :param class_http http: The related http object.
797 :param string query: The new query.
798
Thierry FOURNIER0d79cf62015-08-26 14:20:58 +0200799.. js:function:: HTTP.req_set_uri(http, uri)
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100800
801 Rewrites the request URI with the parameter "uri".
802
803 :param class_http http: The related http object.
804 :param string uri: The new uri.
805
Thierry FOURNIER35d70ef2015-08-26 16:21:56 +0200806.. js:function:: HTTP.res_set_status(http, status)
807
808 Rewrites the response status code with the parameter "code". Note that the
809 reason is automatically adapted to the new code.
810
811 :param class_http http: The related http object.
812 :param integer status: The new response status code.
813
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100814TXN class
815=========
816
817.. js:class:: TXN
818
819 The txn class contain all the functions relative to the http or tcp
820 transaction (Note than a tcp stream is the same than a tcp transaction, but
821 an HTTP transaction is not the same than a tcp stream).
822
823 The usage of this class permits to retrieve data from the requests, alter it
824 and forward it.
825
826 All the functions provided by this class are available in the context
827 **sample-fetches** and **actions**.
828
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100829.. js:attribute:: TXN.c
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100830
831 This attribute contains a Converters class object.
832
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100833.. js:attribute:: TXN.sc
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100834
835 This attribute contains a Converters class object. The functions of
836 this object returns always a string.
837
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100838.. js:attribute:: TXN.f
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100839
840 This attribute contains a Fetches class object.
841
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100842.. js:attribute:: TXN.sf
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100843
844 This attribute contains a Fetches class object. The functions of
845 this object returns always a string.
846
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100847.. js:attribute:: TXN.req
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100848
849 This attribute contains a channel class object for the request buffer.
850
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100851.. js:attribute:: TXN.res
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100852
853 This attribute contains a channel class object for the response buffer.
854
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100855.. js:attribute:: TXN.http
Thierry FOURNIER08504f42015-03-16 14:17:08 +0100856
857 This attribute contains an HTTP class object. It is avalaible only if the
858 proxy has the "mode http" enabled.
859
Thierry FOURNIERc798b5d2015-03-17 01:09:57 +0100860.. js:function:: TXN.log(TXN, loglevel, msg)
861
862 This function sends a log. The log is sent, according with the HAProxy
863 configuration file, on the default syslog server if it is configured and on
864 the stderr if it is allowed.
865
866 :param class_txn txn: The class txn object containing the data.
867 :param integer loglevel: Is the log level asociated with the message. It is a
868 number between 0 and 7.
869 :param string msg: The log content.
870 :see: core.emerg, core.alert, core.crit, core.err, core.warning, core.notice,
871 core.info, core.debug (log level definitions)
872 :see: TXN.deflog
873 :see: TXN.Debug
874 :see: TXN.Info
875 :see: TXN.Warning
876 :see: TXN.Alert
877
878.. js:function:: TXN.deflog(TXN, msg)
879
880 Sends a log line with the default loglevel for the proxy ssociated with the
881 transaction.
882
883 :param class_txn txn: The class txn object containing the data.
884 :param string msg: The log content.
885 :see: TXN.log
886
887.. js:function:: TXN.Debug(txn, msg)
888
889 :param class_txn txn: The class txn object containing the data.
890 :param string msg: The log content.
891 :see: TXN.log
892
893 Does the same job than:
894
895.. code-block:: lua
896
897 function Debug(txn, msg)
898 TXN.log(txn, core.debug, msg)
899 end
900..
901
902.. js:function:: TXN.Info(txn, msg)
903
904 :param class_txn txn: The class txn object containing the data.
905 :param string msg: The log content.
906 :see: TXN.log
907
908.. code-block:: lua
909
910 function Debug(txn, msg)
911 TXN.log(txn, core.info, msg)
912 end
913..
914
915.. js:function:: TXN.Warning(txn, msg)
916
917 :param class_txn txn: The class txn object containing the data.
918 :param string msg: The log content.
919 :see: TXN.log
920
921.. code-block:: lua
922
923 function Debug(txn, msg)
924 TXN.log(txn, core.warning, msg)
925 end
926..
927
928.. js:function:: TXN.Alert(txn, msg)
929
930 :param class_txn txn: The class txn object containing the data.
931 :param string msg: The log content.
932 :see: TXN.log
933
934.. code-block:: lua
935
936 function Debug(txn, msg)
937 TXN.log(txn, core.alert, msg)
938 end
939..
940
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100941.. js:function:: TXN.get_priv(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100942
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100943 Return Lua data stored in the current transaction (with the `TXN.set_priv()`)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100944 function. If no data are stored, it returns a nil value.
945
946 :param class_txn txn: The class txn object containing the data.
947 :returns: the opaque data previsously stored, or nil if nothing is
948 avalaible.
949
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100950.. js:function:: TXN.set_priv(txn, data)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100951
952 Store any data in the current HAProxy transaction. This action replace the
953 old stored data.
954
955 :param class_txn txn: The class txn object containing the data.
956 :param opaque data: The data which is stored in the transaction.
957
Thierry FOURNIER053ba8ad2015-06-08 13:05:33 +0200958.. js:function:: TXN.set_var(TXN, var, value)
959
960 Converts an Lua type in a HAProxy type and store it in a variable <var>.
961
962 :param class_txn txn: The class txn object containing the data.
963 :param string var: The variable name according with the HAProxy variable syntax.
964 :param opaque value: The data which is stored in the variable.
965
966.. js:function:: TXN.get_var(TXN, var)
967
968 Returns data stored in the variable <var> converter in Lua type.
969
970 :param class_txn txn: The class txn object containing the data.
971 :param string var: The variable name according with the HAProxy variable syntax.
972
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100973.. js:function:: TXN.get_headers(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100974
975 This function returns an array of headers.
976
977 :param class_txn txn: The class txn object containing the data.
978 :returns: an array of headers.
979
Willy Tarreaubc183a62015-08-28 10:39:11 +0200980.. js:function:: TXN.done(txn)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100981
Willy Tarreaubc183a62015-08-28 10:39:11 +0200982 This function terminates processing of the transaction and the associated
983 session. It can be used when a critical error is detected or to terminate
984 processing after some data have been returned to the client (eg: a redirect).
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100985
986 :param class_txn txn: The class txn object containing the data.
987
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100988
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100989
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100990
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100991
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100992
Thierry FOURNIER17bd1522015-03-11 20:31:00 +0100993
Thierry FOURNIER486f5a02015-03-16 15:13:03 +0100994.. js:function:: TXN.set_loglevel(txn, loglevel)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +0100995
996 Is used to change the log level of the current request. The "loglevel" must
997 be an integer between 0 and 7.
998
999 :param class_txn txn: The class txn object containing the data.
1000 :param integer loglevel: The required log level. This variable can be one of
1001 :see: core.<loglevel>
1002
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001003.. js:function:: TXN.set_tos(txn, tos)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001004
1005 Is used to set the TOS or DSCP field value of packets sent to the client to
1006 the value passed in "tos" on platforms which support this.
1007
1008 :param class_txn txn: The class txn object containing the data.
1009 :param integer tos: The new TOS os DSCP.
1010
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001011.. js:function:: TXN.set_mark(txn, mark)
Thierry FOURNIER2cce3532015-03-16 12:04:16 +01001012
1013 Is used to set the Netfilter MARK on all packets sent to the client to the
1014 value passed in "mark" on platforms which support it.
1015
1016 :param class_txn txn: The class txn object containing the data.
1017 :param integer mark: The mark value.
1018
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001019Socket class
1020============
1021
1022.. js:class:: Socket
1023
1024 This class must be compatible with the Lua Socket class. Only the 'client'
1025 functions are available. See the Lua Socket documentation:
1026
1027 `http://w3.impa.br/~diego/software/luasocket/tcp.html
1028 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_
1029
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001030.. js:function:: Socket.close(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001031
1032 Closes a TCP object. The internal socket used by the object is closed and the
1033 local address to which the object was bound is made available to other
1034 applications. No further operations (except for further calls to the close
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001035 method) are allowed on a closed Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001036
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001037 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001038
1039 Note: It is important to close all used sockets once they are not needed,
1040 since, in many systems, each socket uses a file descriptor, which are limited
1041 system resources. Garbage-collected objects are automatically closed before
1042 destruction, though.
1043
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001044.. js:function:: Socket.connect(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001045
1046 Attempts to connect a socket object to a remote host.
1047
1048 Address can be an IP address or a host name. Port must be an integer number
1049 in the range [1..64K).
1050
1051 In case of error, the method returns nil followed by a string describing the
1052 error. In case of success, the method returns 1.
1053
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001054 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001055 :returns: 1 or nil.
1056
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001057 Note: The function Socket.connect is available and is a shortcut for the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001058 creation of client sockets.
1059
1060 Note: Starting with LuaSocket 2.0, the settimeout method affects the behavior
1061 of connect, causing it to return with an error in case of a timeout. If that
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001062 happens, you can still call Socket.select with the socket in the sendt table.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001063 The socket will be writable when the connection is established.
1064
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001065.. js:function:: Socket.connect_ssl(socket, address, port)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001066
1067 Same behavior than the function socket:connect, but uses SSL.
1068
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001069 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001070 :returns: 1 or nil.
1071
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001072.. js:function:: Socket.getpeername(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001073
1074 Returns information about the remote side of a connected client object.
1075
1076 Returns a string with the IP address of the peer, followed by the port number
1077 that peer is using for the connection. In case of error, the method returns
1078 nil.
1079
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001080 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001081 :returns: a string containing the server information.
1082
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001083.. js:function:: Socket.getsockname(socket)
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001084
1085 Returns the local address information associated to the object.
1086
1087 The method returns a string with local IP address and a number with the port.
1088 In case of error, the method returns nil.
1089
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001090 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001091 :returns: a string containing the client information.
1092
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001093.. js:function:: Socket.receive(socket, [pattern [, prefix]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001094
1095 Reads data from a client object, according to the specified read pattern.
1096 Patterns follow the Lua file I/O format, and the difference in performance
1097 between all patterns is negligible.
1098
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001099 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001100 :param string|integer pattern: Describe what is required (see below).
1101 :param string prefix: A string which will be prefix the returned data.
1102 :returns: a string containing the required data or nil.
1103
1104 Pattern can be any of the following:
1105
1106 * **`*a`**: reads from the socket until the connection is closed. No
1107 end-of-line translation is performed;
1108
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001109 * **`*l`**: reads a line of text from the Socket. The line is terminated by a
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001110 LF character (ASCII 10), optionally preceded by a CR character
1111 (ASCII 13). The CR and LF characters are not included in the
1112 returned line. In fact, all CR characters are ignored by the
1113 pattern. This is the default pattern.
1114
1115 * **number**: causes the method to read a specified number of bytes from the
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001116 Socket. Prefix is an optional string to be concatenated to the
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001117 beginning of any received data before return.
1118
1119 If successful, the method returns the received pattern. In case of error, the
1120 method returns nil followed by an error message which can be the string
1121 'closed' in case the connection was closed before the transmission was
1122 completed or the string 'timeout' in case there was a timeout during the
1123 operation. Also, after the error message, the function returns the partial
1124 result of the transmission.
1125
1126 Important note: This function was changed severely. It used to support
1127 multiple patterns (but I have never seen this feature used) and now it
1128 doesn't anymore. Partial results used to be returned in the same way as
1129 successful results. This last feature violated the idea that all functions
1130 should return nil on error. Thus it was changed too.
1131
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001132.. js:function:: Socket.send(socket, data [, start [, end ]])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001133
1134 Sends data through client object.
1135
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001136 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001137 :param string data: The data that will be sent.
1138 :param integer start: The start position in the buffer of the data which will
1139 be sent.
1140 :param integer end: The end position in the buffer of the data which will
1141 be sent.
1142 :returns: see below.
1143
1144 Data is the string to be sent. The optional arguments i and j work exactly
1145 like the standard string.sub Lua function to allow the selection of a
1146 substring to be sent.
1147
1148 If successful, the method returns the index of the last byte within [start,
1149 end] that has been sent. Notice that, if start is 1 or absent, this is
1150 effectively the total number of bytes sent. In case of error, the method
1151 returns nil, followed by an error message, followed by the index of the last
1152 byte within [start, end] that has been sent. You might want to try again from
1153 the byte following that. The error message can be 'closed' in case the
1154 connection was closed before the transmission was completed or the string
1155 'timeout' in case there was a timeout during the operation.
1156
1157 Note: Output is not buffered. For small strings, it is always better to
1158 concatenate them in Lua (with the '..' operator) and send the result in one
1159 call instead of calling the method several times.
1160
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001161.. js:function:: Socket.setoption(socket, option [, value])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001162
1163 Just implemented for compatibility, this cal does nothing.
1164
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001165.. js:function:: Socket.settimeout(socket, value [, mode])
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001166
1167 Changes the timeout values for the object. All I/O operations are blocking.
1168 That is, any call to the methods send, receive, and accept will block
1169 indefinitely, until the operation completes. The settimeout method defines a
1170 limit on the amount of time the I/O methods can block. When a timeout time
1171 has elapsed, the affected methods give up and fail with an error code.
1172
1173 The amount of time to wait is specified as the value parameter, in seconds.
1174
1175 The timeout modes are bot implemented, the only settable timeout is the
1176 inactivity time waiting for complete the internal buffer send or waiting for
1177 receive data.
1178
Thierry FOURNIER486f5a02015-03-16 15:13:03 +01001179 :param class_socket socket: Is the manipulated Socket.
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001180 :param integer value: The timeout value.
1181
Thierry FOURNIER3def3932015-04-07 11:27:54 +02001182Map class
1183=========
1184
1185.. js:class:: Map
1186
1187 This class permits to do some lookup in HAProxy maps. The declared maps can
1188 be modified during the runtime throught the HAProxy management socket.
1189
1190.. code-block:: lua
1191
1192 default = "usa"
1193
1194 -- Create and load map
1195 geo = Map.new("geo.map", Map.ip);
1196
1197 -- Create new fetch that returns the user country
1198 core.register_fetches("country", function(txn)
1199 local src;
1200 local loc;
1201
1202 src = txn.f:fhdr("x-forwarded-for");
1203 if (src == nil) then
1204 src = txn.f:src()
1205 if (src == nil) then
1206 return default;
1207 end
1208 end
1209
1210 -- Perform lookup
1211 loc = geo:lookup(src);
1212
1213 if (loc == nil) then
1214 return default;
1215 end
1216
1217 return loc;
1218 end);
1219
1220.. js:attribute:: Map.int
1221
1222 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1223 samples" ans subchapter "ACL basics" to understand this pattern matching
1224 method.
1225
1226.. js:attribute:: Map.ip
1227
1228 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1229 samples" ans subchapter "ACL basics" to understand this pattern matching
1230 method.
1231
1232.. js:attribute:: Map.str
1233
1234 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1235 samples" ans subchapter "ACL basics" to understand this pattern matching
1236 method.
1237
1238.. js:attribute:: Map.beg
1239
1240 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1241 samples" ans subchapter "ACL basics" to understand this pattern matching
1242 method.
1243
1244.. js:attribute:: Map.sub
1245
1246 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1247 samples" ans subchapter "ACL basics" to understand this pattern matching
1248 method.
1249
1250.. js:attribute:: Map.dir
1251
1252 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1253 samples" ans subchapter "ACL basics" to understand this pattern matching
1254 method.
1255
1256.. js:attribute:: Map.dom
1257
1258 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1259 samples" ans subchapter "ACL basics" to understand this pattern matching
1260 method.
1261
1262.. js:attribute:: Map.end
1263
1264 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1265 samples" ans subchapter "ACL basics" to understand this pattern matching
1266 method.
1267
1268.. js:attribute:: Map.reg
1269
1270 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching
1271 samples" ans subchapter "ACL basics" to understand this pattern matching
1272 method.
1273
1274
1275.. js:function:: Map.new(file, method)
1276
1277 Creates and load a map.
1278
1279 :param string file: Is the file containing the map.
1280 :param integer method: Is the map pattern matching method. See the attributes
1281 of the Map class.
1282 :returns: a class Map object.
1283 :see: The Map attributes.
1284
1285.. js:function:: Map.lookup(map, str)
1286
1287 Perform a lookup in a map.
1288
1289 :param class_map map: Is the class Map object.
1290 :param string str: Is the string used as key.
1291 :returns: a string containing the result or nil if no match.
1292
1293.. js:function:: Map.slookup(map, str)
1294
1295 Perform a lookup in a map.
1296
1297 :param class_map map: Is the class Map object.
1298 :param string str: Is the string used as key.
1299 :returns: a string containing the result or empty string if no match.
1300
Thierry FOURNIER17bd1522015-03-11 20:31:00 +01001301External Lua libraries
1302======================
1303
1304A lot of useful lua libraries can be found here:
1305
1306* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_
1307
1308Redis acces:
1309
1310* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_
1311
1312This is an example about the usage of the Redis library with HAProxy. Note that
1313each call of any function of this library can throw an error if the socket
1314connection fails.
1315
1316.. code-block:: lua
1317
1318 -- load the redis library
1319 local redis = require("redis");
1320
1321 function do_something(txn)
1322
1323 -- create and connect new tcp socket
1324 local tcp = core.tcp();
1325 tcp:settimeout(1);
1326 tcp:connect("127.0.0.1", 6379);
1327
1328 -- use the redis library with this new socket
1329 local client = redis.connect({socket=tcp});
1330 client:ping();
1331
1332 end
1333
1334OpenSSL:
1335
1336* `http://mkottman.github.io/luacrypto/index.html
1337 <http://mkottman.github.io/luacrypto/index.html>`_
1338
1339* `https://github.com/brunoos/luasec/wiki
1340 <https://github.com/brunoos/luasec/wiki>`_
Thierry FOURNIER2e4893c2015-03-18 13:37:27 +01001341