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



57
58
59
60
61
62
63
64
 
# File 'lib/packetgen/capture.rb', line 57

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 = []
  @timestamps = []
  set_options iface, max, timeout, filter, promisc, parse, snaplen, monitor
end

Instance Attribute Details

#iface ⇒ String (readonly)

Get interface name

Returns:

  • (String) 


37
38
39
 
# File 'lib/packetgen/capture.rb', line 37

def iface
  @iface
end

#packets ⇒ Array<Packets> (readonly)

Get captured packets.

Returns:

  • (Array<Packets>) 


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

def packets
  @packets
end

#raw_packets ⇒ Array<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

#timestamps ⇒ Array<Time> (readonly)

Get timestamps associated with #packets and #raw_packets

Returns:

  • (Array<Time>)

Since:

  • 3.3.0



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

def timestamps
  @timestamps
end

Instance Method Details

#start(iface: nil, max: nil, timeout: nil, filter: nil, promisc: false, parse: true, snaplen: nil, monitor: nil) {|packet, timestamp| ... } ⇒ 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)

  • timestamp (Time) —

    packet timestamp

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

  • 3.3.0 add packet timestamp as second yield parameter



76
77
78
79
80
81
82
83
84
85
86
 
# File 'lib/packetgen/capture.rb', line 76

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|
      add_packet(packet, &block)
      break if defined?(@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.



93
94
95
 
# File 'lib/packetgen/capture.rb', line 93

def stop
  cap_thread.kill
end