NAME
Net::Packet::Dump - a tcpdump-like object providing frame capturing
SYNOPSIS
use Net::Packet::Dump;
#
# Example live capture (sniffer like)
#
# Instanciate object, will start capturing from network
my $dump = Net::Packet::Dump->new(
filter => 'tcp',
noStore => 1,
);
while (1) {
if (my $frame = $dump->next) {
print $frame->l2->print, "\n" if $frame->l2;
print $frame->l3->print, "\n" if $frame->l3;
print $frame->l4->print, "\n" if $frame->l4;
print $frame->l7->print, "\n" if $frame->l7;
}
}
#
# Example offline analysis
#
my $dump2 = Net::Packet::Dump->new(
unlinkOnDestroy => 0,
file => 'existant-file.pcap',
callStart => 0,
);
# Analyze the .pcap file, build an array of Net::Packet::Frame's
$dump->analyze;
# Browses captured frames
for ($dump->frames) {
# Do what you want
print $_->l2->print, "\n" if $_->l2;
print $_->l3->print, "\n" if $_->l3;
print $_->l4->print, "\n" if $_->l4;
print $_->l7->print, "\n" if $_->l7;
}DESCRIPTION
This module is the capturing part of Net::Packet framework. It is basically a tcpdump process. When a capture starts, the tcpdump process is forked, and saves all traffic to a .pcap file. The parent process can call next, nextAll or analyze to convert captured frames from .pcap file to Net::Packet::Frames.
Then, you can call recv method on your sent frames to see if a corresponding reply is waiting in the frames array attribute of Net::Packet::Dump.
By default, if you use this module to analyze frames you've sent (very likely ;)), and you've sent those frames at layer 4 (using Net::Packet::DescL4) (for example), lower layers will be wiped on storing in frames array. This behaviour can be disabled using noLayerWipe attribute.
ATTRIBUTES
- env
-
Stores a Net::Packet::Env object. It is used in start method, for example. The default is to use the global $Env object created when using Net::Packet.
- file
-
Where to save captured frames. By default, a random name file is chosen, named like `netpacket-tmp-$$.@{[getRandom32bitsInt()]}.pcap'.
- filter
-
A pcap filter to restrain what to capture. It also works in offline mode, to analyze only what you want, and not all traffic. Default to capture all traffic. WARNING: every time a packet passes this filter, and the next method is called, the internal counter used by b<timeoutOnNext> is reset. So the timeout attribute can only be used if you now exactly that the filter will only catch what you want and not perturbating traffic.
- overwrite
-
If the file exists, setting this to 1 will overwrite it. Default to not overwrite it.
- waitOnStop
-
When the stop method is called, you should wait a few seconds before stopping the capture. The default is to wait for 3 seconds.
- timeout
-
Is auto set to 1 when a timeout has occured. It is not set to 0 automatically, you need to do it yourself.
- timeoutOnNext
-
Each time next method is called, an internal counter is incremented if no frame has been capture. When a frame is captured (that is, a frame passed the pcap filter), the timeout attribute is reset to 0. When the counter reaches the value of timeoutOnNext, the timeout attribute is set to 1, meaning no frames have been captured during the specified amount of time. Default to 3 seconds.
- nextFrame
-
This one stores the latest received frame after a call to next method. If a next call is done, and no frame is received, this attribute is set to undef.
- callStart
-
When set to 1, the capturing process starts right after new method has finished executing. When set to 0, you must call start method to start capturing. Default to 1.
- isRunning
-
When the capturing process is running, this is set to 1. So, when start method has been called, it is set to 1, and when stop method is called, set to 0.
- unlinkOnDestroy
-
When the Net::Packet::Dump object goes out of scope, the DESTROY method is called, and if this attribute is set to 1, the file is removed. BEWARE: default to 1.
- noStore
-
If you set this attribute to 1, frames will not be stored in frames array. It is used in sniffer-like programs, in order to avoid memory exhaustion by keeping all captured Net::Packet::Frame into memory. Default is to store frames.
- noLayerWipe
-
As explained in DESCRIPTION, if you send packets at layer 4, layer 2 and 3 are not keeped when stored in frames. The same is true when sending at layer 3 (layer 2 is not kept). Default to wipe those layers. WARNING: if you set it to 1, and you need the recv method from Net::Packet::Frame, it will fail. In fact, this is a speed improvements, that is in order to find matching frame for your request, they are stored in a hash, using layer as keys (getKey and getKeyReverse are used to get keys from each layer. So, if you do not wipe layers, a key will be used to store the frame, but another will be used to search for it, and no match will be found. This is a current limitation I'm working on to remove.
- noEnvSet
-
By default, when a Net::Packet::Dump object is created, the default $Env object has its dump attribute pointing to it. If you do not want this behaviour, you can disable it by setting it to 1. Default to 0.
- frames
-
Stores all analyzed frames found in a pcap file in this array.
- framesSorted
-
Stores all analyzed frames found in a pcap file in this hash, using keys to store and search related packet request/replies.
METHODS
- new
-
Object contructor. Default values for attributes:
env: $Env
file: "netpacket-tmp-$$.@{[getRandom32bitsInt()]}.pcap"
filter: ""
overwrite: 0
waitOnStop: 3
timeout: 0
timeoutOnNext: 3
callStart: 1
isRunning: 0
unlinkOnDestroy: 1
noStore: 0
noLayerWipe: 0
noEnvSet: 0
- start
-
Forks the tcpdump-like process that do frame capturing saved to a file. It does not forks a new process if the specified file attribute exists, and overwrite attributes is set to 0. It also sets isRunning to 1 if a process is forked.
- stop
-
Kills the tcpdump-like process, and sets isRunning to 0. It first waits waitOnStop seconds before killing it.
- flush
-
Will removed all analyzed frames from frames array and framesSorted hash. Use it with caution, because recv from Net::Packet::Frame relies on those.
- next
-
Returns the next captured frames; undef if none found in .pcap file. In all cases, nextFrame attribute is set (either to the captured frame or undef). Each time this method is run, a comparison is done to see if no frame has been captured during timeoutOnNext amount of seconds. If so, timeout attribute is set to 1 to reflect the pending timeout. When a frame is received, it is stored in frames array, and in framesSorted hash, used to quickly recv it (see Net::Packet::Frame), and internal counter for time elapsed since last received packet is reset.
- nextAll
- analyze
-
Calls next method until it returns undef (meaning no new frame waiting to be analyzed from pcap file).
- framesFor (scalar)
-
You pass a Net::Packet::Frame has parameter, and it returns an array of all frames relating to the connection. For example, when you send a TCP SYN packet, this method will return TCP packets relating to the used source/destination IP, source/destination port, and also related ICMP packets.
AUTHOR
Patrice <GomoR> Auffret
COPYRIGHT AND LICENSE
Copyright (c) 2004-2006, Patrice <GomoR> Auffret
You may distribute this module under the terms of the Artistic license. See Copying file in the source distribution archive.