Configuring Native Node with the All-in-One Installer or Docker Image¶
When deploying the self-hosted Wallarm Native Node using the all-in-one installer or the Docker image, you create the .yaml
configuration file. In this file, you can specify node configiration, all the parameters for that are described in this document.
To modify the settings after the node is running using the all-in-one installer:
-
Update the
/opt/wallarm/etc/wallarm/go-node.yaml
file. The initial configuration file is copied to this path during installation. -
Restart the Wallarm service to apply changes:
If the node is deployed using a Docker image, it is recommended to update the configuration file on the host machine and restart the Docker container with the updated file.
mode (required)¶
The Wallarm node operation mode. It can be:
-
connector-server
for MuleSoft, Cloudflare or Amazon CloudFront connectors. -
tcp-capture
for TCP traffic mirror analysis.
If you installed the Native Node for a Wallarm connector, the basic configuration looks as follows:
version: 2
mode: connector-server
connector:
address: ":5050"
tls_cert: path/to/tls-cert.crt
tls_key: path/to/tls-key.key
blocking: true
allowed_networks:
- 0.0.0.0/0
allowed_hosts:
- w.com
- "*.test.com"
mesh:
discovery: dns
name: go-node-mesh-discovery
port: 9093
route_config:
wallarm_application: 10
wallarm_mode: monitoring
routes:
- route: /example/api/v1
wallarm_mode: off
- route: /example/extra_api
wallarm_application: 2
- route: /example/testing
wallarm_mode: off
log:
pretty: true
level: debug
log_file: stderr
access_log:
enabled: true
verbose: true
log_file: stderr
If you installed the Native Node for TCP traffic mirror analysis, the basic configuration looks as follows:
version: 2
mode: tcp-capture
goreplay:
filter: <your network interface and port, e.g. 'lo:' or 'enp7s0:'>
extra_args:
- -input-raw-engine
- vxlan
path: /opt/wallarm/usr/bin/gor
http_inspector:
real_ip_header: "X-Real-IP"
middleware:
parse_responses: true
response_timeout: 5s
route_config:
wallarm_application: 10
wallarm_mode: monitoring
routes:
- route: /example/api/v1
wallarm_mode: off
- route: /example/extra_api
wallarm_application: 2
- route: /example/testing
wallarm_mode: off
log:
pretty: true
level: debug
log_file: stderr
access_log:
enabled: true
verbose: true
log_file: stderr
Connector-specific settings¶
connector.address (required)¶
Specifies the listening IP address and port separated by a colon (:
).
Ensure the port is not 80
, 8080
, 9000
, or 3313
, as these are used by other Wallarm processes.
connector.tls_cert (required)¶
Path to the TLS/SSL certificate (usually a .crt
or .pem
file) issued for the domain where the node is running.
The certificate must be provided by a trusted Certificate Authority (CA) to ensure secure communication.
If the node is deployed using a Docker image, this parameter is not needed because SSL decryption should occur at the load balancer level, before the traffic reaches the containerized node.
connector.tls_key (required)¶
Path to the private key corresponding to the TLS/SSL certificate (typically a .key
file).
If the node is deployed using a Docker image, this parameter is not needed because SSL decryption should occur at the load balancer level, before the traffic reaches the containerized node.
connector.blocking¶
Typically, you do not need to modify this parameter. Specific blocking behavior for malicious requests is controlled by the wallarm_mode
parameter.
This parameter enables the Native Node's general capability to block incoming requests, whether they are malicious, from denylisted IPs, or any other conditions that require blocking.
Defalt: false
.
connector.allowed_networks¶
A list of IP networks allowed to connect.
Default: 0.0.0.0/0
(all IP networks are allowed).
connector.allowed_hosts¶
A list of allowed hostnames.
Default: all hosts are allowed.
This parameter supports wildcard matching:
-
*
matches any sequence of non-separator characters -
?
matches any single non-separator character -
'[' [ '^' ] { character-range } ']'
Wildcard matching syntax details
// The pattern syntax is:
//
// pattern:
// { term }
// term:
// '*' matches any sequence of non-Separator characters
// '?' matches any single non-Separator character
// '[' [ '^' ] { character-range } ']'
// character class (must be non-empty)
// c matches character c (c != '*', '?', '\\', '[')
// '\\' c matches character c
//
// character-range:
// c matches character c (c != '\\', '-', ']')
// '\\' c matches character c
// lo '-' hi matches character c for lo <= c <= hi
//
// Match requires pattern to match all of name, not just a substring.
For example:
connector.mesh¶
The mesh feature is used in connector-server
mode for Wallarm nodes to ensure consistent traffic processing when multiple node replicas are deployed. It routes requests and their corresponding responses to the same node, even if initially handled by different replicas. This is critical when horizontally scaling, such as with auto-scaling or multiple replicas in ECS.
Kubernetes environments
In Kubernetes, use the Helm chart for native Wallarm node deployment. Mesh is automatically configured when auto-scaling or multiple replicas are detected, with no extra setup needed.
To configure the mesh in ECS:
-
Set up service discovery (e.g., AWS Cloud Map, Google Cloud DNS, or similar services) to allow nodes in the mesh to dynamically find and communicate with each other.
Without service discovery, the mesh will not function properly, as nodes will be unable to locate each other, leading to traffic routing issues.
-
Configure the Wallarm node to use the mesh by specifying the
connector.mesh
parameters in the configuration file as shown below:
discovery¶
Defines how nodes in the mesh discover each other. Currently, only the dns
value is allowed.
Nodes discover each other using DNS. The DNS record must resolve to the IP addresses of all nodes participating in the mesh.
name¶
The DNS domain name used by nodes to resolve the IP addresses of other nodes in the mesh. This is typically set to a value that resolves to all the node instances in the ECS service.
port¶
Specifies the internal port used for communication between nodes in the mesh. This port is not exposed externally and is reserved for node-to-node traffic within the ECS cluster.
TCP mirror-specific settings¶
goreplay.filter¶
Specifies a network interface to capture traffic from. If no value is specified, it captures traffic from all network interfaces on the instance.
The value should be the network interface and port separated by a colon (:
), e.g.:
To capture traffic from multiple interfaces and ports, use goreplay.filter
along with goreplay.extra_args
, e.g.:
version: 2
goreplay:
filter: 'eth0:80'
extra_args:
- "-input-raw"
- "eth0:8080"
- "-input-raw"
- "eth0:8081"
- "-input-raw"
- "eth1:80"
The filter
sets GoReplay with the -input-raw
argument, and extra_args
allows for specifying additional -input-raw
inputs.
To check network interfaces available on the host, run:
goreplay.extra_args¶
This parameter allows you to specify extra arguments to be passed to GoReplay.
-
Typically, you will use it to define the types of mirrored traffic requiring analysis, such as VLAN, VXLAN. For example:
If the mirrored traffic is not wrapped in additional protocols like VLAN or VXLAN, you can omit the
extra_args
configuration. Unencapsulated traffic is parsed by default. -
You can extend
filter
withextra_args
to capture additional interfaces and ports:version: 2 goreplay: filter: 'eth0:80' extra_args: - "-input-raw" - "eth0:8080" - "-input-raw" - "eth0:8081" - "-input-raw" - "eth1:80"
The
filter
sets GoReplay with the-input-raw
argument, andextra_args
allows for specifying additional-input-raw
inputs.
goreplay.path¶
The path to the GoReplay binary file. Typically, you do not need to modify this parameter.
Default: /opt/wallarm/usr/bin/gor
.
http_inspector.real_ip_header¶
By default, Wallarm reads the source IP address from the network packet's IP headers. However, proxies and load balancers can change this to their own IPs.
To preserve the real client IP, these intermediaries often add an HTTP header (e.g., X-Real-IP
, X-Forwarded-For
). The real_ip_header
parameter tells Wallarm which header to use to extract the original client IP.
middleware.parse_responses¶
Controls whether to parse mirrored responses. This enables Wallarm features that rely on response data, such as vulnerability detection and API discovery.
By default, true
.
Ensure response mirroring is configured in your environment to the target instance with the Wallarm node.
middleware.response_timeout¶
Specifies the maximum time to wait for a response. If a response is not received within this time, the Wallarm processes stop waiting the corresponding response.
Default: 5s
.
Basic settings¶
route_config¶
Configuration section where you specify settings for specific routes.
route_config.wallarm_application¶
Wallarm application ID. This value can be overridden for specific routes.
Default: -1
.
route_config.wallarm_mode¶
General traffic filtration mode: block
, safe_blocking
, monitoring
or off
. In OOB mode, traffic blocking is not supported.
The mode can be overridden for specific routes.
Default: monitoring
.
route_config.routes¶
Sets route-specific Wallarm configuration. Includes Wallarm mode and application IDs. Example configuration:
version: 2
route_config:
wallarm_application: 10
wallarm_mode: monitoring
routes:
- host: example.com
wallarm_application: 1
routes:
- route: /app2
wallarm_application: 2
- host: api.example.com
route: /api
wallarm_application: 100
- route: /testing
wallarm_mode: off
host¶
Specifies the route host.
This parameter supports wildcard matching similar to connector.allowed_hosts
.
For example:
routes.route or route¶
Defines specific routes. Routes can be configured with NGINX-like prefixes:
- route: [ = | ~ | ~* | ^~ | ]/location
# | | | | ^ prefix (lower priority than regexes)
# | | | ^ prefix (higher priority than regexes)
# | | ^re case insensitive
# | ^re case sensitive
# ^exact match
For example, to match only the exact route:
To match routes with a regular expression:
wallarm_application¶
Sets the Wallarm application ID. Overrides the route_config.wallarm_application
for specific endpoints.
wallarm_mode¶
Host-specific traffic filtration mode: block
, safe_blocking
, monitoring
or off
. In OOB mode, traffic blocking is not supported.
Default: monitoring
.
log.pretty¶
Controls the error and access log format. Set to true
for human-readable logs, or false
for JSON logs.
Default: true
.
log.level¶
Log level, can be debug
, info
, warn
, error
, fatal
.
Default: info
.
log.log_file¶
Specifies the destination for error log output. Options are stdout
, stderr
, or a path to a log file.
Default: stderr
. However, the node redirects stderr
to the file /opt/wallarm/var/log/wallarm/go-node.log
.
log.access_log.enabled¶
Controls whether to collect access logs.
Default: true
.
log.access_log.verbose¶
Controls whether to include detailed information about each request in the access log output.
Default: true
.
log.access_log.log_file¶
Specifies the destination for access log output. Options are stdout
, stderr
, or a path to a log file.
Default: stderr
. However, the node redirects stderr
to the file /opt/wallarm/var/log/wallarm/go-node.log
.
If not set, the log.log_file
setting is used.
Advanced settings¶
version: 2
http_inspector:
workers: auto
libdetection_enabled: true
api_firewall_enabled: true
api_firewall_database: /opt/wallarm/var/lib/wallarm-api/2/wallarm_api.db
wallarm_dir: /opt/wallarm/etc/wallarm
shm_dir: /tmp
tarantool_exporter:
address: 127.0.0.1:3313
enabled: true
log:
proton_log_mask: info@*
metrics:
enabled: true
listen_address: :9000
legacy_status:
enabled: true
listen_address: 127.0.0.8:80
health_check:
enabled: true
listen_address: :8080
http_inspector.workers¶
Wallarm worker number.
Default: auto
, which means the number of workers is set to the number of CPU cores.
http_inspector.libdetection_enabled¶
Whether to additionally validate the SQL Injection attacks using the libdetection library.
Default: true
.
http_inspector.api_firewall_enabled¶
Controls whether API Specification Enforcement is enabled. Please note that activating this feature does not substitute for the required subscription and configuration through the Wallarm Console UI.
Default: true
.
http_inspector.api_firewall_database¶
Specifies the path to the database containing the API specifications you have uploaded for API Specification Enforcement. This database synchronizes with the Wallarm Cloud.
Typically, you do not need to modify this parameter.
Default: /opt/wallarm/var/lib/wallarm-api/2/wallarm_api.db
.
http_inspector.wallarm_dir¶
Specifies the directory path for node configuration files. Typically, you do not need to modify this parameter. If you need assistance, please contact the Wallarm support team.
Default: /opt/wallarm/etc/wallarm
.
http_inspector.shm_dir¶
HTTP analyzer shared directory. Typically, you do not need to modify this parameter.
Default: /tmp
.
tarantool_exporter.address¶
Sets the address for the postanalytics service which handles statistical request analysis in Wallarm's request processing. Typically, you do not need to modify this parameter.
Default: 127.0.0.1:3313
.
tarantool_exporter.enabled¶
Controls whether the postanalytics service is enabled. This parameter must be set to true
as the Wallarm node does not function without the postanalytics service.
Default: true
.
log.proton_log_mask¶
The mask for internal traffic logging. Typically, you do not need to modify this parameter.
Default: info@*
.
metrics.enabled¶
Controls whether Prometheus metrics are enabled. This parameter must be set to true
as the Wallarm node does not function properly without it.
Default: true
.
metrics.listen_address¶
Sets the address and port where Prometheus metrics will be exposed. To access these metrics, use the /metrics
endpoint.
Default: :9000
(all network interfaces on the port 9000).
metrics.legacy_status.enabled¶
Controls whether the /wallarm-status
metrics service is enabled. This parameter must be set to true
as the Wallarm node does not function properly without it.
Default: true
.
metrics.legacy_status.listen_address¶
Sets the address and port where /wallarm-status
metrics in JSON format will be exposed. To access these metrics, use the /wallarm-status
endpoint.
Default: 127.0.0.8:80
.
health_check.enabled¶
Controls whether health check endpoints are enabled.
Default: true
.
health_check.listen_address¶
Sets the address and port for the /live
and /ready
health check endpoints.
Default: :8080
(all network interfaces on the port 8080).