twampyre plugin | twamp

This plugin implements an asynchronous TWAMP (TWAMP Light/STAMP) client for one-way and round-trip delay/loss measurements using timestamped UDP packets. It is designed for scalable network performance testing and supports both IPv4 and IPv6, with options to fine-tune headers and test characteristics.

Note This plugin supports unauthenticated STAMP test-packets only. For interoperability with TWAMP/light reflectors use SSID value 0.

✨ Key Features

  • Sends timestamped UDP packets to a STAMP server (TWAMP/light reflector)
  • Supports:
  • IPv4 and IPv6
  • Custom payload sizes (fixed or IMIX-style)
  • Custom IP headers (TTL, DSCP/TOS, DF bit)
  • Custom STAMP Session ID and error estimate
  • Exported as structured inbound, outbound and roundtrip metrics via twampyre telemetry backend

📚 IETF References

⚖ License

Licensed under the BSD 3-Clause License.

🧩 Plugin Configuration

These parameters apply to the plugin instance (shared across sessions):

Name Type Default Description
local_port int 0 Local UDP port to bind
ttl int 64 Time To Live (TTL) for outgoing packets
traffic_class int 0 DSCP/TOS to be used in the IP header
do_not_fragment bool false Set Don't Fragment (DF) bit

🧪 Session Parameters

These parameters are configured per test session (per target):

Name Type Default Description
remote_port int 862 UDP port of remote STAMP server
payload_size int -1 Packet padding or -1 for IMIX-style
ssid int 0 Optional STAMP Session ID

🛠 Usage Example

plugins:
  twamp:
    local_port: 55000
    ttl: 64
    do_not_fragment: true
    traffic_class: 32 # CS1 DSCP

kinds:
  router:
    twamp:
      interval: 0.001
      timeout: 0.2

targets:
  192.0.2.1:
    kind: router
    twamp:
      payload_size: 64
      ssid: 20

🔧 Implementation details

IPv4 Headers, Packet Sizes, IMIX Distribution

Total Ethernet IPv4 UDP STAMP TLVs Packets Bandwidth
86 14 20 8 44 0 7/12 14.5%
512 14 20 8 44 426 4/12 49.1%
1514 14 20 8 44 1428 1/12 36.4%

IPv6 Headers, Packet Sizes, IMIX Distribution

Total Ethernet IPv6 UDP STAMP TLVs Packets Bandwidth
106 14 40 8 44 0 7/12 17.2%
512 14 40 8 44 406 4/12 47.6%
1514 14 40 8 44 1408 1/12 35.2%

Time synchronization, Error Estimate

Error Estimate Source Scale Multiplier Encoded
100 µs NTP 15 14 8F0Eh
500 µs NTP 18 16 9210h
1 ms NTP 20 4 9404h
2 ms NTP 21 4 9504h
5 ms NTP 22 5 9605h
10 ms manual 22 10 160Ah
20 ms manual 22 20 1614h

Example: 100µs with NTP is encoded as 0x8F0E (S=1, Z=0, Scale=15, Mult=14)

For error estimates of >=10ms the table assumes manual/local sync (S=0).

Best Practices/Assumptions:

  • TWAMPYRE/TWAMPLIFY should be synced using NTP
  • VNF/CNF under test should be synced using PTP (software timestamping)
  • Hardware Devices (e.g., routers) should use PTP (hardware timestamping)
  • Error Estimate need to account for:
  • NTP/PTP synchronization/clock accuracy: network latency, clock drift, clock resolution
  • Software timestamping: IP stack, application stack, CPU load, task switching, ...
  • Environment: containerized, virtualized, bare-metal
  • Load Scenario: light, typical, heavy
  • For TWAMPYRE/TWAMPLIFY, we assume NTP synchronization with an error estimate of 2ms (0x9504). This is a realistic estimate for typical load in containerized environments.

DSCP Value Mapping

DSCP Name DSCP Value TOS (bin) TOS (hex)
be 0 0000 0000 00
cp1 1 0000 0100 04
cp2 2 0000 1000 08
cp3 3 0000 1100 0C
cp4 4 0001 0000 10
cp5 5 0001 0100 14
cp6 6 0001 1000 18
cp7 7 0001 1100 1C
cs1 8 0010 0000 20
cp9 9 0010 0100 24
af11 10 0010 1000 28
cp11 11 0010 1100 2C
af12 12 0011 0000 30
cp13 13 0011 0100 34
af13 14 0011 1000 38
cp15 15 0011 1100 3C
cs2 16 0100 0000 40
cp17 17 0100 0100 44
af21 18 0100 1000 48
cp19 19 0100 1100 4C
af22 20 0101 0000 50
cp21 21 0101 0100 54
af23 22 0101 1000 58
cp23 23 0101 1100 5C
cs3 24 0110 0000 60
cp25 25 0110 0100 64
af31 26 0110 1000 68
cp27 27 0110 1100 6C
af32 28 0111 0000 70
cp29 29 0111 0100 74
af33 30 0111 1000 78
cp31 31 0111 1100 7C
cs4 32 1000 0000 80
cp33 33 1000 0100 84
af41 34 1000 1000 88
cp35 35 1000 1100 8C
af42 36 1001 0000 90
cp37 37 1001 0100 94
af43 38 1001 1000 98
cp39 39 1001 1100 9C
cs5 40 1010 0000 A0
cp41 41 1010 0100 A4
cp42 42 1010 1000 A8
cp43 43 1010 1100 AC
cp44 44 1011 0000 B0
cp45 45 1011 0100 B4
ef 46 1011 1000 B8
cp47 47 1011 1100 BC
nc1 48 1100 0000 C0
cp49 49 1100 0100 C4
cp50 50 1100 1000 C8
cp51 51 1100 1100 CC
cp52 52 1101 0000 D0
cp53 53 1101 0100 D4
cp54 54 1101 1000 D8
cp55 55 1101 1100 DC
nc2 56 1110 0000 E0
cp57 57 1110 0100 E4
cp58 58 1110 1000 E8
cp59 59 1110 1100 EC
cp60 60 1111 0000 F0
cp61 61 1111 0100 F4
cp62 62 1111 1000 F8
cp63 63 1111 1100 FC