# 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:

```bash
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:

```bash
# 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:

```bash
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:

```bash
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

```bash
./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.

```bash
go test ./pkg/packet/ -run TestHandshakeVectorPackAndReplay
```

## Cross-stack timeline

See [interop-timeline.md](interop-timeline.md) for INTEROP_EVENT names shared with Python and other ports.