Class: PacketGen::Capture

Inherits:
Object
  • Object
show all
Defined in:
lib/packetgen/capture.rb

Overview

Capture packets from wire

Author:

  • Sylvain Daubert

  • Kent 'picat' Gruber

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil) ⇒ Capture

Returns a new instance of Capture.

Parameters:

  • iface (String) (defaults to: nil)

    interface on which capture packets on. Default: Use default interface lookup. If no interface found, use loopback one.

  • max (Integer) (defaults to: nil)

    maximum number of packets to capture.

  • timeout (Integer) (defaults to: nil)

    maximum number of seconds before end of capture. Default: nil (no timeout)

  • filter (String) (defaults to: nil)

    bpf filter

  • promisc (Boolean) (defaults to: false)

    (default: false)

  • parse (Boolean) (defaults to: true)

    parse raw data to generate packets before yielding. Default: true

  • snaplen (Integer) (defaults to: nil)

    maximum number of bytes to capture for each packet.

  • monitor (Boolean) (defaults to: nil)

    enable or disable monitor mode on interface (if supported by iface).

Author:

  • Sylvain Daubert

  • optix2000 - add monitor argument

Since:

  • 2.0.0 remove old 1.x API

  • 3.0.0 arguments are kwargs and no more a hash

  • 3.1.5 add monitor argument


52
53
54
55
56
57
58
# File 'lib/packetgen/capture.rb', line 52

def initialize(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil)
  @iface = iface || PacketGen.default_iface || PacketGen.loopback_iface

  @packets     = []
  @raw_packets = []
  set_options iface, max, timeout, filter, promisc, parse, snaplen, monitor
end

Instance Attribute Details

#ifaceString (readonly)

Get interface name

Returns:

  • (String)

32
33
34
# File 'lib/packetgen/capture.rb', line 32

def iface
  @iface
end

#packetsArray<Packets> (readonly)

Get captured packets.

Returns:

  • (Array<Packets>)

24
25
26
# File 'lib/packetgen/capture.rb', line 24

def packets
  @packets
end

#raw_packetsArray<String> (readonly)

Get captured packet raw data.

Returns:

  • (Array<String>)

28
29
30
# File 'lib/packetgen/capture.rb', line 28

def raw_packets
  @raw_packets
end

Instance Method Details

#start(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil) {|packet| ... } ⇒ Object

Start capture

Yield Parameters:

  • packet (Packet, String)

    if a block is given, yield each captured packet (Packet or raw data String, depending on :parse option)

See Also:

  • for parameters

Author:

  • Sylvain Daubert

  • optix2000 - add monitor argument

Since:

  • 3.0.0 arguments are kwargs and no more a hash

  • 3.1.5 add monitor argument


68
69
70
71
72
73
74
75
76
77
78
# File 'lib/packetgen/capture.rb', line 68

def start(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil, &block)
  set_options iface, max, timeout, filter, promisc, parse, snaplen, monitor

  @cap_thread = Thread.new do
    PCAPRUBWrapper.capture(**capture_args) do |packet_data|
      add_packet(packet_data, &block)
      break if defined?(@max) && (raw_packets.size >= @max)
    end
  end
  cap_thread.join(@timeout)
end

#stopvoid

This method returns an undefined value.

Stop capture. Should be used from another thread, as #start blocks.

BEWARE: multiple capture should not be started in different threads. No effort has been made to make Capture nor PacketGen thread-safe.


85
86
87
# File 'lib/packetgen/capture.rb', line 85

def stop
  cap_thread.kill
end