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:

$
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 directive. The chroot directive prevents HAProxy Enforcer from accessing remote servers.
• HAProxy must enable threads support. See 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

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:

    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”.

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

Minimal haproxy.cfg example

1
global
2
3
    # Enforcer module could take a few seconds during cold start
4
    tune.lua.session-timeout 10s
5
    tune.lua.service-timeout 10s
6
7
    # load PX HAProxy module, px_core.so file must be present in `/usr/local/lib/lua/` directory
8
    # please edit "px_config.lua" file first to adjust PX module configuration
9
    lua-prepend-path /usr/local/lib/lua/?.so cpath
10
    lua-prepend-path /usr/local/etc/?.lua
11
    lua-load /usr/local/lib/lua/px_haproxy.lua
12
13
14
frontend fe
15
    bind *:80
16
17
    # PX HAProxy module accepts HTTP requests
18
    mode http
19
20
    # let PX module inspect HTTP request
21
    http-request lua.px_handle_request
22
23
    # "txn.px_first_party" variable will be "true" if the request is handled by "first party"
24
    http-request use-service lua.px_handle_first_party if { var(txn.px_first_party) -m bool }
25
    # "txn.px_block" variable will be "true" if the request must be blocked
26
 use_backend px_backend if { var(txn.px_block) -m bool }
27
28
    default_backend backend
29
30
# for "non-blocked" requests
31
backend backend
32
    mode http
33
34
    # append PX headers to outgoing responses
35
    http-response lua.px_handle_response
36
37
    server s1 web-backend-server
38
39
# display PX blocking page for blocked requests
40
# send response for "first party" requests
41
backend px_backend
42
    mode http
43
    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 for more information.
• Run HAProxy as a “root” user (not recommended)