PCAP Replay

Replays a previously recorded PCAP or PCAPNG capture as if it were a live device. Nothing is sent to a network: the driver connects, and the frames it "receives" come out of the file.

This is a debugging and development transport. It is what lets you work on a driver against a capture taken from a machine you cannot reach, and it pairs naturally with the audit-log - record once, then replay as often as you need.

Transport syntax

{path to the capture}

An absolute path names a file on disk. A path that matches a resource on the classpath is read from there instead and unpacked to a temporary file, which is how the drivers' own tests ship their captures alongside the code.

Example
profinet:pcap-replay:///var/captures/line-3.pcapng?pcap-replay.speed-factor=1.0
The three slashes are not a typo - two end the transport code, and the third begins the absolute path.

The capture can also be named with the pcap-replay.pcap-file option instead; the address segment wins if both name one.

Name

Type

Default Value

Required

Description

Name

PCAP Replay

Code

pcap-replay

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-transports-pcap-replay</artifactId>
  <version>1.1.0</version>
</dependency>

Config options:

pcap-replay.pcap-file

STRING

Path to the PCAP file to replay. Alternative to naming the capture in the address segment of the connection string, which takes precedence.

pcap-replay.local-address

STRING

Local MAC address to simulate (acts as this device).

pcap-replay.remote-address

STRING

Remote MAC address to communicate with.

pcap-replay.protocol-id

INT

0

EtherType / Protocol number to filter (e.g., 0x88B5 for PROFINET).

pcap-replay.speed-factor

DOUBLE

0

Replay speed multiplier. 1.0 = real-time, 0.0 = as fast as possible, 2.0 = double speed.

pcap-replay.loop

BOOLEAN

false

Loop the PCAP file when it reaches the end.

pcap-replay.only-incoming-packets

BOOLEAN

true

Only replay packets from remote to local (simulates device responses). When false, replays all packets.

pcap-replay.only-outgoing-packets

BOOLEAN

false

Only replay packets from local to remote (simulates device requests).

pcap-replay.max-frame-size

INT

1500

Maximum frame size in bytes.

pcap-replay.read-timeout-ms

INT

0

Read timeout for blocking reads in milliseconds.

pcap-replay.packet-queue-size

INT

1000

Buffer size for packet queue.

pcap-replay.auto-detect-mac-addresses

BOOLEAN

true

Auto-detect MAC addresses from PCAP file based on first packet.

pcap-replay.auto-start

BOOLEAN

true

Start replay automatically when transport is created.

pcap-replay.vlan-id

INT

0

Filter by VLAN ID (0 means no VLAN filtering).

Two options are worth knowing before the first run:

  • pcap-replay.speed-factor defaults to 0, which replays the capture as fast as it can be read. Set it to 1.0 to reproduce the original timing - which is what you want when the bug you are chasing is a timing one.

  • pcap-replay.only-incoming-packets defaults to true, so by default only the frames the device sent are replayed and the driver’s own requests go nowhere. That is the right setting for standing in for a device.