Directives
This topic describes the global NGINX directives and directives specific to F5 WAF for NGINX.
Global configuration consists of a series of nginx.conf directives at the http context controlling aspects that are not specific to a specific application. When applied to a cluster, all cluster members will get the same globals.
The URL in a request determines whether or not it will be inspected by F5 WAF for NGINX. This is defined by app_protect_enable and app_protect_policy_file directives in the location scope.
In the case that the URL itself has violations such as bad unescape or illegal metacharacter, the request may be assigned to a location in which F5 WAF for NGINX is disabled or has a relaxed policy that does not detect these violations.
Such malicious requests will be allowed without inspection.
In order to avoid this, it is recommended to have a basic policy enabled at the http scope or at least at the server scope to process malicious requests in a more complete manner.
| Name | Syntax | Description | Default |
|---|---|---|---|
| app_protect_physical_memory_util_thresholds | app_protect_physical_memory_util_thresholds high=<number_0-100> low=<number_0-100> | Sets the physical memory utilization thresholds for entering (high) and exiting (low) failure mode. When the high threshold is exceeded the system enters failure mode until memory drops below the low threshold. Setting the value of 100 disables this feature. | high=low=100 (disabled) |
| app_protect_cpu_thresholds | app_protect_cpu_thresholds high=<number_0-100> low=<number_0-100> | Sets the CPU utilization thresholds for entering and exiting failure mode respectively: when the high threshold is exceeded the system enters failure mode until CPU drops below the low threshold. Setting the value of 100 disables this feature. Note: The system does not enter failure mode during policy compilation after reload even if the threshold is exceeded. |
high=low=100 (disabled) |
| app_protect_failure_mode_action | app_protect_failure_mode_action pass | drop | How to handle requests when the F5 WAF for NGINX Enforcer cannot process them, either because it is down, disconnected or because of excessive CPU or memory utilization. There are two values:
|
pass |
| app_protect_cookie_seed | app_protect_cookie_seed |
A long randomized string that serves to generate the encryption key for the cookies generated by F5 WAF for NGINX. The string should contain only alphanumeric characters and be no longer than 1000 characters. | Auto-generated random string |
| app_protect_compressed_requests_action | app_protect_compressed_requests_action pass | drop | Determines how to handle compressed requests. There are two values:
nginx.conf file. |
drop |
| app_protect_request_buffer_overflow_action | app_protect_request_buffer_overflow_action pass | drop | Determines how to handle requests in case the NGINX request buffer is full and requests cannot be buffered anymore. There are two values:
|
pass |
| app_protect_user_defined_signatures | app_protect_user_defined_signatures |
Imports the user-defined tagged signature file with the respective tag name from the provided path. Multiple instances of this directive are supported. In order to import multiple signatures files, each file must have a different tag. | N/A |
| app_protect_reconnect_period_seconds | app_protect_reconnect_period_seconds Value type: number with decimal fraction Value Range: 0-60. 0 is illegal |
Determines the period of time between reconnect retries of the module to the web application firewall (WAF) engine. The time unit is seconds. | 5 |
| Name | Syntax | Functionality | Contexts | Example |
|---|---|---|---|---|
| load_module | load_module <library_file_path> | NGINX directive to load the F5 WAF for NGINX module. It must be invoked with the F5 WAF for NGINX library path | Global | load_module modules/ngx_http_app_protect_module.so |
| app_protect_enable | app_protect_enable on | off | Whether to enable F5 WAF for NGINX at the respective context. If not present, inherits from the parent context | HTTP, Server, Location | app_protect_enable on |
| app_protect_policy_file | app_protect_policy_file <file_path> | Set a F5 WAF for NGINX policy configuring behavior for the respective context. | HTTP, Server, Location | app_protect_policy_file /config/waf/strict_policy.json |
| app_protect_security_log_enable | app_protect_security_log_enable on | off | Whether to enable the F5 WAF for NGINX per-request log at the respective context. | HTTP, Server, Location | app_protect_security_log_enable on |
| app_protect_security_log | app_protect_security_log <file_path> |
Specifies the per-request logging: what to log and where | HTTP, Server, Location | app_protect_security_log /config/waf/log_illegal.json syslog:localhost:522 |
| app_protect_custom_log_attribute | app_protect_custom_log_attribute <key_value> | Specifies the assigned location/server/http dimension of each request. | HTTP, Server, Location | app_protect_custom_log_attribute ‘environment’ ’env1' |
F5 WAF for NGINX can be deployed in multiple instances that share the traffic to the same applications.
In this case, all instances must share the same configuration files.
It is your responsibility to synchronize the files on all instances. You must also load balancing each of those instances, such as using additional NGINX instances.
When deploying multiple scalability instances add the app_protect_cookie_seed directive to nginx.conf in the http block:
...
http {
...
app_protect_cookie_seed jkldsf90upiokasdj120;
...
server {
listen 80;
...
}
...The argument for the directive should be a random alphanumeric string of at least 20 characters length (Maximum 1000 characters).
This is a seed used by F5 WAF for NGINX to generate the encryption key for the cookies it creates. These cookies are used for various purposes such as validating the integrity of the cookies generated by the application.
In the absence of this directive, F5 WAF for NGINX generates a random string by itself. In that case, each instance will have a different seed.
A cookie created and encrypted on one instance of F5 WAF for NGINX will fail to be decrypted when sent by the same client to another F5 WAF for NGINX instance having a different encryption key.
If the F5 WAF for NGINX daemons are down or disconnected from the NGINX workers, there are two modes of operation until they are up and connected again:
- Pass the traffic without inspection. Use this when preferring availability over security. This mode is also known as “fail open”.
- Drop the traffic. Use this when preferring security over availability. This mode is also known as “fail closed”.
The default is to pass, fail open, but you can control this using the app_protect_failure_mode_action directive with one argument with two possible values: “pass” or “fail” for the two above options.
This directive is also placed in the http block of the nginx.conf file.
...
http {
...
app_protect_failure_mode_action drop;
...
server {
listen 80;
...
}
...From F5 WAF for NGINX release version 4.6, the
app_protect_compressed_requests_actiondirective was removed deprecated from the nginx configuration.When configuring this directive in the
nginx.conffile, F5 WAF for NGINX will disregard any previously used values (“pass” or “drop”) and issue a warning.
By default, the enforcer will now decompress all the HTTP compressed payload request and will apply the enforcment.
The supported compression algorithms for this feature are “gzip” and “deflate”.
Decompression may fail under certain conditions:
- If the compression method is not supported
- If the ‘Content-Encoding’ header does not match the compression algorithm used while sending a compressed payload in a HTTP request
- If thehe decompressed request is larger than 10 MB
If it does exceed this limit, F5 WAF for NGINX will only decompress the first 10 KB, ignoring the remainder, and trigger the VIOL_REQUEST_MAX_LENGTH violation, just as it would for an uncompressed request that exceeds 10 MB.
In the cases where decompression fails, F5 WAF for NGINX will continue with the scan in the same manner as it does for uncompressed requests.