Raw Socket

Sends and receives Ethernet frames directly on a network interface, below IP. Protocols that are not carried over TCP or UDP at all - PROFINET real-time traffic, for instance - need this.

It captures and injects through libpcap, so the host needs a libpcap (Linux, macOS) or Npcap (Windows) installation, and the process needs permission to open the interface in capture mode - root, CAP_NET_RAW, or membership of a group the packet-capture device belongs to.

Transport syntax

{name of the network interface}

The name depends on the operating system - eth0 or enp3s0 on Linux, en0 on macOS, \\Device\\NPF_{GUID} on Windows. Leave it out and the transport takes the first interface it finds, which is only sensible on a machine with one.

Example
profinet://en0?raw-socket.remote-address=00:0e:cf:12:34:56&raw-socket.protocol-id=34962

The interface can also be named with the raw-socket.interface-name option instead; the address segment wins if both name one.

Name

Type

Default Value

Required

Description

Name

Raw Socket (Ethernet)

Code

raw-socket

Maven Dependency

 
<dependency>
  <groupId>org.apache.plc4x</groupId>
  <artifactId>plc4j-transports-raw-socket</artifactId>
  <version>1.1.0</version>
</dependency>

Config options:

raw-socket.interface-name

STRING

Network interface name to use (e.g., "eth0", "en0", "\\Device\\NPF_{GUID}" on Windows). Alternative to naming the interface in the address segment of the connection string, which takes precedence. If neither names one, the first available interface is used.

raw-socket.local-address

STRING

Local MAC address to send from. If not set, uses interface’s MAC address.

raw-socket.remote-address

STRING

required

Remote MAC address to send to.

raw-socket.protocol-id

INT

required

EtherType / Protocol number (e.g., 0x88B5 for PROFINET, 0x88CC for LLDP, custom values)

raw-socket.promiscuous-mode

BOOLEAN

false

Promiscuous mode - capture all packets on the network, not just those destined for this interface.

raw-socket.capture-timeout

INT

1000

Packet capture timeout in milliseconds.

raw-socket.snapshot-length

INT

65536

Snapshot length - maximum bytes to capture per packet. 0 means capture entire packet.

raw-socket.buffer-size

INT

1048576

Buffer size for packet capture in bytes.

raw-socket.receive-queue-size

INT

1048576

Bytes of captured frames that may wait for a consumer before frames are dropped.

raw-socket.vlan-id

INT

0

VLAN ID (0 means no VLAN tag). Range: 0-4095

raw-socket.vlan-priority

INT

0

VLAN priority (0-7). Only used if vlanId > 0.

raw-socket.reuse-interface

BOOLEAN

false

Reuse the underlying network interface across multiple transport instances. When true, instances with the same interface and protocol will share a pcap handle. This is useful for protocols where multiple logical connections share one Ethernet type.

raw-socket.bpf-filter

STRING

BPF (Berkeley Packet Filter) expression to filter packets.

raw-socket.max-frame-size

INT

1500

Maximum frame size (MTU) in bytes.

raw-socket.read-timeout-ms

INT

0

Read timeout for blocking reads in milliseconds.

raw-socket.include-ethernet-header

BOOLEAN

false

Deliver full Ethernet frames to the driver and accept raw Ethernet frames on send. Required for L2 protocols that build their own Ethernet headers.

raw-socket.remote-address and raw-socket.protocol-id have no sensible default and must be given. The protocol id is the EtherType - 0x88B5 (34997) and 0x8892 (34962) for PROFINET, 0x88CC (35020) for LLDP.

If frames go missing under load, raise raw-socket.receive-queue-size - it bounds how many bytes of captured frames may wait for the driver before the oldest are dropped.