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.