Using NGINX App Protect WAF with NGINX Controller
Take the steps in this guide to deploy NGINX App Protect WAF as a datapath instance for use with NGINX Controller.
Take the steps in this guide to deploy NGINX App Protect WAF as a datapath instance for use with NGINX Controller.
Note:
Refer to the NGINX Controller Technical Specifications guide to find out which distributions are supported for use with NGINX Controller and NGINX Controller Agent.
Setup
Before proceeding, you should review the Prerequisites, Platform Security Considerations and User Permissions sections of the NGINX App Protect WAF Admin Guide.
Install NGINX App Protect WAF
Note:
If a version of NGINX App Protect WAF prior to 3.6 is required, please contact the NGINX Sales team to assist with this configuration.
CentOS 7.4+
-
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 NGINX Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
See Also:
You can use the NGINX Controller REST API to download the key and cert files. -
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
-
If NGINX Plus or NGINX App Protect WAF was previously installed on the system, clean up package manager cache information:
sudo yum clean all
-
Install NGINX App Protect WAF package
app-protect-25+3.671.0
, which includes NGINX Plus 25 and NGINX App Protect WAF 3.6:
sudo yum install app-protect-25+3.671.0
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
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.
Note:
NGINX Controller has specific requirements regarding SELinux configuration. -
Start the NGINX service:
sudo systemctl start nginx
-
Start the
bd_agent
service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only)
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the bd_agent
:
/bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
Note:
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify thatbd_agent
is running:
ps -ef | grep bd_agent
- To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
Red Hat Enterprise Linux 7.4+
-
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 NGINX 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
-
-
If NGINX Plus or NGINX App Protect WAF was previously installed on the system, clean up package manager cache information:
sudo yum clean all
-
Install NGINX App Protect WAF package
app-protect-25+3.671.0
, which includes NGINX Plus 25 and NGINX App Protect WAF 3.6:sudo yum install app-protect-25+3.671.0
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
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.
Note:
NGINX Controller has specific requirements regarding SELinux configuration. -
Start the NGINX service:
sudo systemctl start nginx
-
Start the
bd_agent
service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only)
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the bd_agent
:
/bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
Note:
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify thatbd_agent
is running:
ps -ef | grep bd_agent
- To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
Debian 9
Note:
As of NGINX Plus R24, support for Debian 9 is no longer available. As a consequence, NGINX App Protect WAF 3.1 is the final version available for this operating system version.
-
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 NGINX 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
-
Add NGINX Plus repository:
printf "deb https://plus-pkgs.nginx.com/R23/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.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/90nginx
-
Update the repository and install NGINX Plus 23 and NGINX App Protect WAF 3.1 packages:
sudo apt-get update sudo apt-get install app-protect-compiler=6.53.1-1~stretch sudo apt-get install app-protect-engine=6.53.1-1~stretch sudo apt-get install app-protect-plugin=3.462.0-1~stretch sudo apt-get install nginx-plus-module-appprotect=23+3.462.0-1~stretch sudo apt-get install app-protect=23+3.462.0-1~stretch
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
Start the NGINX service:
sudo systemctl start nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
-
To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
Debian 10
-
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 NGINX 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 NGINX Plus 25 and NGINX App Protect WAF 3.6 packages:
sudo apt-get update sudo apt-get install app-protect-compiler=8.12.1-1~buster sudo apt-get install app-protect-plugin=3.671.0-1~buster sudo apt-get install app-protect-engine=8.12.1-1~buster sudo apt-get install nginx-plus-module-appprotect=25+3.671.0-1~buster sudo apt-get install app-protect=25+3.671.0-1~buster
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
Start the NGINX service:
sudo systemctl start nginx
-
Start the
bd_agent
service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only)
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start the bd_agent
:
/bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
Note:
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify that thebd_agent
is running:
ps -ef | grep bd_agent
- To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
Ubuntu 18.04
-
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 NGINX 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 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/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 NGINX Plus 25 and NGINX App Protect WAF 3.6 packages:
sudo apt-get update sudo apt-get install app-protect-compiler=8.12.1-1~bionic sudo apt-get install app-protect-plugin=3.671.0-1~bionic sudo apt-get install app-protect-engine=8.12.1-1~bionic sudo apt-get install nginx-plus-module-appprotect=25+3.671.0-1~bionic sudo apt-get install app-protect=25+3.671.0-1~bionic
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
Start the NGINX service:
sudo systemctl start nginx
-
Start the
bd_agent
service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only)
If you plan to use this instance with Controller Agent 3.20.1, you need to start bd_agent
:
/bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
Note:
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify thatbd_agent
is running:
ps -ef | grep bd_agent
- To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
Ubuntu 20.04
-
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 NGINX 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 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/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 NGINX Plus 25 and NGINX App Protect WAF 3.6 packages:
sudo apt-get update sudo apt-get install app-protect-compiler=8.12.1-1~focal sudo apt-get install app-protect-plugin=3.671.0-1~focal sudo apt-get install app-protect-engine=8.12.1-1~focal sudo apt-get install nginx-plus-module-appprotect=25+3.671.0-1~focal sudo apt-get install app-protect=25+3.671.0-1~focal
-
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
-
Start the NGINX service:
sudo systemctl start nginx
-
Start the
bd_agent
service (for Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2 only)
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, you need to start bd_agent
:
/bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx
-
Verify NGINX Plus and BD processes are running:
ps -ef | grep nginx ps -ef | grep bd
Note:
If you plan to use this instance with Controller ADC Agent 3.20.1 or Controller APIM Agent 3.19.2, also verify thatbd_agent
is running:
ps -ef | grep bd_agent
- To upgrade your signature package to the latest version and obtain the best protection, refer to Updating App Protect Attack Signatures.
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.
Amazon Linux 2 LTS
Using NGINX App Protect WAF with NGINX Controller isn’t supported on Amazon Linux 2 LTS.
Alpine
Using NGINX App Protect WAF with NGINX Controller isn’t supported on Alpine.
Add NGINX App Protect WAF to NGINX Controller
If this NGINX Plus instance is already managed by Controller, restart the Agent after NGINX App Protect WAF is installed.
Otherwise, complete the tasks in the NGINX Controller Add an NGINX App Protect WAF Instance guide.
Use NGINX App Protect WAF with NGINX Controller
Note:
When configuring NGINX App Protect WAF as a datapath instance for NGINX Controller, you should not modify thenginx.conf
file. Thenginx.conf
file will be automatically updated when enabling WAF on a Component in NGINX Controller.
Refer to the following NGINX Controller user guides for further information about how to secure your apps and/or APIs with NGINX Controller:
- Learn about App Security for the NGINX Controller App Delivery module
- Add Security to your Apps with the NGINX Controller App Delivery module
- Add Advanced Security (WAF) to your APIs with the NGINX Controller API Management module.
This documentation applies to the following versions of NGINX App Protect WAF: 3.10.