search close

HAProxy Module Install

access_time Updated Jun 20, 2021

Requirements

  • HAProxy 1.7 or higher
  • Lua module enabled on host

Note: The HAProxy module can be used with any OS because it is Lua code.

Installation

Agent configuration changes

Note: This section may not be required for your installation. If you have set HAProxy’s chroot directory, you will need to modify the commands below to reflect your custom chroot directory by following the instructions in this section.

If your HAProxy configuration has been modified to set a chroot directory for HAProxy, you will need to update your Signal Sciences agent configuration to reflect this. The default location of the agent socket file (/var/run/sigsci.sock) will be inaccessible by the HAProxy module outside of your specified chroot directory.

After installing the Signal Sciences agent, you will need to create the directory structure for the Unix domain socket under chroot:

sudo mkdir -p /haproxy-chroot-directory/var/run/

Then, add the following line your agent configuration file (by default at /etc/sigsci/agent.conf) to specify the new socket file location under chroot:

rpc-address="unix:/haproxy-chroot-directory/var/run/sigsci.sock"

Module installation

Installation with Package Manager

The HAProxy module can be easily installed via the package manager of most major OS versions:

OS Command
Alpine
sudo apk add sigsci-module-haproxy
CentOS
sudo yum install sigsci-module-haproxy
Debian
sudo apt-get install sigsci-module-haproxy
Ubuntu
sudo apt-get install sigsci-module-haproxy

Manual Installation

Alternatively, the HAProxy module can also be manually installed.

  1. Download the latest version of the HAProxy module:

     wget https://dl.signalsciences.net/sigsci-module-haproxy/sigsci-module-haproxy_latest.tar.gz
    
  2. After downloading the module .tar.gz archive, create the directory it will be moved to:

     sudo mkdir -p /usr/local/lib/lua/5.3/sigsci/
    
  3. Extract the HAProxy archive to the new directory:

     tar xvzf sigsci-module-haproxy_latest.tar.gz -C /usr/local/lib/lua/5.3/sigsci/
    

HAProxy configuration changes

Now that the module has been unpacked or installed, you will need to edit your HAProxy configuration file (by default at /etc/haproxy/haproxy.cfg) to add the following lines:

global
    ...
    #Signal Sciences
    lua-load /usr/local/lib/lua/5.3/sigsci/SignalSciences.lua
    pidfile /var/run/haproxy.pid
 
    ...

frontend http-in
    ...
    #Signal Sciences
    http-request lua.sigsci_prerequest
    http-response lua.sigsci_postrequest
    ...

HAProxy 1.9+

In addition to the HAProxy configuration file edits above, if you are running HAProxy 1.9 or higher, you will also need to add the following line to the frontend http-in context:

    ...
    # for haproxy-1.9 and above add the following:
    http-request use-service lua.sigsci_send_block if { var(txn.sigsci_block) -m bool }
    ...

Configuration

Configuration changes are typically not required for the HAProxy module to work. However, it is possible to override the default settings if needed. To do so, you must create an override.lua file in which to add these configuration directives. Then, update the global section of your HAProxy config file (/usr/local/etc/haproxy/haproxy.cfg) to load this over-ride config file.

Example of configuration

global
   ...
   lua-load /path/to/override.lua
   ...

Over-ride Directives

These directives may be used in your over-ride config file.

Name Description
sigsci.agenthost The IP address or path to unix domain socket the SignalSciences Agent is listening on, default: “/var/run/sigsci.sock” (unix domain socket).
sigsci.agentport The local port (when using TCP) that the agent listens on, default: nil
sigsci.timeout Agent socket timeout (in seconds), default: 1 (0 means off).
sigsci.maxpost Maximum POST body site in bytes, default: 100000
sigsci.extra_blocking_resp_hdr User may supply a response header to be added upon 406 responses, default: ""

Example of over-ride configuration

sigsci.agenthost = "172.19.0.2"
sigsci.agentport = 9090
sigsci.extra_blocking_resp_hdr = "Access-Control-Allow-Origin: https://my-company.com"

Upgrading

To upgrade the HAProxy module, you will need to download and install the latest version of the module.

After installing, you will need to restart HAProxy for the new module version to be detected.