GSP
Quick Navigator

Search Site

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

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


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

.ds Aq ’

NAME

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

CONTENTS

SYNOPSIS



   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
   $dump->start;

   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
   $dump->stop;
   $dump->clean;

   #
   # 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
   $dump2->start;
   $dump2->nextAll;

   # 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
   $dump2->stop;
   $dump2->clean;

   #
   # Example writing mode
   #

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

   $dump3->start;

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

   # Write them
   $dump3->write($frame);

   # Cleanup
   $dump3->stop;
   $dump3->clean;



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 <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>).

ATTRIBUTES

<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:

NP_DUMP_MODE_ONLINE

NP_DUMP_MODE_OFFLINE

NP_DUMP_MODE_WRITER

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.

METHODS

<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

mode: NP_DUMP_MODE_ONLINE

keepTimestamp: 0

<B>isModeOnlineB>
<B>isModeOfflineB>
<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>isFatherB>
<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.

CONSTANTS

<B>NP_DUMP_LINK_NULLB>
<B>NP_DUMP_LINK_EN10MBB>
<B>NP_DUMP_LINK_RAWB>
<B>NP_DUMP_LINK_SLLB> Constants for first layers within the pcap file.
<B>NP_DUMP_MODE_OFFLINEB>
<B>NP_DUMP_MODE_ONLINEB>
<B>NP_DUMP_MODE_WRITERB> Constants to set the dump mode.

AUTHOR

Patrice <GomoR> Auffret

COPYRIGHT AND LICENSE

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.

RELATED MODULES

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.