--- title: HAProxy module install summary: null url: >- https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/haproxy-module --- ## Requirements - HAProxy 1.7 or higher - [Lua module](https://www.lua.org/download.html) enabled on host - [Next-Gen WAF agent](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/agent-management/getting-started-with-the-agent/) > **HINT:** The HAProxy module can be used with any operating system because it is Lua code. ## Installation Follow these steps to install the HAProxy module. ### Configure the agent > **HINT:** 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 Next-Gen WAF agent configuration to reflect this. The default location of the agent socket file (`/var/run/sigsci.sock`) will be inaccessible to the HAProxy module outside of your specified chroot directory. 1. Create the directory structure for the Unix domain socket by running the following command, replacing `$HAPROXY-CHROOT-DIRECTORY` with your HAProxy chroot directory: ```term copy $ sudo mkdir -p /$HAPROXY-CHROOT-DIRECTORY/var/run/ ``` 2. Add the following line to your agent configuration file (located by default at `/etc/sigsci/agent.conf`) to specify the new socket file location under chroot: ```text rpc-address="unix:/$HAPROXY-CHROOT-DIRECTORY/var/run/sigsci.sock" ``` For example, if the `HAPROXY-CHROOT-DIRECTORY` is set in the `haproxy.conf` as `/var/lib/haproxy` then you would run the command: ```term copy $ sudo mkdir -p /var/lib/haproxy/var/run/ ``` and add the following line to your agent configuration file: ```text rpc-address="unix:/var/lib/haproxy/var/run/sigsci.sock" ``` ### Module installation Install the HAProxy module using a package manager or manually. #### Install with Package Manager The HAProxy module can be installed via the package manager of most major operating system versions: - 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` #### Install manually Alternatively, the HAProxy module can be manually installed. 1. Download the latest version of the HAProxy module from one of our websites: ### Dl.Security.Fastly.Com ```term copy $ wget https://dl.security.fastly.com/sigsci-module-haproxy/sigsci-module-haproxy_latest.tar.gz ``` ### Dl.Signalsciences.Net ```term copy $ wget https://dl.signalsciences.net/sigsci-module-haproxy/sigsci-module-haproxy_latest.tar.gz ``` 2. Create the directory the HAProxy module will be moved to. ```term copy $ sudo mkdir -p /usr/local/lib/lua/5.3/sigsci/ ``` 3. Extract the HAProxy archive to the new directory. ```term copy $ tar xvzf sigsci-module-haproxy_latest.tar.gz -C /usr/local/lib/lua/5.3/sigsci/ ``` ### HAProxy configuration changes After installing the HAProxy module, edit your HAProxy configuration file (located by default at `/etc/haproxy/haproxy.cfg`) to add the following lines: ```text global ... #Signal Sciences lua-load /usr/local/lib/lua/5.3/sigsci/SignalSciences.lua pidfile /var/run/haproxy.pid ... frontend http-in ... #Signal Sciences #Required for buffering request body to ensure inspection is performed #Can also be set in the defaults section option http-buffer-request #Signal Sciences http-request lua.sigsci_prerequest http-response lua.sigsci_postrequest ... ``` #### HAProxy 1.9+ If you are running HAProxy 1.9 or higher, in addition to the HAProxy configuration file edits above, you will also need to add the following line to the `frontend http-in` context: ```text ... # 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 ```text global ... lua-load /path/to/override.lua ... ``` ### Over-ride Directives These directives may be used in your override 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 size in bytes, default: `100000` | | `sigsci.extra\_blocking\_resp\_hdr` | A response header to be added upon 406 responses, default: `""` | ### Example of over-ride configuration ```text sigsci.agenthost = "192.0.2.243" sigsci.agentport = 9090 sigsci.extra_blocking_resp_hdr = "Access-Control-Allow-Origin: https://example.com" ``` ## Upgrading To upgrade the HAProxy module, [download and install](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/haproxy-module/#installation) the latest version of the module. After installing, restart HAProxy for the new module version to be detected. ## Related content - [About module-agent deployment](https://www.fastly.com/documentation/guides/next-gen-waf/setup-and-configuration/module-agent-deployment/about-module-agent-deployment) - [Using an API with the Next-Gen WAF](https://www.fastly.com/documentation/guides/next-gen-waf/developer/using-an-api-with-the-next-gen-waf)