Packet Capture

Packet Capture (PCAP)

The router includes a built-in packet capture feature that streams traffic to Wireshark or other network tools in real-time via TCP.

Capture Modes

The capture system supports three modes:

Mode	Description	STA Traffic	AP Traffic
off	Capture disabled	❌	❌
acl	ACL Monitor mode - only capture packets matching ACL rules with +M flag	✅ (if flagged)	✅ (if flagged)
promisc	Promiscuous mode - capture all AP client traffic	❌	✅ All

Key behavior:

• Packets are only buffered when a Wireshark client is connected (saves resources)
• In ACL monitor mode (pcap mode acl): Only packets matching rules with +M (monitor) flag are captured, from any interface
• In promiscuous mode (pcap mode promisc): All AP traffic is captured; STA traffic is only captured if it matches an ACL +M rule

The STA interface is intentionally excluded from promiscuous capture to avoid a feedback loop - the PCAP stream itself is sent over the STA interface to Wireshark.

Connecting Wireshark

Method 1: Pipe via netcat

nc <ESP32's IP address> 19000 | wireshark -k -i -

Method 2: Direct pipe in Wireshark

• Go to Capture > Options > Manage Interfaces > Pipes
• Add new pipe: TCP@<ESP32's IP address>:19000

Using zeek for analysis

mkdir zeek_logs && chmod 777 zeek_logs
nc <ESP32's IP address> 19000 | docker run --rm -i -v $(pwd)/zeek_logs:/logs -w /logs zeek/zeek:latest zeek -r -

Use Cases for Monitor Rules

# Capture all DNS queries going to the Internet (for debugging)
acl add from_esp UDP any * any 53 allow_monitor

# Capture specific client's traffic without blocking (by IP)
acl add to_ap IP 192.168.4.100 * any * allow_monitor

# Capture specific client's traffic using device name
acl add to_ap IP MyPhone * any * allow_monitor

Web Interface

On the Configuration page (/config), the PCAP Packet Capture section allows you to:

• Select capture mode (Off / ACL Monitor / Promiscuous)
• View client connection status
• See captured/dropped packet counts
• Set the snaplen value (64-1600 bytes)

The System Status page (/) shows the current capture mode and statistics.

Console Commands

pcap mode            # Show current capture mode
pcap mode off        # Disable capture
pcap mode acl        # ACL monitor mode (only +M flagged packets)
pcap mode promisc    # Promiscuous mode (all AP traffic)
pcap status          # Show capture statistics
pcap snaplen         # Show current snaplen (bytes per packet)
pcap snaplen 1500    # Set snaplen (64-1600 bytes)
pcap start           # Legacy: enable promiscuous mode
pcap stop            # Legacy: disable capture

Technical Details

• TCP Port: 19000
• Buffer Size: 32KB ring buffer (16 KB on the ESP32c3)
• Default Snaplen: 96 bytes (64 bytes on the ESP32c3, configurable 64-1600)
• Format: Standard PCAP with DLT_EN10MB (Ethernet)
• Single Client: One Wireshark connection at a time

Tips

• Use promiscuous mode to capture all traffic from WiFi clients
• Use ACL monitor mode to selectively capture specific traffic (e.g., DNS queries, specific hosts)
• Use a smaller snaplen (e.g., 128) to capture more packets in the buffer if you only need headers
• Use a larger snaplen (e.g., 1500) to capture full packet contents
• Check pcap status to monitor for dropped packets (buffer overflow)
• No packets are buffered until Wireshark connects, saving CPU and memory