Configuration

This section covers all configuration options available in nFW, including command-line arguments, environment variables, and runtime behavior.

Command-Line Options

Basic Options

-q, –queue-id <id>[:<num>]

Specifies the NFQUEUE ID(s) to listen on.

  • Single queue: -q 0

  • Multiple queues: -q 0:4 (uses queues 0, 1, 2, 3)

The number of queues determines thread count. Each queue is handled by a separate thread.

Examples:

# Single queue
sudo nfw -q 0

# Four queues (0-3) for load balancing
sudo nfw -q 0:4

# Eight queues starting at queue 10
sudo nfw -q 10:8

-v, –verbose

Enable verbose logging output. Shows detailed information about packet processing, protocol detection, and flow management.

sudo nfw -q 0 -v

-h, –help

Display help message with all available options.

nfw --help

-V, –version

Display version information.

nfw --version

-H

Display list of supported nDPI protocols.

nfw -H

Policy Options

-r, –rules <path>

Load policy rules from a JSON file. The file contains pool definitions and policy rules.

sudo nfw -q 0 -r /etc/nfw/policy.json

When using this option, you can reload policies by sending SIGHUP to the nFW process:

sudo kill -HUP $(pidof nfw)

-p, –zmq-policy-endpoint <url>

Subscribe to policy updates from ntopng via ZeroMQ. This enables dynamic policy management through ntopng’s web interface.

sudo nfw -q 0 -p tcp://127.0.0.1:5557

Multiple endpoints are supported for redundancy:

sudo nfw -q 0 -p tcp://127.0.0.1:5557 -p tcp://10.0.0.1:5557

Flow Export Options

-z, –zmq-flow-endpoint <url>

Send flow data to ntopng via ZeroMQ. This is typically required for monitoring and visualization.

sudo nfw -q 0 -z tcp://127.0.0.1:1234

Multiple endpoints are supported to send flows to multiple ntopng instances:

sudo nfw -q 0 -z tcp://192.168.1.10:1234 -z tcp://192.168.1.20:1234

-j, –json

Export flows in JSON format instead of the default TLV (Type-Length-Value) format.

sudo nfw -q 0 -z tcp://127.0.0.1:1234 -j

Note: TLV format is more compact and efficient. Use JSON only if required for debugging or custom integrations.

-f, –flush

Flush flows immediately over ZMQ without batching. This reduces latency but may increase overhead.

sudo nfw -q 0 -z tcp://127.0.0.1:1234 -f

-u, –flow-update <seconds>

Set the interval (in seconds) for periodic flow updates. Default is 30 seconds.

# Update flows every 10 seconds
sudo nfw -q 0 -z tcp://127.0.0.1:1234 -u 10

Range: 3-120 seconds

-y, –zmq-encryption-key <key>

Enable ZeroMQ CURVE encryption for secure flow export. Provide the server’s public key.

sudo nfw -q 0 -z tcp://127.0.0.1:1234 -y "server-public-key"

Connection Tracking Options

-s, –skip-ct-reset

Skip conntrack initialization at startup. By default, nFW:

  • Enables conntrack accounting

  • Enables conntrack timestamps

  • Flushes nfacct counters

Use this option if these settings are already configured or managed externally.

sudo nfw -q 0 -s

License Options

–show-system-id

Display the system ID used for license generation.

nfw --show-system-id

–check-license

Check the validity of the installed license.

nfw --check-license

–check-maintenance

Check the maintenance expiration date.

nfw --check-maintenance

Configuration Files

License File

Locations (checked in order):

  1. nfw.license (current directory)

  2. /etc/nfw.license

Format: Binary license file provided by ntop.org

Policy File

Location: Specified with -r option

Format: JSON (newline-delimited JSON objects)

Example: /etc/nfw/policy.json

See Policy Rules for detailed policy file format.

Runtime Configuration

Signals

nFW responds to POSIX signals:

SIGINT / SIGTERM

Gracefully shutdown nFW:

sudo kill -TERM $(pidof nfw)
# or press Ctrl+C

SIGHUP

Reload policy rules from file (only if -r option was used):

sudo kill -HUP $(pidof nfw)

System Settings

nFW requires specific kernel settings for optimal operation:

Conntrack Accounting:

echo 1 | sudo tee /proc/sys/net/netfilter/nf_conntrack_acct

Conntrack Timestamps:

echo 1 | sudo tee /proc/sys/net/netfilter/nf_conntrack_timestamp

Conntrack Table Size (for high connection counts):

# Increase conntrack table size
echo 262144 | sudo tee /proc/sys/net/netfilter/nf_conntrack_max

Conntrack Timeouts (adjust as needed):

# TCP established timeout (default: 5 days)
echo 3600 | sudo tee /proc/sys/net/netfilter/nf_conntrack_tcp_timeout_established

Make these settings persistent by adding them to /etc/sysctl.conf:

net.netfilter.nf_conntrack_acct=1
net.netfilter.nf_conntrack_timestamp=1
net.netfilter.nf_conntrack_max=262144
net.netfilter.nf_conntrack_tcp_timeout_established=3600

Common Configuration Examples

Standalone with Static Policy

sudo nfw -q 0 -r /etc/nfw/policy.json -v

Integrated with ntopng

# On ntopng host
sudo ntopng -i tcp://0.0.0.0:5556c --zmq-publish-events tcp://0.0.0.0:5557

# On nFW host
sudo nfw -q 0 -z tcp://ntopng-server:5556 -p tcp://ntopng-server:5557

Multi-Queue for Performance

# Configure 8 queues
sudo nfw -q 0:8 -z tcp://127.0.0.1:1234 -u 15

Bridge Mode with Policy File

# Set up bridge
sudo /usr/share/nfw/scripts/bridge_setup.sh eth0 eth1

# Start nFW
sudo nfw -q 0 -r /etc/nfw/policy.json -z tcp://127.0.0.1:1234

Multiple ntopng Collectors

sudo nfw -q 0 \
  -z tcp://ntopng1.local:5556 \
  -z tcp://ntopng2.local:5556 \
  -p tcp://ntopng1.local:5557

Encrypted Flow Export

sudo nfw -q 0 \
  -z tcp://remote-ntopng:5556 \
  -y "Yne@$w-vo<fVvi]a<NY6T1ed:M$fCG*[IaLV{hID" \
  -p tcp://remote-ntopng:5557

Performance Tuning

For high-traffic environments:

Multi-Queue Setup:

# Use one queue per CPU core
sudo nfw -q 0:$(nproc) -z tcp://127.0.0.1:1234 -u 10

Optimize Flow Updates:

# Reduce update interval for real-time monitoring
sudo nfw -q 0 -z tcp://127.0.0.1:1234 -u 5

# Increase update interval for high-volume environments
sudo nfw -q 0 -z tcp://127.0.0.1:1234 -u 60

CPU Affinity:

# Pin to specific CPU cores
sudo taskset -c 0-3 nfw -q 0:4 -z tcp://127.0.0.1:1234

Next Steps