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)

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

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::Frame's
	  $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	next or	nextAll	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 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).

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

       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.

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

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

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

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

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

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

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

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

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

       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.

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

	   NP_DUMP_MODE_ONLINE

	   NP_DUMP_MODE_OFFLINE

	   NP_DUMP_MODE_WRITER

	   Default behaviour is	to use online mode.

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

METHODS
       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

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

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

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

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

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

       getStats
	   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,
	   ps_ifdrop.

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

       nextAll
	   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
	   mode.

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

       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
       NP_DUMP_LINK_NULL
       NP_DUMP_LINK_EN10MB
       NP_DUMP_LINK_RAW
       NP_DUMP_LINK_SLL
	   Constants for first layers within the pcap file.

       NP_DUMP_MODE_OFFLINE
       NP_DUMP_MODE_ONLINE
       NP_DUMP_MODE_WRITER
	   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

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

NAME | SYNOPSIS | DESCRIPTION | ATTRIBUTES | METHODS | CONSTANTS | AUTHOR | COPYRIGHT AND LICENSE | RELATED MODULES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Packet::Dump&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help