.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::RawIP 3pm"
.TH Net::RawIP 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Net::RawIP \- Perl extension to manipulate raw IP packets with interface to libpcap
.SH VERSION
.IX Header "VERSION"
This is the documentation of \f(CW\*(C`Net::RawIP\*(C'\fR version 0.25
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  use Net::RawIP;
\&
\&  $n = Net::RawIP\->new({
\&                        ip  => {
\&                                saddr => \*(Aqmy.target.lan\*(Aq,
\&                                daddr => \*(Aqmy.target.lan\*(Aq,
\&                               },
\&                       });
\&                        tcp => {
\&                                source => 139,
\&                                dest   => 139,
\&                                psh    => 1,
\&                                syn    => 1,
\&                               },
\&                       });
\&  $n\->send;
\&  $n\->ethnew("eth0");
\&  $n\->ethset(source => \*(Aqmy.target.lan\*(Aq, dest =>\*(Aqmy.target.lan\*(Aq);    
\&  $n\->ethsend;
\&  $p = $n\->pcapinit("eth0", "dst port 21", 1500, 30);
\&  $f = dump_open($p, "/my/home/log");
\&  loop($p, 10, \e&dump, $f);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This package provides a class which can be used for
creating, manipulating and sending raw IP packets with
optional features for manipulating Ethernet headers.
.PP
\&\fBNote:\fR Ethernet related methods are implemented on Linux and *BSD only.
.PP
As its name implies, this module is quite low-level, and currently 
duplicates some features with \f(CW\*(C`Net::Pcap\*(C'\fR. If you prefer a 
higher-level module (in terms of Perl support), please take a look
at \f(CW\*(C`Net::Write\*(C'\fR, which provides a portable interface to construct 
and send raw packets on the network.
.SH "Exported constants"
.IX Header "Exported constants"
.Vb 4
\&  PCAP_ERRBUF_SIZE
\&  PCAP_VERSION_MAJOR
\&  PCAP_VERSION_MINOR
\&  lib_pcap_h
.Ve
.SH "Exported functions"
.IX Header "Exported functions"
open_live
open_offline
dump_open
lookupdev
lookupnet
dispatch
loop
dump
compile
setfilter
next
datalink
snapshot
is_swapped
major_version
minor_version
stats
file
fileno
perror
geterr
strerror
close
dump_close
timem
linkoffset
ifaddrlist
rdev
.PP
By default exported functions are the \fBloop\fR, \fBdispatch\fR, \fBdump_open\fR, \fBdump\fR,
\&\fBopen_live\fR, \fBtimem\fR, \fBlinkoffset\fR, \fBifaddrlist\fR, \fBrdev\fR. 
You have to use the export tag \fBpcap\fR for export all of the pcap functions.
Please read the docs for the libpcap and look at \fBNet::RawIP::libpcap\fR\|(3pm).
.PP
Please look at the examples in the examples/ folder of the distribution.
.SH METHODS
.IX Header "METHODS"
.IP new 3
.IX Item "new"
.Vb 4
\&    Net::RawIP\->new({
\&              ARGPROTO => {PROTOKEY => PROTOVALUE,...} 
\&              ip       => {IPKEY => IPVALUE,...},
\&      })
.Ve
.Sp
\&\fBARGPROTO\fR is one of (\fBtcp\fR, \fBudp\fR, \fBicmp\fR, \fBgeneric\fR) defining the
protocol of the current packet. Defaults to \fBtcp\fR.
.Sp
You can \fBNOT\fR change protocol in the object after its creation.  Unless you
want your packet to be TCP, you must set the protocol type in the \fBnew()\fR call.
.Sp
The possible values of \fBPROTOKEY\fR depend on the value of ARGPROTO
.Sp
If ARGPROTO is <tcp> PROTOKEY can be one of 
(\fBsource\fR, \fBdest\fR, \fBseq\fR, \fBack_seq\fR, \fBdoff\fR, \fBres1\fR, \fBres2\fR, 
\&\fBurg\fR, \fBack\fR, \fBpsh\fR, \fBrst\fR, \fBsyn\fR, \fBfin\fR, \fBwindow\fR, \fBcheck\fR,
\&\fBurg_ptr\fR, \fBdata\fR).
.Sp
If ARGPROTO is \fBicmp\fR PROTOKEY can be one of
(\fBtype\fR, \fBcode\fR, \fBcheck\fR, \fBgateway\fR, \fBid\fR, \fBsequence\fR, \fBunused\fR, 
\&\fBmtu\fR, \fBdata\fR).
.Sp
If ARGPROTO is \fBudp\fR PROTOKEY can be one of 
(\fBsource\fR, \fBdest\fR, \fBlen\fR, \fBcheck\fR, \fBdata\fR)
.Sp
If ARGPROTO is \fBgeneric\fR PROTOKEY can be \fBdata\fR only.
.Sp
The \fBdata\fR entries are scalars containing packed network byte order
data.
.Sp
As the real icmp packet is a C union one can specify only one 
of the following set of values.
.RS 3
.IP \(bu 4
\&\fBgateway\fR \- (int)
.IP \(bu 4
(\fBid\fR and \fBsequence\fR) \- (short and short)
.IP \(bu 4
(\fBmtu\fR and \fBunused\fR) \- (short and short)
.RE
.RS 3
.Sp
The default values are:
.IP \(bu 4
(0,0,0,0,5,0,0,0,0,0,0,0,0,0xffff,0,0,'') for tcp
.IP \(bu 4
(0,0,0,0,0,0,0,0,'') for icmp
.IP \(bu 4
(0,0,0,0,'') for udp
.IP \(bu 4
('') for generic
.RE
.RS 3
.Sp
The valid values for \fBurg\fR \fBack\fR \fBpsh\fR \fBrst\fR \fBsyn\fR \fBfin\fR are 0 or 1.
The value of \fBdata\fR is a string. Length of the result packet will be calculated
if you do not specify non-zero value for \fBtot_len\fR.
.Sp
The value of \fBip\fR is a hash defining the parameters of the IP header
(\fBiphdr\fR) in the current IP packet.
.Sp
\&\fBIPKEY\fR is one of (\fBversion\fR, \fBihl\fR, \fBtos\fR, \fBtot_len\fR, \fBid\fR,
\&\fBfrag_off\fR, \fBttl\fR, \fBprotocol\fR, \fBcheck\fR, \fBsaddr\fR, \fBdaddr\fR).
You can to specify any and all of the above parameters.
If \fBcheck\fR is not given checksum will be calculated automatically.
.Sp
The values of the \fBsaddr\fR and the \fBdaddr\fR can be hostname
(e.g. www.oracle.com ) or IP address (205.227.44.16),
and even the integer value if you happen to know what is 205.227.44.16 
as an unsigned int in the host format ;).
.Sp
Examples:
.Sp
.Vb 1
\&    my $rawip = Net::RawIP\->new({udp =>{}});
.Ve
.Sp
or
.Sp
.Vb 1
\&    my $rawip = Net::RawIP\->new({ip => { tos => 22 }, udp => { source => 22,dest =>23 } });
.Ve
.Sp
The default values of the \fBip\fR hash are
.IP \(bu 4
(4,5,16,0,0,0x4000,64,6,0,0,0) for \fBtcp\fR
.IP \(bu 4
(4,5,16,0,0,0x4000,64,17,0,0,0) for \fBudp\fR
.IP \(bu 4
(4,5,16,0,0,0x4000,64,1,0,0,0) for \fBicmp\fR
.IP \(bu 4
(4,5,16,0,0,0x4000,64,0,0,0,0) for \fBgeneric\fR
.RE
.RS 3
.RE
.IP dump_open 3
.IX Item "dump_open"
If \fBdump_open\fR opens and returns a valid file descriptor, this descriptor 
can be used in the perl callback as a perl filehandle.
.IP loop 3
.IX Item "loop"
.PD 0
.IP dispatch 3
.IX Item "dispatch"
.PD
\&\fBloop\fR and \fBdispatch\fR can run a perl code refs as a callbacks for packet 
analyzing and printing.
the fourth parameter for \fBloop\fR and \fBdispatch\fR can be an array or a hash 
reference and it can be dereferenced in a perl callback.
.IP next 3
.IX Item "next"
\&\fBnext()\fR returns a string (next packet).
.IP timem 3
.IX Item "timem"
\&\fBtimem()\fR returns a string that looks like \fBsec\fR.\fBmicrosec\fR, 
where the \fBsec\fR and the \fBmicrosec\fR are the values returned by
\&\fBgettimeofday\fR\|(3).
If \fBmicrosec\fR is less than 100000 then zeros will be added to the 
left side of \fBmicrosec\fR for adjusting to six digits.
.Sp
Similar to sprintf("%.6f", \fBTime::HiRes::time()\fR);
.IP linkoffset 3
.IX Item "linkoffset"
The function which called \fBlinkoffset\fR returns a number of the bytes
in the link protocol header e.g. 14 for a Ethernet or 4 for a Point-to-Point
protocol. This function has one input parameter (pcap_t*) that is returned
by open_live.
.IP ifaddrlist 3
.IX Item "ifaddrlist"
\&\fBifaddrlist()\fR returns a hash reference. In this hash keys are 
the running network devices, values are ip addresses of those devices 
in an internet address format.
.IP rdev 3
.IX Item "rdev"
\&\fBrdev()\fR returns a name of the outgoing device for given destination address.
It has one input parameter (destination address in an internet address
or a domain name or a host byteorder int formats).
.IP proto 3
.IX Item "proto"
Returns the name of the subclass current object e.g. \fBtcp\fR.
No input parameters.
.IP packet 3
.IX Item "packet"
Returns a scalar which contain the packed ip packet of the current object.
No input parameters.
.IP set 3
.IX Item "set"
Method for setting the parameters of the current object. The given parameters
must look like the parameters for the constructor.
.IP bset($packet,$eth) 3
.IX Item "bset($packet,$eth)"
Method for setting the parameters of the current object.
\&\fR\f(CB$packet\fR\fB\fR is a scalar which contain binary structure (an ip or an eth packet).
This scalar must match with the subclass of the current object.
If \fB\fR\f(CB$eth\fR\fB\fR is given and it have a non-zero value then assumed that packet is a
ethernet packet,otherwise it is a ip packet.
.IP get 3
.IX Item "get"
is a method for get the parameters from the current object. This method returns
the array which will be filled with an asked parameters in order as they have ordered in
packet if you'd call it with an array context.
If this method is called with a scalar context then it returns a hash reference.
In that hash will stored an asked parameters as values,the keys are their names.
.Sp
The input parameter is a hash reference. In this hash can be three keys.
They are a \fBip\fR and an one of the \fBARGPROTO\fRs. The value must be an array reference. This
array contain asked parameters.
E.g. you want to know current value of the tos from the iphdr and
the flags of the tcphdr.
Here is a code :
.Sp
.Vb 4
\&  ($tos,$urg,$ack,$psh,$rst,$syn,$fin) = $packet\->get({
\&            ip => [qw(tos)],
\&        tcp => [qw(psh syn urg ack rst fin)]
\&        });
.Ve
.Sp
The members in the array can be given in any order.
.Sp
For get the ethernet parameters you have to use the key \fBeth\fR and the 
values of the array (\fBdest\fR,\fBsource\fR,\fBproto\fR). The values of the \fBdest\fR and 
the \fBsource\fR will look like the output of the \fBifconfig\fR\|(8) e.g. 00:00:E8:43:0B:2A.
.IP open_live 3
.IX Item "open_live"
.PD 0
.IP send($delay,$times) 3
.IX Item "send($delay,$times)"
.PD
is a method which has used for send raw ip packet.
The input parameters are the delay seconds and the times for repeating send.
If you do not specify parameters for the \fBsend\fR,then packet will be sent once
without delay. 
If you do specify for the times a negative value then packet will be sent forever.
E.g. you want to send the packet for ten times with delay equal to one second.
Here is a code :
.Sp
.Vb 1
\&    $packet\->send(1,10);
.Ve
.Sp
The delay could be specified not only as integer but 
and as 0.25 for sleep to 250 ms or 3.5 to sleep for 3 seconds and 500 ms.
.IP pcapinit($device,$filter,$psize,$timeout) 3
.IX Item "pcapinit($device,$filter,$psize,$timeout)"
is a method for some a pcap init. The input parameters are a device,a string with
a program for a filter,a packet size,a timeout.
This method will call the function open_live,then compile the filter string by \fBcompile()\fR,
set the filter and returns the pointer (\fBpcap_t *\fR).
.IP pcapinit_offline($fname) 3
.IX Item "pcapinit_offline($fname)"
is a method for an offline pcap init.The input parameter is a name of the file
which contains raw output of the libpcap dump function.
Returns the pointer (\fBpcap_t *\fR).
.ie n .IP "\fBethnew\fR(\fR\fB$device\fR\fB\fR,\fBdest\fR => \fBARGOFDEST\fR,\fBsource\fR => \fBARGOFSOURCE\fR)" 3
.el .IP "\fBethnew\fR(\fR\f(CB$device\fR\fB\fR,\fBdest\fR => \fBARGOFDEST\fR,\fBsource\fR => \fBARGOFSOURCE\fR)" 3
.IX Item "ethnew($device,dest => ARGOFDEST,source => ARGOFSOURCE)"
is a method for init the ethernet subclass in the current object, \fR\f(CB$device\fR\fB\fR is a
required parameter,\fBdest\fR and \fBsource\fR are an optional, \fB\fR\f(CB$device\fR\fB\fR is an ethernet
device e.g. \fBeth0\fR, an \fBARGOFDEST\fR and an \fBARGOFSOURCE\fR are a the ethernet addresses
in the ethernet header of the current object.
.Sp
The \fBARGOFDEST\fR and the \fBARGOFSOURCE\fR can be given as a string which contain 
just 6 bytes of the real ethernet address or like the output of the \fBifconfig\fR\|(8) 
e.g. 00:00:E8:43:0B:2A or just an ip address or a hostname of a target, 
then a mac address will be discovered automatically.
.Sp
The ethernet frame will be sent with given addresses.
By default the \fBsource\fR and the \fBdest\fR will be filled with a hardware address of   
the \fR\f(CB$device\fR\fB\fR.
.Sp
\&\fBNOTE:\fR For use methods which are related to the ethernet you have to before initialize
ethernet subclass by \fBethnew\fR.
.IP ethset 3
.IX Item "ethset"
is a method for set an ethernet parameters in the current object.
The given parameters must look like parameters for the \fBethnew\fR without
a \fR\f(CB$device\fR\fB\fR.
.IP ethsend 3
.IX Item "ethsend"
is a method for send an ethernet frame.
The given parameters must look like a parameters for the \fBsend\fR.
.IP send_eth_frame($frame,$times,$delay) 3
.IX Item "send_eth_frame($frame,$times,$delay)"
is a method for send any ethernet frame which you may construct by
hands.\fR\f(CB$frame\fR\fB\fR is a packed ethernet frame exept destination and
source fields(these fields can be setting by \fBethset\fR or \fBethnew\fR).
Another parameters must look like the parameters for the \fBsend\fR.
.IP "optset(OPTPROTO => { type => [...],data => [...] },...)" 3
.IX Item "optset(OPTPROTO => { type => [...],data => [...] },...)"
is a method for set an IP and a TCP options.
The parameters for the optset must be given as a key-value pairs.  
The \fBOPTPROTO\fR,s are the prototypes of the options(\fBip\fR,\fBtcp\fR),values are the hashes
references.The keys in this hashes are \fBtype\fR and \fBdata\fR.
The value of the \fBtype\fR is an array reference.
This array must be filled with an integers.Refer to a RFC for a valid types.The value of 
the \fBdata\fR also is an array reference. This array must be filled 
with strings which must contain all bytes from a option except bytes 
with type and length of an option.Of course indexes in those arrays must be 
equal for the one option.If type is equal to 0 or 1 then there is no bytes
with a length and a data,but you have to specify zero data for compatibility.
.IP "\fBoptget\fR(OPTPROTO => { type => [...] },...)" 3
.IX Item "optget(OPTPROTO => { type => [...] },...)"
is a method for get an IP and a TCP options.
The parameters for the optget must be given as key-value pairs.
The \fBOPTPROTO\fR is the prototype of the options(\fBip\fR,\fBtcp\fR),the values are 
the hashes references.The key is the \fBtype\fR.The value of the \fBtype\fR is an array reference.
The return value is an array which will be filled with asked types,lengths,datas
of the each type of the option in order as you have asked.If you do not specify type then
all types,lengths,datas of an options will be returned.
E.g. you want to know all the IP options from the current object.
Here is a code:
.Sp
.Vb 1
\&    @opts = $n\->optget(ip => {});
.Ve
.Sp
E.g. you want to know just the IP options with the type which equal to 131 and 137.
Here is a code:
.Sp
.Vb 4
\&    ($t131,$l131,$d131,$t137,$l137,$d137) = $n\->optget(
\&                                   ip =>{
\&                        type =>[(131,137)]
\&                        }        );
.Ve
.IP \fBoptunset\fR 3
.IX Item "optunset"
is a method for unset a subclass of the IP or the TCP options from a current
object.It can be used if you  won't use options in the current object later.
This method must be used only after the \fBoptset\fR.
The parameters for this method are the \fBOPTPROTO\fR's. 
E.g. you want to unset an IP options.
Here is a code:
.Sp
.Vb 1
\&    $n\->optunset(\*(Aqip\*(Aq);
.Ve
.Sp
E.g. you want to unset a TCP and an IP options.
Here is a code:
.Sp
.Vb 1
\&    $n\->optunset(\*(Aqip\*(Aq,\*(Aqtcp\*(Aq);
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBpcap\fR\|(3), \fBtcpdump\fR\|(1), RFC 791\-793, RFC 768.
.PP
Net::Pcap, Net::Pcap::Easy, Net::Pcap::Reassemble,
Net::Pcap::FindDevice
.PP
Net::Write for an alternative module to send raw packets on the network
.SH AUTHORS
.IX Header "AUTHORS"
Current maintainer is Sébastien Aperghis-Tramoni 
<sebastien@aperghis.net>
.PP
Previous authors & maintainers:
.IP \(bu 4
Sergey Kolychev <ksv@al.lg.ua>
.IP \(bu 4
Gabor Szabo <gabor@pti.co.il>
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright (c) 1998\-2006 Sergey Kolychev. All rights reserved. This program is free
software; you can redistribute it and/or modify it under the same terms
as Perl itself.
.SH CREDITS
.IX Header "CREDITS"
Steve Bonds <u5rhsiz02@sneakemail.com>
  + work on some endianness bugs and improving code comments