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(iface = Pcap.lookupdev, options = {}) ⇒ Capture #initialize(options = {}) ⇒ Capture

Returns a new instance of Capture.

Overloads:

  • #initialize(iface = Pcap.lookupdev, options = {}) ⇒ Capture

    Parameters:

    • iface (String) (defaults to: Pcap.lookupdev) —

      interface on which capture packets

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

    Options Hash (options):

    • :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.

  • #initialize(options = {}) ⇒ 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.



54
55
56
57
58
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 54

def initialize(iface_or_options={}, options={})
  begin
    @iface = Pcap.lookupdev
  rescue PCAPRUB::BindingError
    @iface = 'lo'
  end

  case iface_or_options
  when Hash
    options = iface_or_options
  else
    warn "[deprecation] use of PacketGen::Capture#initialize with iface name as\n" \
         "              first argument is deprecated. Instead, use:\n" \
         '              PacketGen::Capture.new(iface: \'name\').'
    @iface = iface_or_options.to_s
  end

  @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) 


26
27
28
 
# File 'lib/packetgen/capture.rb', line 26

def iface
  @iface
end

#packets ⇒ Array<Packets> (readonly)

Get captured packets.

Returns:

  • (Array<Packets>) 


18
19
20
 
# File 'lib/packetgen/capture.rb', line 18

def packets
  @packets
end

#raw_packets ⇒ Array<String> (readonly)

Get captured packet raw data.

Returns:

  • (Array<String>) 


22
23
24
 
# File 'lib/packetgen/capture.rb', line 22

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)



83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
 
# File 'lib/packetgen/capture.rb', line 83

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?
      else
        yield packet_data if block_given?
      end
      break if @max and @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.



108
109
110
 
# File 'lib/packetgen/capture.rb', line 108

def stop
  @cap_thread.kill
end