Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  NET::PACKET::DUMP (3)

.ds Aq ’


Net::Packet::Dump - a tcpdump-like object providing frame capturing and more



   require Net::Packet::Dump;
   use Net::Packet::Consts qw(:dump);

   # Example live capture (sniffer like)

   # Instanciate object
   my $dump = Net::Packet::Dump->new(
      mode          => NP_DUMP_MODE_ONLINE,
      file          => live.pcap,
      filter        => tcp,
      promisc       => 1,
      snaplen       => 1514,
      noStore       => 1,
      keepTimestamp => 1,
      unlinkOnClean => 0,
      overwrite     => 1,
   # Start capture

   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;

   # Cleanup

   # Example offline analysis

   my $dump2 = Net::Packet::Dump->new(
      mode          => NP_DUMP_MODE_OFFLINE,
      file          => existant-file.pcap,
      unlinkOnClean => 0,

   # Analyze the .pcap file, build an array of Net::Packet::Frames

   # Browses captured frames
   for ($dump2->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;

   # Cleanup

   # Example writing mode

   my $dump3 = Net::Packet::Dump->new(
      mode      => NP_DUMP_MODE_WRITER,
      file      => write.pcap,
      overwrite => 1,


   # Build or capture some frames here
   my $frame = Net::Packet::Frame->new;

   # Write them

   # Cleanup


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 <B>nextB> or <B>nextAllB> to convert captured frames from .pcap file to <B>Net::Packet::FrameB>s.

Then, you can call <B>recvB> method on your sent frames to see if a corresponding reply is waiting in the <B>framesB> array attribute of <B>Net::Packet::DumpB>.

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 <B>Net::Packet::DescL4B>) (for example), lower layers will be wiped on storing in <B>framesB> array. This behaviour can be disabled by using <B>noLayerWipeB> attribute.

Since <B>Net::PacketB> 3.00, it is also possible to create complete .pcap files, thanks to the writer mode (see <B>SYNOPSISB>).


<B>devB> By default, this attribute is set to <B>devB> found in default <B>B>$Env<B>B> object. You can overwrite it by specifying another one in <B>newB> constructor.
<B>envB> Stores a <B>Net::Packet::EnvB> object. It is used in <B>startB> method, for example. The default is to use the global <B>B>$Env<B>B> object created when using <B>Net::Packet::EnvB>.
<B>fileB> Where to save captured frames. By default, a random name file is chosen, named like ‘netpacket-tmp-$$.@{[getRandom32bitsInt()]}.pcap’.
<B>filterB> 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 <B>nextB> method is called, the internal counter used by b<timeoutOnNext> is reset. So the <B>timeoutB> attribute can only be used if you know exactly that the filter will only catch what you want and not perturbating traffic.
<B>overwriteB> If the <B>fileB> exists, setting this to 1 will overwrite it. Default to not overwrite it.
<B>timeoutOnNextB> Each time <B>nextB> method is called, an internal counter is incremented if no frame has been captured. When a frame is captured (that is, a frame passed the pcap filter), the <B>timeoutB> attribute is reset to 0. When the counter reaches the value of <B>timeoutOnNextB>, the <B>timeoutB> attribute is set to 1, meaning no frames have been captured during the specified amount of time. Default to 3 seconds.
<B>timeoutB> Is auto set to 1 when a timeout has occured. It is not reset to 0 automatically, you need to do it yourself.
<B>promiscB> If you want to capture in promiscuous mode, set it to 1. Default to 0.
<B>snaplenB> If you want to capture a different snaplen, set it a number. Default to 1514.
<B>linkB> This attribute tells which datalink type is used for .pcap files.
<B>nextFrameB> This one stores a pointer to the latest received frame after a call to <B>nextB> method. If a <B>nextB> call is done, and no frame is received, this attribute is set to undef.
<B>isRunningB> When the capturing process is running (<B>startB> has been called), this is set to 1. So, when <B>startB> method has been called, it is set to 1, and when <B>stopB> method is called, set to 0.
<B>unlinkOnCleanB> When the <B>cleanB> method is called, and this attribute is set to 1, the <B>fileB> is deleted from disk. Set it to 0 to avoid this behaviour. BEWARE: default to 1.
<B>noStoreB> If you set this attribute to 1, frames will not be stored in <B>framesB> array. It is used in sniffer-like programs, in order to avoid memory exhaustion by keeping all captured <B>Net::Packet::FrameB> into memory. Default is to store frames.
<B>noLayerWipeB> As explained in DESCRIPTION, if you send packets at layer 4, layer 2 and 3 are not keeped when stored in <B>framesB>. 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 <B>recvB> method from <B>Net::Packet::FrameB>, 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 (<B>getKeyB> and <B>getKeyReverseB> 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.
<B>modeB> When you crate a <B>Net::Packet::DumpB>, you have 3 possible modes : online, offline and writer. You need to load constants from <B>Net::Packet::ConstsB> to have access to that (see <B>SYNOPSISB>). The three constants are:




Default behaviour is to use online mode.

<B>keepTimestampB> Sometimes, when frames are captured and saved to a .pcap file, timestamps sucks. That is, you send a frame, and receive the reply, but your request appear to have been sent after the reply. So, to correct that, you can use <B>Net::PacketB> framework own timestamping system. The default is 0. Set it manually to 1 if you need original .pcap frames timestamps.
<B>framesB> [is an arrayref] Stores all analyzed frames found in a pcap file in this arrayref.
<B>framesSortedB> [is an hashref] Stores all analyzed frames found in a pcap file in this hashref, using keys to store and search related frames request/replies.


<B>newB> Object contructor. Default values for attributes:

dev: $Env->dev

env: $Env

file: netpacket-tmp-$$.@{[getRandom32bitsInt()]}.pcap

filter: ’’

overwrite: 0

timeout: 0

promisc: 0

snaplen: 1514

timeoutOnNext: 3

isRunning: 0

unlinkOnClean: 1

noStore: 0

noLayerWipe: 0


keepTimestamp: 0

<B>isModeWriterB> Returns 1 if <B>Net::Packet::DumpB> object is respectively set to online, offline or writer mode. 0 otherwise.
<B>startB> You MUST manually call this method to start frame capture, whatever mode you are in. In online mode, it will fork a tcpdump-like process to save captured frames to a .pcap file. It will not overwrite an existing file by default, use <B>overwriteB> attribute for that. In offline mode, it will only provide analyzing methods. In writer mode, it will only provide writing methods for frames. It will set <B>isRunningB> attribute to 1 when called.
<B>stopB> You MUST manually call this method to stop the process. In online mode, it will not remove the generated .pcap file, you MUST call <B>cleanB> method. In offline mode, it will to nothing. In writer mode, it will call <B>Net::Pcap::dump_closeB> method. Then, it will set <B>isRunningB> attribute to 0.
<B>isSonB> These methods will tell you if your current process is respectively the father, or son process of <B>Net::Packet::DumpB> object.
<B>cleanB> You MUST call this method manually. It will never be called by <B>Net::PacketB> framework. This method will remove the generated .pcap file in online mode if the <B>unlinkOnCleanB> attribute is set to 1. In other modes, it will do nothing.
<B>getStatsB> Tries to get packet statistics on an open descriptor. It returns a reference to a hash that has to following fields: <B>ps_recvB>, <B>ps_dropB>, <B>ps_ifdropB>.
<B>flushB> Will removed all analyzed frames from <B>framesB> array and <B>framesSortedB> hash. Use it with caution, because <B>recvB> from <B>Net::Packet::FrameB> relies on those.
<B>nextB> Returns the next captured frame; undef if none found in .pcap file. In all cases, <B>nextFrameB> 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 <B>timeoutOnNextB> amount of seconds. If so, <B>timeoutB> attribute is set to 1 to reflect the pending timeout. When a frame is received, it is stored in <B>framesB> arrayref, and in <B>framesSortedB> hashref, used to quickly <B>recvB> it (see <B>Net::Packet::FrameB>), and internal counter for time elapsed since last received packet is reset.
<B>nextAllB> Calls <B>nextB> method until it returns undef (meaning no new frame waiting to be analyzed from pcap file).
<B>writeB> (scalar) In writer mode, this method takes a <B>Net::Packet::FrameB> as a parameter, and writes it to the .pcap file. Works only in writer mode.
<B>timeoutResetB> Used to reset manually the <B>timeoutB> attribute. This is a helper method.
<B>framesForB> (scalar) You pass a <B>Net::Packet::FrameB> 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.
<B>framesSortedB> (scalar) Method mostly used internally to store in a hashref a captured frame. This is used to retrieve it quickly on <B>recvB> call.


<B>NP_DUMP_LINK_SLLB> Constants for first layers within the pcap file.
<B>NP_DUMP_MODE_WRITERB> Constants to set the dump mode.


Patrice <GomoR> Auffret


Copyright (c) 2004-2009, Patrice <GomoR> Auffret

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


NetPacket, Net::RawIP, Net::RawSock
Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 NET::PACKET::DUMP (3) 2009-11-09

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.