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

Constant Summary collapse

DEFAULT_SNAPLEN =

Default snaplen to use if :snaplen option not defined.

0xffff

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Capture

Returns a new instance of Capture.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :iface (String) —

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

  • :max (Integer) —

    maximum number of packets to capture.

  • :timeout (Integer) —

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

  • :filter (String) —

    bpf filter

  • :promiscuous (Boolean) — default: default: +false+
  • :parse (Boolean) —

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

  • :snaplen (Integer) —

    maximum number of bytes to capture for each packet.

Since:

  • 2.0.0 remove old 1.x API



44
45
46
47
48
49
50
51
52
53
 
# File 'lib/packetgen/capture.rb', line 44

def initialize(options={})
  @iface = Interfacez.default || Interfacez.loopback

  @packets     = []
  @raw_packets = []
  @promisc = false
  @snaplen = DEFAULT_SNAPLEN
  @parse = true
  set_options options
end

Instance Attribute Details

#iface ⇒ String (readonly)

Get interface name

Returns:

  • (String) 


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

def iface
  @iface
end

#packets ⇒ Array<Packets> (readonly)

Get captured packets.

Returns:

  • (Array<Packets>) 


20
21
22
 
# File 'lib/packetgen/capture.rb', line 20

def packets
  @packets
end

#raw_packets ⇒ Array<String> (readonly)

Get captured packet raw data.

Returns:

  • (Array<String>) 


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

def raw_packets
  @raw_packets
end

Instance Method Details

#start(options = {}) {|packet| ... } ⇒ Object

Start capture

Parameters:

  • options (Hash) (defaults to: {}) —

    complete see #initialize.

Yield Parameters:

  • packet (Packet, String) —

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



59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/packetgen/capture.rb', line 59

def start(options={})
  set_options options
  @pcap = PCAPRUB::Pcap.open_live(@iface, @snaplen, @promisc, 1)
  set_filter
  @cap_thread = Thread.new do
    @pcap.each do |packet_data|
      @raw_packets << packet_data
      if @parse
        packet = Packet.parse(packet_data)
        @packets << packet
        yield packet if block_given?
      elsif block_given?
        yield packet_data
      end
      break if @max && @raw_packets.size >= @max
    end
  end
  @cap_thread.join(@timeout)
end

#stop ⇒ void

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.



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

def stop
  @cap_thread.kill
end