> 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

Before beginning the installation, ensure you have the following:

* **F5 BIG-IP** version 11.5 or higher
* **Public internet access** from the BIG-IP device to communicate with HUMAN cloud services
* **HSSR and HSSR-helper iRules** from [F5 DevCentral](https://clouddocs.f5.com/api/irules/HTTP-Super-SIDEBAND-Requestor-Client-Handles-Redirects-Cookies-Chunked-Transfer-APM-Access-etc.html)
* The following items provided by HUMAN. [Contact us](/applications/human-customer-support) if you have not received these already:
  * The `px.tcl` iRule file
  * The `px-datagroup.txt` configuration template
* Your unique HUMAN credentials:
  * **Application ID** - The HUMAN application ID in the format of `PXxxxxxxxx`. Found in the **Applications** section on the [HUMAN Portal](https://console.humansecurity.com).
  * **Authentication Token** - The JWT token for REST API. Generated in the **Applications** section on the [HUMAN Portal](https://console.humansecurity.com).
  * **Cookie Key** - The key used for cookie signing. Generated in the **Policies** section on the [HUMAN Portal](https://console.humansecurity.com).

## Configuring a virtual server and pool for HUMAN backend requests

> **Note**
>
> The BIG-IP device must have public internet access in order to communicate with the HUMAN cloud services. Make sure to include the proper routing and gateway configuration.

Import the HSSR and HSSR-helper iRules downloaded from [F5 DevCentral](https://clouddocs.f5.com/api/irules/HTTP-Super-SIDEBAND-Requestor-Client-Handles-Redirects-Cookies-Chunked-Transfer-APM-Access-etc.html). These iRules are used for http client communication and TLS/SSL communication with HUMAN backends.

> **Important**
>
> Make sure that the iRule names are: **HSSR** and **HSSR-helper** (corresponding to each rule).

## Configure Data Groups

The HUMAN enforcer configuration is stored in a data group named `pxconfig`. You must create this data group with your HUMAN credentials before the iRule will function.
For multiple appID configuration, the data group name should be `pxconfig_APP_ID` where APP_ID is the app id of the application as configured in the portal.

### Create the Data Group

1. Download the `px-datagroup.txt` file from the enforcer package.
2. Edit the file and replace all instances of `APP_ID` with your HUMAN application ID (e.g., `PXabcd1234`).
3. In the same file, replace `AUTH_TOKEN` with your Authentication Token and `COOKIE_SECRET` with your Cookie Key.

> **Note**
>
> See the [Prerequisites](#prerequisites) section for where to find these credentials in the HUMAN Console.

4. SSH to the F5 instance and run the content of `px-datagroup.txt` in the shell. This will create the `pxconfig` data group for the iRule.

```bash
# Example: Run the data group creation command
create /ltm data-group internal pxconfig type string records add { app_id { data PXabcd1234 } cookie_secret_key { data YOUR_COOKIE_SECRET } auth_token { data YOUR_AUTH_TOKEN } ... }
```

#### Multiple AppID Configuration

In order to configure multiple appIDs on the same F5 instance, repeat the installation steps for each appID, and make sure to replace `APP_ID` with the correct app id in all the configuration steps (data group, pool, virtual server and iRule name).

1. Configure a new data group for each app id with the name `pxconfig_APPID` (for example: `pxconfig_px12345`).
2. For each Virtual Server, create and assign the iRule with the name `px_APPID` (for example: `px_px12345`), paste the content of `px.tcl`.
3. In the iRule, uncomment `RULE_INIT` section and enter your APP_ID in the `set static::APP_ID` directive.

### Basic Configuration Options

The following configuration options are set in the data group:

| Configuration       | Description                                                                                                         | Required          |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------- |
| `app_id`            | Your HUMAN application ID (format: `PXxxxxxxxx`)                                                                    | Yes               |
| `cookie_secret_key` | Cookie hashing secret from HUMAN Console                                                                            | Yes               |
| `auth_token`        | JWT authentication token from HUMAN Console                                                                         | Yes               |
| `module_mode`       | Sets the working mode: `1` = monitor (default, recommended for initial deployment), `2` = blocking (for production) | No (default: `1`) |
| `risk_vs`           | Virtual server for risk API calls (format: `px_backend_{APP_ID}_vip`)                                               | Yes               |

For a complete list of configuration options and how to modify them after installation, see [Configuration Reference](/applications/bigipf5-configuration-properties).

## Configuring Pool: px_backend_pool

1. Under **Local Traffic** > **Pools** > **Pool List**, create a new pool.

2. Set the pool name to: *px_backend_pool*.

3. Set **Health Monitor** to *tcp_half_open*.

4. Select **new FQDN Node**.

5. Set **Node Name** to your app ID.

   > **Note**
   >
   > App ID can be retrieved from the HUMAN portal under Admin->Applications.

6. Set **Address** to *sapi-\<APP_ID>.perimeterx.net*

7. Set the **Service Port** to 443.

8. Set **Auto Populate** to *Enabled*.

9. Click **Add** & **Finished**

## Configuring Virtual Server: px_backend_vip

1. Under **Local Traffic** > **Virtual Servers** > **Virtual Servers List**, create new virtual server.
   This virtual server must have external access for the pool members.

2. Set **Name** to `px_backend_{APP_ID}_vip` (The naming convention is important as the HUMAN iRule uses this vip to send backend requests).

   > **Note**
   >
   > Make sure to replace `{APP_ID}` with the same app ID used in the previous section.

3. Set **Source Address** to 0.0.0.0/0

4. Set **Destination Address/Mask** Set the IP of any node that does not already have an IP assigned to it (for example: 10.0.0.30).

5. Set **Service Port** to a random, not publicly accessible port. (for example: port 55000).

6. Set **HTTP Profile** to http.

7. Configure the SSL Profile (Server) to use *serverssl*.

8. Configure the Source Address Translation to *Auto Map*.

9. Under **Resources** enable the *HSSR-helper* iRule.

10. Set the Default pool to *px_backend_pool*.

## Configuring Activities Report

This step is crucial for the HUMAN iRule to send statistics to HUMAN backend and show data in the portal. In order to send statistics and logs from the HUMAN module in an asynchronous way, we will use Syslog.

> **Note**
>
> HUMAN backends are set to reject any unauthorized IP address, please contact your designated HUMAN Solution Architect to authorize your backends IP address with HUMAN backends.

### Configuring an SSL Server Profile

1. Under `Local Traffic` -> `Profiles` -> `SSL` -> `Server` create a new profile.
2. Set `Name` to `px-syslog-ssl-profile`.
3. Set `Parent Profile` to `serverssl`.
4. Click `Finished`.

### Configuring Pool: px_secure_syslog_pool

1. Under `Local Traffic` -> `Pools` -> `Pool List` create a new pool.
2. Set `Name` to `px_secure_syslog_pool`.
3. Set the node to `New FQDN Node`.
4. Set `Node Name` to `px_activities_node`.
5. Set `FQDN` to `px-fst-syslog.perimeterx.net`.
6. Set `Service Port` to `6514`.
7. Set `Auto Populate` to `Enabled`.
8. Click `Add` and `Finished`.

### Configuring Virtual Server: px_syslog_vs

1. Under `Local Traffic` -> `Virtual Servers` -> `Virtual Servers List`, create new virtual server. This virtual server must have external access for the pool members.
2. Set `Name` to `px_syslog_vs`.
3. Set `Source Address` to 0.0.0.0/0
4. Set `Destination Address/Mask` Set any ip of a node that doesn't exist (for example: 10.0.0.20).
5. Set `Service Port` to 514.
6. Configure the SSL Profile (Server) to use `px-syslog-ssl-profile`.
7. Set `px_secure_syslog_pool` as the Default pool.
8. Click `Finished`.

### Configuring Pool: px_syslog_pool

1. Under `Local Traffic` -> `Pools` -> `Pool List` create a new pool.
2. Set `Name` to `px_syslog_pool`. The naming convention is important as the HUMAN iRule use this vip to send backend requests.
3. Set `Health Monitor` to `tcp_half_open`.
4. Set the node to `New Node`.
5. Set `Node Name` to `px_vs_syslog`.
6. Set `Address` to the same address as the `px_syslog_vs` virtual server (in the example above 10.0.0.20).
7. Set `Service Port` to 514.
8. Click `Add` and `Finished`.

### Configure High Speed Login

1. Under **System** > **Logs** > **Configuration** > **Log Destinations** create a new destination.
2. Set **Name** to *perimeterx_hsl*.
3. Set **Type** to *Remote-High-Speed Log*.
4. Set **Pool Name** to *px_syslog_pool*.
5. Set **Protocol** to *TCP*.
6. Click **Finished**.

### Configure Syslog

1. Under **System** > **Logs** > **Configuration** > **Log Destinations** create a new destination.
2. Set **Name** to *perimeterx_syslog*.
3. Set **Type** to *Remote Syslog*.
4. Set **Syslog Format** to *Syslog*.
5. Set **Forward To** to *perimeterx_hsl*.
6. Click **Finished**.

### Configure Publisher

1. Under **System** > **Logs** > **Configuration** > **Log Publishers** create a new publisher.
2. Set **Name** to *perimeterx-publisher*.
3. Under **Destinations** move **perimeterx_syslog** to *Selected*.
   This will forward the logs to the hsl we previously configured.
4. Click **Finished**.

### Configure Log Filters

1. Under **System** > **Logs** > **Configuration** > **Log Filters** create a new filter.
2. Set **Name** to *perimeterx_filter*.
3. Set **Severity** to *Debug*.
4. Set **Source** to *all*.
5. Set **Message ID** to *01070410* (or any other random number).
6. Under **Log Publisher** select *perimeterx-publisher*.
7. Click **Finished**.

## Configure HUMAN iRule

> **Note**
>
> The `px.tcl` iRule file is provided by HUMAN. If you have not received it, [contact us](/applications/human-customer-support) to request the latest enforcer files.

> **iRule Size Limitation**
>
> F5 BIG-IP has a maximum iRule size of **65,520 bytes (\~64KB)**. If the `px.tcl` file exceeds this limit, you'll receive an error like:
>
> `01070712:3: Max string size exceeded during update of attribute:definition`
>
> **Solution:** Before uploading, minify the iRule by removing comments:
>
> ```bash
> sed '/^[[:space:]]*#/d' px.tcl | cat -s > px-minified.tcl
> ```
>
> Use `px-minified.tcl` instead.

1. Create a new iRule named **px**.
2. Copy the content of `px.tcl` (or `px-minified.tcl` if you minified it) into the **px** iRule.

> **Important**
>
> The iRule reads all configuration values from the `pxconfig` data group that you created earlier. You do not need to modify any values directly in the iRule code.

3. Navigate to the Virtual Server you want to protect with HUMAN.
4. Under **Resources**, add the **px** iRule to the Virtual Server.

## Block Score Configuration

Configuring the block score is done in the [HUMAN Console](https://console.humansecurity.com/botDefender/admin).

The BIGIP F5 Enforcer uses a binary cookie (v2). The binary cookie does not store the score value in the cookie in parsed JSON format.

To set a blocking threshold for the binary cookie:

1. Log into the [HUMAN Console](https://console.humansecurity.com/botDefender/admin).
2. On the Admin tab select **POLICIES**.
3. Select the **Risk Cookie** drop-down menu.
4. Select **Advanced Mode** and press **Continue**.
5. Unselect v1/v3 if selected and select **v2**. The binary score field should become active.
6. Set a value and apply changes.

> **Note**
>
> HUMAN recommendation is to set the blocking threshold to `100`.