Peacap (Peacap v0.1.1)

View Source

Packet capture using libpcap with BPF filtering.

Usage

program = BPF.compile(fn <<_::binary>> -> true end)
{:ok, pid} = Peacap.start("en0", program)

# Packets delivered as messages to caller:
# {:peacap_packet, pid, packet_binary}

receive do
  {:peacap_packet, ^pid, packet} ->
    IO.inspect(packet, label: "captured")
end

Peacap.stop(pid)

Options

  • :snaplen - Maximum bytes to capture per packet (default: 65535)
  • :promisc - Enable promiscuous mode (default: false)
  • :poll_interval - Polling interval for macOS workaround in ms (default: 100)

Summary

Functions

start(interface, program, opts \\ [])

Starts packet capture on the given interface with the specified BPF filter.

stop(pid)

Stops the packet capture.

Functions

start(interface, program, opts \\ [])

@spec start(String.t(), BPF.Program.t(), keyword()) :: {:ok, pid()} | {:error, term()}

Starts packet capture on the given interface with the specified BPF filter.

Returns {:ok, pid} on success or {:error, reason} on failure. Captured packets are sent to the calling process as {:peacap_packet, pid, binary}.

Error Handling

If an error occurs while reading packets, the capture GenServer will terminate. The caller may monitor the returned pid to detect unexpected termination:

{:ok, pid} = Peacap.start("en0", program)
ref = Process.monitor(pid)

receive do
  {:peacap_packet, ^pid, packet} -> handle_packet(packet)
  {:DOWN, ^ref, :process, ^pid, reason} -> handle_error(reason)
end

Arguments

  • interface - Network interface name (e.g., "en0", "lo0", "eth0")
  • program - A compiled BPF program from BPF.compile/1
  • opts - Keyword list of options

Options

  • :snaplen - Maximum bytes to capture per packet. Packets larger than this will be truncated. Default: 65535 (captures full packets up to jumbo frames).

  • :promisc - When true, puts the interface in promiscuous mode to capture all packets on the network segment, not just those addressed to this host. Requires appropriate permissions. Default: false.

  • :poll_interval - Polling interval in milliseconds for the macOS BPF buffering workaround. On macOS, the BPF device may buffer packets and not trigger select() notifications reliably. This timer ensures packets are read periodically. Only used on macOS. Default: 100.

Examples

# Capture all packets
program = BPF.compile(fn <<_::binary>> -> true end)
{:ok, pid} = Peacap.start("en0", program)

# Capture with promiscuous mode and smaller snaplen
{:ok, pid} = Peacap.start("en0", program, promisc: true, snaplen: 1500)

stop(pid)

@spec stop(pid()) :: :ok

Stops the packet capture.