Configuration of the blocking page and error code¶
These instructions describe the method to customize the blocking page and error code returned to the client in response to a blocked request.
Configuration methods¶
The blocking page and error code are configured via NGINX directives. The set of directives depends on the reason and method of request blocking:
-
If the request has attack signs and the filtering node operates in blocking mode → directives
wallarm_block_page
andwallarm_block_page_add_dynamic_path
-
If the request is originated from a blocked IP address → directives
wallarm_acl_block_page
andwallarm_block_page_add_dynamic_path
By default, the response code 403 and default NGINX blocking page are returned to the client.
NGINX directives¶
wallarm_block_page¶
The directive wallarm_block_page
lets you set up the response to the request blocked by the filtering node due to detected attack signs.
This directive value should correspond to the following format:
-
Path to the HTM or HTML file and error code (optional)
wallarm_block_page &/<PATH_TO_FILE/HTML_HTM_FILE_NAME> response_code=<CUSTOM_CODE>;
You can use NGINX variables on the blocking page. For this, add the variable name in the format
${variable_name}
to the blocking page code. For example,${remote_addr}
displays the IP address from which the blocked request was originated.Wallarm provides the default blocking page. To use this page, please specify the path
&/usr/share/nginx/html/wallarm_blocked.html
in the directive value.Important information for Debian and CentOS users
If you use an NGINX version lower than 1.11 installed from CentOS/Debian repositories, you should remove the
request_id
variable from the page code to display the dynamic blocking page correctly:
UUID ${request_id}
This applies to both
wallarm_blocked.html
and to the custom block page. -
URL for the client redirection
wallarm_block_page /<REDIRECT_URL>;
-
Named NGINX
location
wallarm_block_page @<NAMED_LOCATION>;
-
Variable and error code (optional)
wallarm_block_page &<VARIABLE_NAME> response_code=<CUSTOM_CODE>;
Initializing the blocking page with NGINX variables in the code
If using this method to set the blocking page with NGINX variables in its code, please initialize this page via the directive
wallarm_block_page_add_dynamic_path
.
The directive wallarm_block_page
can be set inside the http
, server
, location
blocks of the NGINX configuration file.
wallarm_acl_block_page¶
The directive wallarm_acl_block_page
lets you set up the response to the request originated from a blocked IP address.
This directive value has the same format as wallarm_block_page
.
wallarm_block_page_add_dynamic_path¶
The directive wallarm_block_page_add_dynamic_path
is used to initialize the blocking page that has NGINX variables in its code and the path to this blocking page is also set using a variable. Otherwise, the directive is not used.
The directive can be set inside the http
block of the NGINX configuration file.
Configuration examples¶
Below are examples of configuring the blocking page and error code via the directives wallarm_block_page
and wallarm_block_page_add_dynamic_path
. Example settings are applied to requests blocked by the filtering node due to detected attack signs.
When configuring the response to requests originated from blocked IP addresses, please replace the directive wallarm_block_page
with wallarm_acl_block_page
.
Path to the HTM or HTML file with the blocking page and error code¶
This example shows the following response settings:
-
Default Wallarm blocking page and the error code 445
-
Custom blocking page
/usr/share/nginx/html/block.html
and the error code 445
NGINX configuration file¶
wallarm_block_page &/usr/share/nginx/html/wallarm_blocked.html response_code=445;
wallarm_block_page &/usr/share/nginx/html/block.html response_code=445;
-
To apply the settings to the Docker container, the NGINX configuration file with appropriate settings should be mounted to the container. If configuring the custom blocking page, this page should also be mounted to the container. Running the container mounting the configuration file →
-
To apply the settings to Wallarm sidecar container, the directive should be passed in Wallarm ConfigMap (see the instructions for Kubernetes deployment based on Helm charts or Manifests).
Ingress annotations¶
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='&/usr/share/nginx/html/wallarm_blocked.html response_code=445'
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='&/usr/share/nginx/html/block.html response_code=445'
Before adding the Ingress annotation:
- Create ConfigMap from the file
block.html
. -
Mount created ConfigMap to the pod with Wallarm Ingress controller. For this, please update the Deployment object relevant for Wallarm Ingress controller following the instructions.
Directory for mounted ConfigMap
Since existing files in the directory used to mount ConfigMap can be deleted, it is recommended to create a new directory for the files mounted via ConfigMap.
URL for the client redirection¶
This example shows settings to redirect the client to the page host/err445
.
NGINX configuration file¶
wallarm_block_page /err445;
-
To apply the settings to the Docker container, the NGINX configuration file with appropriate settings should be mounted to the container. Running the container mounting the configuration file →
-
To apply the settings to Wallarm sidecar container, the directive should be passed in Wallarm ConfigMap (see the instructions for Kubernetes deployment based on Helm charts or Manifests).
Ingress annotations¶
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='/err445'
Named NGINX location
¶
This example shows settings to return to the client the message The page is blocked
and the error code 445.
NGINX configuration file¶
wallarm_block_page @block;
location @block {
return 445 'The page is blocked';
}
-
To apply the settings to the Docker container, the NGINX configuration file with appropriate settings should be mounted to the container. Running the container mounting the configuration file →
-
To apply the settings to Wallarm sidecar container, the directive should be passed in Wallarm ConfigMap (see the instructions for Kubernetes deployment based on Helm charts or Manifests).
Ingress annotations¶
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/server-snippet="location @block {return 445 'The page is blocked';}"
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='@block'
Variable and error code¶
This example shows settings to return to the client code 445 and different blocking pages depending on the User-Agent
header value:
-
By default, the default Wallarm blocking page
/usr/share/nginx/html/wallarm_blocked.html
is returned. Since NGINX variables are used in the blocking page code, this page should be initialized via the directivewallarm_block_page_add_dynamic_path
. -
For users of Firefox —
/usr/share/nginx/html/block_page_firefox.html
:You are blocked! IP ${remote_addr} Blocked on ${time_iso8601} UUID ${request_id}
Since NGINX variables are used in the blocking page code, this page should be initialized via the directive
wallarm_block_page_add_dynamic_path
. -
For users of Chrome —
/usr/share/nginx/html/block_page_chrome.html
:You are blocked!
Since NGINX variables are NOT used in the blocking page code, this page should NOT be initialized.
NGINX configuration file¶
wallarm_block_page_add_dynamic_path /usr/share/nginx/html/block_page_firefox.html /usr/share/nginx/html/wallarm_blocked.html;
map $http_user_agent $block_page {
"~Firefox" &/usr/share/nginx/html/block_page_firefox.html;
"~Chrome" &/usr/share/nginx/html/block_page_chrome.html;
default &/usr/share/nginx/html/wallarm_blocked.html;
}
wallarm_block_page $block_page response_code=445;
-
To apply the settings to the Docker container, the NGINX configuration file with appropriate settings should be mounted to the container. If configuring the custom blocking page, this page should also be mounted to the container. Running the container mounting the configuration file →
-
To apply the settings to Wallarm sidecar container, the directives should be passed in Wallarm ConfigMap (see the instructions for Kubernetes deployment based on Helm charts or Manifests).
Ingress controller¶
-
Add the following parameter to the
config
object in values.yaml of the cloned Wallarm Helm chart repository:config: { http-snippet: 'wallarm_block_page_add_dynamic_path /usr/test-block-page/blocked.html /usr/share/nginx/html/wallarm_blocked.html; map $http_user_agent $block_page { "~Firefox" &/usr/share/nginx/html/block_page_firefox.html; "~Chrome" &/usr/share/nginx/html/block_page_chrome.html; default &/usr/share/nginx/html/wallarm_blocked.html;}' }
-
Execute the command
helm install
as described in step 4 of the installation instructions. -
Create ConfigMap from the files
block_page_firefox.html
andblock_page_chrome.html
. -
Mount created ConfigMap to the pod with Wallarm Ingress controller. For this, please update the Deployment object relevant for Wallarm Ingress controller following the instructions.
Directory for mounted ConfigMap
Since existing files in the directory used to mount ConfigMap can be deleted, it is recommended to create a new directory for the files mounted via ConfigMap.
-
Add the following annotation to the Ingress:
kubectl annotate ingress <INGRESS_NAME> nginx.ingress.kubernetes.io/wallarm-block-page='$block_page response_code=445'