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

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 for more information.
• Run HAProxy as a "root" user (not recommended)