Deploying with All-in-One Installer¶
An all-in-one installer is designed to streamline and standardize the process of installing Wallarm node as a dynamic module for NGINX in various environments. This installer automatically identifies your operating system’s and NGINX versions, and install all the necessary dependencies.
The all-in-one installer provides a simple node installation process by automatically performing the following actions:
-
Checking your OS and NGINX version.
-
Adding Wallarm repositories for the detected OS and NGINX version.
-
Installing Wallarm packages from these repositories.
-
Connecting the installed Wallarm module to your NGINX.
-
Connecting the filtering node to Wallarm Cloud using the provided token.
Use cases¶
Among all supported Wallarm deployment options, this solution is the recommended one for the following use cases:
-
Your infrastructure is based on bare metal or virtual machines without using container-based methods. Typically, these setups are managed with Infrastructure as Code (IaC) tools like Ansible or SaltStack.
-
Your services are built around NGINX. Wallarm can extend its functionalities using the all-in-one installer.
Requirements¶
-
Access to the account with the Administrator role in Wallarm Console for the US Cloud or EU Cloud.
-
Supported OS:
- Debian 10, 11 and 12.x
- Ubuntu LTS 18.04, 20.04, 22.04
- CentOS 7, 8 Stream, 9 Stream
- Alma/Rocky Linux 9
- RHEL 8.x
- RHEL 9.x
- Oracle Linux 8.x
- Redox
- SuSe Linux
- Others (the list is constantly widening, contact Wallarm support team to check if your OS is in the list)
-
Access to
https://meganode.wallarm.com
to download all-in-one Wallarm installer. Ensure the access is not blocked by a firewall. -
Access to
https://us1.api.wallarm.com
for working with US Wallarm Cloud or tohttps://api.wallarm.com
for working with EU Wallarm Cloud. If access can be configured only via the proxy server, then use the instructions. -
Access to the IP addresses below for downloading updates to attack detection rules and API specifications, as well as retrieving precise IPs for your allowlisted, denylisted, or graylisted countries, regions, or data centers
-
Executing all commands as a superuser (e.g.
root
).
Step 1: Install NGINX and dependencies¶
Install the latest NGINX version of:
-
NGINX
stable
- see how to install it in the NGINX documentation. -
NGINX Mainline (the latest supported version is v1.25.5) - see how to install it in the NGINX documentation.
-
NGINX Plus - see how to install it in the NGINX documentation.
-
Distribution-Provided NGINX - to install, use the following commands:
Step 2: Prepare Wallarm token¶
To install node, you will need a Wallarm token of the appropriate type. To prepare a token:
Step 3: Download all-in-one Wallarm installer¶
Wallarm suggests all-in-one installations for the following processors:
-
x86_64
-
ARM64 (beta)
To download all-in-one Wallarm installation script, execute the command:
Step 4: Run all-in-one Wallarm installer¶
-
Run downloaded script:
# If using the x86_64 version: sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-5.0.3.x86_64-glibc.sh # If using the ARM64 version: sudo env WALLARM_LABELS='group=<GROUP>' sh wallarm-5.0.3.aarch64-glibc.sh
The
WALLARM_LABELS
variable sets group into which the node will be added (used for logical grouping of nodes in the Wallarm Console UI). -
Enter Wallarm token.
Commands in the further steps are the same for x86_64 and ARM64 installations.
Step 5: Enable Wallarm node to analyze traffic¶
By default, the deployed Wallarm node does not analyze incoming traffic.
Depending on the selected Wallarm deployment approach (in-line or Out-of-Band), configure Wallarm to either proxy traffic or process the traffic mirror.
Perform the following configuration in the NGINX configuration file on the machine with the installed node:
-
Set an IP address for Wallarm to proxy legitimate traffic to. It can be an IP of an application instance, load balancer, or DNS name, etc., depending on your architecture.
To do so, edit the
proxy_pass
value, e.g. Wallarm should send legitimate requests tohttp://10.80.0.5
: -
For the Wallarm node to analyze the incoming traffic, set the
wallarm_mode
directive tomonitoring
:The monitoring mode is the recommended one for the first deployment and solution testing. Wallarm provides safe blocking and blocking modes as well, read more.
-
For the Wallarm node to accept mirrored traffic, set the following configuration in the
server
NGINX block:server { listen 80; wallarm_mode monitoring; ... wallarm_force server_addr $http_x_server_addr; wallarm_force server_port $http_x_server_port; # Change 222.222.222.22 to the address of the mirroring server #set_real_ip_from 222.222.222.22; #real_ip_header X-Forwarded-For; #real_ip_recursive on; wallarm_force response_status 0; wallarm_force response_time 0; wallarm_force response_size 0; }
- The
set_real_ip_from
andreal_ip_header
directives are required to have Wallarm Console display the IP addresses of the attackers. - The
wallarm_force_response_*
directives are required to disable analysis of all requests except for copies received from the mirrored traffic.
- The
-
For the Wallarm node to analyze the mirrored traffic, set the
wallarm_mode
directive tomonitoring
:Since malicious requests cannot be blocked, the only mode Wallarm accepts is monitoring. For in-line deployment, there are also safe blocking and blocking modes but even if you set the
wallarm_mode
directive to a value different from monitoring, the node continues to monitor traffic and only record malicious traffic (aside from the mode set to off).
Step 6: Restart NGINX¶
Restart NGINX using the following command:
Step 7: Configure sending traffic to Wallarm node¶
Depending on the deployment approach being used, perform the following settings:
Update targets of your load balancer to send traffic to the Wallarm instance. For details, please refer to the documentation on your load balancer.
Configure your web or proxy server (e.g. NGINX, Envoy) to mirror incoming traffic to the Wallarm node. For configuration details, we recommend to refer to your web or proxy server documentation.
Inside the link, you will find the example configuration for the most popular of web and proxy servers (NGINX, Traefik, Envoy).
Step 8: Test Wallarm node operation¶
-
Send the request with test Path Traversal attack to a protected resource address:
-
Open Wallarm Console → Attacks section in the US Cloud or EU Cloud and make sure the attack is displayed in the list.
Step 9: Fine-tune deployed solution¶
The dynamic Wallarm module with default settings is installed. The filtering node may require some additional configuration after deployment.
Wallarm settings are defined using the NGINX directives or the Wallarm Console UI. Directives should be set in the following files on the machine with the Wallarm node:
-
/etc/nginx/nginx.conf
with NGINX settings -
/etc/nginx/wallarm-status.conf
with Wallarm node monitoring settings. Detailed description is available within the link -
/opt/wallarm/etc/collectd/wallarm-collectd.conf.d/wallarm-tarantool.conf
with the settings for thecollectd
plugin that collects statistics from Tarantool
Below there are a few of the typical settings that you can apply if needed:
-
Using the balancer of the proxy server behind the filtering node
-
Limiting the single request processing time in the directive
wallarm_process_time_limit
-
Limiting the server reply waiting time in the NGINX directive
proxy_read_timeout
-
Limiting the maximum request size in the NGINX directive
client_max_body_size
Launch options¶
As soon as you have the all-in one script downloaded, you can get help on it with:
Which returns:
...
Usage: setup.sh [options]... [arguments]... [filtering/postanalytics]
OPTION DESCRIPTION
-b, --batch Batch mode, non-interactive installation.
--install-only Initiates the first stage of the all-in-one installer in batch mode. Copies essential configurations, including files and binaries, and sets up NGINX for node installation, bypassing Cloud registration and activation. Requires --batch.
--skip-ngx-config Avoids automatic NGINX configuration changes that occur during the --install-only stage in batch mode, suitable for users who prefer manual adjustments later. When used with --install-only, it ensures only essential configurations are copied without altering NGINX settings. Requires --batch.
--register-only Initiates the second stage of the all-in-one installer in batch mode, completing the setup by registering the node in the Cloud and starting its service. Requires --batch.
-t, --token TOKEN Node token, required in a batch mode.
-c, --cloud CLOUD Wallarm Cloud, one of US/EU, default is EU, only used in a batch mode.
-H, --host HOST Wallarm API address, for example, api.wallarm.com or us1.api.wallarm.com, only used in a batch mode.
-P, --port PORT Wallarm API pot, for example, 443.
--no-ssl Disable SSL for Wallarm API access.
--no-verify Disable SSL certificates verification.
-f, --force If there is a node with the same name, create a new instance.
-h, --help
--version
Batch mode¶
The --batch
option triggers batch (non-interactive) mode, where the script requires configuration options via the --token
and --cloud
flags, along with the WALLARM_LABELS
environment variable if needed. In this mode, the script does not prompt the user for data input step by step as in the default mode; instead, it requires explicit commands for interaction.
Below are examples of commands to run the script in batch mode for node installation, assuming the script has already been downloaded:
Separate execution of node installation stages¶
When preparing your own machine image using the all-in-one installer for cloud infrastructure, the standard installation process outlined in this article may not suffice. Instead, you will need to execute specific stages of the all-in-one installer separately to accommodate the requirements of creating and deploying a machine image:
-
Build machine image: At this stage, it is necessary to download binaries, libraries, and configuration files of the filtering node and create a machine image based on them. Utilizing the
--install-only
flag, the script copies the required files and modifies NGINX configurations for node operation. If you wish to make manual adjustments, you can opt to bypass the NGINX file modification by using the--skip-ngx-config
flag. -
Initialize a cloud instance with cloud-init: During instance initialization, the bootstrap phase (cloud registration and service start) can be executed using cloud-init scripts. This stage can be run independently from the build phase by applying the
--register-only
flag to the/opt/wallarm/setup.sh
script copied during the build stage.
This functionality is supported starting from version 4.10.0 of the all-in-one installer in batch mode. The commands below enable the sequential execution of the outlined steps:
# If using the x86_64 version:
curl -O https://meganode.wallarm.com/5.0/wallarm-5.0.3.x86_64-glibc.sh
sudo sh wallarm-5.0.3.x86_64-glibc.sh -- --batch --install-only
sudo env WALLARM_LABELS='group=<GROUP>' /opt/wallarm/setup.sh --batch --register-only -t <TOKEN> -c US
# If using the ARM64 version:
curl -O https://meganode.wallarm.com/5.0/wallarm-5.0.3.aarch64-glibc.sh
sudo sh wallarm-5.0.3.aarch64-glibc.sh -- --batch --install-only
sudo env WALLARM_LABELS='group=<GROUP>' /opt/wallarm/setup.sh --batch --register-only -t <TOKEN> -c US
# If using the x86_64 version:
curl -O https://meganode.wallarm.com/5.0/wallarm-5.0.3.x86_64-glibc.sh
sudo sh wallarm-5.0.3.x86_64-glibc.sh -- --batch --install-only
sudo env WALLARM_LABELS='group=<GROUP>' /opt/wallarm/setup.sh --batch --register-only -t <TOKEN>
# If using the ARM64 version:
curl -O https://meganode.wallarm.com/5.0/wallarm-5.0.3.aarch64-glibc.sh
sudo sh wallarm-5.0.3.aarch64-glibc.sh -- --batch --install-only
sudo env WALLARM_LABELS='group=<GROUP>' /opt/wallarm/setup.sh --batch --register-only -t <TOKEN>
Finally, to complete the installation, you need to enable Wallarm to analyze traffic and restart NGINX.
Separate installation of filtering and postanalytics nodes¶
The filtering/postanalytics switch provides the option to install the postanalytics module separately. Without this switch, both filtering and postanalytics components are installed together by default.
Starting the installation over¶
If you need to delete the Wallarm node installation and start again, follow the steps below.
Impact of starting the installation over
Starting the installation over involves stopping and deleteing already running Wallarm services, thus pausing traffic filtering until reinstallation. Exercise caution in production or critical traffic environments, as this leaves traffic unfiltered and at risk.
To upgrade an existing node (e.g., from 4.10 to 5.0), see the upgrade instructions.
-
Terminate Wallarm processes and remove configuration files:
-
Continue with the reinstallation process by following the setup instructions from the 2nd step.