Skip to main content

Troubleshooting

Common failures during bring-up and how to recover. Flow-export-specific issues live on their own page — Flow export (operator guide) → Flow troubleshooting — because they cross into collector-side rp_filter and FORWARD-chain territory.

Common issues​

Permission denied​

The simulator creates TUN interfaces and manages the nl6sim network namespace; both require privileges. Run with sudo or use a container that grants CAP_NET_ADMIN plus access to /dev/net/tun — see Docker.

Port conflicts​

Something else is listening on :8080 (the default control plane). Pick an alternative with -port, e.g. -port 9090.

Privileged SNMP port​

Port 161 requires root or CAP_NET_BIND_SERVICE. If you can't grant either, run the simulator on a non-privileged port:

sudo ./nl6 -auto-start-ip 192.168.100.1 -auto-count 5 -snmp-port 1161

Then query it with snmpwalk -v2c -c public -p 1161 ….

TUN module missing​

sudo modprobe tun

If modprobe fails the host kernel may be missing TUN support entirely (some minimal cloud images). Switch kernels or use a container host.

High resource usage / file descriptors​

Each device opens several sockets, so large fleets need a high nofile. The Go runtime nl6 is built on raises the soft limit to the hard limit at startup, so this is usually handled automatically. If you still hit too many open files, the hard limit is capped (restrictive container or systemd LimitNOFILE=…:1024) — raise it:

ulimit -Hn 1048576          # current shell; nl6 then lifts the soft limit to it
# persistent: raise LimitNOFILE on the systemd unit, or nofile in
# /etc/security/limits.conf

Keep the nl6sim namespace enabled (default); running in the root namespace with -no-namespace at scale drags systemd-networkd into every interface change. See Scaling.

SNMP integer-encoding panics​

Historical regression — fixed. If you see panics in ASN.1 encoding of negative integer values on a tagged release, upgrade to a newer build.

Debug commands​

# Check TUN interfaces
ip addr show | grep sim
sudo ip netns exec nl6sim ip addr | grep sim

# Verify device processes (adjust port if using -snmp-port)
ss -tulpn | grep -E "(161|1161|22)"

# Monitor system resources
htop

Log files​

  • Application logs — stdout / stderr. Redirect with shell plumbing when daemonising.
  • System logs — journalctl -u <service-name> when run under systemd.
  • Web access logs — built into the application and visible in the stdout stream.

When the namespace is stuck​

If the simulator dies without cleaning up (e.g. kill -9), the nl6sim namespace and veth-sim-host / veth-sim-ns may linger. Tear them down by hand:

sudo ip netns delete nl6sim
sudo ip link delete veth-sim-host
# iptables rule, if still present
sudo iptables -D FORWARD -i veth-sim-host -j ACCEPT 2>/dev/null

See Network namespace for the full bridge anatomy.