Virtual machine or bare metal

This page describes how to install F5 WAF for NGINX in a virtual machine or bare metal environment.

Before you begin

To complete this guide, you will need the following prerequisites:

A supported operating system.
A working NGINX Open Source or NGINX Plus instance.
An active F5 WAF for NGINX subscription (Purchased or trial).

Depending on your deployment type, you may have additional requirements:

Docker is required for NGINX Open Source or NGINX Plus type deployments.

You should read the IP intelligence and Secure traffic using mTLS topics for additional set-up configuration if you want to use them immediately.

Security mechanisms like SELinux or AppArmor may potentially block necessary file access for the NGINX process and any component containers.

For more information, view the Configure SELinux topic.

Platform-specific instructions

Navigate to your chosen operating system, which are alphabetically ordered.

Alpine Linux

Add the F5 WAF for NGINX signing key:

sudo wget -O /etc/apk/keys/app-protect-security-updates.rsa.pub https://cs.nginx.com/static/keys/app-protect-security-updates.rsa.pub

Add the F5 WAF for NGINX repository:

shellprintf "https://pkgs.nginx.com/app-protect/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | sudo tee -a /etc/apk/repositories
printf "https://pkgs.nginx.com/app-protect-security-updates/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | sudo tee -a /etc/apk/repositories

Update the repositories, then install the F5 WAF for NGINX package and its dependencies:

shell

sudo apk update
sudo apk add openssl ca-certificates app-protect

Amazon Linux

Add the F5 WAF for NGINX repository:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-amazonlinux2023.repo

Add F5 WAF for NGINX dependencies:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.amazonlinux2023.repo

Install the F5 WAF for NGINX package and its dependencies:

sudo dnf install app-protect

Debian

Add the F5 WAF for NGINX signing key:

shellwget -qO - https://cs.nginx.com/static/keys/app-protect-security-updates.key | gpg --dearmor | \
sudo tee /usr/share/keyrings/app-protect-security-updates.gpg > /dev/null

Add the F5 WAF for NGINX repositories:

shellprintf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | \
sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

printf "deb [signed-by=/usr/share/keyrings/app-protect-security-updates.gpg] \
https://pkgs.nginx.com/app-protect-security-updates/debian `lsb_release -cs` nginx-plus\n" | \
sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list

Update the repositories, then install the F5 WAF for NGINX package and its dependencies:

shell

sudo apt-get update
sudo apt-get install app-protect

Oracle Linux / RHEL / Rocky Linux 8

The steps are identical for these platforms due to their similar architecture.

Add the F5 WAF for NGINX repository:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo

Add F5 WAF for NGINX dependencies:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo

Enable F5 WAF for NGINX dependencies:

sudo dnf config-manager --set-enabled crb

Enable the ol8_codeready_builder repository:

sudo dnf config-manager --set-enabled ol8_codeready_builder

Install the F5 WAF for NGINX package and its dependencies:

sudo dnf install app-protect

RHEL / Rocky Linux 9

Add the F5 WAF for NGINX repository:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-9.repo

Add F5 WAF for NGINX dependencies:

sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo

Enable F5 WAF for NGINX dependencies:

sudo dnf config-manager --set-enabled crb

Install the F5 WAF for NGINX package and its dependencies:

sudo dnf install app-protect

Ubuntu

Add the F5 WAF for NGINX signing key:

shellwget -qO - https://cs.nginx.com/static/keys/app-protect-security-updates.key | \
gpg --dearmor | sudo tee /usr/share/keyrings/app-protect-security-updates.gpg > /dev/null

Add the F5 WAF for NGINX repositories:

shellprintf "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \
https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | \
sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

printf "deb [signed-by=/usr/share/keyrings/app-protect-security-updates.gpg] \
https://pkgs.nginx.com/app-protect-security-updates/ubuntu `lsb_release -cs` nginx-plus\n" | \
sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list

Update the repositories, then install the F5 WAF for NGINX package and its dependencies:

shell

sudo apt-get update
sudo apt-get install app-protect

Update configuration files

Once you have installed F5 WAF for NGINX, you must load it as a module in the main context of your NGINX configuration.

load_module modules/ngx_http_app_protect_module.so;

The Enforcer address must be added at the http context:

app_protect_enforcer_address 127.0.0.1:50000;

And finally, F5 WAF for NGINX can enabled on a http, server or location context:

app_protect_enable on;

You should only enable F5 WAF for NGINX on proxy_pass and grpc_pass locations.

Here are two examples of how these additions could look in configuration files:

nginx.conf
default.conf

The default path for this file is _/etc/nginx/nginx.conf_.

nginxuser  nginx;
worker_processes  auto;

# F5 WAF for NGINX
load_module modules/ngx_http_app_protect_module.so;

error_log  /var/log/nginx/error.log notice;
pid        /var/run/nginx.pid;


events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    # F5 WAF for NGINX
    app_protect_enforcer_address 127.0.0.1:50000;

    include /etc/nginx/conf.d/*.conf;
}

The default path for this file is _/etc/nginx/conf.d/default.conf_.

nginxserver {
    listen 80;
    server_name domain.com;


    location / {

        # F5 WAF for NGINX
        app_protect_enable on;

        client_max_body_size 0;
        default_type text/html;
        proxy_pass http://127.0.0.1:8080/;
    }
}

server {
    listen 8080;
    server_name localhost;


    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
    }

    # redirect server error pages to the static page /50x.html
    #
    error_page 500 502 503 504 /50x.html;
    location = /50x.html {
        root /usr/share/nginx/html;
    }
}

Post-installation checks

The following steps check that F5 WAF for NGINX enforcement is operational.

They should be ran in the environment with the WAF components.

Check that the three processes for F5 WAF for NGINX are running using ps aux:

bd-socket-plugin
nginx: master process
nginx: worker process

shellUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
root         8  1.3  2.4 3486948 399092 ?      Sl   09:11   0:02 /usr/share/ts/bin/bd-socket-plugin tmm_count 4 proc_cpuinfo_cpu_mhz 2000000 total_xml_memory 307200000 total_umu_max_size 3129344 sys_max_account_id 1024 no_static_config
root        14  0.0  0.1  71060 26680 ?        S    09:11   0:00 nginx: master process /usr/sbin/nginx -c /tmp/policy/test_nginx.conf -g daemon off;
root        26  0.0  0.3  99236 52092 ?        S    09:12   0:00 nginx: worker process
root        28  0.0  0.0  11788  2920 pts/0    Ss   09:12   0:00 bash
root        43  0.0  0.0  47460  3412 pts/0    R+   09:14   0:00 ps aux

Verify there are no errors in the file /var/log/nginx/error.log and that the policy compiled successfully:

2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_start", "configSetFile": "/opt/f5waf/config/config_set.json" }
2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT policy 'app_protect_default_policy' from: /etc/app_protect/conf/NginxDefaultPolicy.json compiled successfully
2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_success", "software_version": "1.1.1", "attack_signatures_package":{"revision_datetime":"2019-07-16T12:21:31Z"},"completed_successfully":true}
2020/05/10 13:21:04 [notice] 402#402: using the "epoll" event method
2020/05/10 13:21:04 [notice] 402#402: nginx/1.17.6 (nginx-plus-r20)
2020/05/10 13:21:04 [notice] 402#402: built by gcc 4.8.5 20150623 (Red Hat 4.8.5-36) (GCC)
2020/05/10 13:21:04 [notice] 402#402: OS: Linux 3.10.0-957.27.2.el7.x86_64
2020/05/10 13:21:04 [notice] 402#402: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2020/05/10 13:21:04 [notice] 406#406: start worker processes
2020/05/10 13:21:04 [notice] 406#406: start worker process 407

Check that sending an attack signature in a request returns a response block page containing a support ID:

shellRequest:
http://10.240.185.211/?a=<script>

Response:
The requested URL was rejected. Please consult with your administrator.

Your support ID is: 9847191526422998597

[Go Back]

If your policy includes JSON/XML profiles, check /var/log/app_protect/bd-socket-plugin.log for possible errors:

grep '|ERR' /var/log/app_protect/bd-socket-plugin.log

Verify that Enforcement functionality is working by checking the following request is rejected:

curl "localhost/<script>"

If you notice problems, there are ways to remediate them based on the context:

Description	Solution
NGINX is not running or F5 WAF for NGINX does not behave as expected	Review warning or error messages within the log files
unknown directive app_protect_xxx error message	Ensure F5 WAF for NGINX is loaded as a module in the main context of NGINX configuration.
Too many open files error message	Increase the maximum amount of open files with the worker_rlimit_nofile directive.
setrlimit … failed (Permission denied) error message	Increase the limit by by running the following command as root: `setsebool -P httpd_setrlimit 1`

Next steps

Once you have successfully installed F5 WAF for NGINX, there are some topics you may want to follow afterwards:

Configure NGINX features with F5 WAF, to see common configurations
Configure policies, to begin customizing your deployment
Converter tools, to convert existing resources from a BIG-IP environment
Changelog, to view information from the latest releases

View source

Edit this page

Create a new issue