NAME

Net::PcapWriter - simple creation of pcap files from code

SYNOPSIS

 use Net::PcapWriter;

 # disabling checksum calculation leads to huge performance boost
 Net::PcapWriter::IP->calculate_checksums(0);

 my $writer = Net::PcapWriter->new('test.pcap');
 my $conn = $writer->tcp_conn('1.2.3.4',1234,'5.6.7.8',80);

 # this will automatically add syn..synack..ack handshake to pcap
 # each write will be a single packet
 $conn->write(0,"POST / HTTP/1.0\r\nContent-length: 3\r\n\r\n");
 $conn->ack(1); # force ack from server

 # send another packet w/o forcing ack
 $conn->write(0,"abc");

 # client will no longer write
 $conn->shutdown(0);

 # this will automatically add ack to last packet
 $conn->write(1,"HTTP/1.0 200 Ok\r\nContent-length: 10\r\n\r\n");
 $conn->write(1,"0123456789");

 # will automatically add remaining FIN+ACK
 undef $conn;

 # write some UDP packets with IPv6
 $conn = $writer->udp_conn('dead::beaf',1234,'beaf::dead',53);
 $conn->write(0,"....");
 $conn->write(1,"....");

 # write a ping exchange (works also with IPv6)
 $conn = $writer->icmp_echo_conn('1.2.3.4','5.6.7.8',10);
 $conn->ping(1,"foo");
 $conn->ping(2,"bar");
 $conn->pong(1,"foo");

DESCRIPTION

With Net::PcapWriter it is possible to create pcap files within a program without capturing any data. This is useful for setting up test data without setting up the needed infrastructure for data creation and capturing.

The following methods are supported:

$class->new([$filename|$handle])

Creates new object. If file name is given it will be opened for writing, if file handle is given it will be used. Otherwise the pcap data will be written to STDOUT. Will write pcap header for DLT_RAW to pcap file.

$class->reopen([$filename|$handle])

This will close the current pcap file and open a new one. No connections will be implicitely closed, i.e. they will continue inside the new pcap file. The main purpose is to be able to rotate the file after some time or size.

$writer->packet($pkt,[$timestamp])

Will write raw Layer 2 packet $pkt with $timestamp in pcap file. $timestamp can be time_t (seconds), float (like time_t, but with higher resolution) or <[$sec,$msec]> like in <struct timeval>. If $timestamp is not given will use Time::HiRes::gettimeofday.

To get the Layer 2 prefix in case of IP data use $writer-layer2prefix($ip)>.

$writer->tcp_conn($src,$sport,$dst,$dport)

Will return Net::PcapWriter::TCP object, which then provides the following methods:

$tcpconn->write($dir,$data,[$timestamp])

Will write the given data for the direction $dir (0 are data from client to server, 1 the other way). Will write TCP handshake if not done yet.

$tcpconn->ack($dir,[$timestamp])

Will write an empty message with an ACK from direction $dir.

$tcpconn->keepalive_probe($dir,[$timestamp])

Will write a TCP keep-alive probe from direction $dir, i.e. a packet with no payload and a sequence number one less than expected. To reply to this probe the peer should just ack it.

$tcpconn->shutdown($dir,[$timestamp])

Will add FIN+ACK for shutdown from direction $dir unless already done.

$tcpconn->write_with_flags($dir,$data,\%flags,[$timestamp])

Write a TCP packet with specific flags, like <{ syn = 1, ack => 1 }>>. This is also internally used to automatically add the initial handshake (i.e SYN from client, SYN+ACK from server and SYN+ACK from client) and the close of the connection (FIN), whereby the close can be easier handled with shutdown.

Possible flags are syn, ack, fin, rst, psh and rst.

If $data is undef only the internal state regarding the flags will be set.

$tcpconn->close($dir,$flag,[$timestamp]);

Close the connection. $dir is the side which initiates the close and $flag is how the connection is closed, i.e. 'fin', 'rst' or ''. In the last case no data will be written but only the internal state will be set to mark the connection as closed. This way no more closing data will be written on DESTROY of the object.

Note that the DESTROY of the object will automatically write a normal close (with FIN) if the connection is not yet considered closed and thus an explicit close is only needed if one needs more explicit control how the closing should look like.

$tcpconn->connect($dir,[$timestamp])

This will explicitely open the connection (3-way handshake) unless it is already open. This will be implicitely done if the connection is not fully open in case of write or shutdown so usually it is not necessary to call this function explicitely.

undef $tcpconn

Will call shutdown for both $dir before destroying connection object.

$writer->udp_conn($src,$sport,$dst,$dport)

Will return Net::PcapWriter::UDP object, which then provides the following methods:

$tcpconn->write($dir,$data,[$timestamp])

Will write the given data for the direction $dir (0 are data from client to server, 1 the other way).

$writer->icmp_echo_conn($src,$dst,[$id])

Will return Net::PcapWriter::ICMP_Echo object which provides a connection with echo request and reply using the identifier $id (default 0). This object can handle echo request/reply for ICMP and ICMPv6. It has the following methods:

$echo->ping($seq,$data,[$timestamp])

Will write an ICMP echo request from connection source to destination with sequence $seq and data $data.

$echo->pong($seq,$data,[$timestamp])

Will write an ICMP echo reply from connection destination to source with sequence $seq and data $data.

Additionally a huge performance boost can be reached by disabling checksum calculation:

   Net::PcapWriter::IP->calculate_checksums(0);

AUTHOR

Steffen Ullrich <sullr@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Steffen Ullrich.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.