NAME

Net::Packet::Dump - an interface for a tcpdump-like process and a frame analyzer

SYNOPSIS

   #
   # Example offline analysis
   #

   use Net::Packet::Dump;
   my $dump = Net::Packet::Dump->new(filter => "tcp and dst host $Net::Packet::Ip");

   # Code sending packets
   ...
   sleep(5);

   for ($dump->analyze) {
      # Play with what have been captured
      # See Net::Packet::Frame for packet format
   }


   #
   # Example live analysis
   #

   use Net::Packet::Dump;
   my $dump =  Net::Packet::Dump->new(
      filter        => "tcp and dst host $Net::Packet::Ip",
      timeoutOnNext => 5,
   );

   until ($Net::Packet::Timeout) {
      # Code sending packets here

      if ($dump->next) {
         $dump->nextFrame->l3->print;
         # Code analyzing reply here
      }
   }

DESCRIPTION

This module provides an interface for a tcpdump-like process creator and a frame analyzer. When you call the new method, an object is returned with some default values set, and the global $Net::Packet::Dump is set with it.

OPTIONS

callStart < BOOL >

If set to a true value, the start method will be called on the new object creation. It is the default.

file < SCALAR >

This specifies in which file to store the captured frames, stored in a .pcap format file. The default is to create a randomly named file (like netpkt-tmp-PID-RANDOM32BITSINT.pcap).

unlinkOnDestroy < SCALAR >

When set to 1, the file used to capture frames will be deleted after it has become out of scope (from a Perl perspective). The default is 1, so if you want to keep the file, set it to 0.

filter < SCALAR >

This sets the filter used to capture frames, in a pcap filter format. You can use the method Net::Packet::Frame::getFilter to automatically set it from a Net::Packet::Frame object. See Net::Packet::Frame. The default is to set an empty filter, in order to capture all frames.

overwrite < SCALAR >

When set to 1, will overwrite an existing file. If not, it will only analyze an existing one, or create a new file if it does not exist. The default is to not overwrite.

waitOnStop < SCALAR >

When you call the stop method, you can specify a timeout before stopping the capture. The default is to sleep for 3 seconds.

noStore < SCALAR >

When set to 1, the method next will not add the analyzed frame into the frames array, in order to avoid memory exhaustion. The default is to store frames (so to perform memory exhaustion ;) ).

timeoutOnNext < SCALAR >

When set to a value, a timeout will occur if no new frame is received within the SCALAR value seconds. The default is 3 seconds. A 0 value means no timeout at all. If a timeout occur, the global $Net::Packet::Timeout is set to a true value.

METHODS

new ( OPTIONS )

Create an object. The global $Net::Packet::Dump variable will be set to the newly created object. The default is to auto-call the start method, to override this set the callStart option to 0. Also the file created will be deleted after the object goes out of scope, use unlinkOnDestroy option to change this behaviour.

start

Start packet capture, the file specified is created, unless it exists and the overwrite option is not set. The instance date isRunning is set to 1.

isRunning

Returns 1 or 0 respectively if the process is running or not.

stop

Stop packet capture. isRunning is set to 0, and the file is not touched, only when the object goes out of scope does this.

analyze

Parse captured packets (from a .pcap file) and return an array of Net::Packet::Frame objects.

frames

Returns the analyzed frames as an array of Net::Packet::Frame objects, or an empty array if none have been analyzed.

next

Returns the next captured frame as a Net::Packet::Frame object. Returns undef if no frame is waiting to be analyzed. By default, all new captured frames are stored into the frames array (accessed through frames method). The noStore option avoids this. If you have used the timeoutOnNext option, the global $Net::Packet::Timeout will be set to a true value, and undef value returned. Also, when the next awaiting frame is captured, it is stored in the nextFrame object data.

nextFrame

When the method next is called, and a frame was found and analyzed, it is stored here, and can be accessed by calling this method.

AUTHOR

Patrice <GomoR> Auffret

COPYRIGHT AND LICENSE

Copyright (c) 2004, Patrice <GomoR> Auffret

You may distribute this module under the terms of the Artistic license. See Copying file in the source distribution archive.

RELATED MODULES

NetPacket, Net::RawIP, Net::RawSock