> This page is for Applications Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Installation

## Prerequisites

In order to start HAProxy Enforcer installation, please collect the output of the following two commands and send to your Solution Architect or HUMAN Support:

**`Bash`**

```bash Bash
cat /etc/os-release

haproxy -vv
```

Upon receiving this information, you will receive an archive with HAProxy Enforcer files, built for your system.

Notes:

* HAProxy must be in “HTTP” mode.
* HAProxy must contain LUA support. You can check this by running `haproxy -vv | grep USE_LUA`.
* HAProxy configuration must not include the [`chroot`](https://docs.haproxy.org/2.8/configuration.html#chroot) directive. The `chroot` directive prevents HAProxy Enforcer from accessing remote servers.
* HAProxy must enable threads support. See [Enable threads support](#enable-threads-support) for more information.

## Installation

### Dependencies installation

The following packages are required:

* apr-1
* apr-util-1
* libcurl
* openssl
* jansson
* lua
* pcre

Linux distribution specific installation instructions:

* For Debian/Ubuntu distribution: `apt-get update && apt-get install -y libcurl4 libapr1 libjansson4 libaprutil1 curl libpcre3 liblua5.4`
* For Alpine Linux distribution: `apk add apr-util apr jansson curl pcre lua5.4`

### Adjust `px_config.lua` Enforcer configuration file

Required parameters:

`_M.px_appId` / `_M.auth_token`: Application ID / AppId and Token / Auth Token can be found in the Portal, in the “Applications” section.\
`_M.cookie_secret`: Cookie Encryption Key can be found in the portal, in the “Policies” section.

For other configuration parameteters please see [HAProxy Module Configuration](./configuration)

### Enforcer files installation

From the archive received from HUMAN, extract and copy files:

* `px_haproxy.lua` to `/usr/local/lib/lua/` directory (create `lua` directory if it doesn't exist)
* `px_core.so` file to `/usr/local/lib/lua/` directory
* `px_config.lua` to `/usr/local/etc/` directory

### Modify haproxy.cfg HAProxy configuration file

* Add the following 3 lines to `global` section:

```plaintext
    lua-prepend-path /usr/local/lib/lua/?.so cpath
    lua-prepend-path /usr/local/etc/?.lua
    lua-load /usr/local/lib/lua/px_haproxy.lua
```

* To all frontends with HTTP mode (\`mode http\`) add `use_backend %[lua.px_handle_request]` line to redirect incoming traffic to PX HAProxy module
* Add a new HTTP backend `request_pass`. This backend handles traffic which is marked as "human requests". Add `http-response lua.px_handle_response` line to append PX specific headers to outgoing responses
* Add a new HTTP backend `request_block` with the context below. This backend handles traffic which is marked as "blocked".

```plaintext
backend request_block
    mode http
    # display Enforcer Captcha page
    http-request use-service lua.px_response
```

### Minimal haproxy.cfg example

```undefined
global

    # Enforcer module could take a few seconds during cold start
    tune.lua.session-timeout 10s
    tune.lua.service-timeout 10s

    # load PX HAProxy module, px_core.so file must be present in `/usr/local/lib/lua/` directory
    # please edit "px_config.lua" file first to adjust PX module configuration
    lua-prepend-path /usr/local/lib/lua/?.so cpath
    lua-prepend-path /usr/local/etc/?.lua
    lua-load /usr/local/lib/lua/px_haproxy.lua


frontend fe
    bind *:80

    # PX HAProxy module accepts HTTP requests
    mode http

    # let PX module inspect HTTP request
    http-request lua.px_handle_request

    # "txn.px_first_party" variable will be "true" if the request is handled by "first party"
    http-request use-service lua.px_handle_first_party if { var(txn.px_first_party) -m bool }
    # "txn.px_block" variable will be "true" if the request must be blocked
 use_backend px_backend if { var(txn.px_block) -m bool }

    default_backend backend

# for "non-blocked" requests
backend backend
    mode http

    # append PX headers to outgoing responses
    http-response lua.px_handle_response

    server s1 web-backend-server

# display PX blocking page for blocked requests
# send response for "first party" requests
backend px_backend
    mode http
    http-request use-service lua.px_response
```

## Enable threads support

By default, HAProxy prevents modules from creating new threads. However, PX HAProxy Enforcer spawns several threads while working.

The solution:

* Enable threads creating by adding `insecure-fork-wanted` configuration to HAProxy global section. See HAProxy's [documentation](https://cbonte.github.io/haproxy-dconv/2.2/configuration.html#3.1-insecure-fork-wanted) for more information.
* Run HAProxy as a "root" user (not recommended)