udpUser Datagram ProtocolFire-and-Forget Datagrams (a -> b udp, Zero Handshake Tax)
What It Does on the Wire
No syn, no fin, no regrets: udp fires arbitrary string or hex bytes at any port, remembers the port pair on <- replies, and nails the mandatory IPv6 UDP checksum every time.
User Datagram Protocol (udp, IP protocol 17, RFC 768) provides stateless, minimal-overhead 8-byte Layer 4 framing (Source Port, Destination Port, Length, and Checksum) over both IPv4 and IPv6. It is the ideal building block for custom binary protocols, proprietary game/financial market-data feeds, firewall ACL probes, and IPv4 fragmentation tests.
FrameAssembly computes the exact UDP Length (8 + payload.len()) and non-zero RFC 768 / RFC 8200 pseudo-header checksum (mapping computed 0x0000 to 0xffff as required on IPv6), while remembering (srcport, dstport) across -> and <- frames on the same host pair.
Custom Binary Wire Dissectors & Lua Plugin Testing
Combine udp dstport <port> with hexpayload "<hex>" to build deterministic regression .pcap fixtures for custom Wireshark Lua/C dissectors and proprietary telemetry feeds.
Firewall Stateless UDP ACLs & NAT Pinholing Verification
Validate that stateful firewalls open return UDP pinholes when <- replies reverse the initial (srcport, dstport) tuple within timeout windows.
MTU Discovery & IPv4 Fragmented Datagram Reassembly
Pair udp with ipid, mf, and fragoffset to test host and NGFW IPv4 fragment reassembly queues.
Minimal Quickstart (udp_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host sensor { ip 10.20.0.15 }host gateway { ip 10.20.0.1 }compile { sensor -> gateway udp srcport 53100 dstport 9000 payload "ping:seq=1" wait 2ms sensor <- gateway udp payload "pong:seq=1"}What the Compiler Calculates So You Don't Have To
- Computes the 16-bit UDP Length (
8 + payload bytes) and outer IPv4 Total Length / IPv6 Payload Length automatically. - Calculates the ones'-complement pseudo-header checksum over IPv4 or IPv6 addresses, converting
0x0000to0xffffper RFC 768 / RFC 8200. - Remembers
srcport 53100anddstport 9000on the(sensor, gateway)pair so the<-reply automatically emits9000 -> 53100.
Dual-Stack Custom Binary Telemetry Feed with QoS Marking
Uses a reusable flow(tx, rx) template to emit identical hex-encoded binary UDP frames marked dscp 46 (EF) over both IPv4 and IPv6 endpoints.
host feed_v4 { ip 192.0.2.10 }host recv_v4 { ip 192.0.2.20 }host feed_v6 { ip 2001:db8:feed::10 }host recv_v6 { ip 2001:db8:feed::20 }flow telemetry_burst(tx, rx) { tx -> rx udp srcport 55100 dstport 19500 dscp 46 hexpayload "cafebabe00010008deadbeef" wait 500us tx -> rx udp dscp 46 hexpayload "cafebabe0002000801020304" wait 1ms tx <- rx udp dscp 46 payload "ACK:2"}compile { telemetry_burst(feed_v4, recv_v4) telemetry_burst(feed_v6, recv_v6)}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show udp_dualstack_binary.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly udp_dualstack_binary.frasm udp_dualstack_binary.pcap
frameassembly udp_dualstack_binary.frasm udp_dualstack_binary.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse udp_dualstack_binary.pcap udp_dualstack_binary_edited.frasmAll udp Keywords & Header Options
Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after udp:
src_host -> dst_host udp [srcport <0..65535>] [dstport <0..65535>] [payload "<text>" | hexpayload "<hex>"]| Keyword / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| srcport <0..65535> | Whole number (0..65535) | 49152 (or inherited pair port) | Sets the 16-bit UDP Source Port in bytes 0..1 of the UDP header. |
| dstport <0..65535> | Whole number (0..65535) | 80 (or inherited pair port) | Sets the 16-bit UDP Destination Port in bytes 2..3 of the UDP header. |
| payload "<text>" | Quoted text | Empty (0 bytes) | Appends UTF-8 bytes after the 8-byte UDP header (mutually exclusive with hexpayload). |
| hexpayload "<hex>" | Even-length hex octets ("deadbeef" or "de:ad:be:ef") | Empty (0 bytes) | Appends raw decoded bytes after the 8-byte UDP header (mutually exclusive with payload). |
Cross-Layer Wrappers Valid with udp
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
9 options
Cross-Layer Wrappers Valid with udp
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
| Option | Range / Format | Default | Effect on Packet |
|---|---|---|---|
| wait <number><ns|us|ms|s|m> | Time gap (ns, us, ms, s, m) | 10ms | Advances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back). |
| payload "<text>" | hexpayload "<hex>" | Quoted text or hex bytes (choose one) | Omitted | Appends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums. |
| srcmac <mac> | dstmac <mac> | Colon, hyphen, or Cisco dot MAC | Host MAC / RFC multicast MAC | Overrides the 14-byte Ethernet II source or destination MAC address for this single packet. |
| vlan <0..4095> [pcp <0..7>] [dei <0|1>] | VLAN ID 0..4095, PCP 0..7, DEI 0..1 | Untagged | Wraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority. |
| qinq <0..4095> [innervlan <0..4095>] | Outer S-VLAN 0..4095, Inner C-VLAN 0..4095 | Untagged (innervlan 1 when qinq is set) | Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100). |
| mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>] | Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255 | Unlabeled (at most 1 mpls tag per packet) | Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header. |
| ttl <0..255> [dscp <0..63>] [ecn <0..3>] | TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3 | ttl 64, dscp 0, ecn 0 | Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings. |
| ipid <0..65535> [df] [mf] [fragoffset <0..8191>] | IPv4 ID, DF/MF flags, fragment offset 0..8191 | ipid 1, flags 0, fragoffset 0 | Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6). |
| flowlabel <0..1048575> | 20-bit IPv6 Flow Label (0..1048575) | 0 | Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts). |
Gotchas & Quick Fixes
TCP Flags and Options Are Rejected on UDP Frames
sensor -> gateway udp dstport 9000 syn seq 100sensor -> gateway udp dstport 9000 hexpayload "00000064"TCP-only flags and options (syn, ack, psh, seq, acknum, win, mss, sackperm) cannot be used on UDP packets.
Never Combine payload and hexpayload on One Frame
sensor -> gateway udp dstport 9000 payload "hdr" hexpayload "deadbeef"sensor -> gateway udp dstport 9000 hexpayload "686472deadbeef"A single frame statement accepts either payload "<utf8>" or hexpayload "<hex>", never both simultaneously.