Advanced Features

This section covers advanced nEdge Lite features and optimization techniques for experienced users.

Multi-Queue Processing

nEdge Lite supports distributing packet processing across multiple CPU cores using multiple NFQUEUE instances.

Configuring Multiple Queues

iptables Configuration:

# Configure 4 queues with CPU fanout
sudo iptables -t mangle -A PREROUTING -j CONNMARK --restore-mark
sudo iptables -t mangle -A PREROUTING -m mark --mark 2 -j DROP
sudo iptables -t mangle -A PREROUTING -m mark --mark 0 \
  -j NFQUEUE --queue-balance 0:3 --queue-cpu-fanout
sudo iptables -t mangle -A POSTROUTING -j CONNMARK --save-mark

Start nEdge Lite:

sudo nedgelite -q 0:4 -z tcp://127.0.0.1:1234

This creates 4 threads, each handling one queue (0, 1, 2, 3).

Performance Benefits

  • Parallel Processing: Distributes packet inspection across CPU cores

  • Higher Throughput: Scales linearly with number of queues (up to available cores)

  • Lower Latency: Reduces per-packet processing time

Optimal Queue Count

Recommended:

# Use number of CPU cores
CORES=$(nproc)
sudo nedgelite -q 0:$CORES -z tcp://127.0.0.1:1234

Considerations:

  • More queues = more threads = higher CPU usage

  • Diminishing returns beyond physical core count

  • Consider hyperthreading and other workloads

CPU Affinity

Pin nEdge Lite threads to specific CPU cores for better cache locality:

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

Performance Optimization

System Tuning

Increase Conntrack Table Size:

# For high connection counts
sudo sysctl -w net.netfilter.nf_conntrack_max=1048576

# Make persistent
echo "net.netfilter.nf_conntrack_max=1048576" | \
  sudo tee -a /etc/sysctl.conf

Adjust Conntrack Timeouts:

# Reduce TCP established timeout
sudo sysctl -w net.netfilter.nf_conntrack_tcp_timeout_established=3600

# Reduce TCP close-wait timeout
sudo sysctl -w net.netfilter.nf_conntrack_tcp_timeout_close_wait=30

Increase NFQUEUE Buffer:

# In iptables rule
sudo iptables -t mangle -A PREROUTING -m mark --mark 0 \
  -j NFQUEUE --queue-num 0 --queue-bypass --queue-size 4096

Memory Management

Monitor Memory Usage:

# Check nEdge Lite memory usage
ps aux | grep nedgelite
pmap $(pidof nedgelite)

Flow Hash Size: The flow hash table is fixed at compile time. For very high flow counts, consider increasing the hash table size in the source code.

IPv6 Support

nEdge Lite supports IPv6 packet inspection alongside IPv4.

Enabling IPv6

The sample scripts described in the Quick Start Guide already support IPv6, it can be enabled by adding the -6 parameter.

Load IPv6 Conntrack Module:

sudo modprobe nf_conntrack_ipv6

Configure ip6tables:

sudo ip6tables -t mangle -A PREROUTING -j CONNMARK --restore-mark
sudo ip6tables -t mangle -A PREROUTING -m mark --mark 2 -j DROP
sudo ip6tables -t mangle -A PREROUTING -m mark --mark 0 -j NFQUEUE --queue-num 0
sudo ip6tables -t mangle -A POSTROUTING -j CONNMARK --save-mark

Start nEdge Lite:

No special options needed. nEdge Lite automatically handles both IPv4 and IPv6.

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

IPv6 Considerations

  • Flow Export: IPv6 flows are exported to ntopng like IPv4

  • Policy Rules: IP pools can include IPv6 CIDR ranges

Custom nDPI Configuration

nDPI supports custom protocol definitions through the nDPI API. Refer to the nDPI documentation for details.

Detection Sensitivity

Some protocols have configurable detection thresholds. These are typically set in nDPI’s protocol-specific detection functions.

Traffic Shaping Integration

While nEdge Lite itself doesn’t perform traffic shaping, it can integrate with Linux tc (traffic control).

Using CONNMARK for tc

nEdge Lite’s CONNMARK values can be used by tc to apply QoS policies:

# Create tc classes
sudo tc qdisc add dev eth0 root handle 1: htb default 30
sudo tc class add dev eth0 parent 1: classid 1:1 htb rate 100mbit
sudo tc class add dev eth0 parent 1:1 classid 1:10 htb rate 80mbit
sudo tc class add dev eth0 parent 1:1 classid 1:20 htb rate 20mbit

# Use connmark to classify traffic
sudo tc filter add dev eth0 parent 1: protocol ip prio 1 \
  handle 1 fw classid 1:10  # High priority (mark=1)

sudo tc filter add dev eth0 parent 1: protocol ip prio 2 \
  handle 2 fw classid 1:20  # Low priority (mark=2)

Connection Labels

In addition to the pass/drop mark, nEdge Lite can tag each connection with conntrack labels (connlabels) describing what nDPI detected: protocols, categories and flow risks. Labels are stored in the conntrack entry, so any iptables rule can match on them with the connlabel match, for example to drop, log or mark traffic of a given application independently of the nEdge Lite policies.

The kernel provides 128 label bits per connection, while nDPI detects several hundred protocols. A label map file selects the protocols, categories and risks of interest and assigns each of them a label bit.

Label Map File

The label map is a text file with one mapping per line; # starts a comment:

<bit> protocol <name|id>                     [<label>]
<bit> category <name|id>                     [<label>]
<bit> risk     <NDPI_xxx code|short name|id> [<label>]
<bit> over                                   [<label>]

  • <bit>: label bit, 0-127.

  • protocol: nDPI protocol name or id (see nedgelite -H). Both the master and the application protocol are matched, so TLS matches TLS.Google too. Unknown matches flows nDPI could not detect.

  • category: nDPI category name or id (e.g. SocialNetwork, Streaming; see nedgelite -H). Names containing spaces (User custom category N) must be given by id.

  • risk: nDPI flow risk, as NDPI_xxx code (e.g. NDPI_TLS_SELFSIGNED_CERTIFICATE), short name (e.g. non_standard_port) or id (see nedgelite -H).

  • over: set on every flow once detection is completed.

  • <label>: optional name of the bit in connlabel.conf. By default it is generated from the first mapping of the bit: NDPI-<PROTOCOL>, NDPI-CAT-<CATEGORY>, NDPI-RISK-<RISK> or NDPI-OVER (uppercase, other characters replaced by -). Labels may only contain letters, digits and - (a connlabel.conf restriction).

Names are case-insensitive. Several mappings can share the same bit: the bit is set when any of them matches. Flows matching no mapping are not labelled (unless over is used). Any error in the file (unknown name, bit out of range, malformed line) is reported with its line number and nEdge Lite does not start.

Example (/etc/nedgelite/labels.conf):

0   over

# Protocols
1   protocol  TLS
2   protocol  QUIC
3   protocol  BitTorrent
4   protocol  Facebook   FB
5   protocol  Instagram
6   protocol  TikTok

# Categories
10  category  SocialNetwork SOCIAL
11  category  Streaming

# Flow risks
20  risk      NDPI_TLS_SELFSIGNED_CERTIFICATE
21  risk      non_standard_port

Enabling Labels

  1. Generate connlabel.conf from the map and install it as /etc/xtables/connlabel.conf, so that iptables and conntrack can refer to labels by name (the /etc/xtables directory usually does not exist and must be created). Repeat this step whenever the map changes.

    nedgelite -L /etc/nedgelite/labels.conf -o /tmp
sudo mkdir -p /etc/xtables
sudo cp /tmp/connlabel.conf /etc/xtables/connlabel.conf

    With the example map above the generated file is:

    0 NDPI-OVER
1 NDPI-TLS
2 NDPI-QUIC
3 NDPI-BITTORRENT
4 FB
5 NDPI-INSTAGRAM
6 NDPI-TIKTOK
10        SOCIAL
11        NDPI-CAT-STREAMING
20        NDPI-RISK-TLS-SELFSIGNED-CERT
21        NDPI-RISK-NON-STANDARD-PORT

    Note

    nftables reads labels from /etc/connlabel.conf instead. When using ct label in nft rules, install the same file there too (e.g. as a symlink to /etc/xtables/connlabel.conf).

  2. Load at least one connlabel rule. The kernel reserves label space only for connections created while a connlabel rule is loaded: without one, labels set by nEdge Lite are silently discarded. The rules must be added after the netfilter setup scripts (bridge_setup.sh and default_setup.sh flush the iptables tables).

    Any rule using the connlabel match is enough, including a match-only rule without a target (the packet continues unchanged):

    sudo modprobe xt_connlabel
sudo iptables -t mangle -I PREROUTING -m connlabel --label NDPI-OVER

    Rules that act on labels can be added as needed, for example:

    # Drop BitTorrent and social network traffic
sudo iptables -A FORWARD -m connlabel --label NDPI-BITTORRENT -j DROP
sudo iptables -A FORWARD -m connlabel --label SOCIAL -j DROP

# Log connections with a self-signed TLS certificate
sudo iptables -A FORWARD -m connlabel --label NDPI-RISK-TLS-SELFSIGNED-CERT \
  -j LOG --log-prefix "self-signed: "

    Connections that already existed when the first connlabel rule was loaded cannot be labelled. Flush the conntrack table to have them recreated (this also resets their pass/drop mark, so they are inspected again):

    sudo conntrack -F

  3. Start nEdge Lite with -L (or --labels=/etc/nedgelite/labels.conf in the configuration file):

    sudo nedgelite -q 0 -L /etc/nedgelite/labels.conf

    When nEdge Lite runs as a systemd service, the setup script is executed at every service start and flushes the label rules. Add them back from a drop-in, whose ExecStartPre commands run after the ones of the service (i.e. after the setup script) and before nEdge Lite starts:

    sudo systemctl edit nedgelite

    [Service]
ExecStartPre=/usr/sbin/iptables -t mangle -I PREROUTING -m connlabel --label NDPI-OVER
ExecStartPre=/usr/sbin/iptables -A FORWARD -m connlabel --label SOCIAL -j DROP

  4. Check the labels assigned to connections:

    sudo conntrack -L -o labels

    Labels are reported by name at the end of each entry, after the mark:

    tcp      6 431996 ESTABLISHED src=192.168.1.20 dst=157.240.231.35 sport=52814 dport=443 packets=42 bytes=6120 src=157.240.231.35 dst=192.168.1.20 sport=443 dport=52814 packets=55 bytes=48211 [ASSURED] mark=1 use=1 labels=NDPI-OVER,NDPI-TLS,FB,SOCIAL
tcp      6 431990 ESTABLISHED src=192.168.1.31 dst=203.0.113.7 sport=40122 dport=8443 packets=12 bytes=1830 src=203.0.113.7 dst=192.168.1.31 sport=8443 dport=40122 packets=10 bytes=4420 [ASSURED] mark=1 use=1 labels=NDPI-OVER,NDPI-TLS,NDPI-RISK-TLS-SELFSIGNED-CERT,NDPI-RISK-NON-STANDARD-PORT

    Only bits named in /etc/xtables/connlabel.conf are shown. Connections with a given label can be listed with -l:

    sudo conntrack -L -o labels -l SOCIAL

Notes

  • Labels are set once per connection, when nDPI detection completes, together with the pass/drop mark. The packets exchanged before that point are not affected by label rules.

  • Labels are independent of the nEdge Lite policies: a connection dropped by a policy is labelled as well, and label rules apply on top of the policy verdict.

  • To enforce traffic with label rules only, simply do not configure drop policies: without -r and -p nEdge Lite uses a built-in pass-all policy. Connections are still marked as passed once detection completes, which is required to stop sending them to nEdge Lite, so keep the mark rules installed by the setup scripts.

  • Only TCP and UDP connections are labelled; broadcast and multicast traffic is skipped.

  • Labels are written to the conntrack entry via netlink, which requires the entry to be already confirmed by the kernel. Flows detected on their very first packet (e.g. short UDP exchanges such as DNS) may therefore remain unlabelled; with -v nEdge Lite logs Unable to set flow label for them.

Bridge Mode Advanced Configuration

VLAN Support

nEdge Lite works with VLAN-tagged traffic in bridge mode:

# Create bridge
sudo ip link add name br0 type bridge
sudo ip link set dev br0 up

# Add VLAN interfaces
sudo ip link add link eth0 name eth0.10 type vlan id 10
sudo ip link add link eth0 name eth0.20 type vlan id 20
sudo ip link set dev eth0.10 master br0
sudo ip link set dev eth0.20 master br0
sudo ip link set dev eth0.10 up
sudo ip link set dev eth0.20 up

Configure iptables for bridge:

sudo iptables -t mangle -A PREROUTING -i br0 -j CONNMARK --restore-mark
sudo iptables -t mangle -A PREROUTING -i br0 -m mark --mark 0 \
  -j NFQUEUE --queue-num 0
sudo iptables -t mangle -A POSTROUTING -o br0 -j CONNMARK --save-mark

Debugging and Development

Verbose Logging

Enable detailed logging:

sudo nedgelite -q 0 -z tcp://127.0.0.1:1234 -v

Core Dumps

Enable core dumps for debugging crashes:

ulimit -c unlimited
sudo sysctl -w kernel.core_pattern=/tmp/core-%e-%p-%t

Running Under Debugger

sudo gdb --args nedgelite -q 0 -z tcp://127.0.0.1:1234 -v

Packet Capture Integration

Capture packets for offline analysis:

# Capture packets going to NFQUEUE
sudo tcpdump -i eth0 -w /tmp/capture.pcap

# Analyze with Wireshark or tcpdump
tcpdump -r /tmp/capture.pcap -n

Best Practices for Production

  1. Use Multiple Queues: Distribute load across CPU cores

  2. Monitor Performance: Watch CPU, memory, and queue depth

  3. Tune Update Interval: Balance real-time visibility with performance

  4. Enable Queue Bypass: Prevent packet loss if nEdge Lite crashes

  5. Regular Maintenance: Update nDPI for new protocols

  6. Backup Policies: Keep policy files under version control

  7. Test Changes: Verify policy changes in a test environment first

  8. Monitor Dropped Flows: Ensure legitimate traffic isn’t blocked

  9. Plan Capacity: Size hardware for peak traffic loads

Next Steps