Provided by: libnet-rawip-perl_0.25-2build6_amd64 bug

NAME

       Net::RawIP - Perl extension to manipulate raw IP packets with interface to libpcap

VERSION

       This is the documentation of "Net::RawIP" version 0.25

SYNOPSIS

         use Net::RawIP;

         $n = Net::RawIP->new({
                               ip  => {
                                       saddr => 'my.target.lan',
                                       daddr => 'my.target.lan',
                                      },
                              });
                               tcp => {
                                       source => 139,
                                       dest   => 139,
                                       psh    => 1,
                                       syn    => 1,
                                      },
                              });
         $n->send;
         $n->ethnew("eth0");
         $n->ethset(source => 'my.target.lan', dest =>'my.target.lan');
         $n->ethsend;
         $p = $n->pcapinit("eth0", "dst port 21", 1500, 30);
         $f = dump_open($p, "/my/home/log");
         loop($p, 10, \&dump, $f);

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.

       Note: Ethernet related methods are implemented on Linux and *BSD only.

       As its name implies, this module is quite low-level, and currently duplicates some
       features with "Net::Pcap". If you prefer a higher-level module (in terms of Perl support),
       please take a look at "Net::Write", which provides a portable interface to construct and
       send raw packets on the network.

Exported constants

         PCAP_ERRBUF_SIZE
         PCAP_VERSION_MAJOR
         PCAP_VERSION_MINOR
         lib_pcap_h

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

       By default exported functions are the loop, dispatch, dump_open, dump, open_live, timem,
       linkoffset, ifaddrlist, rdev.  You have to use the export tag pcap for export all of the
       pcap functions.  Please read the docs for the libpcap and look at
       Net::RawIP::libpcap(3pm).

       Please look at the examples in the examples/ folder of the distribution.

METHODS

       new
              Net::RawIP->new({
                        ARGPROTO => {PROTOKEY => PROTOVALUE,...}
                        ip       => {IPKEY => IPVALUE,...},
                })

          ARGPROTO is one of (tcp, udp, icmp, generic) defining the protocol of the current
          packet. Defaults to tcp.

          You can NOT change protocol in the object after its creation.  Unless you want your
          packet to be TCP, you must set the protocol type in the new() call.

          The possible values of PROTOKEY depend on the value of ARGPROTO

          If ARGPROTO is <tcp> PROTOKEY can be one of (source, dest, seq, ack_seq, doff, res1,
          res2, urg, ack, psh, rst, syn, fin, window, check, urg_ptr, data).

          If ARGPROTO is icmp PROTOKEY can be one of (type, code, check, gateway, id, sequence,
          unused, mtu, data).

          If ARGPROTO is udp PROTOKEY can be one of (source, dest, len, check, data)

          If ARGPROTO is generic PROTOKEY can be data only.

          The data entries are scalars containing packed network byte order data.

          As the real icmp packet is a C union one can specify only one of the following set of
          values.

          ·   gateway - (int)

          ·   (id and sequence) - (short and short)

          ·   (mtu and unused) - (short and short)

          The default values are:

          ·   (0,0,0,0,5,0,0,0,0,0,0,0,0,0xffff,0,0,'') for tcp

          ·   (0,0,0,0,0,0,0,0,'') for icmp

          ·   (0,0,0,0,'') for udp

          ·   ('') for generic

          The valid values for urg ack psh rst syn fin are 0 or 1.  The value of data is a
          string. Length of the result packet will be calculated if you do not specify non-zero
          value for tot_len.

          The value of ip is a hash defining the parameters of the IP header (iphdr) in the
          current IP packet.

          IPKEY is one of (version, ihl, tos, tot_len, id, frag_off, ttl, protocol, check, saddr,
          daddr).  You can to specify any and all of the above parameters.  If check is not given
          checksum will be calculated automatically.

          The values of the saddr and the daddr 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 ;).

          Examples:

              my $rawip = Net::RawIP->new({udp =>{}});

          or

              my $rawip = Net::RawIP->new({ip => { tos => 22 }, udp => { source => 22,dest =>23 } });

          The default values of the ip hash are

          ·   (4,5,16,0,0,0x4000,64,6,0,0,0) for tcp

          ·   (4,5,16,0,0,0x4000,64,17,0,0,0) for udp

          ·   (4,5,16,0,0,0x4000,64,1,0,0,0) for icmp

          ·   (4,5,16,0,0,0x4000,64,0,0,0,0) for generic

       dump_open
          If dump_open opens and returns a valid file descriptor, this descriptor can be used in
          the perl callback as a perl filehandle.

       loop
       dispatch
          loop and dispatch can run a perl code refs as a callbacks for packet analyzing and
          printing.  the fourth parameter for loop and dispatch can be an array or a hash
          reference and it can be dereferenced in a perl callback.

       next
          next() returns a string (next packet).

       timem
          timem() returns a string that looks like sec.microsec, where the sec and the microsec
          are the values returned by gettimeofday(3).  If microsec is less than 100000 then zeros
          will be added to the left side of microsec for adjusting to six digits.

          Similar to sprintf("%.6f", Time::HiRes::time());

       linkoffset
          The function which called linkoffset 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.

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

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

       proto
          Returns the name of the subclass current object e.g. tcp.  No input parameters.

       packet
          Returns a scalar which contain the packed ip packet of the current object.  No input
          parameters.

       set
          Method for setting the parameters of the current object. The given parameters must look
          like the parameters for the constructor.

       bset($packet,$eth)
          Method for setting the parameters of the current object.  $packet 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 $eth is given and it have a non-zero value then
          assumed that packet is a ethernet packet,otherwise it is a ip packet.

       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.

          The input parameter is a hash reference. In this hash can be three keys.  They are a ip
          and an one of the ARGPROTOs. 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 :

            ($tos,$urg,$ack,$psh,$rst,$syn,$fin) = $packet->get({
                      ip => [qw(tos)],
                  tcp => [qw(psh syn urg ack rst fin)]
                  });

          The members in the array can be given in any order.

          For get the ethernet parameters you have to use the key eth and the values of the array
          (dest,source,proto). The values of the dest and the source will look like the output of
          the ifconfig(8) e.g. 00:00:E8:43:0B:2A.

       open_live
       send($delay,$times)
          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
          send,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 :

              $packet->send(1,10);

          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.

       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 compile(), set the filter and returns the
          pointer (pcap_t *).

       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 (pcap_t *).

       ethnew($device,dest => ARGOFDEST,source => ARGOFSOURCE)
          is a method for init the ethernet subclass in the current object, $device is a required
          parameter,dest and source are an optional, $device is an ethernet device e.g. eth0, an
          ARGOFDEST and an ARGOFSOURCE are a the ethernet addresses in the ethernet header of the
          current object.

          The ARGOFDEST and the ARGOFSOURCE can be given as a string which contain just 6 bytes
          of the real ethernet address or like the output of the ifconfig(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.

          The ethernet frame will be sent with given addresses.  By default the source and the
          dest will be filled with a hardware address of the $device.

          NOTE: For use methods which are related to the ethernet you have to before initialize
          ethernet subclass by ethnew.

       ethset
          is a method for set an ethernet parameters in the current object.  The given parameters
          must look like parameters for the ethnew without a $device.

       ethsend
          is a method for send an ethernet frame.  The given parameters must look like a
          parameters for the send.

       send_eth_frame($frame,$times,$delay)
          is a method for send any ethernet frame which you may construct by hands.$frame is a
          packed ethernet frame exept destination and source fields(these fields can be setting
          by ethset or ethnew).  Another parameters must look like the parameters for the send.

       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 OPTPROTO,s are the prototypes of the
          options(ip,tcp),values are the hashes references.The keys in this hashes are type and
          data.  The value of the type is an array reference.  This array must be filled with an
          integers.Refer to a RFC for a valid types.The value of the data 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.

       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 OPTPROTO is the prototype of the options(ip,tcp),the
          values are the hashes references.The key is the type.The value of the type 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:

              @opts = $n->optget(ip => {});

          E.g. you want to know just the IP options with the type which equal to 131 and 137.
          Here is a code:

              ($t131,$l131,$d131,$t137,$l137,$d137) = $n->optget(
                                             ip =>{
                                  type =>[(131,137)]
                                  }        );

       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 optset.  The parameters for this method are the OPTPROTO's.  E.g.
          you want to unset an IP options.  Here is a code:

              $n->optunset('ip');

          E.g. you want to unset a TCP and an IP options.  Here is a code:

              $n->optunset('ip','tcp');

SEE ALSO

       pcap(3), tcpdump(1), RFC 791-793, RFC 768.

       Net::Pcap, Net::Pcap::Easy, Net::Pcap::Reassemble, Net::Pcap::FindDevice

       Net::Write for an alternative module to send raw packets on the network

AUTHORS

       Current maintainer is Sébastien Aperghis-Tramoni <sebastien@aperghis.net>

       Previous authors & maintainers:

       ·   Sergey Kolychev <ksv@al.lg.ua>

       ·   Gabor Szabo <gabor@pti.co.il>

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.

CREDITS

       Steve Bonds <u5rhsiz02@sneakemail.com>
         + work on some endianness bugs and improving code comments