ptpIEEE 1588 Precision Time Protocol v2Nanosecond Hardware Clock Sync (gm -> BoundaryClock ptp IEEE 1588v2)
What It Does on the Wire
For high-frequency trading, 5G fronthaul, and substation synchrophasors where NTP is way too slow, ptp routes event messages to UDP 319 and general messages to UDP 320 automatically.
IEEE 1588 Precision Time Protocol v2 (ptp) delivers sub-microsecond hardware timestamp synchronization for 5G fronthaul (ITU-T G.8275), SMPTE ST 2110 broadcast media, IEC 61850 power substations, and high-frequency trading fabrics. PTPv2 splits messages across two UDP ports: hardware-timestamped Event messages on UDP 319 (sync 0x0, delayreq 0x1) and software General messages on UDP 320 (followup 0x8, delayresp 0x9, announce 0xb).
FrameAssembly selects UDP 319 or 320 automatically from the message type, populates the 34-byte PTPv2 Common Header (versionPTP = 2, domainNumber, 8-byte ClockIdentity + 2-byte PortNumber, sequenceId, controlField), and appends precision 10-byte (48b sec, 32b nsec) timestamp payloads.
Two-Step Grandmaster Clock Sync (announce + sync + followup + delayreq/delayresp)
Model a complete 5-packet IEEE 1588 two-step slave offset and path-delay measurement loop with nanosecond .pcapng frame spacing (wait 250us).
SMPTE ST 2110 Broadcast & Financial Trading Switch Boundary Clock Testing
Verify QoS priority queuing (dscp 46 EF for Event UDP 319, dscp 34 AF41 for General UDP 320) and PTP domain isolation across leaf switches.
IEC 61850 Digital Substation Time-Distribution Security
Test OT IDS rules that alert on rogue ptp announce messages attempting Best Master Clock Algorithm (BMCA) takeover.
Minimal Quickstart (ptp_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host grandmaster { ip 10.60.1.1 }host boundary_sw { ip 10.60.1.10 }compile { grandmaster -> boundary_sw ptp sync domain 0 seqid 100 clockid "001c73fffe000001" wait 200us grandmaster -> boundary_sw ptp followup domain 0 seqid 100 clockid "001c73fffe000001"}What the Compiler Calculates So You Don't Have To
- Routes time-critical Event messages (
sync,delayreq) to UDP319and General messages (followup,delayresp,announce) to UDP320automatically. - Computes exact IEEE 1588-2008
messageLength(44bytes forsync/followup/delayreq,54bytes fordelayresp,64bytes forannounce) and setstwoStepFlagonsync. - Swaps
319/320ontosrcportcleanly when<-reverse arrows are used.
Complete Two-Step IEEE 1588v2 Grandmaster <-> Ordinary Clock Exchange (.pcapng Ready)
Executes a 5-frame PTPv2 announce -> sync -> followup -> delayreq -> delayresp cycle with sub-millisecond wait intervals ideal for .pcapng nanosecond export.
host gm_clock { ip 172.22.0.1 }host media_node { ip 172.22.0.45 }compile { // 1. Grandmaster announces BMCA hierarchy on UDP 320 (domain 127 = SMPTE ST 2059-2) gm_clock -> media_node ptp announce domain 127 seqid 500 clockid "ec4670fffe010203" dscp 46 wait 500us // 2. Two-step Sync (UDP 319) + Follow_Up (UDP 320) with matching seqid 501 gm_clock -> media_node ptp sync domain 127 seqid 501 clockid "ec4670fffe010203" dscp 46 wait 120us gm_clock -> media_node ptp followup domain 127 seqid 501 clockid "ec4670fffe010203" dscp 46 wait 250us // 3. Slave measures reverse path delay via Delay_Req (UDP 319) -> Delay_Resp (UDP 320) media_node -> gm_clock ptp delayreq domain 127 seqid 88 clockid "001b21fffeaa0045" dscp 46 wait 180us media_node <- gm_clock ptp delayresp domain 127 seqid 88 clockid "ec4670fffe010203" dscp 46}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show ptp_twostep_grandmaster.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcap
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse ptp_twostep_grandmaster.pcap ptp_twostep_grandmaster_edited.frasmAll ptp 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 ptp:
src_host -> dst_host ptp [sync | delayreq | followup | delayresp | announce | msgtype "<text>"] [domain <0..255>] [seqid <0..65535>] [clockid "<text>"]| Keyword / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| sync | delayreq | followup | delayresp | announce | msgtype "<text>" | PTPv2 message type keyword | sync (0x0 on UDP 319) | Selects lower nibble of byte 0 and target UDP port (0x0 Sync/319, 0x1 Delay_Req/319, 0x8 Follow_Up/320, 0x9 Delay_Resp/320, 0xb Announce/320). |
| domain <0..255> | Whole number (0..255) | 0 | Sets domainNumber in byte 4 (0 default IEEE 1588, 24/44 telecom G.8275, 127 SMPTE ST 2059). |
| seqid <0..65535> | Whole number (0..65535) | 1 | Sets sequenceId in bytes 30..31 pairing sync with followup and delayreq with delayresp. |
| clockid "<text>" | 16-char EUI-64 hex ("001c73fffe000001") or 8B string | Derived from source MAC (EUI-64 fffe) | Populates the 8-byte ClockIdentity inside the 10-byte sourcePortIdentity field. |
Cross-Layer Wrappers Valid with ptp
802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol
10 options
Cross-Layer Wrappers Valid with ptp
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). |
| srcport <0..65535> | dstport <0..65535> | Port number 0..65535 | srcport 49152 (remembered), UDP 319 (Event) / UDP 320 (General) | Overrides source or destination port and remembers the port pair automatically on <- replies. |
Gotchas & Quick Fixes
Message Keywords Contain Zero Underscores (delayreq, followup, delayresp)
gm_clock -> media_node ptp follow_up seqid 501gm_clock -> media_node ptp followup seqid 501Spell PTPv2 message types without underscores: sync, delayreq, followup, delayresp, and announce.
Export Sub-Microsecond PTP Captures as .pcapng for 1ns Timestamp Resolution
frameassembly ptp_twostep_grandmaster.frasm ptp_twostep_grandmaster.pcapngClassic .pcap (0xa1b2c3d4) stores 1us timestamps; .pcapng writes if_tsresol = 9 (10^-9s) so wait 25ns or wait 150ns hardware timestamps are preserved without rounding.
Companion Guides & Neighboring Protocols
.pcap Captures onto Real Copper & Fiber (tcpreplay)