1.. 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 a 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 a 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 a Lua function conditionally executed. These 46 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)`. 49 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:: 59 It is possible that this function cannot found the required data in the 60 original HAProxy sample-fetches, in this case, it cannot return the 61 result. This case is not yet supported 62 636. The **converter context**. It is a Lua function that takes a string as input 64 and returns another string as output. These types of function are stateless, 65 it cannot access to any context. They don't execute any blocking function. 66 The call prototype is `function string fcn(string)`. This function can be 67 registered with the Lua function `core.register_converters()`. Each declared 68 converter is prefixed by the string "lua.". 69 70HAProxy Lua Hello world 71----------------------- 72 73HAProxy configuration file (`hello_world.conf`): 74 75:: 76 77 global 78 lua-load hello_world.lua 79 80 listen proxy 81 bind 127.0.0.1:10001 82 tcp-request inspect-delay 1s 83 tcp-request content use-service lua.hello_world 84 85HAProxy Lua file (`hello_world.lua`): 86 87.. code-block:: lua 88 89 core.register_service("hello_world", "tcp", function(applet) 90 applet:send("hello world\n") 91 end) 92 93How to start HAProxy for testing this configuration: 94 95:: 96 97 ./haproxy -f hello_world.conf 98 99On other terminal, you can test with telnet: 100 101:: 102 103 #:~ telnet 127.0.0.1 10001 104 hello world 105 106Core class 107========== 108 109.. js:class:: core 110 111 The "core" class contains all the HAProxy core functions. These function are 112 useful for the controlling the execution flow, registering hooks, manipulating 113 global maps or ACL, ... 114 115 "core" class is basically provided with HAProxy. No `require` line is 116 required to uses these function. 117 118 The "core" class is static, it is not possible to create a new object of this 119 type. 120 121.. js:attribute:: core.emerg 122 123 :returns: integer 124 125 This attribute is an integer, it contains the value of the loglevel "emergency" (0). 126 127.. js:attribute:: core.alert 128 129 :returns: integer 130 131 This attribute is an integer, it contains the value of the loglevel "alert" (1). 132 133.. js:attribute:: core.crit 134 135 :returns: integer 136 137 This attribute is an integer, it contains the value of the loglevel "critical" (2). 138 139.. js:attribute:: core.err 140 141 :returns: integer 142 143 This attribute is an integer, it contains the value of the loglevel "error" (3). 144 145.. js:attribute:: core.warning 146 147 :returns: integer 148 149 This attribute is an integer, it contains the value of the loglevel "warning" (4). 150 151.. js:attribute:: core.notice 152 153 :returns: integer 154 155 This attribute is an integer, it contains the value of the loglevel "notice" (5). 156 157.. js:attribute:: core.info 158 159 :returns: integer 160 161 This attribute is an integer, it contains the value of the loglevel "info" (6). 162 163.. js:attribute:: core.debug 164 165 :returns: integer 166 167 This attribute is an integer, it contains the value of the loglevel "debug" (7). 168 169.. js:attribute:: core.proxies 170 171 **context**: task, action, sample-fetch, converter 172 173 This attribute is a table of declared proxies (frontend and backends). Each 174 proxy give an access to his list of listeners and servers. The table is 175 indexed by proxy name, and each entry is of type :ref:`proxy_class`. 176 177 .. Warning:: 178 if you are declared frontend and backend with the same name, only one of 179 these are listed. 180 181 :see: :js:attr:`core.backends` 182 :see: :js:attr:`core.frontends` 183 184.. js:attribute:: core.backends 185 186 **context**: task, action, sample-fetch, converter 187 188 This attribute is a table of declared proxies with backend capability. Each 189 proxy give an access to his list of listeners and servers. The table is 190 indexed by the backend name, and each entry is of type :ref:`proxy_class`. 191 192 :see: :js:attr:`core.proxies` 193 :see: :js:attr:`core.frontends` 194 195.. js:attribute:: core.frontends 196 197 **context**: task, action, sample-fetch, converter 198 199 This attribute is a table of declared proxies with frontend capability. Each 200 proxy give an access to his list of listeners and servers. The table is 201 indexed by the frontend name, and each entry is of type :ref:`proxy_class`. 202 203 :see: :js:attr:`core.proxies` 204 :see: :js:attr:`core.backends` 205 206.. js:attribute:: core.thread 207 208 **context**: task, action, sample-fetch, converter, applet 209 210 This variable contains the executing thread number starting at 1. 0 is a 211 special case for the common lua context. So, if thread is 0, Lua scope is 212 shared by all threads, otherwise the scope is dedicated to a single thread. 213 A program which needs to execute some parts exactly once regardless of the 214 number of threads can check that core.thread is 0 or 1. 215 216.. js:function:: core.log(loglevel, msg) 217 218 **context**: body, init, task, action, sample-fetch, converter 219 220 This function sends a log. The log is sent, according with the HAProxy 221 configuration file, on the default syslog server if it is configured and on 222 the stderr if it is allowed. 223 224 :param integer loglevel: Is the log level associated with the message. It is a 225 number between 0 and 7. 226 :param string msg: The log content. 227 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`, 228 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`, 229 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions) 230 :see: :js:func:`core.Debug` 231 :see: :js:func:`core.Info` 232 :see: :js:func:`core.Warning` 233 :see: :js:func:`core.Alert` 234 235.. js:function:: core.Debug(msg) 236 237 **context**: body, init, task, action, sample-fetch, converter 238 239 :param string msg: The log content. 240 :see: :js:func:`core.log` 241 242 Does the same job than: 243 244.. code-block:: lua 245 246 function Debug(msg) 247 core.log(core.debug, msg) 248 end 249.. 250 251.. js:function:: core.Info(msg) 252 253 **context**: body, init, task, action, sample-fetch, converter 254 255 :param string msg: The log content. 256 :see: :js:func:`core.log` 257 258.. code-block:: lua 259 260 function Info(msg) 261 core.log(core.info, msg) 262 end 263.. 264 265.. js:function:: core.Warning(msg) 266 267 **context**: body, init, task, action, sample-fetch, converter 268 269 :param string msg: The log content. 270 :see: :js:func:`core.log` 271 272.. code-block:: lua 273 274 function Warning(msg) 275 core.log(core.warning, msg) 276 end 277.. 278 279.. js:function:: core.Alert(msg) 280 281 **context**: body, init, task, action, sample-fetch, converter 282 283 :param string msg: The log content. 284 :see: :js:func:`core.log` 285 286.. code-block:: lua 287 288 function Alert(msg) 289 core.log(core.alert, msg) 290 end 291.. 292 293.. js:function:: core.add_acl(filename, key) 294 295 **context**: init, task, action, sample-fetch, converter 296 297 Add the ACL *key* in the ACLs list referenced by the file *filename*. 298 299 :param string filename: the filename that reference the ACL entries. 300 :param string key: the key which will be added. 301 302.. js:function:: core.del_acl(filename, key) 303 304 **context**: init, task, action, sample-fetch, converter 305 306 Delete the ACL entry referenced by the key *key* in the list of ACLs 307 referenced by *filename*. 308 309 :param string filename: the filename that reference the ACL entries. 310 :param string key: the key which will be deleted. 311 312.. js:function:: core.del_map(filename, key) 313 314 **context**: init, task, action, sample-fetch, converter 315 316 Delete the map entry indexed with the specified key in the list of maps 317 referenced by his filename. 318 319 :param string filename: the filename that reference the map entries. 320 :param string key: the key which will be deleted. 321 322.. js:function:: core.get_info() 323 324 **context**: body, init, task, action, sample-fetch, converter 325 326 Returns HAProxy core information. We can found information like the uptime, 327 the pid, memory pool usage, tasks number, ... 328 329 These information are also returned by the management socket via the command 330 "show info". See the management socket documentation for more information 331 about the content of these variables. 332 333 :returns: an array of values. 334 335.. js:function:: core.now() 336 337 **context**: body, init, task, action 338 339 This function returns the current time. The time returned is fixed by the 340 HAProxy core and assures than the hour will be monotonic and that the system 341 call 'gettimeofday' will not be called too. The time is refreshed between each 342 Lua execution or resume, so two consecutive call to the function "now" will 343 probably returns the same result. 344 345 :returns: a table which contains two entries "sec" and "usec". "sec" 346 contains the current at the epoch format, and "usec" contains the 347 current microseconds. 348 349.. js:function:: core.http_date(date) 350 351 **context**: body, init, task, action 352 353 This function take a string representing http date, and returns an integer 354 containing the corresponding date with a epoch format. A valid http date 355 me respect the format IMF, RFC850 or ASCTIME. 356 357 :param string date: a date http-date formatted 358 :returns: integer containing epoch date 359 :see: :js:func:`core.imf_date`. 360 :see: :js:func:`core.rfc850_date`. 361 :see: :js:func:`core.asctime_date`. 362 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1 363 364.. js:function:: core.imf_date(date) 365 366 **context**: body, init, task, action 367 368 This function take a string representing IMF date, and returns an integer 369 containing the corresponding date with a epoch format. 370 371 :param string date: a date IMF formatted 372 :returns: integer containing epoch date 373 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1 374 375 The IMF format is like this: 376 377.. code-block:: text 378 379 Sun, 06 Nov 1994 08:49:37 GMT 380.. 381 382.. js:function:: core.rfc850_date(date) 383 384 **context**: body, init, task, action 385 386 This function take a string representing RFC850 date, and returns an integer 387 containing the corresponding date with a epoch format. 388 389 :param string date: a date RFC859 formatted 390 :returns: integer containing epoch date 391 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1 392 393 The RFC850 format is like this: 394 395.. code-block:: text 396 397 Sunday, 06-Nov-94 08:49:37 GMT 398.. 399 400.. js:function:: core.asctime_date(date) 401 402 **context**: body, init, task, action 403 404 This function take a string representing ASCTIME date, and returns an integer 405 containing the corresponding date with a epoch format. 406 407 :param string date: a date ASCTIME formatted 408 :returns: integer containing epoch date 409 :see: https://tools.ietf.org/html/rfc7231#section-7.1.1.1 410 411 The ASCTIME format is like this: 412 413.. code-block:: text 414 415 Sun Nov 6 08:49:37 1994 416.. 417 418.. js:function:: core.rfc850_date(date) 419 420 **context**: body, init, task, action 421 422 This function take a string representing http date, and returns an integer 423 containing the corresponding date with a epoch format. 424 425 :param string date: a date http-date formatted 426 427.. js:function:: core.asctime_date(date) 428 429 **context**: body, init, task, action 430 431 This function take a string representing http date, and returns an integer 432 containing the corresponding date with a epoch format. 433 434 :param string date: a date http-date formatted 435 436.. js:function:: core.msleep(milliseconds) 437 438 **context**: body, init, task, action 439 440 The `core.msleep()` stops the Lua execution between specified milliseconds. 441 442 :param integer milliseconds: the required milliseconds. 443 444.. js:attribute:: core.proxies 445 446 **context**: body, init, task, action, sample-fetch, converter 447 448 Proxies is a table containing the list of all proxies declared in the 449 configuration file. The table is indexed by the proxy name, and each entry 450 of the proxies table is an object of type :ref:`proxy_class`. 451 452 .. warning:: 453 if you have declared a frontend and backend with the same name, only one of 454 these are listed. 455 456.. js:function:: core.register_action(name, actions, func [, nb_args]) 457 458 **context**: body 459 460 Register a Lua function executed as action. All the registered action can be 461 used in HAProxy with the prefix "lua.". An action gets a TXN object class as 462 input. 463 464 :param string name: is the name of the converter. 465 :param table actions: is a table of string describing the HAProxy actions who 466 want to register to. The expected actions are 'tcp-req', 467 'tcp-res', 'http-req' or 'http-res'. 468 :param integer nb_args: is the expected number of argument for the action. 469 By default the value is 0. 470 :param function func: is the Lua function called to work as converter. 471 472 The prototype of the Lua function used as argument is: 473 474.. code-block:: lua 475 476 function(txn [, arg1 [, arg2]]) 477.. 478 479 * **txn** (:ref:`txn_class`): this is a TXN object used for manipulating the 480 current request or TCP stream. 481 482 * **argX**: this is argument provided through the HAProxy configuration file. 483 484 Here, an example of action registration. The action just send an 'Hello world' 485 in the logs. 486 487.. code-block:: lua 488 489 core.register_action("hello-world", { "tcp-req", "http-req" }, function(txn) 490 txn:Info("Hello world") 491 end) 492.. 493 494 This example code is used in HAProxy configuration like this: 495 496:: 497 498 frontend tcp_frt 499 mode tcp 500 tcp-request content lua.hello-world 501 502 frontend http_frt 503 mode http 504 http-request lua.hello-world 505.. 506 507 A second example using arguments 508 509.. code-block:: lua 510 511 function hello_world(txn, arg) 512 txn:Info("Hello world for " .. arg) 513 end 514 core.register_action("hello-world", { "tcp-req", "http-req" }, hello_world, 2) 515.. 516 517 This example code is used in HAProxy configuration like this: 518 519:: 520 521 frontend tcp_frt 522 mode tcp 523 tcp-request content lua.hello-world everybody 524.. 525.. js:function:: core.register_converters(name, func) 526 527 **context**: body 528 529 Register a Lua function executed as converter. All the registered converters 530 can be used in HAProxy with the prefix "lua.". An converter get a string as 531 input and return a string as output. The registered function can take up to 9 532 values as parameter. All the value are strings. 533 534 :param string name: is the name of the converter. 535 :param function func: is the Lua function called to work as converter. 536 537 The prototype of the Lua function used as argument is: 538 539.. code-block:: lua 540 541 function(str, [p1 [, p2 [, ... [, p5]]]]) 542.. 543 544 * **str** (*string*): this is the input value automatically converted in 545 string. 546 * **p1** .. **p5** (*string*): this is a list of string arguments declared in 547 the HAProxy configuration file. The number of arguments doesn't exceed 5. 548 The order and the nature of these is conventionally choose by the 549 developer. 550 551.. js:function:: core.register_fetches(name, func) 552 553 **context**: body 554 555 Register a Lua function executed as sample fetch. All the registered sample 556 fetch can be used in HAProxy with the prefix "lua.". A Lua sample fetch 557 return a string as output. The registered function can take up to 9 values as 558 parameter. All the value are strings. 559 560 :param string name: is the name of the converter. 561 :param function func: is the Lua function called to work as sample fetch. 562 563 The prototype of the Lua function used as argument is: 564 565.. code-block:: lua 566 567 string function(txn, [p1 [, p2 [, ... [, p5]]]]) 568.. 569 570 * **txn** (:ref:`txn_class`): this is the txn object associated with the current 571 request. 572 * **p1** .. **p5** (*string*): this is a list of string arguments declared in 573 the HAProxy configuration file. The number of arguments doesn't exceed 5. 574 The order and the nature of these is conventionally choose by the 575 developer. 576 * **Returns**: A string containing some data, or nil if the value cannot be 577 returned now. 578 579 lua example code: 580 581.. code-block:: lua 582 583 core.register_fetches("hello", function(txn) 584 return "hello" 585 end) 586.. 587 588 HAProxy example configuration: 589 590:: 591 592 frontend example 593 http-request redirect location /%[lua.hello] 594 595.. js:function:: core.register_service(name, mode, func) 596 597 **context**: body 598 599 Register a Lua function executed as a service. All the registered service can 600 be used in HAProxy with the prefix "lua.". A service gets an object class as 601 input according with the required mode. 602 603 :param string name: is the name of the converter. 604 :param string mode: is string describing the required mode. Only 'tcp' or 605 'http' are allowed. 606 :param function func: is the Lua function called to work as converter. 607 608 The prototype of the Lua function used as argument is: 609 610.. code-block:: lua 611 612 function(applet) 613.. 614 615 * **applet** *applet* will be a :ref:`applettcp_class` or a 616 :ref:`applethttp_class`. It depends the type of registered applet. An applet 617 registered with the 'http' value for the *mode* parameter will gets a 618 :ref:`applethttp_class`. If the *mode* value is 'tcp', the applet will gets 619 a :ref:`applettcp_class`. 620 621 .. warning:: 622 Applets of type 'http' cannot be called from 'tcp-*' rulesets. Only the 623 'http-*' rulesets are authorized, this means that is not possible to call 624 an HTTP applet from a proxy in tcp mode. Applets of type 'tcp' can be 625 called from anywhere. 626 627 Here, an example of service registration. The service just send an 'Hello world' 628 as an http response. 629 630.. code-block:: lua 631 632 core.register_service("hello-world", "http", function(applet) 633 local response = "Hello World !" 634 applet:set_status(200) 635 applet:add_header("content-length", string.len(response)) 636 applet:add_header("content-type", "text/plain") 637 applet:start_response() 638 applet:send(response) 639 end) 640.. 641 642 This example code is used in HAProxy configuration like this: 643 644:: 645 646 frontend example 647 http-request use-service lua.hello-world 648 649.. js:function:: core.register_init(func) 650 651 **context**: body 652 653 Register a function executed after the configuration parsing. This is useful 654 to check any parameters. 655 656 :param function func: is the Lua function called to work as initializer. 657 658 The prototype of the Lua function used as argument is: 659 660.. code-block:: lua 661 662 function() 663.. 664 665 It takes no input, and no output is expected. 666 667.. js:function:: core.register_task(func) 668 669 **context**: body, init, task, action, sample-fetch, converter 670 671 Register and start independent task. The task is started when the HAProxy 672 main scheduler starts. For example this type of tasks can be executed to 673 perform complex health checks. 674 675 :param function func: is the Lua function called to work as initializer. 676 677 The prototype of the Lua function used as argument is: 678 679.. code-block:: lua 680 681 function() 682.. 683 684 It takes no input, and no output is expected. 685 686.. js:function:: core.register_cli([path], usage, func) 687 688 **context**: body 689 690 Register and start independent task. The task is started when the HAProxy 691 main scheduler starts. For example this type of tasks can be executed to 692 perform complex health checks. 693 694 :param array path: is the sequence of word for which the cli execute the Lua 695 binding. 696 :param string usage: is the usage message displayed in the help. 697 :param function func: is the Lua function called to handle the CLI commands. 698 699 The prototype of the Lua function used as argument is: 700 701.. code-block:: lua 702 703 function(AppletTCP, [arg1, [arg2, [...]]]) 704.. 705 706 I/O are managed with the :ref:`applettcp_class` object. Args are given as 707 parameter. The args embed the registered path. If the path is declared like 708 this: 709 710.. code-block:: lua 711 712 core.register_cli({"show", "ssl", "stats"}, "Display SSL stats..", function(applet, arg1, arg2, arg3, arg4, arg5) 713 end) 714.. 715 716 And we execute this in the prompt: 717 718.. code-block:: text 719 720 > prompt 721 > show ssl stats all 722.. 723 724 Then, arg1, arg2 and arg3 will contains respectively "show", "ssl" and "stats". 725 arg4 will contain "all". arg5 contains nil. 726 727.. js:function:: core.set_nice(nice) 728 729 **context**: task, action, sample-fetch, converter 730 731 Change the nice of the current task or current session. 732 733 :param integer nice: the nice value, it must be between -1024 and 1024. 734 735.. js:function:: core.set_map(filename, key, value) 736 737 **context**: init, task, action, sample-fetch, converter 738 739 Set the value *value* associated to the key *key* in the map referenced by 740 *filename*. 741 742 :param string filename: the Map reference 743 :param string key: the key to set or replace 744 :param string value: the associated value 745 746.. js:function:: core.sleep(int seconds) 747 748 **context**: body, init, task, action 749 750 The `core.sleep()` functions stop the Lua execution between specified seconds. 751 752 :param integer seconds: the required seconds. 753 754.. js:function:: core.tcp() 755 756 **context**: init, task, action 757 758 This function returns a new object of a *socket* class. 759 760 :returns: A :ref:`socket_class` object. 761 762.. js:function:: core.concat() 763 764 **context**: body, init, task, action, sample-fetch, converter 765 766 This function returns a new concat object. 767 768 :returns: A :ref:`concat_class` object. 769 770.. js:function:: core.done(data) 771 772 **context**: body, init, task, action, sample-fetch, converter 773 774 :param any data: Return some data for the caller. It is useful with 775 sample-fetches and sample-converters. 776 777 Immediately stops the current Lua execution and returns to the caller which 778 may be a sample fetch, a converter or an action and returns the specified 779 value (ignored for actions and init). It is used when the LUA process finishes 780 its work and wants to give back the control to HAProxy without executing the 781 remaining code. It can be seen as a multi-level "return". 782 783.. js:function:: core.yield() 784 785 **context**: task, action, sample-fetch, converter 786 787 Give back the hand at the HAProxy scheduler. It is used when the LUA 788 processing consumes a lot of processing time. 789 790.. js:function:: core.parse_addr(address) 791 792 **context**: body, init, task, action, sample-fetch, converter 793 794 :param network: is a string describing an ipv4 or ipv6 address and optionally 795 its network length, like this: "127.0.0.1/8" or "aaaa::1234/32". 796 :returns: a userdata containing network or nil if an error occurs. 797 798 Parse ipv4 or ipv6 addresses and its facultative associated network. 799 800.. js:function:: core.match_addr(addr1, addr2) 801 802 **context**: body, init, task, action, sample-fetch, converter 803 804 :param addr1: is an address created with "core.parse_addr". 805 :param addr2: is an address created with "core.parse_addr". 806 :returns: boolean, true if the network of the addresses match, else returns 807 false. 808 809 Match two networks. For example "127.0.0.1/32" matches "127.0.0.0/8". The order 810 of network is not important. 811 812.. js:function:: core.tokenize(str, separators [, noblank]) 813 814 **context**: body, init, task, action, sample-fetch, converter 815 816 This function is useful for tokenizing an entry, or splitting some messages. 817 :param string str: The string which will be split. 818 :param string separators: A string containing a list of separators. 819 :param boolean noblank: Ignore empty entries. 820 :returns: an array of string. 821 822 For example: 823 824.. code-block:: lua 825 826 local array = core.tokenize("This function is useful, for tokenizing an entry.", "., ", true) 827 print_r(array) 828.. 829 830 Returns this array: 831 832.. code-block:: text 833 834 (table) table: 0x21c01e0 [ 835 1: (string) "This" 836 2: (string) "function" 837 3: (string) "is" 838 4: (string) "useful" 839 5: (string) "for" 840 6: (string) "tokenizing" 841 7: (string) "an" 842 8: (string) "entry" 843 ] 844.. 845 846.. _proxy_class: 847 848Proxy class 849============ 850 851.. js:class:: Proxy 852 853 This class provides a way for manipulating proxy and retrieving information 854 like statistics. 855 856.. js:attribute:: Proxy.name 857 858 Contain the name of the proxy. 859 860.. js:attribute:: Proxy.uuid 861 862 Contain the unique identifier of the proxy. 863 864.. js:attribute:: Proxy.servers 865 866 Contain a table with the attached servers. The table is indexed by server 867 name, and each server entry is an object of type :ref:`server_class`. 868 869.. js:attribute:: Proxy.stktable 870 871 Contains a stick table object attached to the proxy. 872 873.. js:attribute:: Proxy.listeners 874 875 Contain a table with the attached listeners. The table is indexed by listener 876 name, and each each listeners entry is an object of type 877 :ref:`listener_class`. 878 879.. js:function:: Proxy.pause(px) 880 881 Pause the proxy. See the management socket documentation for more information. 882 883 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 884 proxy. 885 886.. js:function:: Proxy.resume(px) 887 888 Resume the proxy. See the management socket documentation for more 889 information. 890 891 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 892 proxy. 893 894.. js:function:: Proxy.stop(px) 895 896 Stop the proxy. See the management socket documentation for more information. 897 898 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 899 proxy. 900 901.. js:function:: Proxy.shut_bcksess(px) 902 903 Kill the session attached to a backup server. See the management socket 904 documentation for more information. 905 906 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 907 proxy. 908 909.. js:function:: Proxy.get_cap(px) 910 911 Returns a string describing the capabilities of the proxy. 912 913 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 914 proxy. 915 :returns: a string "frontend", "backend", "proxy" or "ruleset". 916 917.. js:function:: Proxy.get_mode(px) 918 919 Returns a string describing the mode of the current proxy. 920 921 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 922 proxy. 923 :returns: a string "tcp", "http", "health" or "unknown" 924 925.. js:function:: Proxy.get_stats(px) 926 927 Returns a table containing the proxy statistics. The statistics returned are 928 not the same if the proxy is frontend or a backend. 929 930 :param class_proxy px: A :ref:`proxy_class` which indicates the manipulated 931 proxy. 932 :returns: a key/value table containing stats 933 934.. _server_class: 935 936Server class 937============ 938 939.. js:class:: Server 940 941 This class provides a way for manipulating servers and retrieving information. 942 943.. js:attribute:: Server.name 944 945 Contain the name of the server. 946 947.. js:attribute:: Server.puid 948 949 Contain the proxy unique identifier of the server. 950 951.. js:function:: Server.is_draining(sv) 952 953 Return true if the server is currently draining sticky connections. 954 955 :param class_server sv: A :ref:`server_class` which indicates the manipulated 956 server. 957 :returns: a boolean 958 959.. js:function:: Server.set_maxconn(sv, weight) 960 961 Dynamically change the maximum connections of the server. See the management 962 socket documentation for more information about the format of the string. 963 964 :param class_server sv: A :ref:`server_class` which indicates the manipulated 965 server. 966 :param string maxconn: A string describing the server maximum connections. 967 968.. js:function:: Server.get_maxconn(sv, weight) 969 970 This function returns an integer representing the server maximum connections. 971 972 :param class_server sv: A :ref:`server_class` which indicates the manipulated 973 server. 974 :returns: an integer. 975 976.. js:function:: Server.set_weight(sv, weight) 977 978 Dynamically change the weight of the server. See the management socket 979 documentation for more information about the format of the string. 980 981 :param class_server sv: A :ref:`server_class` which indicates the manipulated 982 server. 983 :param string weight: A string describing the server weight. 984 985.. js:function:: Server.get_weight(sv) 986 987 This function returns an integer representing the server weight. 988 989 :param class_server sv: A :ref:`server_class` which indicates the manipulated 990 server. 991 :returns: an integer. 992 993.. js:function:: Server.set_addr(sv, addr[, port]) 994 995 Dynamically change the address of the server. See the management socket 996 documentation for more information about the format of the string. 997 998 :param class_server sv: A :ref:`server_class` which indicates the manipulated 999 server. 1000 :param string addr: A string describing the server address. 1001 1002.. js:function:: Server.get_addr(sv) 1003 1004 Returns a string describing the address of the server. 1005 1006 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1007 server. 1008 :returns: A string 1009 1010.. js:function:: Server.get_stats(sv) 1011 1012 Returns server statistics. 1013 1014 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1015 server. 1016 :returns: a key/value table containing stats 1017 1018.. js:function:: Server.shut_sess(sv) 1019 1020 Shutdown all the sessions attached to the server. See the management socket 1021 documentation for more information about this function. 1022 1023 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1024 server. 1025 1026.. js:function:: Server.set_drain(sv) 1027 1028 Drain sticky sessions. See the management socket documentation for more 1029 information about this function. 1030 1031 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1032 server. 1033 1034.. js:function:: Server.set_maint(sv) 1035 1036 Set maintenance mode. See the management socket documentation for more 1037 information about this function. 1038 1039 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1040 server. 1041 1042.. js:function:: Server.set_ready(sv) 1043 1044 Set normal mode. See the management socket documentation for more information 1045 about this function. 1046 1047 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1048 server. 1049 1050.. js:function:: Server.check_enable(sv) 1051 1052 Enable health checks. See the management socket documentation for more 1053 information about this function. 1054 1055 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1056 server. 1057 1058.. js:function:: Server.check_disable(sv) 1059 1060 Disable health checks. See the management socket documentation for more 1061 information about this function. 1062 1063 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1064 server. 1065 1066.. js:function:: Server.check_force_up(sv) 1067 1068 Force health-check up. See the management socket documentation for more 1069 information about this function. 1070 1071 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1072 server. 1073 1074.. js:function:: Server.check_force_nolb(sv) 1075 1076 Force health-check nolb mode. See the management socket documentation for more 1077 information about this function. 1078 1079 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1080 server. 1081 1082.. js:function:: Server.check_force_down(sv) 1083 1084 Force health-check down. See the management socket documentation for more 1085 information about this function. 1086 1087 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1088 server. 1089 1090.. js:function:: Server.agent_enable(sv) 1091 1092 Enable agent check. See the management socket documentation for more 1093 information about this function. 1094 1095 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1096 server. 1097 1098.. js:function:: Server.agent_disable(sv) 1099 1100 Disable agent check. See the management socket documentation for more 1101 information about this function. 1102 1103 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1104 server. 1105 1106.. js:function:: Server.agent_force_up(sv) 1107 1108 Force agent check up. See the management socket documentation for more 1109 information about this function. 1110 1111 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1112 server. 1113 1114.. js:function:: Server.agent_force_down(sv) 1115 1116 Force agent check down. See the management socket documentation for more 1117 information about this function. 1118 1119 :param class_server sv: A :ref:`server_class` which indicates the manipulated 1120 server. 1121 1122.. _listener_class: 1123 1124Listener class 1125============== 1126 1127.. js:function:: Listener.get_stats(ls) 1128 1129 Returns server statistics. 1130 1131 :param class_listener ls: A :ref:`listener_class` which indicates the 1132 manipulated listener. 1133 :returns: a key/value table containing stats 1134 1135.. _concat_class: 1136 1137Concat class 1138============ 1139 1140.. js:class:: Concat 1141 1142 This class provides a fast way for string concatenation. The way using native 1143 Lua concatenation like the code below is slow for some reasons. 1144 1145.. code-block:: lua 1146 1147 str = "string1" 1148 str = str .. ", string2" 1149 str = str .. ", string3" 1150.. 1151 1152 For each concatenation, Lua: 1153 * allocate memory for the result, 1154 * catenate the two string copying the strings in the new memory block, 1155 * free the old memory block containing the string which is no longer used. 1156 This process does many memory move, allocation and free. In addition, the 1157 memory is not really freed, it is just mark mark as unused and wait for the 1158 garbage collector. 1159 1160 The Concat class provide an alternative way to concatenate strings. It uses 1161 the internal Lua mechanism (it does not allocate memory), but it doesn't copy 1162 the data more than once. 1163 1164 On my computer, the following loops spends 0.2s for the Concat method and 1165 18.5s for the pure Lua implementation. So, the Concat class is about 1000x 1166 faster than the embedded solution. 1167 1168.. code-block:: lua 1169 1170 for j = 1, 100 do 1171 c = core.concat() 1172 for i = 1, 20000 do 1173 c:add("#####") 1174 end 1175 end 1176.. 1177 1178.. code-block:: lua 1179 1180 for j = 1, 100 do 1181 c = "" 1182 for i = 1, 20000 do 1183 c = c .. "#####" 1184 end 1185 end 1186.. 1187 1188.. js:function:: Concat.add(concat, string) 1189 1190 This function adds a string to the current concatenated string. 1191 1192 :param class_concat concat: A :ref:`concat_class` which contains the currently 1193 built string. 1194 :param string string: A new string to concatenate to the current built 1195 string. 1196 1197.. js:function:: Concat.dump(concat) 1198 1199 This function returns the concatenated string. 1200 1201 :param class_concat concat: A :ref:`concat_class` which contains the currently 1202 built string. 1203 :returns: the concatenated string 1204 1205.. _fetches_class: 1206 1207Fetches class 1208============= 1209 1210.. js:class:: Fetches 1211 1212 This class contains a lot of internal HAProxy sample fetches. See the 1213 HAProxy "configuration.txt" documentation for more information about her 1214 usage. They are the chapters 7.3.2 to 7.3.6. 1215 1216 .. warning:: 1217 some sample fetches are not available in some context. These limitations 1218 are specified in this documentation when they're useful. 1219 1220 :see: :js:attr:`TXN.f` 1221 :see: :js:attr:`TXN.sf` 1222 1223 Fetches are useful for: 1224 1225 * get system time, 1226 * get environment variable, 1227 * get random numbers, 1228 * known backend status like the number of users in queue or the number of 1229 connections established, 1230 * client information like ip source or destination, 1231 * deal with stick tables, 1232 * Established SSL information, 1233 * HTTP information like headers or method. 1234 1235.. code-block:: lua 1236 1237 function action(txn) 1238 -- Get source IP 1239 local clientip = txn.f:src() 1240 end 1241.. 1242 1243.. _converters_class: 1244 1245Converters class 1246================ 1247 1248.. js:class:: Converters 1249 1250 This class contains a lot of internal HAProxy sample converters. See the 1251 HAProxy documentation "configuration.txt" for more information about her 1252 usage. Its the chapter 7.3.1. 1253 1254 :see: :js:attr:`TXN.c` 1255 :see: :js:attr:`TXN.sc` 1256 1257 Converters provides statefull transformation. They are useful for: 1258 1259 * converting input to base64, 1260 * applying hash on input string (djb2, crc32, sdbm, wt6), 1261 * format date, 1262 * json escape, 1263 * extracting preferred language comparing two lists, 1264 * turn to lower or upper chars, 1265 * deal with stick tables. 1266 1267.. _channel_class: 1268 1269Channel class 1270============= 1271 1272.. js:class:: Channel 1273 1274 HAProxy uses two buffers for the processing of the requests. The first one is 1275 used with the request data (from the client to the server) and the second is 1276 used for the response data (from the server to the client). 1277 1278 Each buffer contains two types of data. The first type is the incoming data 1279 waiting for a processing. The second part is the outgoing data already 1280 processed. Usually, the incoming data is processed, after it is tagged as 1281 outgoing data, and finally it is sent. The following functions provides tools 1282 for manipulating these data in a buffer. 1283 1284 The following diagram shows where the channel class function are applied. 1285 1286 **Warning**: It is not possible to read from the response in request action, 1287 and it is not possible to read for the request channel in response action. 1288 1289 **Warning**: It is forbidden to alter the Channels buffer from HTTP contexts. 1290 So only :js:func:`Channel.get_in_length`, :js:func:`Channel.get_out_length` 1291 and :js:func:`Channel.is_full` can be called from an HTTP conetext. 1292 1293.. image:: _static/channel.png 1294 1295.. js:function:: Channel.dup(channel) 1296 1297 This function returns a string that contain the entire buffer. The data is 1298 not remove from the buffer and can be reprocessed later. 1299 1300 If the buffer can't receive more data, a 'nil' value is returned. 1301 1302 :param class_channel channel: The manipulated Channel. 1303 :returns: a string containing all the available data or nil. 1304 1305.. js:function:: Channel.get(channel) 1306 1307 This function returns a string that contain the entire buffer. The data is 1308 consumed from the buffer. 1309 1310 If the buffer can't receive more data, a 'nil' value is returned. 1311 1312 :param class_channel channel: The manipulated Channel. 1313 :returns: a string containing all the available data or nil. 1314 1315.. js:function:: Channel.getline(channel) 1316 1317 This function returns a string that contain the first line of the buffer. The 1318 data is consumed. If the data returned doesn't contains a final '\n' its 1319 assumed than its the last available data in the buffer. 1320 1321 If the buffer can't receive more data, a 'nil' value is returned. 1322 1323 :param class_channel channel: The manipulated Channel. 1324 :returns: a string containing the available line or nil. 1325 1326.. js:function:: Channel.set(channel, string) 1327 1328 This function replace the content of the buffer by the string. The function 1329 returns the copied length, otherwise, it returns -1. 1330 1331 The data set with this function are not send. They wait for the end of 1332 HAProxy processing, so the buffer can be full. 1333 1334 :param class_channel channel: The manipulated Channel. 1335 :param string string: The data which will sent. 1336 :returns: an integer containing the amount of bytes copied or -1. 1337 1338.. js:function:: Channel.append(channel, string) 1339 1340 This function append the string argument to the content of the buffer. The 1341 function returns the copied length, otherwise, it returns -1. 1342 1343 The data set with this function are not send. They wait for the end of 1344 HAProxy processing, so the buffer can be full. 1345 1346 :param class_channel channel: The manipulated Channel. 1347 :param string string: The data which will sent. 1348 :returns: an integer containing the amount of bytes copied or -1. 1349 1350.. js:function:: Channel.send(channel, string) 1351 1352 This function required immediate send of the data. Unless if the connection 1353 is close, the buffer is regularly flushed and all the string can be sent. 1354 1355 :param class_channel channel: The manipulated Channel. 1356 :param string string: The data which will sent. 1357 :returns: an integer containing the amount of bytes copied or -1. 1358 1359.. js:function:: Channel.get_in_length(channel) 1360 1361 This function returns the length of the input part of the buffer. 1362 1363 :param class_channel channel: The manipulated Channel. 1364 :returns: an integer containing the amount of available bytes. 1365 1366.. js:function:: Channel.get_out_length(channel) 1367 1368 This function returns the length of the output part of the buffer. 1369 1370 :param class_channel channel: The manipulated Channel. 1371 :returns: an integer containing the amount of available bytes. 1372 1373.. js:function:: Channel.forward(channel, int) 1374 1375 This function transfer bytes from the input part of the buffer to the output 1376 part. 1377 1378 :param class_channel channel: The manipulated Channel. 1379 :param integer int: The amount of data which will be forwarded. 1380 1381.. js:function:: Channel.is_full(channel) 1382 1383 This function returns true if the buffer channel is full. 1384 1385 :returns: a boolean 1386 1387.. _http_class: 1388 1389HTTP class 1390========== 1391 1392.. js:class:: HTTP 1393 1394 This class contain all the HTTP manipulation functions. 1395 1396.. js:function:: HTTP.req_get_headers(http) 1397 1398 Returns a table containing all the request headers. 1399 1400 :param class_http http: The related http object. 1401 :returns: table of headers. 1402 :see: :js:func:`HTTP.res_get_headers` 1403 1404 This is the form of the returned table: 1405 1406.. code-block:: lua 1407 1408 HTTP:req_get_headers()['<header-name>'][<header-index>] = "<header-value>" 1409 1410 local hdr = HTTP:req_get_headers() 1411 hdr["host"][0] = "www.test.com" 1412 hdr["accept"][0] = "audio/basic q=1" 1413 hdr["accept"][1] = "audio/*, q=0.2" 1414 hdr["accept"][2] = "*/*, q=0.1" 1415.. 1416 1417.. js:function:: HTTP.res_get_headers(http) 1418 1419 Returns a table containing all the response headers. 1420 1421 :param class_http http: The related http object. 1422 :returns: table of headers. 1423 :see: :js:func:`HTTP.req_get_headers` 1424 1425 This is the form of the returned table: 1426 1427.. code-block:: lua 1428 1429 HTTP:res_get_headers()['<header-name>'][<header-index>] = "<header-value>" 1430 1431 local hdr = HTTP:req_get_headers() 1432 hdr["host"][0] = "www.test.com" 1433 hdr["accept"][0] = "audio/basic q=1" 1434 hdr["accept"][1] = "audio/*, q=0.2" 1435 hdr["accept"][2] = "*.*, q=0.1" 1436.. 1437 1438.. js:function:: HTTP.req_add_header(http, name, value) 1439 1440 Appends an HTTP header field in the request whose name is 1441 specified in "name" and whose value is defined in "value". 1442 1443 :param class_http http: The related http object. 1444 :param string name: The header name. 1445 :param string value: The header value. 1446 :see: :js:func:`HTTP.res_add_header` 1447 1448.. js:function:: HTTP.res_add_header(http, name, value) 1449 1450 Appends an HTTP header field in the response whose name is 1451 specified in "name" and whose value is defined in "value". 1452 1453 :param class_http http: The related http object. 1454 :param string name: The header name. 1455 :param string value: The header value. 1456 :see: :js:func:`HTTP.req_add_header` 1457 1458.. js:function:: HTTP.req_del_header(http, name) 1459 1460 Removes all HTTP header fields in the request whose name is 1461 specified in "name". 1462 1463 :param class_http http: The related http object. 1464 :param string name: The header name. 1465 :see: :js:func:`HTTP.res_del_header` 1466 1467.. js:function:: HTTP.res_del_header(http, name) 1468 1469 Removes all HTTP header fields in the response whose name is 1470 specified in "name". 1471 1472 :param class_http http: The related http object. 1473 :param string name: The header name. 1474 :see: :js:func:`HTTP.req_del_header` 1475 1476.. js:function:: HTTP.req_set_header(http, name, value) 1477 1478 This variable replace all occurrence of all header "name", by only 1479 one containing the "value". 1480 1481 :param class_http http: The related http object. 1482 :param string name: The header name. 1483 :param string value: The header value. 1484 :see: :js:func:`HTTP.res_set_header` 1485 1486 This function does the same work as the following code: 1487 1488.. code-block:: lua 1489 1490 function fcn(txn) 1491 TXN.http:req_del_header("header") 1492 TXN.http:req_add_header("header", "value") 1493 end 1494.. 1495 1496.. js:function:: HTTP.res_set_header(http, name, value) 1497 1498 This variable replace all occurrence of all header "name", by only 1499 one containing the "value". 1500 1501 :param class_http http: The related http object. 1502 :param string name: The header name. 1503 :param string value: The header value. 1504 :see: :js:func:`HTTP.req_rep_header()` 1505 1506.. js:function:: HTTP.req_rep_header(http, name, regex, replace) 1507 1508 Matches the regular expression in all occurrences of header field "name" 1509 according to "regex", and replaces them with the "replace" argument. The 1510 replacement value can contain back references like \1, \2, ... This 1511 function works with the request. 1512 1513 :param class_http http: The related http object. 1514 :param string name: The header name. 1515 :param string regex: The match regular expression. 1516 :param string replace: The replacement value. 1517 :see: :js:func:`HTTP.res_rep_header()` 1518 1519.. js:function:: HTTP.res_rep_header(http, name, regex, string) 1520 1521 Matches the regular expression in all occurrences of header field "name" 1522 according to "regex", and replaces them with the "replace" argument. The 1523 replacement value can contain back references like \1, \2, ... This 1524 function works with the request. 1525 1526 :param class_http http: The related http object. 1527 :param string name: The header name. 1528 :param string regex: The match regular expression. 1529 :param string replace: The replacement value. 1530 :see: :js:func:`HTTP.req_rep_header()` 1531 1532.. js:function:: HTTP.req_set_method(http, method) 1533 1534 Rewrites the request method with the parameter "method". 1535 1536 :param class_http http: The related http object. 1537 :param string method: The new method. 1538 1539.. js:function:: HTTP.req_set_path(http, path) 1540 1541 Rewrites the request path with the "path" parameter. 1542 1543 :param class_http http: The related http object. 1544 :param string path: The new path. 1545 1546.. js:function:: HTTP.req_set_query(http, query) 1547 1548 Rewrites the request's query string which appears after the first question 1549 mark ("?") with the parameter "query". 1550 1551 :param class_http http: The related http object. 1552 :param string query: The new query. 1553 1554.. js:function:: HTTP.req_set_uri(http, uri) 1555 1556 Rewrites the request URI with the parameter "uri". 1557 1558 :param class_http http: The related http object. 1559 :param string uri: The new uri. 1560 1561.. js:function:: HTTP.res_set_status(http, status [, reason]) 1562 1563 Rewrites the response status code with the parameter "code". 1564 1565 If no custom reason is provided, it will be generated from the status. 1566 1567 :param class_http http: The related http object. 1568 :param integer status: The new response status code. 1569 :param string reason: The new response reason (optional). 1570 1571.. _txn_class: 1572 1573TXN class 1574========= 1575 1576.. js:class:: TXN 1577 1578 The txn class contain all the functions relative to the http or tcp 1579 transaction (Note than a tcp stream is the same than a tcp transaction, but 1580 an HTTP transaction is not the same than a tcp stream). 1581 1582 The usage of this class permits to retrieve data from the requests, alter it 1583 and forward it. 1584 1585 All the functions provided by this class are available in the context 1586 **sample-fetches** and **actions**. 1587 1588.. js:attribute:: TXN.c 1589 1590 :returns: An :ref:`converters_class`. 1591 1592 This attribute contains a Converters class object. 1593 1594.. js:attribute:: TXN.sc 1595 1596 :returns: An :ref:`converters_class`. 1597 1598 This attribute contains a Converters class object. The functions of 1599 this object returns always a string. 1600 1601.. js:attribute:: TXN.f 1602 1603 :returns: An :ref:`fetches_class`. 1604 1605 This attribute contains a Fetches class object. 1606 1607.. js:attribute:: TXN.sf 1608 1609 :returns: An :ref:`fetches_class`. 1610 1611 This attribute contains a Fetches class object. The functions of 1612 this object returns always a string. 1613 1614.. js:attribute:: TXN.req 1615 1616 :returns: An :ref:`channel_class`. 1617 1618 This attribute contains a channel class object for the request buffer. 1619 1620.. js:attribute:: TXN.res 1621 1622 :returns: An :ref:`channel_class`. 1623 1624 This attribute contains a channel class object for the response buffer. 1625 1626.. js:attribute:: TXN.http 1627 1628 :returns: An :ref:`http_class`. 1629 1630 This attribute contains an HTTP class object. It is available only if the 1631 proxy has the "mode http" enabled. 1632 1633.. js:function:: TXN.log(TXN, loglevel, msg) 1634 1635 This function sends a log. The log is sent, according with the HAProxy 1636 configuration file, on the default syslog server if it is configured and on 1637 the stderr if it is allowed. 1638 1639 :param class_txn txn: The class txn object containing the data. 1640 :param integer loglevel: Is the log level associated with the message. It is a 1641 number between 0 and 7. 1642 :param string msg: The log content. 1643 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`, 1644 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`, 1645 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions) 1646 :see: :js:func:`TXN.deflog` 1647 :see: :js:func:`TXN.Debug` 1648 :see: :js:func:`TXN.Info` 1649 :see: :js:func:`TXN.Warning` 1650 :see: :js:func:`TXN.Alert` 1651 1652.. js:function:: TXN.deflog(TXN, msg) 1653 1654 Sends a log line with the default loglevel for the proxy associated with the 1655 transaction. 1656 1657 :param class_txn txn: The class txn object containing the data. 1658 :param string msg: The log content. 1659 :see: :js:func:`TXN.log 1660 1661.. js:function:: TXN.Debug(txn, msg) 1662 1663 :param class_txn txn: The class txn object containing the data. 1664 :param string msg: The log content. 1665 :see: :js:func:`TXN.log` 1666 1667 Does the same job than: 1668 1669.. code-block:: lua 1670 1671 function Debug(txn, msg) 1672 TXN.log(txn, core.debug, msg) 1673 end 1674.. 1675 1676.. js:function:: TXN.Info(txn, msg) 1677 1678 :param class_txn txn: The class txn object containing the data. 1679 :param string msg: The log content. 1680 :see: :js:func:`TXN.log` 1681 1682.. code-block:: lua 1683 1684 function Debug(txn, msg) 1685 TXN.log(txn, core.info, msg) 1686 end 1687.. 1688 1689.. js:function:: TXN.Warning(txn, msg) 1690 1691 :param class_txn txn: The class txn object containing the data. 1692 :param string msg: The log content. 1693 :see: :js:func:`TXN.log` 1694 1695.. code-block:: lua 1696 1697 function Debug(txn, msg) 1698 TXN.log(txn, core.warning, msg) 1699 end 1700.. 1701 1702.. js:function:: TXN.Alert(txn, msg) 1703 1704 :param class_txn txn: The class txn object containing the data. 1705 :param string msg: The log content. 1706 :see: :js:func:`TXN.log` 1707 1708.. code-block:: lua 1709 1710 function Debug(txn, msg) 1711 TXN.log(txn, core.alert, msg) 1712 end 1713.. 1714 1715.. js:function:: TXN.get_priv(txn) 1716 1717 Return Lua data stored in the current transaction (with the `TXN.set_priv()`) 1718 function. If no data are stored, it returns a nil value. 1719 1720 :param class_txn txn: The class txn object containing the data. 1721 :returns: the opaque data previously stored, or nil if nothing is 1722 available. 1723 1724.. js:function:: TXN.set_priv(txn, data) 1725 1726 Store any data in the current HAProxy transaction. This action replace the 1727 old stored data. 1728 1729 :param class_txn txn: The class txn object containing the data. 1730 :param opaque data: The data which is stored in the transaction. 1731 1732.. js:function:: TXN.set_var(TXN, var, value[, ifexist]) 1733 1734 Converts a Lua type in a HAProxy type and store it in a variable <var>. 1735 1736 :param class_txn txn: The class txn object containing the data. 1737 :param string var: The variable name according with the HAProxy variable syntax. 1738 :param type value: The value associated to the variable. The type can be string or 1739 integer. 1740 :param boolean ifexist: If this parameter is set to a truthy value the variable 1741 will only be set if it was defined elsewhere (i.e. used 1742 within the configuration). It is highly recommended to 1743 always set this to true. 1744 1745.. js:function:: TXN.unset_var(TXN, var) 1746 1747 Unset the variable <var>. 1748 1749 :param class_txn txn: The class txn object containing the data. 1750 :param string var: The variable name according with the HAProxy variable syntax. 1751 1752.. js:function:: TXN.get_var(TXN, var) 1753 1754 Returns data stored in the variable <var> converter in Lua type. 1755 1756 :param class_txn txn: The class txn object containing the data. 1757 :param string var: The variable name according with the HAProxy variable syntax. 1758 1759.. js:function:: TXN.reply([reply]) 1760 1761 Return a new reply object 1762 1763 :param table reply: A table containing info to initialize the reply fields. 1764 :returns: A :ref:`reply_class` object. 1765 1766 The table used to initialized the reply object may contain following entries : 1767 1768 * status : The reply status code. the code 200 is used by default. 1769 * reason : The reply reason. The reason corresponding to the status code is 1770 used by default. 1771 * headers : An list of headers, indexed by header name. Empty by default. For 1772 a given name, multiple values are possible, stored in an ordered list. 1773 * body : The reply body, empty by default. 1774 1775.. code-block:: lua 1776 1777 local reply = txn:reply{ 1778 status = 400, 1779 reason = "Bad request", 1780 headers = { 1781 ["content-type"] = { "text/html" }, 1782 ["cache-control"] = {"no-cache", "no-store" } 1783 }, 1784 body = "<html><body><h1>invalid request<h1></body></html>" 1785 } 1786.. 1787 :see: :js:class:`Reply` 1788 1789.. js:function:: TXN.done(txn[, reply]) 1790 1791 This function terminates processing of the transaction and the associated 1792 session and optionally reply to the client for HTTP sessions. 1793 1794 :param class_txn txn: The class txn object containing the data. 1795 :param class_reply reply: The class reply object to return to the client. 1796 1797 This functions can be used when a critical error is detected or to terminate 1798 processing after some data have been returned to the client (eg: a redirect). 1799 To do so, a reply may be provided. This object is optional and may contain a 1800 status code, a reason, a header list and a body. All these fields are 1801 optional. When not provided, the default values are used. By default, with an 1802 empty reply object, an empty HTTP 200 response is returned to the client. If 1803 no reply object is provided, the transaction is terminated without any 1804 reply. If a reply object is provided, it must not exceed the buffer size once 1805 converted into the internal HTTP representing. Because for now there is no 1806 easy way to be sure it fits, it is probably better to keep it reasonably 1807 small. 1808 1809 The reply object may be fully created in lua or the class Reply may be used to 1810 create it. 1811 1812.. code-block:: lua 1813 1814 local reply = txn:reply() 1815 reply:set_status(400, "Bad request") 1816 reply:add_header("content-type", "text/html") 1817 reply:add_header("cache-control", "no-cache") 1818 reply:add_header("cache-control", "no-store") 1819 reply:set_body("<html><body><h1>invalid request<h1></body></html>") 1820 txn:done(reply) 1821.. 1822 1823.. code-block:: lua 1824 1825 txn:done{ 1826 status = 400, 1827 reason = "Bad request", 1828 headers = { 1829 ["content-type"] = { "text/html" }, 1830 ["cache-control"] = { "no-cache", "no-store" }, 1831 }, 1832 body = "<html><body><h1>invalid request<h1></body></html>" 1833 } 1834.. 1835 1836 .. warning:: 1837 It not make sense to call this function from sample-fetches. In this case 1838 the behaviour of this one is the same than core.done(): it quit the Lua 1839 execution. The transaction is really aborted only from an action registered 1840 function. 1841 1842 :see: :js:func:`TXN.reply`, :js:class:`Reply` 1843 1844.. js:function:: TXN.set_loglevel(txn, loglevel) 1845 1846 Is used to change the log level of the current request. The "loglevel" must 1847 be an integer between 0 and 7. 1848 1849 :param class_txn txn: The class txn object containing the data. 1850 :param integer loglevel: The required log level. This variable can be one of 1851 :see: :js:attr:`core.emerg`, :js:attr:`core.alert`, :js:attr:`core.crit`, 1852 :js:attr:`core.err`, :js:attr:`core.warning`, :js:attr:`core.notice`, 1853 :js:attr:`core.info`, :js:attr:`core.debug` (log level definitions) 1854 1855.. js:function:: TXN.set_tos(txn, tos) 1856 1857 Is used to set the TOS or DSCP field value of packets sent to the client to 1858 the value passed in "tos" on platforms which support this. 1859 1860 :param class_txn txn: The class txn object containing the data. 1861 :param integer tos: The new TOS os DSCP. 1862 1863.. js:function:: TXN.set_mark(txn, mark) 1864 1865 Is used to set the Netfilter MARK on all packets sent to the client to the 1866 value passed in "mark" on platforms which support it. 1867 1868 :param class_txn txn: The class txn object containing the data. 1869 :param integer mark: The mark value. 1870 1871.. js:function:: TXN.set_priority_class(txn, prio) 1872 1873 This function adjusts the priority class of the transaction. The value should 1874 be within the range -2047..2047. Values outside this range will be 1875 truncated. 1876 1877 See the HAProxy configuration.txt file keyword "http-request" action 1878 "set-priority-class" for details. 1879 1880.. js:function:: TXN.set_priority_offset(txn, prio) 1881 1882 This function adjusts the priority offset of the transaction. The value 1883 should be within the range -524287..524287. Values outside this range will be 1884 truncated. 1885 1886 See the HAProxy configuration.txt file keyword "http-request" action 1887 "set-priority-offset" for details. 1888 1889.. _reply_class: 1890 1891Reply class 1892============ 1893 1894.. js:class:: Reply 1895 1896 **context**: action 1897 1898 This class represents an HTTP response message. It provides some methods to 1899 enrich it. Once converted into the internal HTTP representation, the response 1900 message must not exceed the buffer size. Because for now there is no 1901 easy way to be sure it fits, it is probably better to keep it reasonably 1902 small. 1903 1904 See tune.bufsize in the configuration manual for dettails. 1905 1906.. code-block:: lua 1907 1908 local reply = txn:reply({status = 400}) -- default HTTP 400 reason-phase used 1909 reply:add_header("content-type", "text/html") 1910 reply:add_header("cache-control", "no-cache") 1911 reply:add_header("cache-control", "no-store") 1912 reply:set_body("<html><body><h1>invalid request<h1></body></html>") 1913.. 1914 1915 :see: :js:func:`TXN.reply` 1916 1917.. js:attribute:: Reply.status 1918 1919 The reply status code. By default, the status code is set to 200. 1920 1921 :returns: integer 1922 1923.. js:attribute:: Reply.reason 1924 1925 The reason string describing the status code. 1926 1927 :returns: string 1928 1929.. js:attribute:: Reply.headers 1930 1931 A table indexing all reply headers by name. To each name is associated an 1932 ordered list of values. 1933 1934 :returns: Lua table 1935 1936.. code-block:: lua 1937 1938 { 1939 ["content-type"] = { "text/html" }, 1940 ["cache-control"] = {"no-cache", "no-store" }, 1941 x_header_name = { "value1", "value2", ... } 1942 ... 1943 } 1944.. 1945 1946.. js:attribute:: Reply.body 1947 1948 The reply payload. 1949 1950 :returns: string 1951 1952.. js:function:: Reply.set_status(REPLY, status[, reason]) 1953 1954 Set the reply status code and optionally the reason-phrase. If the reason is 1955 not provided, the default reason corresponding to the status code is used. 1956 1957 :param class_reply reply: The related Reply object. 1958 :param integer status: The reply status code. 1959 :param string reason: The reply status reason (optional). 1960 1961.. js:function:: Reply.add_header(REPLY, name, value) 1962 1963 Add a header to the reply object. If the header does not already exist, a new 1964 entry is created with its name as index and a one-element list containing its 1965 value as value. Otherwise, the header value is appended to the ordered list of 1966 values associated to the header name. 1967 1968 :param class_reply reply: The related Reply object. 1969 :param string name: The header field name. 1970 :param string value: The header field value. 1971 1972.. js:function:: Reply.del_header(REPLY, name) 1973 1974 Remove all occurrences of a header name from the reply object. 1975 1976 :param class_reply reply: The related Reply object. 1977 :param string name: The header field name. 1978 1979.. js:function:: Reply.set_body(REPLY, body) 1980 1981 Set the reply payload. 1982 1983 :param class_reply reply: The related Reply object. 1984 :param string body: The reply payload. 1985 1986.. _socket_class: 1987 1988Socket class 1989============ 1990 1991.. js:class:: Socket 1992 1993 This class must be compatible with the Lua Socket class. Only the 'client' 1994 functions are available. See the Lua Socket documentation: 1995 1996 `http://w3.impa.br/~diego/software/luasocket/tcp.html 1997 <http://w3.impa.br/~diego/software/luasocket/tcp.html>`_ 1998 1999.. js:function:: Socket.close(socket) 2000 2001 Closes a TCP object. The internal socket used by the object is closed and the 2002 local address to which the object was bound is made available to other 2003 applications. No further operations (except for further calls to the close 2004 method) are allowed on a closed Socket. 2005 2006 :param class_socket socket: Is the manipulated Socket. 2007 2008 Note: It is important to close all used sockets once they are not needed, 2009 since, in many systems, each socket uses a file descriptor, which are limited 2010 system resources. Garbage-collected objects are automatically closed before 2011 destruction, though. 2012 2013.. js:function:: Socket.connect(socket, address[, port]) 2014 2015 Attempts to connect a socket object to a remote host. 2016 2017 2018 In case of error, the method returns nil followed by a string describing the 2019 error. In case of success, the method returns 1. 2020 2021 :param class_socket socket: Is the manipulated Socket. 2022 :param string address: can be an IP address or a host name. See below for more 2023 information. 2024 :param integer port: must be an integer number in the range [1..64K]. 2025 :returns: 1 or nil. 2026 2027 An address field extension permits to use the connect() function to connect to 2028 other stream than TCP. The syntax containing a simpleipv4 or ipv6 address is 2029 the basically expected format. This format requires the port. 2030 2031 Other format accepted are a socket path like "/socket/path", it permits to 2032 connect to a socket. Abstract namespaces are supported with the prefix 2033 "abns@", and finally a file descriptor can be passed with the prefix "fd@". 2034 The prefix "ipv4@", "ipv6@" and "unix@" are also supported. The port can be 2035 passed int the string. The syntax "127.0.0.1:1234" is valid. In this case, the 2036 parameter *port* must not be set. 2037 2038.. js:function:: Socket.connect_ssl(socket, address, port) 2039 2040 Same behavior than the function socket:connect, but uses SSL. 2041 2042 :param class_socket socket: Is the manipulated Socket. 2043 :returns: 1 or nil. 2044 2045.. js:function:: Socket.getpeername(socket) 2046 2047 Returns information about the remote side of a connected client object. 2048 2049 Returns a string with the IP address of the peer, followed by the port number 2050 that peer is using for the connection. In case of error, the method returns 2051 nil. 2052 2053 :param class_socket socket: Is the manipulated Socket. 2054 :returns: a string containing the server information. 2055 2056.. js:function:: Socket.getsockname(socket) 2057 2058 Returns the local address information associated to the object. 2059 2060 The method returns a string with local IP address and a number with the port. 2061 In case of error, the method returns nil. 2062 2063 :param class_socket socket: Is the manipulated Socket. 2064 :returns: a string containing the client information. 2065 2066.. js:function:: Socket.receive(socket, [pattern [, prefix]]) 2067 2068 Reads data from a client object, according to the specified read pattern. 2069 Patterns follow the Lua file I/O format, and the difference in performance 2070 between all patterns is negligible. 2071 2072 :param class_socket socket: Is the manipulated Socket. 2073 :param string|integer pattern: Describe what is required (see below). 2074 :param string prefix: A string which will be prefix the returned data. 2075 :returns: a string containing the required data or nil. 2076 2077 Pattern can be any of the following: 2078 2079 * **`*a`**: reads from the socket until the connection is closed. No 2080 end-of-line translation is performed; 2081 2082 * **`*l`**: reads a line of text from the Socket. The line is terminated by a 2083 LF character (ASCII 10), optionally preceded by a CR character 2084 (ASCII 13). The CR and LF characters are not included in the 2085 returned line. In fact, all CR characters are ignored by the 2086 pattern. This is the default pattern. 2087 2088 * **number**: causes the method to read a specified number of bytes from the 2089 Socket. Prefix is an optional string to be concatenated to the 2090 beginning of any received data before return. 2091 2092 * **empty**: If the pattern is left empty, the default option is `*l`. 2093 2094 If successful, the method returns the received pattern. In case of error, the 2095 method returns nil followed by an error message which can be the string 2096 'closed' in case the connection was closed before the transmission was 2097 completed or the string 'timeout' in case there was a timeout during the 2098 operation. Also, after the error message, the function returns the partial 2099 result of the transmission. 2100 2101 Important note: This function was changed severely. It used to support 2102 multiple patterns (but I have never seen this feature used) and now it 2103 doesn't anymore. Partial results used to be returned in the same way as 2104 successful results. This last feature violated the idea that all functions 2105 should return nil on error. Thus it was changed too. 2106 2107.. js:function:: Socket.send(socket, data [, start [, end ]]) 2108 2109 Sends data through client object. 2110 2111 :param class_socket socket: Is the manipulated Socket. 2112 :param string data: The data that will be sent. 2113 :param integer start: The start position in the buffer of the data which will 2114 be sent. 2115 :param integer end: The end position in the buffer of the data which will 2116 be sent. 2117 :returns: see below. 2118 2119 Data is the string to be sent. The optional arguments i and j work exactly 2120 like the standard string.sub Lua function to allow the selection of a 2121 substring to be sent. 2122 2123 If successful, the method returns the index of the last byte within [start, 2124 end] that has been sent. Notice that, if start is 1 or absent, this is 2125 effectively the total number of bytes sent. In case of error, the method 2126 returns nil, followed by an error message, followed by the index of the last 2127 byte within [start, end] that has been sent. You might want to try again from 2128 the byte following that. The error message can be 'closed' in case the 2129 connection was closed before the transmission was completed or the string 2130 'timeout' in case there was a timeout during the operation. 2131 2132 Note: Output is not buffered. For small strings, it is always better to 2133 concatenate them in Lua (with the '..' operator) and send the result in one 2134 call instead of calling the method several times. 2135 2136.. js:function:: Socket.setoption(socket, option [, value]) 2137 2138 Just implemented for compatibility, this cal does nothing. 2139 2140.. js:function:: Socket.settimeout(socket, value [, mode]) 2141 2142 Changes the timeout values for the object. All I/O operations are blocking. 2143 That is, any call to the methods send, receive, and accept will block 2144 indefinitely, until the operation completes. The settimeout method defines a 2145 limit on the amount of time the I/O methods can block. When a timeout time 2146 has elapsed, the affected methods give up and fail with an error code. 2147 2148 The amount of time to wait is specified as the value parameter, in seconds. 2149 2150 The timeout modes are not implemented, the only settable timeout is the 2151 inactivity time waiting for complete the internal buffer send or waiting for 2152 receive data. 2153 2154 :param class_socket socket: Is the manipulated Socket. 2155 :param float value: The timeout value. Use floating point to specify 2156 milliseconds. 2157 2158.. _regex_class: 2159 2160Regex class 2161=========== 2162 2163.. js:class:: Regex 2164 2165 This class allows the usage of HAProxy regexes because classic lua doesn't 2166 provides regexes. This class inherits the HAProxy compilation options, so the 2167 regexes can be libc regex, pcre regex or pcre JIT regex. 2168 2169 The expression matching number is limited to 20 per regex. The only available 2170 option is case sensitive. 2171 2172 Because regexes compilation is a heavy process, it is better to define all 2173 your regexes in the **body context** and use it during the runtime. 2174 2175.. code-block:: lua 2176 2177 -- Create the regex 2178 st, regex = Regex.new("needle (..) (...)", true); 2179 2180 -- Check compilation errors 2181 if st == false then 2182 print "error: " .. regex 2183 end 2184 2185 -- Match the regexes 2186 print(regex:exec("Looking for a needle in the haystack")) -- true 2187 print(regex:exec("Lokking for a cat in the haystack")) -- false 2188 2189 -- Extract words 2190 st, list = regex:match("Looking for a needle in the haystack") 2191 print(st) -- true 2192 print(list[1]) -- needle in the 2193 print(list[2]) -- in 2194 print(list[3]) -- the 2195 2196.. js:function:: Regex.new(regex, case_sensitive) 2197 2198 Create and compile a regex. 2199 2200 :param string regex: The regular expression according with the libc or pcre 2201 standard 2202 :param boolean case_sensitive: Match is case sensitive or not. 2203 :returns: boolean status and :ref:`regex_class` or string containing fail reason. 2204 2205.. js:function:: Regex.exec(regex, str) 2206 2207 Execute the regex. 2208 2209 :param class_regex regex: A :ref:`regex_class` object. 2210 :param string str: The input string will be compared with the compiled regex. 2211 :returns: a boolean status according with the match result. 2212 2213.. js:function:: Regex.match(regex, str) 2214 2215 Execute the regex and return matched expressions. 2216 2217 :param class_map map: A :ref:`regex_class` object. 2218 :param string str: The input string will be compared with the compiled regex. 2219 :returns: a boolean status according with the match result, and 2220 a table containing all the string matched in order of declaration. 2221 2222.. _map_class: 2223 2224Map class 2225========= 2226 2227.. js:class:: Map 2228 2229 This class permits to do some lookup in HAProxy maps. The declared maps can 2230 be modified during the runtime through the HAProxy management socket. 2231 2232.. code-block:: lua 2233 2234 default = "usa" 2235 2236 -- Create and load map 2237 geo = Map.new("geo.map", Map._ip); 2238 2239 -- Create new fetch that returns the user country 2240 core.register_fetches("country", function(txn) 2241 local src; 2242 local loc; 2243 2244 src = txn.f:fhdr("x-forwarded-for"); 2245 if (src == nil) then 2246 src = txn.f:src() 2247 if (src == nil) then 2248 return default; 2249 end 2250 end 2251 2252 -- Perform lookup 2253 loc = geo:lookup(src); 2254 2255 if (loc == nil) then 2256 return default; 2257 end 2258 2259 return loc; 2260 end); 2261 2262.. js:attribute:: Map._int 2263 2264 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2265 samples" and subchapter "ACL basics" to understand this pattern matching 2266 method. 2267 2268 Note that :js:attr:`Map.int` is also available for compatibility. 2269 2270.. js:attribute:: Map._ip 2271 2272 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2273 samples" and subchapter "ACL basics" to understand this pattern matching 2274 method. 2275 2276 Note that :js:attr:`Map.ip` is also available for compatibility. 2277 2278.. js:attribute:: Map._str 2279 2280 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2281 samples" and subchapter "ACL basics" to understand this pattern matching 2282 method. 2283 2284 Note that :js:attr:`Map.str` is also available for compatibility. 2285 2286.. js:attribute:: Map._beg 2287 2288 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2289 samples" and subchapter "ACL basics" to understand this pattern matching 2290 method. 2291 2292 Note that :js:attr:`Map.beg` is also available for compatibility. 2293 2294.. js:attribute:: Map._sub 2295 2296 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2297 samples" and subchapter "ACL basics" to understand this pattern matching 2298 method. 2299 2300 Note that :js:attr:`Map.sub` is also available for compatibility. 2301 2302.. js:attribute:: Map._dir 2303 2304 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2305 samples" and subchapter "ACL basics" to understand this pattern matching 2306 method. 2307 2308 Note that :js:attr:`Map.dir` is also available for compatibility. 2309 2310.. js:attribute:: Map._dom 2311 2312 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2313 samples" and subchapter "ACL basics" to understand this pattern matching 2314 method. 2315 2316 Note that :js:attr:`Map.dom` is also available for compatibility. 2317 2318.. js:attribute:: Map._end 2319 2320 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2321 samples" and subchapter "ACL basics" to understand this pattern matching 2322 method. 2323 2324.. js:attribute:: Map._reg 2325 2326 See the HAProxy configuration.txt file, chapter "Using ACLs and fetching 2327 samples" and subchapter "ACL basics" to understand this pattern matching 2328 method. 2329 2330 Note that :js:attr:`Map.reg` is also available for compatibility. 2331 2332 2333.. js:function:: Map.new(file, method) 2334 2335 Creates and load a map. 2336 2337 :param string file: Is the file containing the map. 2338 :param integer method: Is the map pattern matching method. See the attributes 2339 of the Map class. 2340 :returns: a class Map object. 2341 :see: The Map attributes: :js:attr:`Map._int`, :js:attr:`Map._ip`, 2342 :js:attr:`Map._str`, :js:attr:`Map._beg`, :js:attr:`Map._sub`, 2343 :js:attr:`Map._dir`, :js:attr:`Map._dom`, :js:attr:`Map._end` and 2344 :js:attr:`Map._reg`. 2345 2346.. js:function:: Map.lookup(map, str) 2347 2348 Perform a lookup in a map. 2349 2350 :param class_map map: Is the class Map object. 2351 :param string str: Is the string used as key. 2352 :returns: a string containing the result or nil if no match. 2353 2354.. js:function:: Map.slookup(map, str) 2355 2356 Perform a lookup in a map. 2357 2358 :param class_map map: Is the class Map object. 2359 :param string str: Is the string used as key. 2360 :returns: a string containing the result or empty string if no match. 2361 2362.. _applethttp_class: 2363 2364AppletHTTP class 2365================ 2366 2367.. js:class:: AppletHTTP 2368 2369 This class is used with applets that requires the 'http' mode. The http applet 2370 can be registered with the *core.register_service()* function. They are used 2371 for processing an http request like a server in back of HAProxy. 2372 2373 This is an hello world sample code: 2374 2375.. code-block:: lua 2376 2377 core.register_service("hello-world", "http", function(applet) 2378 local response = "Hello World !" 2379 applet:set_status(200) 2380 applet:add_header("content-length", string.len(response)) 2381 applet:add_header("content-type", "text/plain") 2382 applet:start_response() 2383 applet:send(response) 2384 end) 2385 2386.. js:attribute:: AppletHTTP.c 2387 2388 :returns: A :ref:`converters_class` 2389 2390 This attribute contains a Converters class object. 2391 2392.. js:attribute:: AppletHTTP.sc 2393 2394 :returns: A :ref:`converters_class` 2395 2396 This attribute contains a Converters class object. The 2397 functions of this object returns always a string. 2398 2399.. js:attribute:: AppletHTTP.f 2400 2401 :returns: A :ref:`fetches_class` 2402 2403 This attribute contains a Fetches class object. Note that the 2404 applet execution place cannot access to a valid HAProxy core HTTP 2405 transaction, so some sample fetches related to the HTTP dependent 2406 values (hdr, path, ...) are not available. 2407 2408.. js:attribute:: AppletHTTP.sf 2409 2410 :returns: A :ref:`fetches_class` 2411 2412 This attribute contains a Fetches class object. The functions of 2413 this object returns always a string. Note that the applet 2414 execution place cannot access to a valid HAProxy core HTTP 2415 transaction, so some sample fetches related to the HTTP dependent 2416 values (hdr, path, ...) are not available. 2417 2418.. js:attribute:: AppletHTTP.method 2419 2420 :returns: string 2421 2422 The attribute method returns a string containing the HTTP 2423 method. 2424 2425.. js:attribute:: AppletHTTP.version 2426 2427 :returns: string 2428 2429 The attribute version, returns a string containing the HTTP 2430 request version. 2431 2432.. js:attribute:: AppletHTTP.path 2433 2434 :returns: string 2435 2436 The attribute path returns a string containing the HTTP 2437 request path. 2438 2439.. js:attribute:: AppletHTTP.qs 2440 2441 :returns: string 2442 2443 The attribute qs returns a string containing the HTTP 2444 request query string. 2445 2446.. js:attribute:: AppletHTTP.length 2447 2448 :returns: integer 2449 2450 The attribute length returns an integer containing the HTTP 2451 body length. 2452 2453.. js:attribute:: AppletHTTP.headers 2454 2455 :returns: table 2456 2457 The attribute headers returns a table containing the HTTP 2458 headers. The header names are always in lower case. As the header name can be 2459 encountered more than once in each request, the value is indexed with 0 as 2460 first index value. The table have this form: 2461 2462.. code-block:: lua 2463 2464 AppletHTTP.headers['<header-name>'][<header-index>] = "<header-value>" 2465 2466 AppletHTTP.headers["host"][0] = "www.test.com" 2467 AppletHTTP.headers["accept"][0] = "audio/basic q=1" 2468 AppletHTTP.headers["accept"][1] = "audio/*, q=0.2" 2469 AppletHTTP.headers["accept"][2] = "*/*, q=0.1" 2470.. 2471 2472.. js:function:: AppletHTTP.set_status(applet, code [, reason]) 2473 2474 This function sets the HTTP status code for the response. The allowed code are 2475 from 100 to 599. 2476 2477 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2478 :param integer code: the status code returned to the client. 2479 :param string reason: the status reason returned to the client (optional). 2480 2481.. js:function:: AppletHTTP.add_header(applet, name, value) 2482 2483 This function add an header in the response. Duplicated headers are not 2484 collapsed. The special header *content-length* is used to determinate the 2485 response length. If it not exists, a *transfer-encoding: chunked* is set, and 2486 all the write from the function *AppletHTTP:send()* become a chunk. 2487 2488 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2489 :param string name: the header name 2490 :param string value: the header value 2491 2492.. js:function:: AppletHTTP.start_response(applet) 2493 2494 This function indicates to the HTTP engine that it can process and send the 2495 response headers. After this called we cannot add headers to the response; We 2496 cannot use the *AppletHTTP:send()* function if the 2497 *AppletHTTP:start_response()* is not called. 2498 2499 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2500 2501.. js:function:: AppletHTTP.getline(applet) 2502 2503 This function returns a string containing one line from the http body. If the 2504 data returned doesn't contains a final '\\n' its assumed than its the last 2505 available data before the end of stream. 2506 2507 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2508 :returns: a string. The string can be empty if we reach the end of the stream. 2509 2510.. js:function:: AppletHTTP.receive(applet, [size]) 2511 2512 Reads data from the HTTP body, according to the specified read *size*. If the 2513 *size* is missing, the function tries to read all the content of the stream 2514 until the end. If the *size* is bigger than the http body, it returns the 2515 amount of data available. 2516 2517 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2518 :param integer size: the required read size. 2519 :returns: always return a string,the string can be empty is the connection is 2520 closed. 2521 2522.. js:function:: AppletHTTP.send(applet, msg) 2523 2524 Send the message *msg* on the http request body. 2525 2526 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2527 :param string msg: the message to send. 2528 2529.. js:function:: AppletHTTP.get_priv(applet) 2530 2531 Return Lua data stored in the current transaction. If no data are stored, 2532 it returns a nil value. 2533 2534 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2535 :returns: the opaque data previously stored, or nil if nothing is 2536 available. 2537 :see: :js:func:`AppletHTTP.set_priv` 2538 2539.. js:function:: AppletHTTP.set_priv(applet, data) 2540 2541 Store any data in the current HAProxy transaction. This action replace the 2542 old stored data. 2543 2544 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2545 :param opaque data: The data which is stored in the transaction. 2546 :see: :js:func:`AppletHTTP.get_priv` 2547 2548.. js:function:: AppletHTTP.set_var(applet, var, value[, ifexist]) 2549 2550 Converts a Lua type in a HAProxy type and store it in a variable <var>. 2551 2552 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2553 :param string var: The variable name according with the HAProxy variable syntax. 2554 :param type value: The value associated to the variable. The type ca be string or 2555 integer. 2556 :param boolean ifexist: If this parameter is set to a truthy value the variable 2557 will only be set if it was defined elsewhere (i.e. used 2558 within the configuration). It is highly recommended to 2559 always set this to true. 2560 :see: :js:func:`AppletHTTP.unset_var` 2561 :see: :js:func:`AppletHTTP.get_var` 2562 2563.. js:function:: AppletHTTP.unset_var(applet, var) 2564 2565 Unset the variable <var>. 2566 2567 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2568 :param string var: The variable name according with the HAProxy variable syntax. 2569 :see: :js:func:`AppletHTTP.set_var` 2570 :see: :js:func:`AppletHTTP.get_var` 2571 2572.. js:function:: AppletHTTP.get_var(applet, var) 2573 2574 Returns data stored in the variable <var> converter in Lua type. 2575 2576 :param class_AppletHTTP applet: An :ref:`applethttp_class` 2577 :param string var: The variable name according with the HAProxy variable syntax. 2578 :see: :js:func:`AppletHTTP.set_var` 2579 :see: :js:func:`AppletHTTP.unset_var` 2580 2581.. _applettcp_class: 2582 2583AppletTCP class 2584=============== 2585 2586.. js:class:: AppletTCP 2587 2588 This class is used with applets that requires the 'tcp' mode. The tcp applet 2589 can be registered with the *core.register_service()* function. They are used 2590 for processing a tcp stream like a server in back of HAProxy. 2591 2592.. js:attribute:: AppletTCP.c 2593 2594 :returns: A :ref:`converters_class` 2595 2596 This attribute contains a Converters class object. 2597 2598.. js:attribute:: AppletTCP.sc 2599 2600 :returns: A :ref:`converters_class` 2601 2602 This attribute contains a Converters class object. The 2603 functions of this object returns always a string. 2604 2605.. js:attribute:: AppletTCP.f 2606 2607 :returns: A :ref:`fetches_class` 2608 2609 This attribute contains a Fetches class object. 2610 2611.. js:attribute:: AppletTCP.sf 2612 2613 :returns: A :ref:`fetches_class` 2614 2615 This attribute contains a Fetches class object. 2616 2617.. js:function:: AppletTCP.getline(applet) 2618 2619 This function returns a string containing one line from the stream. If the 2620 data returned doesn't contains a final '\\n' its assumed than its the last 2621 available data before the end of stream. 2622 2623 :param class_AppletTCP applet: An :ref:`applettcp_class` 2624 :returns: a string. The string can be empty if we reach the end of the stream. 2625 2626.. js:function:: AppletTCP.receive(applet, [size]) 2627 2628 Reads data from the TCP stream, according to the specified read *size*. If the 2629 *size* is missing, the function tries to read all the content of the stream 2630 until the end. 2631 2632 :param class_AppletTCP applet: An :ref:`applettcp_class` 2633 :param integer size: the required read size. 2634 :returns: always return a string,the string can be empty is the connection is 2635 closed. 2636 2637.. js:function:: AppletTCP.send(appletmsg) 2638 2639 Send the message on the stream. 2640 2641 :param class_AppletTCP applet: An :ref:`applettcp_class` 2642 :param string msg: the message to send. 2643 2644.. js:function:: AppletTCP.get_priv(applet) 2645 2646 Return Lua data stored in the current transaction. If no data are stored, 2647 it returns a nil value. 2648 2649 :param class_AppletTCP applet: An :ref:`applettcp_class` 2650 :returns: the opaque data previously stored, or nil if nothing is 2651 available. 2652 :see: :js:func:`AppletTCP.set_priv` 2653 2654.. js:function:: AppletTCP.set_priv(applet, data) 2655 2656 Store any data in the current HAProxy transaction. This action replace the 2657 old stored data. 2658 2659 :param class_AppletTCP applet: An :ref:`applettcp_class` 2660 :param opaque data: The data which is stored in the transaction. 2661 :see: :js:func:`AppletTCP.get_priv` 2662 2663.. js:function:: AppletTCP.set_var(applet, var, value[, ifexist]) 2664 2665 Converts a Lua type in a HAProxy type and stores it in a variable <var>. 2666 2667 :param class_AppletTCP applet: An :ref:`applettcp_class` 2668 :param string var: The variable name according with the HAProxy variable syntax. 2669 :param type value: The value associated to the variable. The type can be string or 2670 integer. 2671 :param boolean ifexist: If this parameter is set to a truthy value the variable 2672 will only be set if it was defined elsewhere (i.e. used 2673 within the configuration). It is highly recommended to 2674 always set this to true. 2675 :see: :js:func:`AppletTCP.unset_var` 2676 :see: :js:func:`AppletTCP.get_var` 2677 2678.. js:function:: AppletTCP.unset_var(applet, var) 2679 2680 Unsets the variable <var>. 2681 2682 :param class_AppletTCP applet: An :ref:`applettcp_class` 2683 :param string var: The variable name according with the HAProxy variable syntax. 2684 :see: :js:func:`AppletTCP.unset_var` 2685 :see: :js:func:`AppletTCP.set_var` 2686 2687.. js:function:: AppletTCP.get_var(applet, var) 2688 2689 Returns data stored in the variable <var> converter in Lua type. 2690 2691 :param class_AppletTCP applet: An :ref:`applettcp_class` 2692 :param string var: The variable name according with the HAProxy variable syntax. 2693 :see: :js:func:`AppletTCP.unset_var` 2694 :see: :js:func:`AppletTCP.set_var` 2695 2696StickTable class 2697================ 2698 2699.. js:class:: StickTable 2700 2701 **context**: task, action, sample-fetch 2702 2703 This class can be used to access the HAProxy stick tables from Lua. 2704 2705.. js:function:: StickTable.info() 2706 2707 Returns stick table attributes as a Lua table. See HAProxy documentation for 2708 "stick-table" for canonical info, or check out example below. 2709 2710 :returns: Lua table 2711 2712 Assume our table has IPv4 key and gpc0 and conn_rate "columns": 2713 2714.. code-block:: lua 2715 2716 { 2717 expire=<int>, # Value in ms 2718 size=<int>, # Maximum table size 2719 used=<int>, # Actual number of entries in table 2720 data={ # Data columns, with types as key, and periods as values 2721 (-1 if type is not rate counter) 2722 conn_rate=<int>, 2723 gpc0=-1 2724 }, 2725 length=<int>, # max string length for string table keys, key length 2726 # otherwise 2727 nopurge=<boolean>, # purge oldest entries when table is full 2728 type="ip" # can be "ip", "ipv6", "integer", "string", "binary" 2729 } 2730 2731.. js:function:: StickTable.lookup(key) 2732 2733 Returns stick table entry for given <key> 2734 2735 :param string key: Stick table key (IP addresses and strings are supported) 2736 :returns: Lua table 2737 2738.. js:function:: StickTable.dump([filter]) 2739 2740 Returns all entries in stick table. An optional filter can be used 2741 to extract entries with specific data values. Filter is a table with valid 2742 comparison operators as keys followed by data type name and value pairs. 2743 Check out the HAProxy docs for "show table" for more details. For the 2744 reference, the supported operators are: 2745 "eq", "ne", "le", "lt", "ge", "gt" 2746 2747 For large tables, execution of this function can take a long time (for 2748 HAProxy standards). That's also true when filter is used, so take care and 2749 measure the impact. 2750 2751 :param table filter: Stick table filter 2752 :returns: Stick table entries (table) 2753 2754 See below for example filter, which contains 4 entries (or comparisons). 2755 (Maximum number of filter entries is 4, defined in the source code) 2756 2757.. code-block:: lua 2758 2759 local filter = { 2760 {"gpc0", "gt", 30}, {"gpc1", "gt", 20}}, {"conn_rate", "le", 10} 2761 } 2762 2763.. _action_class: 2764 2765Action class 2766============= 2767 2768.. js:class:: Act 2769 2770 **context**: action 2771 2772 This class contains all return codes an action may return. It is the lua 2773 equivalent to HAProxy "ACT_RET_*" code. 2774 2775.. code-block:: lua 2776 2777 core.register_action("deny", { "http-req" }, function (txn) 2778 return act.DENY 2779 end) 2780.. 2781.. js:attribute:: act.CONTINUE 2782 2783 This attribute is an integer (0). It instructs HAProxy to continue the current 2784 ruleset processing on the message. It is the default return code for a lua 2785 action. 2786 2787 :returns: integer 2788 2789.. js:attribute:: act.STOP 2790 2791 This attribute is an integer (1). It instructs HAProxy to stop the current 2792 ruleset processing on the message. 2793 2794.. js:attribute:: act.YIELD 2795 2796 This attribute is an integer (2). It instructs HAProxy to temporarily pause 2797 the message processing. It will be resumed later on the same rule. The 2798 corresponding lua script is re-executed for the start. 2799 2800.. js:attribute:: act.ERROR 2801 2802 This attribute is an integer (3). It triggers an internal errors The message 2803 processing is stopped and the transaction is terminated. For HTTP streams, an 2804 HTTP 500 error is returned to the client. 2805 2806 :returns: integer 2807 2808.. js:attribute:: act.DONE 2809 2810 This attribute is an integer (4). It instructs HAProxy to stop the message 2811 processing. 2812 2813 :returns: integer 2814 2815.. js:attribute:: act.DENY 2816 2817 This attribute is an integer (5). It denies the current message. The message 2818 processing is stopped and the transaction is terminated. For HTTP streams, an 2819 HTTP 403 error is returned to the client if the deny is returned during the 2820 request analysis. During the response analysis, an HTTP 502 error is returned 2821 and the server response is discarded. 2822 2823 :returns: integer 2824 2825.. js:attribute:: act.ABORT 2826 2827 This attribute is an integer (6). It aborts the current message. The message 2828 processing is stopped and the transaction is terminated. For HTTP streams, 2829 HAProxy assumes a response was already sent to the client. From the Lua 2830 actions point of view, when this code is used, the transaction is terminated 2831 with no reply. 2832 2833 :returns: integer 2834 2835.. js:attribute:: act.INVALID 2836 2837 This attribute is an integer (7). It triggers an internal errors. The message 2838 processing is stopped and the transaction is terminated. For HTTP streams, an 2839 HTTP 400 error is returned to the client if the error is returned during the 2840 request analysis. During the response analysis, an HTTP 502 error is returned 2841 and the server response is discarded. 2842 2843 :returns: integer 2844 2845.. js:function:: act:wake_time(milliseconds) 2846 2847 **context**: action 2848 2849 Set the script pause timeout to the specified time, defined in 2850 milliseconds. 2851 2852 :param integer milliseconds: the required milliseconds. 2853 2854 This function may be used when a lua action returns `act.YIELD`, to force its 2855 wake-up at most after the specified number of milliseconds. 2856 2857External Lua libraries 2858====================== 2859 2860A lot of useful lua libraries can be found here: 2861 2862* `https://lua-toolbox.com/ <https://lua-toolbox.com/>`_ 2863 2864Redis client library: 2865 2866* `https://github.com/nrk/redis-lua <https://github.com/nrk/redis-lua>`_ 2867 2868This is an example about the usage of the Redis library with HAProxy. Note that 2869each call of any function of this library can throw an error if the socket 2870connection fails. 2871 2872.. code-block:: lua 2873 2874 -- load the redis library 2875 local redis = require("redis"); 2876 2877 function do_something(txn) 2878 2879 -- create and connect new tcp socket 2880 local tcp = core.tcp(); 2881 tcp:settimeout(1); 2882 tcp:connect("127.0.0.1", 6379); 2883 2884 -- use the redis library with this new socket 2885 local client = redis.connect({socket=tcp}); 2886 client:ping(); 2887 2888 end 2889 2890OpenSSL: 2891 2892* `http://mkottman.github.io/luacrypto/index.html 2893 <http://mkottman.github.io/luacrypto/index.html>`_ 2894 2895* `https://github.com/brunoos/luasec/wiki 2896 <https://github.com/brunoos/luasec/wiki>`_ 2897
