NGINX App Protect WAF Administration Guide

This guide explains how to deploy NGINX App Protect WAF as well as upgrade App Protect and the App Protect signature sets.

Overview

NGINX App Protect WAF provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10; response inspection; Meta characters check; HTTP protocol compliance; evasion techniques; disallowed file types; JSON & XML well-formedness; sensitive parameters & Data Guard. Refer to Supported Security Policy Features section for more detailed description.

This guide explains how to deploy NGINX App Protect WAF as well as upgrade App Protect and the App Protect signature sets.

Prerequisites

NGINX App Protect WAF is available to customers as a downloadable dynamic module at an additional cost. To purchase or add NGINX App Protect WAF to an existing NGINX Plus subscription, contact the NGINX sales team.

NGINX Plus Release 22 and later supports NGINX App Protect WAF.

NGINX App Protect WAF supports the following operating systems:

CentOS/RHEL 7.4.x and above
RHEL 8.1.x and above
Oracle Linux 8.1.x and above
Amazon Linux 2
Debian 9 - (Deprecated starting from NGINX Plus R24)
Debian 10
Ubuntu 18.04
Ubuntu 20.04
Alpine 3.10 - (Unsupported starting from NGINX Plus R25)

The NGINX App Protect WAF package has 4 dependencies:

nginx-plus-module-appprotect - NGINX Plus dynamic module for App Protect
app-protect-engine - The App Protect enforcement engine
app-protect-plugin - The App Protect connector API between the engine and the NGINX Plus dynamic module
app-protect-compiler - The App Protect enforcement engine compiler agent

See the NGINX Plus full list of prerequisites for more details. NGINX App Protect WAF can be installed as a module to an existing NGINX Plus installation or as a complete NGINX Plus with App Protect installation in a clean environment.

Storage I/O Performance

When deploying App Protect on NGINX Plus take into consideration the performance of storage on which it is going to be installed.
The storage performance may greatly affect the time it takes NGINX Plus to reload whenever there is a configuration change, especially when NGINX App Protect WAF policies are being added or updated.
In order to assess the storage performance you can use a tool called fio. An example of usage follows: (you may need to use sudo):

fio --filename=/opt/tst --size=100MB --direct=1 --rw=randrw --bs=4k --ioengine=libaio --iodepth=256 --runtime=120 --numjobs=4 --time_based --group_reporting --name=iops-test-job --eta-newline=1

The output fields relevant in this context are: read: IOPS= and write: IOPS=.
Below is a table showing how many seconds it takes a reload to complete, when NGINX Plus is reloaded with an updated policy of an average size, in environments of varying I/O performance, and comparable CPU/memory specs:

Read IOPS	Write IOPS	Reload Time
675	678	18
1575	1575	12
13400	13400	8

Platform Security Considerations

When deploying App Protect on NGINX Plus take the following precautions to secure the platform. This avoids the risk of causing a Denial of Service condition or compromising the platform security.

Restrict permissions to the files on the NGINX App Protect WAF platform to user nginx and group nginx, especially for the sensitive areas containing the configuration.
Remove unnecessary remote access services on the platform.
Configure a Syslog destination on the same machine as App Protect and proxy to an external destination. This avoids eavesdropping and man-in-the-middle attacks on the Syslog channel.

User Permissions

If a user other than nginx is to be used, note the following:

If nginx user creation is disallowed on the platform, the following warning may be seen during installation:
```
warning: user nginx does not exist - using root
```
After first installation, upgrade, or security update installation, perform the following steps before starting/restarting/reloading NGINX:
- Modify user permissions on all installed NGINX App Protect WAF files:
```
chown -R <user>:<group> /usr/share/ts /var/log/app_protect /opt/app_protect /etc/app_protect
```
- Modify user of NGINX App Protect WAF processes:
  
  For service startup modify the User in the following files on your platform:
  
  nginx-app-protect.service
  
  For docker deployment, modify the entrypoint.sh script to use the correct user instead of nginx when starting up the bd-socket-plugin process.

CentOS 7.4+ Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the CentOS server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install prerequisite packages:

sudo yum install ca-certificates epel-release wget

Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d:
```
sudo rm /etc/yum.repos.d/nginx-plus-*.repo
```
Add NGINX Plus repository by downloading the file nginx-plus-7.4.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo
```
Add NGINX App Protect WAF repository by downloading the file app-protect-7.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
```
Install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
```
sudo yum install app-protect
```
Alternatively, you can use the following command to list available versions:
```
sudo yum --showduplicates list app-protect
```
Then, install a specific version from the output of command above. For example:
```
sudo yum install app-protect-24+3.639.0
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf file:
```
app_protect_enable on;
```
Configure SELinux as appropriate per your organization’s security policies. NGINX App Protect WAF applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.
Start the NGINX service:
```
sudo systemctl start nginx
```

RHEL 7.4+ Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the RHEL server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.
Install prerequisite packages:
```
sudo yum install ca-certificates wget
```
Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d:
```
sudo rm /etc/yum.repos.d/nginx-plus-*.repo
```
Add NGINX Plus repository by downloading the file nginx-plus-7.4.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo
```
Add NGINX App Protect WAF repository by downloading the file app-protect-7.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
```

Enable Yum repositories to pull App Protect dependencies:

Download the file dependencies.repo to /etc/yum.repos.d:

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

If you have a RHEL subscription:

sudo yum-config-manager --enable rhui-REGION-rhel-server-optional rhui-REGION-rhel-server-releases rhel-7-server-optional-rpms

If you don’t have a RHEL subscription, you can pull the dependencies from the CentOS repository: Create a new repository centos.repo in /etc/yum.repos.d/ with the content:

[centos]
name=CentOS-7
baseurl=http://ftp.heanet.ie/pub/centos/7/os/x86_64/
enabled=1
gpgcheck=1
gpgkey=http://ftp.heanet.ie/pub/centos/7/os/x86_64/RPM-GPG-KEY-CentOS-7

Install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
```
sudo yum install app-protect
```
Alternatively, you can use the following command to list available versions:
```
sudo yum --showduplicates list app-protect
```
Then, install a specific version from the output of command above. For example:
```
sudo yum install app-protect-24+3.639.0
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf file:
```
app_protect_enable on;
```
Configure SELinux as appropriate per your organization’s security policies. App Protect applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.
Start the NGINX service:
```
sudo systemctl start nginx
```

RHEL 8.1+ Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the RHEL server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.
Install prerequisite packages:
```
sudo yum install ca-certificates wget
```
Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d:
```
sudo rm /etc/yum.repos.d/nginx-plus-*.repo
```
Add NGINX Plus repository by downloading the file nginx-plus-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo
```
Add NGINX App Protect WAF repository by downloading the file app-protect-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo
```
Enable Yum repositories to pull App Protect dependencies:

Download the file dependencies.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo
```
Enable codeready-builder repository through subscription manager:
```
sudo subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms
```
Install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
```
sudo yum install app-protect
```
Alternatively, you can use the following command to list available versions:
```
sudo yum --showduplicates list app-protect
```
Then, install a specific version from the output of command above. For example:
```
sudo yum install app-protect-25+3.743.4
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf file:
```
app_protect_enable on;
```
Configure SELinux as appropriate per your organization’s security policies. App Protect applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.
Start the NGINX service:
```
sudo systemctl start nginx
```

Oracle Linux 8.1+ Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Oracle Linux server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install prerequisite packages:

sudo yum install ca-certificates wget yum-utils

Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d:
```
sudo rm /etc/yum.repos.d/nginx-plus-*.repo
```
Add NGINX Plus repository by downloading the file nginx-plus-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo
```
Add NGINX App Protect WAF repository by downloading the file app-protect-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo
```
Enable Yum repositories to pull App Protect dependencies:

Download the file dependencies.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo
```
Enable ol8_codeready_builder repository:
```
sudo yum-config-manager --enable ol8_codeready_builder
```
Install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
```
sudo yum install app-protect
```
Alternatively, you can use the following command to list available versions:
```
sudo yum --showduplicates list app-protect
```
Then, install a specific version from the output of command above. For example:
```
sudo yum install app-protect-26+3.890.0
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf file:
```
app_protect_enable on;
```
Configure SELinux as appropriate per your organization’s security policies. App Protect applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.
Start the NGINX service:
```
sudo systemctl start nginx
```

Amazon Linux 2 LTS Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Amazon Linux server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install prerequisite packages:

sudo amazon-linux-extras enable epel selinux-ng
sudo yum clean metadata
sudo yum install ca-certificates epel-release wget

Remove any previously downloaded NGINX Plus repository file from /etc/yum.repos.d:
```
sudo rm /etc/yum.repos.d/nginx-plus-7.repo
```
Add NGINX Plus repository by downloading the file nginx-plus-7.4.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo
```
Add NGINX App Protect WAF repository by downloading the file app-protect-7.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
```
Install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
```
sudo yum install app-protect
```
Alternatively, you can use the following command to list available versions:
```
sudo yum --showduplicates list app-protect
```
Then, install a specific version from the output of the command above. For example:
```
sudo yum install app-protect-24+3.639.0
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf file:
```
app_protect_enable on; 
```
Configure SELinux as appropriate per your organization’s security policies. NGINX App Protect WAF applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.
Start the NGINX service:
```
sudo systemctl start nginx
```

Debian 9 Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Debian server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install apt utils:

sudo apt-get install apt-transport-https lsb-release ca-certificates wget

Download and add the NGINX signing key:

sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key

Remove any previous NGINX Plus repository and apt configuration files:

sudo rm /etc/apt/sources.list.d/nginx-plus.list
sudo rm /etc/apt/apt.conf.d/90nginx

Add NGINX Plus repository:

printf "deb https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list

Add NGINX App Protect WAF repository:

printf "deb https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):

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

Alternatively, to install a specific version you should modify the repository URL in the /etc/apt/sources.list.d/nginx-plus.list and /etc/apt/sources.list.d/nginx-app-protect.list files in the following way respectively:

deb https://pkgs.nginx.com/plus/Rxx/debian ...

deb https://pkgs.nginx.com/app-protect/Rxx/debian ...

where xx is a release number.

For example, to install the most recent version of the NGINX App Protect WAF for the NGINX Plus R23 make sure of the following:

cat /etc/apt/sources.list.d/nginx-plus.list
deb https://pkgs.nginx.com/plus/R23/debian stretch nginx-plus

cat /etc/apt/sources.list.d/nginx-app-protect.list
deb https://pkgs.nginx.com/plus/R23/debian stretch nginx-plus

Then, use the following commands to update and list available versions:

sudo apt-get update
sudo apt-cache policy app-protect

Finally, install a specific version from the output of command above. For example:

sudo apt-get install -y app-protect-compiler=5.9.4-1~stretch \
app-protect-plugin=3.263.0-1~stretch \
nginx-plus-module-appprotect=23+3.263.0-1~stretch \
app-protect-engine=5.9.4-1~stretch \
app-protect=23+3.263.0-1~stretch

Note:
When installing an older version of NGINX App Protect WAF, the dependent packages have to be installed manually, as shown in the command above. The following script can be used to find out the dependent packages for a specific version of NGINX App Protect WAF.

findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; } 
findDeps app-protect=23+3.263.0-1~stretch

Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf file:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf via:
```
app_protect_enable on;
```
Start the NGINX service:
```
sudo systemctl start nginx
```

Debian 10 Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory and change the directory to the SSL certificate directory after creating the folder:
```
sudo mkdir -p /etc/ssl/nginx
cd /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Debian server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install apt utils:

sudo apt-get update && sudo apt-get install apt-transport-https lsb-release ca-certificates wget gnupg2

Note:
In case the apt installation or database update fails due to release info change, run the below command before you install.

sudo apt-get update --allow-releaseinfo-change

Download and add the NGINX signing key:

sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key

Remove any previous NGINX Plus repository and apt configuration files:

sudo rm /etc/apt/sources.list.d/nginx-plus.list
sudo rm /etc/apt/apt.conf.d/90nginx

Add NGINX Plus repository:

printf "deb https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list

Add NGINX App Protect WAF repository:

printf "deb https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):

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

Alternatively, to install a specific version you should modify the repository URLs in the /etc/apt/sources.list.d/nginx-plus.list and /etc/apt/sources.list.d/nginx-app-protect.list files in the following way respectively:

deb https://pkgs.nginx.com/plus/Rxx/debian ...

deb https://pkgs.nginx.com/app-protect/Rxx/debian ...

where xx is a release number.

For example, to install app-protect version 24 make sure of the following:

cat /etc/apt/sources.list.d/nginx-plus.list
deb https://pkgs.nginx.com/plus/R24/debian buster nginx-plus

cat /etc/apt/sources.list.d/nginx-app-protect.list
deb https://pkgs.nginx.com/app-protect/R24/debian buster nginx-plus

Then, use the following commands to update and list available versions:

sudo apt-get update
sudo apt-cache policy app-protect

Note:
When installing an older version of NGINX App Protect WAF, the dependent packages have to be installed manually, as shown in the command above. The following script can be used to find out the dependent packages for a specific version of NGINX App Protect WAF.

findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; } 
findDeps app-protect=24+3.639.0-1~buster

Finally, install a specific version from the output of command above. For example:

sudo apt-get install -y app-protect-compiler=8.7.4-1~buster \
    app-protect-plugin=3.639.0-1~buster \
    nginx-plus-module-appprotect=24+3.639.0-1~buster\
    app-protect-engine=8.7.4-1~buster \
    app-protect=24+3.639.0-1~buster \
    app-protect-common=8.7.4-1~buster

Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf file:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf via:
```
app_protect_enable on;
```
Start the NGINX service:
```
sudo systemctl start nginx
```

Note:
Debian 10 activates AppArmor by default, but NGINX App Protect WAF will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for NGINX App Protect WAF, you will have to write your own AppArmor profile for NGINX App Protect WAF executables found in /opt/app_protect/bin such that it best suits your environment.

Ubuntu 18.04 Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Ubuntu server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install apt utils:

sudo apt-get update && sudo apt-get install apt-transport-https lsb-release ca-certificates wget gnupg2

Download and add the NGINX signing key:

sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key

Remove any previous NGINX Plus repository and apt configuration files:

sudo rm /etc/apt/sources.list.d/nginx-plus.list
sudo rm /etc/apt/apt.conf.d/90nginx

Add NGINX Plus repository:

printf "deb https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list

Add NGINX App Protect WAF repository:

printf "deb https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):

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

deb https://pkgs.nginx.com/plus/Rxx/ubuntu ...

deb https://pkgs.nginx.com/app-protect/Rxx/ubuntu ...

where xx is a release number.

For example, to install app-protect version 23 make sure of the following:

cat /etc/apt/sources.list.d/nginx-plus.list
deb https://pkgs.nginx.com/plus/R23/ubuntu bionic nginx-plus

cat /etc/apt/sources.list.d/nginx-app-protect.list
deb https://pkgs.nginx.com/app-protect/R23/ubuntu bionic nginx-plus

Then, use the following commands to update and list available versions:

sudo apt-get update
sudo apt-cache policy app-protect

Finally, install a specific version from the output of command above. For example:

sudo apt-get install -y app-protect-compiler=5.9.4-1~bionic \
app-protect-plugin=3.263.0-1~bionic \
nginx-plus-module-appprotect=23+3.263.0-1~bionic \
app-protect-engine=5.9.4-1~bionic \
app-protect=23+3.263.0-1~bionic

Note:
When installing an older version of NGINX App Protect WAF, the dependent packages have to be installed manually, as shown in the command above. The following script can be used to find out the dependent packages for a specific version of NGINX App Protect WAF.

findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; } 
findDeps app-protect=23+3.263.0-1~bionic

Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf file:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf via:
```
app_protect_enable on;
```
Start the NGINX service:
```
sudo systemctl start nginx
```

Ubuntu 20.04 Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Create the /etc/ssl/nginx/ directory:
```
sudo mkdir -p /etc/ssl/nginx
```
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the above two files to the Ubuntu server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

Install apt utils:

sudo apt-get update && sudo apt-get install apt-transport-https lsb-release ca-certificates wget gnupg2

Download and add the NGINX signing key:

sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key

Remove any previous NGINX Plus repository and apt configuration files:

sudo rm /etc/apt/sources.list.d/nginx-plus.list
sudo rm /etc/apt/apt.conf.d/90nginx

Add NGINX Plus repository:

printf "deb https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list

Add NGINX App Protect WAF repository:

printf "deb https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-app-protect.list

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):

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

deb https://pkgs.nginx.com/plus/Rxx/ubuntu ...

deb https://pkgs.nginx.com/app-protect/Rxx/ubuntu ...

where xx is a release number.

For example, to install app-protect version 23 make sure of the following:

cat /etc/apt/sources.list.d/nginx-plus.list
deb https://pkgs.nginx.com/plus/R23/ubuntu focal nginx-plus

cat /etc/apt/sources.list.d/nginx-app-protect.list
deb https://pkgs.nginx.com/app-protect/R23/ubuntu focal nginx-plus

Then, use the following commands to update and list available versions:

sudo apt-get update
sudo apt-cache policy app-protect

Finally, install a specific version from the output of command above. For example:

sudo apt-get install -y app-protect-compiler=5.9.4-1~focal \
app-protect-plugin=3.263.0-1~focal \
nginx-plus-module-appprotect=23+3.263.0-1~focal \
app-protect-engine=5.9.4-1~focal \
app-protect=23+3.263.0-1~focal

Note:
When installing an older version of NGINX App Protect WAF, the dependent packages have to be installed manually, as shown in the command above. The following script can be used to find out the dependent packages for a specific version of NGINX App Protect WAF.

findDeps () { local pkgs=$(apt show $1 2>/dev/null | grep Depends: | grep -oE "(nginx-plus-module|app-protect)-[a-z]+ *\(= *[0-9\+\.-]+~`lsb_release -cs`\)" | tr -d ' ()'); for p in ${pkgs[@]}; do echo $p; findDeps $p; done; } 
findDeps app-protect=23+3.263.0-1~focal

Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf file:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf via:
```
app_protect_enable on;
```
Start the NGINX service:
```
sudo systemctl start nginx
```

Note:
Ubuntu 20.04 activates AppArmor by default, but NGINX App Protect WAF will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for NGINX App Protect WAF, you will have to write your own AppArmor profile for NGINX App Protect WAF executables found in /opt/app_protect/bin such that it best suits your environment.

Alpine 3.10 Installation

If you already have NGINX packages in your system, back up your configs and logs:

sudo cp -a /etc/nginx /etc/nginx-plus-backup
sudo cp -a /var/log/nginx /var/log/nginx-plus-backup

Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Upload nginx-repo.key to /etc/apk/cert.key and nginx-repo.crt to /etc/apk/cert.pem. Make sure that files do not contain other certificates and keys, as Alpine Linux does not support mixing client certificates for different repositories.

Add the NGINX public signing key to the directory /etc/apk/keys:

sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub  https://cs.nginx.com/static/keys/nginx_signing.rsa.pub

Remove any previously configured NGINX Plus repository:
```
sed "/plus-pkgs.nginx.com/d" /etc/apk/repositories
```

Add NGINX Plus repository to /etc/apk/repositories file:

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

Add NGINX App Protect WAF repository to /etc/apk/repositories file:

printf "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

It is recommended to remove all community-supported NGINX packages. Note that all NGINX modules will be removed as well.
```
sudo apk del -r app-protect
sudo apk del -r nginx
```
If you are installing App Protect version 3.3 then also install python3:
```
sudo apk update
sudo apk add python3
```
Update the repository and install the most recent version of the NGINX Plus and NGINX App Protect WAF:
```
sudo apk update
sudo apk add nginx-plus app-protect
```
Alternatively, to install a specific version you should modify the repository URL in the /etc/apk/repositories file in the following way:
```
https://pkgs.nginx.com/plus/Rxx/alpine/v3.10/main
https://pkgs.nginx.com/app-protect/Rxx/alpine/v3.10/main
```
where xx is a release number.

For example, to install NGINX App Protect WAF for NGINX Plus R23 make sure of the following:
```
cat /etc/apk/repositories
https://pkgs.nginx.com/plus/R23/alpine/v3.10/main
https://pkgs.nginx.com/app-protect/R23/alpine/v3.10/main
```
Install the most recent version of NGINX App Protect WAF for NGINX Plus R23:
```
sudo apk update
sudo apk add nginx-plus app-protect
```
Alternatively, use the following commands to list available versions:
```
sudo apk update
sudo apk add nginx-plus app-protect
```
Finally, install a specific version from the output of command above. For example:
```
sudo apk add nginx-plus app-protect=23.3.281.0-r1
```
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
```
sudo nginx -v
```
Load the NGINX App Protect WAF module on the main context in the nginx.conf file:
```
load_module modules/ngx_http_app_protect_module.so;
```
Enable NGINX App Protect WAF on an http/server/location context in the nginx.conf via:
```
app_protect_enable on;
```

Docker Deployment

CentOS 7.4 Docker Deployment Example

# syntax=docker/dockerfile:1
# For CentOS 7:
FROM centos:7.4.1708

# Install prerequisite packages:
RUN yum -y install wget ca-certificates epel-release

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo

# Add NGINX App-protect repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo

# Install NGINX App Protect WAF:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

RHEL UBI7 Docker Deployment Example

# syntax=docker/dockerfile:1
# For RHEL ubi7:
FROM registry.access.redhat.com/ubi7/ubi

ARG RHEL_ORGANIZATION
ARG RHEL_ACTIVATION_KEY

# Install prerequisite packages:
RUN yum -y install wget ca-certificates

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo

# Add NGINX App-protect & dependencies repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo

# Enable Yum repositories to pull App Protect dependencies:
RUN subscription-manager register --org=${RHEL_ORGANIZATION} --activationkey=${RHEL_ACTIVATION_KEY} || true \
    && subscription-manager refresh \
    && subscription-manager attach --auto \
    && yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional rhel-7-server-optional-rpms \
    # You can use either of the dependencies or epel repo
    # && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm \
    && yum clean all

# Install NGINX App Protect WAF:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum \
    && subscription-manager unregister

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

RHEL UBI8 Docker Deployment Example

# syntax=docker/dockerfile:1
# For RHEL ubi8:
FROM registry.access.redhat.com/ubi8/ubi:8.4

ARG RHEL_ORGANIZATION
ARG RHEL_ACTIVATION_KEY

# Install prerequisite packages:
RUN yum -y install wget ca-certificates

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo

# Add NGINX App-protect repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo

# Enable Yum repositories to pull App Protect dependencies:
RUN subscription-manager register --org=${RHEL_ORGANIZATION} --activationkey=${RHEL_ACTIVATION_KEY} || true \
    && subscription-manager refresh \
    && subscription-manager attach --auto \
    && subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms \
    && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \
    # You can use either of the dependencies or epel repo
    # && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm \
    && yum clean all

# Install NGINX App Protect WAF:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum \
    && subscription-manager unregister

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Oracle Linux 8 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Oracle Linux 8:
FROM oraclelinux:8

# Install prerequisite packages:
RUN yum -y install wget ca-certificates yum-utils

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-8.repo

# Add NGINX App-protect repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo

# Enable Yum repositories to pull App Protect dependencies:
RUN yum-config-manager --enable ol8_codeready_builder \
    && wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo \
    # You can use either of the dependencies or epel repo
    # && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm \
    && yum clean all

# Install NGINX App Protect WAF:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Amazon Linux 2 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Amazon Linux 2:
FROM amazonlinux:2

# Install prerequisite packages:
RUN amazon-linux-extras enable epel selinux-ng
RUN yum clean metadata
RUN yum -y install wget ca-certificates epel-release shadow-utils

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.4.repo

# Add NGINX App-protect repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo

# Install NGINX App Protect WAF:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Debian 9 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Debian 9:
FROM debian:stretch

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Add NGINX App-protect repository:
RUN printf "deb https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-app-protect.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Debian 10 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Debian 10:
FROM debian:buster

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://pkgs.nginx.com/plus/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Add NGINX App-protect repository:
RUN printf "deb https://pkgs.nginx.com/app-protect/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-app-protect.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Ubuntu 18.04 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Ubuntu 18.04:
FROM ubuntu:bionic

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Add NGINX App-protect repository:
RUN printf "deb https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-app-protect.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Ubuntu 20.04 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Ubuntu 20.04:
FROM ubuntu:focal

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://pkgs.nginx.com/plus/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Add NGINX App-protect repository:
RUN printf "deb https://pkgs.nginx.com/app-protect/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-app-protect.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && DEBIAN_FRONTEND="noninteractive" apt-get install -y app-protect

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Alpine 3.10 Docker Deployment Example

# syntax=docker/dockerfile:1
# For Alpine 3.10:
FROM alpine:3.10

# Download and add the NGINX signing key:
RUN wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub

# Add NGINX Plus repository:
RUN printf "https://pkgs.nginx.com/plus/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories

# Add NGINX App-protect repository:
RUN printf "https://pkgs.nginx.com/app-protect/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories


# Update the repository and install the most recent version of the NGINX App Protect WAF package (which includes NGINX Plus):
RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \
    apk update && apk add nginx-plus app-protect

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

Docker Deployment Instructions

You need root permissions to execute the following steps.

Create a Dockerfile (see examples above) which copies the following files into the docker image:
- nginx.conf: User defined nginx.conf with app-protect enabled
- entrypoint.sh: Docker startup script which spins up all App Protect processes, must have executable permissions
- custom_log_format.json: Optional user defined app-protect security log format file
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Copy the files to the directory where the Dockerfile is located.

Optionally, create custom_log_format.json in the same directory, for example:

{
    "filter": {
        "request_type": "all"
    },
    "content": {
        "format": "splunk",
        "max_request_size": "any",
        "max_message_size": "10k"
    }
}

In the same directory create an nginx.conf file with the following contents:

user nginx;

worker_processes auto;
load_module modules/ngx_http_app_protect_module.so;

error_log /var/log/nginx/error.log debug;

events {
    worker_connections 10240;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;
    sendfile on;
    keepalive_timeout 65;

    upstream app_backend_com {
        server 192.168.0.1:8000;
        server 192.168.0.1:8001;
    }
    server {
        listen 80;
        server_name app.example.com;
        proxy_http_version 1.1;

        app_protect_enable on;
        app_protect_security_log_enable on;
        app_protect_security_log "/etc/nginx/custom_log_format.json" syslog:server=127.0.0.1:515;

        location / {
            client_max_body_size 0;
            default_type text/html;
            # set your backend here
            proxy_pass http://app_backend_com;
            proxy_set_header Host $host;
        }
    }
}

Important: Make sure to replace upstream and proxy pass directives in this example with relevant application backend settings.

In the same directory create an entrypoint.sh file with executable permissions, and the following content (replace bash with sh for Alpine):

#!/usr/bin/env bash

/bin/su -s /bin/bash -c "/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 2>&1 >> /var/log/app_protect/bd-socket-plugin.log &" nginx
/usr/sbin/nginx -g 'daemon off;'

Create a Docker image:
```
# For CentOS/Oracle Linux/Debian/Ubuntu/Alpine:
DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect .
```
```
# For RHEL:
DOCKER_BUILDKIT=1 docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache --secret id=nginx-crt,src=license/nginx-repo.crt --secret id=nginx-key,src=license/nginx-repo.key -t app-protect .
```
The DOCKER_BUILDKIT=1 enables docker build to recognize the --secret flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (nginx-repo.crt and nginx-repo.key files). More information here.

The --no-cache option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect WAF. If the Dockerfile was previously used to build an image without the --no-cache option, the new image uses versions from the previously built image from the Docker cache.
Verify that the app-protect image was created successfully with the docker images command:
```
docker images app-protect
```
Create a container based on this image, for example, my-app-protect container:
```
docker run --name my-app-protect -p 80:80 -d app-protect
```
Verify that the my-app-protect container is up and running with the docker ps command:
```
docker ps
```

Converter Tool Docker Image

This section explains how to build a Docker image for the purpose of converting policy files from other F5 WAF products to NGINX App Protect WAF JSON declarative format. For more details regarding this feature refer to Converter Tools

CentOS 7.4 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For CentOS 7:
FROM centos:7.4.1708

# Install prerequisite packages:
RUN yum -y install wget ca-certificates epel-release

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect-compiler \
    && yum clean all \
    && rm -rf /var/cache/yum

CMD ["sh"]

RHEL UBI7 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For RHEL ubi7:
FROM registry.redhat.io/ubi7/ubi

ARG RHEL_ORGANIZATION
ARG RHEL_ACTIVATION_KEY

# Install prerequisite packages:
RUN yum -y install wget ca-certificates

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo

# Enable Yum repositories to pull App Protect dependencies:
RUN subscription-manager register --org=${RHEL_ORGANIZATION} --activationkey=${RHEL_ACTIVATION_KEY} \
    && yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional rhel-7-server-optional-rpms \
    && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm \
    && yum clean all

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    yum -y install app-protect-compiler \
    && yum clean all \
    && rm -rf /var/cache/yum \
    && subscription-manager unregister

CMD ["sh"]

Debian 9 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For Debian 9:
FROM debian:stretch

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect-compiler
    
CMD ["sh"]

Debian 10 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For Debian 10:
FROM debian:buster

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect-compiler

CMD ["sh"]

Ubuntu 18.04 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For Ubuntu 18.04:
FROM ubuntu:bionic

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect-compiler

CMD ["sh"]

Ubuntu 20.04 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For Ubuntu 20.04:
FROM ubuntu:focal

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/ssl/nginx/nginx-repo.crt,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/ssl/nginx/nginx-repo.key,mode=0644 \
    apt-get update && apt-get install -y app-protect-compiler

CMD ["sh"]

Alpine 3.10 Converter Docker Deployment Example

# syntax=docker/dockerfile:1
# For Alpine 3.10:
FROM alpine:3.10

# Download and add the NGINX signing key:
RUN wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub

# Add NGINX Plus repository:
RUN printf "https://plus-pkgs.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories

# Update the repository and install the most recent version of the NGINX App Protect WAF Compiler package:
RUN --mount=type=secret,id=nginx-crt,dst=/etc/apk/cert.pem,mode=0644 \
    --mount=type=secret,id=nginx-key,dst=/etc/apk/cert.key,mode=0644 \
    apk update && apk add app-protect-compiler

CMD ["sh"]

Converter Docker Deployment Instructions

You need root permissions to execute the following steps.

Create a Dockerfile (see examples above).
Log in to the Customer Portal and download the following two files:
```
nginx-repo.key
nginx-repo.crt
```
Create a Docker image:
```
# For CentOS/Debian/Ubuntu/Alpine:
DOCKER_BUILDKIT=1 docker build --no-cache --secret id=nginx-crt,src=nginx-repo.crt --secret id=nginx-key,src=nginx-repo.key -t app-protect-converter .
```
```
# For RHEL:
DOCKER_BUILDKIT=1 docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache --secret id=nginx-crt,src=license/nginx-repo.crt --secret id=nginx-key,src=license/nginx-repo.key -t app-protect-converter .
```
The DOCKER_BUILDKIT=1 enables docker build to recognize the --secret flag which allows the user to pass secret information to be used in the Dockerfile for building docker images in a safe way that will not end up stored in the final image. This is a recommended practice for the handling of the certificate and private key for NGINX repository access (nginx-repo.crt and nginx-repo.key files). More information here.

The --no-cache option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect WAF. If the Dockerfile was previously used to build an image without the --no-cache option, the new image uses versions from the previously built image from the Docker cache.
Create a temporary folder and copy your XML policy file(s) to it:
```
mkdir /tmp/converter
cp policy.xml /tmp/converter/
```

Run the docker image with the temporary folder as a mounted volume on the container, and run the policy converter script:

docker run -v /tmp/convert:/tmp/convert app-protect-converter /opt/app_protect/bin/convert-policy -i /tmp/convert/policy.xml -o /tmp/convert/policy.json | jq

Output:

{
    "completed_successfully": true,
    "file_size": 20604,
    "warnings": [
        "Default header '*-bin' cannot be deleted.",
        "Traffic Learning, Policy Building, and staging are unsupported",
        "/general/enableEventCorrelation must be '0' (was '1').",
        "Element '/websocket-urls' is unsupported.",
        "/signature-sets/learn value 1 is unsupported",
        "Element '/redirection-protection' is unsupported.",
        "/protocolIndependent must be '1' (was '0').",
        "Element '/gwt-profiles' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_ASM_COOKIE_HIJACKING' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_BLOCKING_CONDITION' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_BRUTE_FORCE' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_CONVICTION' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_CROSS_ORIGIN_REQUEST' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_CSRF' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_CSRF_EXPIRED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_DYNAMIC_SESSION' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_FLOW' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_FLOW_DISALLOWED_INPUT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_FLOW_ENTRY_POINT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_FLOW_MANDATORY_PARAMS' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_GEOLOCATION' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_GWT_FORMAT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_GWT_MALFORMED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_HOSTNAME_MISMATCH' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_LOGIN_URL_BYPASSED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_LOGIN_URL_EXPIRED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_MALICIOUS_DEVICE' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_MALICIOUS_IP' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_PARAMETER_DYNAMIC_VALUE' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_PLAINTEXT_FORMAT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_REDIRECT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_SESSION_AWARENESS' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_VIRUS' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BAD_REQUEST' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BINARY_MESSAGE_LENGTH' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BINARY_MESSAGE_NOT_ALLOWED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_EXTENSION' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAMES_PER_MESSAGE_COUNT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAME_LENGTH' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAME_MASKING' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAMING_PROTOCOL' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_TEXT_MESSAGE_NOT_ALLOWED' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_TEXT_NULL_VALUE' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_XML_SCHEMA' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_XML_SOAP_ATTACHMENT' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_XML_SOAP_METHOD' is unsupported.",
        "/blocking-settings/violations/name value 'VIOL_XML_WEB_SERVICES_SECURITY' is unsupported.",
        "/blocking-settings/http-protocols/description value 'Unparsable request content' is unsupported.",
        "Element '/plain-text-profiles' is unsupported."
    ],
    "filename": "/tmp/convert/policy-ubuntu.json"
}

Once completed, the newly exported JSON policy file should reside in the same folder as the source XML policy file:

ls -l /tmp/convert/
total 848
-rw-r--r-- 1 root root  20604 Dec 20 12:33 policy.json    # Exported JSON policy file
-rw-r--r-- 1 root root 841818 Dec 20 11:10 policy.xml     # Original XML policy file

Offline Installation

To perform an offline installation of NGINX App Protect WAF you can use a host with access to the NGINX repository to download all the packages (including dependencies) to your local repository.

Example Deployment for CentOS/RHEL

Add the NGINX App Protect WAF Packages to an Internal Repository

On a host with access to the NGINX App Protect WAF repository:

Install the downloadonly plugin for Yum:
```
yum -y install yum-plugin-downloadonly
```

Download all NGINX App Protect WAF packages, including all dependencies:

 mkdir -p /etc/packages/
 yum install --downloadonly --downloaddir=/etc/packages/ app-protect

Download the epel-release dependency package:

For CentOS:

 yum install --downloadonly --downloaddir=/etc/packages/ epel-release

For RHEL 7:

 wget -P /etc/packages https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm

For RHEL 8.1+ / Oracle Linux 8.1+:

 wget -P /etc/packages https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

Add the packages in /etc/packages to your local repository.

Install NGINX App Protect WAF from an Internal Repository

On an offline host:

Add your internal repository configuration.
Install NGINX App Protect WAF:
```
yum -y install app-protect
```

Example Deployment for Debian/Ubuntu

Add the NGINX App Protect WAF Packages to an Internal Repository

On a host with access to the NGINX App Protect WAF repository:

Download all NGINX App Protect WAF packages, including all dependencies:

 mkdir -p /etc/packages/
 cd /etc/packages/
 apt-get update
 for i in $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances app-protect | grep "^\w" | sort -u); do apt-get download $i 2>>errors.txt; done

Add the packages in /etc/packages to your local repository.

Install NGINX App Protect WAF from an Internal Repository

On an offline host:

Add your internal repository configuration.

Install NGINX App Protect WAF:

apt-get update
apt-get install -y app-protect

Post-Installation Checks

You can run the following commands to ensure that NGINX App Protect WAF enforcement is operational.

Check that the three processes needed for NGINX App Protect WAF are running using ps aux:

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

USER       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 that there are no NGINX errors in the /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:

Request:
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]

In case your policy includes JSON/XML profiles, please check /var/log/app_protect/bd-socket-plugin.log and make sure there aren’t any errors by running:
```
grep '|ERR' /var/log/app_protect/bd-socket-plugin.log
```
If you see an error similar to:
```
... Cannot allocate 196744 more bytes for XML parser. current memory size 307089520 (in bytes) ...
```
Increase the bd-socket-plugin process command line variable total_xml_memory in the startup.sh script or in the nginx-app-protect.service file.

The NGINX App Protect’s unit file can be modified with the following command:
```
sudo systemctl edit --full nginx-app-protect.service
```
The file itself is located at /lib/systemd/system/ in deb packages, at /usr/lib/systemd/system/ in rpm packages.

The number 471859200 should be enough for most use cases, you may need to use a bigger number if the number of profiles is large, or large json/xml schemas are used in the policy.
If there are additional problems, refer to the Troubleshooting Guide.

Updating App Protect Attack Signatures

Attack Signatures updates are released at higher frequency than App Protect, therefore they are released in their own package, separate from the App Protect package. You can update the attack signatures without updating the App Protect release, and conversely, you can update App Protect without changing the attack signature package, unless you move to a new NGINX Plus release.

Attack Signatures Package

The attack signature package is named: app-protect-attack-signatures. The version number for this package reflects the date the package was released. The format is: YYYY.MM.DD where:

YYYY is the 4-digit year
MM is the month
DD is the day in the month

Example: 2020.03.31

Compatibility with NGINX Plus Releases

A signature update package is compatible with the NGINX Plus release supported during the time the signature package was released and with all future releases from that point in time on. In other words, it is not compatible with earlier App Protect releases. Those older releases are not supported at this point in time so you will have to upgrade App Protect to benefit from the support which includes Attack Signature updates.

Installing Attack Signature Update

The App Protect installation comes with a built-in Attack Signature package that is not necessarily the most recent one and even if you have the most up to date Attack Signatures installed, updates are released every month or two, so you might want to update your Signatures from time to time. You can upgrade the signatures by updating the package any time after installing App Protect. We recommend you upgrade to the latest signature version right after installing App Protect.

After having updated the Attack Signature package you have to reload the configuration in order for the new version of the Signatures to take effect. Until then App Protect will run with the old version. That is useful when creating an environment with a specific tested version of the Attack Signatures.

CentOS / RHEL 7.4+ / Amazon Linux 2

To add NGINX App Protect WAF Security Updates repository, download the file app-protect-7.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
```

Update attack signatures:

sudo yum install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo yum --showduplicates list app-protect-attack-signatures

To upgrade to a specific version:

sudo yum install app-protect-attack-signatures-2020.04.30

To downgrade to a specific version:

sudo yum downgrade app-protect-attack-signatures-2019.07.16

RHEL 8.1+ / Oracle Linux 8.1+

To add NGINX App Protect WAF Security Updates repository, download the file app-protect-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo
```

Update attack signatures:

sudo yum install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo yum --showduplicates list app-protect-attack-signatures

To upgrade to a specific version:

sudo yum install app-protect-attack-signatures-2021.12.30

To downgrade to a specific version:

sudo yum downgrade app-protect-attack-signatures-2019.07.16

Debian 9

Add NGINX App Protect WAF Security Updates repository:

printf "deb https://pkgs.nginx.com/app-protect-security-updates/debian/ `lsb_release -cs` nginx-plus\n" | sudo tee -a /etc/apt/sources.list.d/nginx-app-protect.list

Download and add the NGINX App Protect WAF signatures signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update attack signatures:

sudo apt-get update && sudo apt-get install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-attack-signatures

Install a specific version:

sudo apt-get install app-protect-attack-signatures=2020.04.30-1~stretch

Debian 10

Add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF signatures signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update attack signatures:

sudo apt-get update && sudo apt-get install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-attack-signatures

Install a specific version:

sudo apt-get install app-protect-attack-signatures=2020.04.30-1~buster

Ubuntu 18.04

Add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF signatures signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update attack signatures:

sudo apt-get update && sudo apt-get install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-attack-signatures

Install a specific version:

sudo apt-get install app-protect-attack-signatures=2020.07.16-1~bionic

Ubuntu 20.04

Add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF signatures signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update attack signatures:

sudo apt-get update && sudo apt-get install app-protect-attack-signatures

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-attack-signatures

Install a specific version:

sudo apt-get install app-protect-attack-signatures=2020.07.16-1~focal

Alpine 3.10

Add NGINX App Protect WAF Security Updates repository:

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

Download and add the NGINX App Protect WAF signatures 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

Update attack signatures:

sudo apk update && sudo apk add app-protect-attack-signatures

To install a specific version, list the available versions:

sudo apk search app-protect-attack-signatures

Install a specific version:

sudo apk add app-protect-attack-signatures=2020.12.28-r1

Attack Signatures when Upgrading App Protect

Upgrading App Protect does not install new Attack Signatures. You will get the same Attack Signature release after upgrading App Protect. If you want to also upgrade the Attack Signatures, you will have to explicitly update them by the respective command above.

Updating App Protect Threat Campaigns

The Threat Campaigns feature is described here.

The Threat campaigns package is named: app-protect-threat-campaigns. The version number for this package reflects the date the package was released. The format is: YYYY.MM.DD where:

YYYY is the 4-digit year
MM is the month
DD is the day in the month

Example: 2020.03.31

Compatibility with NGINX Plus Releases

A threat campaign package is compatible with the NGINX Plus release supported during the time the threat campaign package was released and with all future releases from that point in time on. In other words, it is not compatible with earlier App Protect releases. Those older releases are not supported at this point in time so you will have to upgrade App Protect to benefit from the support which includes Threat campaigns updates.

Installing Threat Campaigns Update

The App Protect installation does not come with a built-in Threat campaigns package like Attack Signatures. Threat campaigns Updates are released periodically whenever new campaigns and vectors are discovered, so you might want to update your Threat campaigns from time to time. You can upgrade the Threat campaigns by updating the package any time after installing App Protect. We recommend you upgrade to the latest Threat campaigns version right after installing App Protect.

After having updated the Threat campaigns package you have to reload the configuration in order for the new version of the Threat campaigns to take effect. Until then App Protect will run with the old version, if one exists. This is useful when creating an environment with a specific tested version of the Threat campaigns.

CentOS / RHEL 7.4+ / Amazon Linux 2

If not already configured, add NGINX App Protect WAF Security Updates repository by downloading the file app-protect-7.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-7.repo
```

Update Threat campaigns:

sudo yum install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo yum --showduplicates list app-protect-threat-campaigns

To upgrade to a specific version:

sudo yum install app-protect-threat-campaigns-2020.06.25

RHEL 8.1+ / Oracle Linux 8.1+

If not already configured, add NGINX App Protect WAF Security Updates repository by downloading the file app-protect-8.repo to /etc/yum.repos.d:
```
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-8.repo
```

Update Threat campaigns:

sudo yum install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo yum --showduplicates list app-protect-threat-campaigns

To upgrade to a specific version:

sudo yum install app-protect-threat-campaigns-2022.01.03

Debian 9

If not already configured, add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF Threat Campaigns signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update Threat campaigns:

sudo apt-get update && sudo apt-get install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-threat-campaigns

Install a specific version:

sudo apt-get install app-protect-threat-campaigns=2020.06.25-1~stretch

Debian 10

If not already configured, add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF Threat Campaigns signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update Threat campaigns:

sudo apt-get update && sudo apt-get install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-threat-campaigns

Install a specific version:

sudo apt-get install app-protect-threat-campaigns=2020.06.25-1~buster

Ubuntu 18.04

If not already configured, add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF Threat Campaigns signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update Threat campaigns:

sudo apt-get update && sudo apt-get install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-threat-campaigns

Install a specific version:

sudo apt-get install app-protect-threat-campaigns=2020.08.05-1~bionic

Ubuntu 20.04

If not already configured, add NGINX App Protect WAF Security Updates repository:

printf "deb 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

Download and add the NGINX App Protect WAF Threat Campaigns signing key:

sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key

Download the apt configuration to /etc/apt/apt.conf.d:

sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90pkgs-nginx

Update Threat campaigns:

sudo apt-get update && sudo apt-get install app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo apt-cache policy app-protect-threat-campaigns

Install a specific version:

sudo apt-get install app-protect-threat-campaigns=2020.08.20-1~focal

Alpine 3.10

If not already configured, add NGINX App Protect WAF Security Updates repository:

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

Download and add the NGINX App Protect WAF Threat Campaigns 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

Update Threat Campaigns:

sudo apk update && sudo apk add app-protect-threat-campaigns

To install a specific version, list the available versions:

sudo apk search app-protect-threat-campaigns

Install a specific version:

sudo apk add app-protect-threat-campaigns=2020.12.24-r1

Upgrading App Protect

You can upgrade to the latest NGINX Plus and App Protect versions by downloading and installing the latest NGINX App Protect WAF package. When upgrading from this package, App Protect will be uninstalled and reinstalled. The old default security policy is deleted and the new default security policy is installed. If you have created a custom security policy, the policy persists and you will need to update nginx.conf and point to the custom security policy by referencing the json file (using the full path).

If you upgrade your NGINX version outside of the App Protect module, App Protect will be uninstalled and you will need to reinstall it. You need to restart NGINX after an upgrade.

After upgrading the NGINX App Protect WAF version, restart NGINX manually:

sudo systemctl restart nginx

SELinux Configuration

The default settings for Security-Enhanced Linux (SELinux) on modern Red Hat Enterprise Linux (RHEL) and related distros can be very strict, erring on the side of security rather than convenience.

Although the App Protect applies its SELinux policy module during installation, your specific configuration might be blocked unless you adjust the policy or modify file labels.

Modifying File Labels

For example, if you plan to store your policy or log configuration files in /etc/policy - you should change the default SELinux file context for this directory:

semanage fcontext -a -t httpd_config_t /etc/policy
restorecon -Rv /etc/policy

Syslog to Custom Port

If you want to send logs to some unreserved port, you can use semanage to add the desired port (here, 35514) to the syslogd_port_t type:

semanage port -a -t syslogd_port_t -p tcp 35514

Review the syslog ports by entering the following command:

semanage port -l | grep syslog

If there are additional problems, refer to the Troubleshooting Guide.

Log Rotate

NGINX App Protect WAF supports log rotation. If you already have logrotate running, NGINX App Protect WAF log files will be rotated automatically according to the configuration file described below. To install logrotate:

For CentOS:

sudo yum install logrotate

For Debian / Ubuntu:

sudo apt-get install logrotate

For Alpine:

sudo apk add logrotate

By default the logrotate configuration file included in NGINX App Protect WAF is:

/var/log/app_protect/*.log {
        size 1M
        copytruncate
        notifempty
        create 644 nginx nginx
        rotate 20
}

size size - log files are rotated only if they grow larger than size.
copytruncate - truncate the original log file in place after creating a copy, instead of moving the old log file and creating a new one.
create mode owner group - the log file is created immediately after rotation with the permissions specified by mode. owner specifies the user name who will own the log file, and group specifies the group the log file will belong to.
rotate count - log files are rotated count times before being removed.

You can modify the attributes and add directories to rotate in /etc/logrotate.d/app_protect.conf.

Normally you would run logrotate periodically using a cron job. For more information about logrotate refer to Linux man page.

All logs in the /var/log/app_protect/ folder will be rotated, including the security log, if the file destination is configured to be under this directory.

Example of configuring security log to be under /var/log/app_protect/:

In /etc/nginx/nginx.conf:

app_protect_security_log_enable on;
app_protect_security_log "/opt/app_protect/share/defaults/log_illegal.json" /var/log/app_protect/security.log;

Note:
The log rotation policy is provided as a default policy. Users can customize to adapt to their need.

This documentation applies to the following versions of NGINX App Protect WAF: 3.11.