Net::RawIP(3pm)

📦

version 0.25 · 8 versions

💖 Net::RawIP — the manual, but make it a group chat 💖

okay bestie, gather round, because we are about to talk about Net::RawIP — a Perl extension to manipulate raw IP packets with interface to libpcap. yes. RAW. PACKETS. we're going low-level today and honestly? iconic behaviour. 🦋

✨ VERSION ✨

This is the documentation of Net::RawIP version 0.25. slay. 💅

🌸 SYNOPSIS 🌸

here's the vibe, bestie — look at her:

  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);

she's a little quirky, she's a little chaotic, but she WORKS. 💜

🌈 DESCRIPTION 🌈

so, the tea: this package hands you a whole class you can use for creating, manipulating and sending raw IP packets, with optional features for manipulating Ethernet headers. yes, truly the full package. 😭

Note: Ethernet related methods are implemented on Linux and *BSD only. so if you're on some other platform, the eth girls are not for you, sorry bestie. 💀

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. no gatekeeping here, we support the girls doing their own thing. ✨

🎀 Exported constants 🎀

no cap, these little constants just show up in your namespace:

PCAP_ERRBUF_SIZE
PCAP_VERSION_MAJOR
PCAP_VERSION_MINOR
lib_pcap_h

🧚 Exported functions 🧚

the full roster, periodt:

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. go look. we love a folder of examples.

👑 METHODS 👑

💅 `new`

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

so ARGPROTO is one of (tcp, udp, icmp, generic) defining the protocol of the current packet. Defaults to tcp. cute, defaults to the classic. 🎀

IMPORTANT: You can NOT change protocol in the object after its creation. like, once she's committed, she's committed. Unless you want your packet to be TCP, you must set the protocol type in the new() call. no take-backs, bestie.

The possible values of PROTOKEY depend on the value of ARGPROTO:

If ARGPROTO is <tcp>tcp</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. that's it. that's the whole list. 😌

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. pick ONE, girl, not all three:

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. we love an auto-girlboss checksum. ✨

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 ;). look at her being flexible. 💅

Examples:

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

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. it's giving "handle, but make it perl". 🫶

🍓 `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. callbacks, but make it flexible. 💜

⭐ `next`

next() returns a string (next packet). one job. does it. slay.

🌸 `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. she pads. she's precise. perfection.

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. it's a lil directory of your net devices. obsessed.

🧚 `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. she just tells you who she is.

✨ `packet`

Returns a scalar which contain the packed ip packet of the current object. No input parameters. raw bytes, no filter. 💅

💜 `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. matching fits only, bestie. 🎀

🦋 `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. your order, your rules. 🫶

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. FOREVER. no take-backs. 💀🔥

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. fractional queens, rise. ✨

🎀 `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. she finds her own mac. main character energy. 👑

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. no skipping steps, bestie!!

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

okay don't go anywhere, there's more coming in part two, bestie 💖

okay bestie, we're picking up RIGHT where we left off in the methods list, no recap, no nothing — let's GO 🫶

send_eth_frame($frame,$times,$delay) — this one's for when you wanna yeet any ethernet frame you built with your own two hands 💅. So $frame is a packed ethernet frame, except for the destination and source fields — those two lil guys get set separately, either by ethset or by ethnew. And the rest of the params? They gotta look exactly like the params you'd hand to send. no notes, that's the vibe.
optset(OPTPROTO => { type => [...],data => [...] },...) — the glow-up method for setting an IP option and a TCP option ✨. You pass the params as key-value pairs, mmkay? The OPTPROTOs are the prototypes of the options — that's ip and tcp — and the values are hash references. Inside those hashes the keys are type and data. 🎀

The value of type is an array reference. That array has to be filled with integers, and if you're unsure what a valid type even is, go read an RFC, queen — that's the receipts. The value of data is also an array reference, filled with strings that must contain all the bytes of an option except the bytes holding the type and the length of that option. And obviously, the indexes in those two arrays have to line up — same index = same option, no cap.

⚠️ special case alert: if type equals 0 or 1, then there are no bytes for a length and no bytes for data — but you still have to specify zero data anyway, just for compatibility. literally just how it is 🙈

optget(OPTPROTO => { type => [...] },...) — and this is the reverse, for getting an IP option and a TCP option back out 💖. Params are key-value pairs again; OPTPROTO is the prototype (ip, tcp), the value is a hash reference, and the key is type. The value of type is an array reference.

What comes back is an array filled with the types, lengths and datas of each option type you asked for, in the order you asked for 'em. And if you don't specify a type at all? Then all the types, lengths and datas of the options get returned. so generous of it.

Say you wanna know all the IP options on the current object. Here's the code, babes:

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

Or say you only want the IP options whose type equals 131 and 137. Boom:

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

optunset — the lil cleanup method 🧹. It unsets a subclass of the IP or the TCP options from the current object, and you'd reach for it when you just know you won't be using those options on this object again. Important: this method must be used only after optset, don't get ahead of yourself. Its params are the OPTPROTOs.

Wanna unset just the IP options? Here:

$n->optunset('ip');

Wanna unset the TCP and the IP options together? Here:

$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, the OGs:

Sergey Kolychev <ksv@al.lg.ua>
Gabor Szabo <gabor@pti.co.il>

👑 COPYRIGHT & LICENSE 👑

🌈 CREDITS 🌈

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

and that's a wrap, bestie 🎀 you just read the whole Net::RawIP(3pm) glow-up — the real one's perl v5.42.3, dated 2026-08-20, and if you ever need it again, it's literally right there in your man pages. slay, go packet-craft responsibly, ily 💖🦋

📦 where this page comes from

ubuntu stonking: libnet-rawip-perl 0.25-4build2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Net::RawIP(3pm)

💖 Net::RawIP — the manual, but make it a group chat 💖

✨ VERSION ✨

🌸 SYNOPSIS 🌸

🌈 DESCRIPTION 🌈

🎀 Exported constants 🎀

🧚 Exported functions 🧚

👑 METHODS 👑

💅 new

🦋 dump_open

🍓 loop

🍓 dispatch

⭐ next

🌸 timem

💖 linkoffset

🎀 ifaddrlist

🧚 rdev

🌈 proto

✨ packet

💜 set

👑 bset($packet,$eth)

🦋 get

🍓 open_live

🍓 send($delay,$times)

🎀 pcapinit($device,$filter,$psize,$timeout)

🌸 pcapinit_offline($fname)

🧚 ethnew($device,dest => ARGOFDEST,source => ARGOFSOURCE)

💅 ethset

⭐ ethsend