PCAP

Overview

PCAP captures network traffic from a node interface and emits one log record per packet. Useful for network forensics, IDS-style enrichment, and ad-hoc traffic capture on a host or DaemonSet.

Capture uses a pure-Go AF_PACKET engine (no libpcap, no cgo), so the standard collector binary captures without any native dependency. The process needs CAP_NET_RAW to open the capture socket — and additionally CAP_NET_ADMIN only if you enable promiscuous mode.

• Host (Linux package): capture is off by default. Install the collector with --enable-pcap (see Linux install) on the hosts you intend to capture on. The installer records the opt-in (PRAXIS_ENABLE_PCAP=true in /etc/default/praxis-collector on Debian/Ubuntu or /etc/sysconfig/praxis-collector on RHEL-family) and the package grants CAP_NET_RAW via a 20-pcap.conf systemd drop-in that persists across auto-updates. Once enabled, you can add or remove the pcap source in the pipeline with no reinstall.
• Kubernetes: run the pod with securityContext.capabilities.add: ["NET_RAW"] (add NET_ADMIN only for promiscuous mode), plus hostNetwork: true if you need to see traffic on the underlying node interfaces.
• macOS / Windows: not supported — the AF_PACKET capture engine is Linux-only. The receiver returns a clear error at start on other platforms.

Supported types: Logs

Basic Configuration

Parameter	Type	Default	Required	Description
interface	string	any	Yes	Network interface to capture from (e.g. eth0, or any to span all interfaces).
bpf	string	—	No	Not available in this build. Kernel BPF requires libpcap, which the pure-Go engine does not link. Leave empty and filter downstream with a filter processor — a non-empty value fails the receiver at start.

Advanced Settings

Parameter	Type	Default	Required	Description
advanced.snaplen	int	65535	No	Maximum bytes captured per packet. The default captures full Ethernet frames; lower it (e.g. 1500) to drop large payloads and reduce memory use.
advanced.promiscuous	bool	false	No	When true, capture frames not addressed to the host's MAC — needed on a SPAN/mirror/tap port. Requires CAP_NET_ADMIN in addition to CAP_NET_RAW, and must be enabled on the interface out-of-band (e.g. ip link set <if> promisc on); the engine does not toggle it. Leave off to capture the host's own traffic.
advanced.read_timeout	duration	1s	No	Capture poll timeout. Lower values reduce latency but increase CPU; a small value keeps shutdown responsive.
advanced.buffer_size	int	engine default	No	Kernel ring-buffer size in bytes. Increase under high packet rates to avoid drops. 0 uses the engine default.
advanced.parse_attributes	bool	true	No	When true, common L3/L4 fields (network.type, network.transport, source.address, destination.address, source.port, destination.port) are decoded and added as log record attributes. When false, only the raw hex packet body is emitted.
advanced.packet_channel_size	int	1024	No	Internal Go channel size between the capture goroutine and the consumer. Overflow is dropped and counted in the receiver's drop metric.

Example Configuration

{
  // Basic — capture the host's own traffic on a specific interface.
  "interface": "eth0",

  // Advanced
  "advanced": {
    "snaplen": 1500,
    "promiscuous": false,     // true also needs CAP_NET_ADMIN + iface in promisc mode
    "read_timeout": "1s",
    "buffer_size": 4194304,
    "parse_attributes": true,
    "packet_channel_size": 4096,
  },
}

Operational Notes

• Privileges: opening a capture socket requires CAP_NET_RAW (and CAP_NET_ADMIN only for promiscuous mode). On a host package, enable it with PRAXIS_ENABLE_PCAP=true (see Overview); in Kubernetes set the pod securityContext. The collector otherwise runs unprivileged and does not hold CAP_NET_RAW by default.
• Filtering: kernel-side BPF is not available in this build. To reduce volume, place a filter processor immediately after the source rather than setting bpf.
• DaemonSet pattern: for cluster-wide packet capture, deploy as a DaemonSet with hostNetwork: true and the NET_RAW capability. Capturing all traffic on a busy node will saturate both the receiver and any downstream destination — filter aggressively.
• Drops: if the packet rate exceeds what the receiver can drain, the kernel ring buffer drops packets. Watch the receiver's drop metrics and consider raising buffer_size, filtering downstream, or scaling out per-node.
• Volume: capture is high-throughput by nature. Always pair with a downstream filter or the probabilistic_sampler processor before any persistent destination.