Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Net::Packet::Dump(3)  User Contributed Perl Documentation Net::Packet::Dump(3)

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

	  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::Frame's

	  # 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	next or	nextAll	to convert captured frames from	.pcap file to

       Then, you can call recv method on your sent frames to see if a
       corresponding reply is waiting in the frames array attribute of

       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 by using
       noLayerWipe attribute.

       Since Net::Packet 3.00, it is also possible to create complete .pcap
       files, thanks to	the writer mode	(see SYNOPSIS).

       dev By default, this attribute is set to	dev found in default $Env
	   object. You can overwrite it	by specifying another one in new

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

	   Where to save captured frames. By default, a	random name file is
	   chosen, named like

	   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 know exactly that the filter will only catch what you
	   want	and not	perturbating traffic.

	   If the file exists, setting this to 1 will overwrite	it. Default to
	   not overwrite it.

	   Each	time next 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 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.

	   Is auto set to 1 when a timeout has occured.	It is not reset	to 0
	   automatically, you need to do it yourself.

	   If you want to capture in promiscuous mode, set it to 1. Default to

	   If you want to capture a different snaplen, set it a	number.
	   Default to 1514.

	   This	attribute tells	which datalink type is used for	.pcap files.

	   This	one stores a pointer to	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.

	   When	the capturing process is running (start	has been called), 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.

	   When	the clean method is called, and	this attribute is set to 1,
	   the file is deleted from disk. Set it to 0 to avoid this behaviour.
	   BEWARE: default to 1.

	   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.

	   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.

	   When	you crate a Net::Packet::Dump, you have	3 possible modes :
	   online, offline and writer. You need	to load	constants from
	   Net::Packet::Consts to have access to that (see SYNOPSIS). The
	   three constants are:




	   Default behaviour is	to use online mode.

	   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 Net::Packet framework own timestamping
	   system. The default is 0. Set it manually to	1 if you need original
	   .pcap frames	timestamps.

       frames [is an arrayref]
	   Stores all analyzed frames found in a pcap file in this arrayref.

       framesSorted [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.

       new 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

	   Returns 1 if	Net::Packet::Dump object is respectively set to
	   online, offline or writer mode. 0 otherwise.

	   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 overwrite	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 isRunning attribute	to 1 when called.

	   You MUST manually call this method to stop the process. In online
	   mode, it will not remove the	generated .pcap	file, you MUST call
	   clean method. In offline mode, it will to nothing. In writer	mode,
	   it will call	Net::Pcap::dump_close method. Then, it will set
	   isRunning attribute to 0.

	   These methods will tell you if your current process is respectively
	   the father, or son process of Net::Packet::Dump object.

	   You MUST call this method manually. It will never be	called by
	   Net::Packet framework. This method will remove the generated	.pcap
	   file	in online mode if the unlinkOnClean attribute is set to	1. In
	   other modes,	it will	do nothing.

	   Tries to get	packet statistics on an	open descriptor. It returns a
	   reference to	a hash that has	to following fields: ps_recv, ps_drop,

	   Will	removed	all analyzed frames from frames	array and framesSorted
	   hash. Use it	with caution, because recv from	Net::Packet::Frame
	   relies on those.

	   Returns the next captured frame; 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
	   arrayref, and in framesSorted hashref, used to quickly recv it (see
	   Net::Packet::Frame),	and internal counter for time elapsed since
	   last	received packet	is reset.

	   Calls next method until it returns undef (meaning no	new frame
	   waiting to be analyzed from pcap file).

       write (scalar)
	   In writer mode, this	method takes a Net::Packet::Frame as a
	   parameter, and writes it to the .pcap file. Works only in writer

	   Used	to reset manually the timeout attribute. This is a helper

       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.

       framesSorted (scalar)
	   Method mostly used internally to store in a hashref a captured
	   frame. This is used to retrieve it quickly on recv call.

	   Constants for first layers within the pcap file.

	   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

perl v5.32.1			  2009-11-09		  Net::Packet::Dump(3)


Want to link to this manual page? Use this URL:

home | help