Packet debugging

Tools for decoding Reticulum on the wire and correlating silent drops.

Wireshark / tshark dissector

Lua plugin: tools/wireshark/rns.lua

Load for one capture:

tshark -X lua_script:tools/wireshark/rns.lua -r capture.pcap -Y rns -V

Or copy rns.lua into your Wireshark plugins directory.

The dissector registers a UDP heuristic and also binds ports 4242 and 7822 on UDP and TCP. Field names match pkg/packet.DecodeFrame (rns.packet_type, rns.context_name, destination hash, hops).

Capture recipes

Loopback UDP between two local stacks:

# Linux example. Adjust ports to your interface listen/forward pair.
sudo tcpdump -i lo -w loopback.pcap udp portrange 40000-50000

Public mesh TCP uplink:

sudo tcpdump -i any -w mesh.pcap host rns.example and tcp port 4242

Before sharing captures, redact or omit payloads that may contain private app_data. Prefer posting rgodump JSONL summaries when possible.

rgodump

Decode hex or pcap UDP payloads to JSON lines:

make build
./bin/reticulum-go dump -hex <packethex>
./bin/reticulum-go dump -pcap capture.pcap
rgodump -pcap capture.pcap | head

Each line includes a frame object with packet_type_name, context_name, hashes, and sizes. The same decoder backs handshake vector replay tests under pkg/packet.

Path and link health snapshot

./bin/reticulum-go snapshot -config ~/.reticulum-go
# or
rgosnap -config ~/.reticulum

JSON includes interface stats, path table rows, active link count, and transport health counters (including announce and path drop reasons). Requires shared-instance RPC like rgostatus.

Drop counters

New health kinds (also under each interface in interface_stats):

Name	Meaning
announce_dup	Duplicate announce ignored within TTL
path_resp_suppressed	PATH_RESPONSE skipped because next hop is requestor
path_req_dup	Duplicate path request tag ignored
path_req_no_cache	Known path but no cached announce to answer with
path_resp_queued_skip	PATH_RESPONSE already queued for same iface
link_relay_unknown_iface	Link relay dropped for unknown source iface

Exposed in rgosnap as health and per-interface fields on rgostatus -json.

Handshake reference vectors

pkg/packet/testdata/handshake_vectors.json is regenerated by TestHandshakeVectorPackAndReplay. It stores raw hex plus expected decode trees for announce, PATH_RESPONSE, and LINKREQUEST frames.

go test ./pkg/packet/ -run TestHandshakeVectorPackAndReplay

Cross-stack timeline

See interop-timeline.md for INTEROP_EVENT names shared with Python and other ports.

2.6 KiB Raw Permalink Blame History