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

Everything this transport needs comes from its configuration parameters, and the address segment of the connection string is not interpreted. Drivers using it therefore leave it empty or fill it with something meaningful to the driver itself.

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

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.0.0</version>
</dependency>

Config options:

raw-socket.interface-name

STRING

Network interface name to use (e.g., "eth0", "en0", "\\Device\\NPF_{GUID}" on Windows). If not specified, will use the first available interface.

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.