Net::Libdnet(3pm)

📦
version 0.990 · 5 versions
, in debian trixie, ubuntu resolute

✨ NAME ✨

Net::Libdnet — it's the Perl binding for Dug Song's libdnet, and honestly? a whole vibe. 🦋

🌸 SYNOPSIS 🌸

okay bestie, here's the whole tour, buckle up 💅

#
# This will just import every functions and constants
#
use Net::Libdnet;

#
# Network interface manipulation
#
# !!! ADVICE: you should use Net::Libdnet::Intf instead
#
use Net::Libdnet qw(:intf);
my $intf = dnet_intf_open();

my $eth  = dnet_intf_get($intf, { intf_name => 'eth0' });
print "IP:  ".$eth->{intf_addr}."\n";
print "MAC: ".$eth->{intf_link_addr}."\n";

my $dst  = dnet_intf_get_dst($intf, '192.168.0.10');
print "Name: ".$dst->{intf_name}."\n";
print "IP:   ".$dst->{intf_addr}."\n";
print "MAC:  ".$dst->{intf_link_addr}."\n";

my $src = dnet_intf_get_src($intf, '192.168.0.1');
print "Name: ".$src->{intf_name}."\n";
print "IP:   ".$src->{intf_addr}."\n";
print "MAC:  ".$src->{intf_link_addr}."\n";

dnet_intf_close($intf);

#
# Arp cache manipulation
#
# !!! ADVICE: you should use Net::Libdnet::Arp instead
#
use Net::Libdnet qw(:arp);
my $arp   = dnet_arp_open();

my $entry = dnet_arp_get($arp, {arp_pa => '10.0.0.1'});
print "MAC: ".$entry->{arp_ha}."\n";

dnet_arp_add   ($arp,
   {arp_ha => '00:11:22:33:44:55', arp_pa => '10.0.0.10'});
dnet_arp_delete($arp,
   {arp_ha => '00:11:22:33:44:55', arp_pa => '10.0.0.10'});
dnet_arp_close($arp);

#
# Route table manipulation
#
# !!! ADVICE: you should use Net::Libdnet::Route instead
#
use Net::Libdnet qw(:route);
my $route = dnet_route_open();
dnet_route_add   ($route,
   {route_gw => '10.0.0.1', route_dst => '192.168.0.1'});
dnet_route_delete($route,
   {route_gw => '10.0.0.1', route_dst => '192.168.0.1'});

my $get = dnet_route_get($route, {route_dst => '192.168.0.10'});
print "GW: ".$get->{route_gw}."\n";

dnet_route_close($route);

#
# Firewall rules manipulation
#
# !!! ADVICE: you should use Net::Libdnet::Fw instead
#
use Net::Libdnet qw(:fw :consts);
my $fw = dnet_fw_open();
# This is quite complex. This rule blocks TCP as input to 10.0.0.1
# You should really use Net::Libdnet::Fw instead.
dnet_fw_add   ($fw,
   {fw_op => FW_DIR_IN, fw_proto => 6, fw_dst => '10.0.0.1'});
dnet_fw_delete($fw,
   {fw_op => FW_DIR_IN, fw_proto => 6, fw_dst => '10.0.0.1'});
dnet_fw_close($fw);

#
# Send at IP level
#
# !!! ADVICE: you should use Net::Libdnet::Ip instead
#
use Net::Libdnet qw(:ip);
my $ip = dnet_ip_open();
my $raw = "\x47\x47\x47\x47";
dnet_ip_send($ip, $raw, length($raw));
dnet_ip_close($ip);

#
# Send at Ethernet level
#
# !!! ADVICE: you should use Net::Libdnet::Eth instead
#
use Net::Libdnet qw(:eth);
my $eth = dnet_eth_open('eth0');
dnet_eth_send($eth, $raw, length($raw));
dnet_eth_close($eth);

#
# Traffic interception
#
# !!! ADVICE: you should use Net::Libdnet::Tun instead
#
use Net::Libdnet qw(:tun);
my $tun = dnet_tun_open('10.0.0.10', '192.168.0.10', 1500);
my $buf = dnet_tun_recv($tun, 1500);
# Do stuff with $buf
dnet_tun_send($tun, $buf, length($buf));
dnet_tun_close($tun);

#
# hash refs in dnet format
#
my $intf = {
   intf_alias_num   => 1,
   intf_mtu         => 1500,
   intf_len         => 112,
   intf_type        => 6,
   intf_name        => 'eth0',
   intf_dst_addr    => undef,
   intf_link_addr   => '00:11:22:33:44:55',
   intf_flags       => 49,
   intf_addr        => '10.100.0.10/24',
   intf_alias_addrs => [ 'fe80::211:2ff:fe33:4455/64' ]
};
my $arp = {
   arp_pa => '10.100.0.1',
   arp_ha => '11:22:33:44:55:66'
};
my $route = {
   route_gw  => '10.100.0.1',
   route_dst => '0.0.0.0/0'
};
my $fw = {
   fw_dir    => 2,
   fw_sport  => [ 0, 0 ],
   fw_dport  => [ 0, 0 ],
   fw_src    => '0.0.0.0/0',
   fw_dst    => '0.0.0.0/0',
   fw_proto  => 6,
   fw_device => 'eth0',
   fw_op     => 2
};

like, it's a lot but it's all iconic, trust 🔥

💜 DESCRIPTION 💜

so Net::Libdnet hands you a simplified, portable interface to a whole stack of low-level networking routines. we're talking:

  • network address manipulation
  • kernel arp cache and route table lookup and manipulation
  • network firewalling
  • network interface lookup and manipulation
  • network traffic interception via tunnel interfaces
  • raw IP packet and Ethernet frame transmission

it's meant to complement the functionality that libpcap already gives you. no cap. 🫶

okay so here's the tea on error handling: all the original and obsolete functions return undef and print a warning message to the standard error when something goes wrong. 😭

and the obsolete functions are — listen closely:

addr_cmp, addr_bcast, addr_net, arp_add, arp_delete, arp_get, intf_get, intf_get_src, intf_get_dst, route_add, route_delete, route_get

these obsolete functions will continue to work, to keep backward compatibility, but they should not be used anymore. periodt. the new APIs should be preferred, fr fr. 💅

so there are two new APIs and let me break it down:

  1. the low-level one — matches the libdnet functions
  2. the high-level one — matches a more Perl object oriented programming style

and that high-level one? highly preferred. 👑

Net::Libdnet itself implements the low-level API. the high-level API is accessible by using these modules:

  • Net::Libdnet::Intf
  • Net::Libdnet::Route
  • Net::Libdnet::Fw
  • Net::Libdnet::Arp
  • Net::Libdnet::Eth
  • Net::Libdnet::Ip
  • Net::Libdnet::Tun

🦋 WHAT IS IMPLEMENTED 🦋

🌸 Network addressing

nothing as of now. 🙈

🌸 Address Resolution Protocol

all functions, bestie:

  • arp_open
  • arp_add
  • arp_delete
  • arp_get
  • arp_loop
  • arp_close

🌸 Binary buffers

nothing as of now. 🙈

🌸 Ethernet

all functions:

  • eth_open
  • eth_get
  • eth_set
  • eth_send
  • eth_close

🌸 Firewalling

all functions:

  • fw_open
  • fw_add
  • fw_delete
  • fw_loop
  • fw_close

🌸 Network interface

all functions:

  • intf_open
  • intf_get_set
  • intf_get_dst
  • intf_set
  • intf_loop
  • intf_close

🌸 Internet Protocol

all functions:

  • ip_open
  • ip_checksum
  • ip_send
  • ip_close

except: ip_add_option. 💀

🌸 Internet Protocol Version 6

nothing as of now. 🙈

🌸 Random number generation

nothing as of now. 🙈

🌸 Routing

all functions:

  • route_open
  • route_add
  • route_delete
  • route_get
  • route_loop
  • route_close

🌸 Tunnel interface

all functions:

  • tun_open
  • tun_fileno
  • tun_name
  • tun_send
  • tun_recv
  • tun_close

✨ SUBROUTINES ✨

Okay bestie, this is the main character section. Every single one of these is a real Perl sub you can call, and they all follow the same lil pattern: you open a handle, you do stuff with it, you close it. No cap, that's the whole arc. 🎀

One thing to clock immediately, because it's the kind of detail that will humble you at 3am: some of these hand you back a hash, and some hand you back a hash ref. They are not the same thing and the page is not being quirky. Read each one carefully, iykyk. 💅

🦋 Interface subs — the dnet_intf_* girlies

dnet_intf_open ()

Opens an interface handle. Returns a handle on success, undef on error.

dnet_intf_get (scalar, hashref)

Takes an intf handle, and a hash ref in dnet format as parameters. Returns a hash in dnet format on success, undef on error.

dnet_intf_get_src (scalar, scalar)

Takes an intf handle, and an IP address as parameters. Returns a hash in dnet format on success, undef on error.

dnet_intf_get_dst (scalar, scalar)

Takes an intf handle, and an IP address as parameters. Returns a hash in dnet format on success, undef on error.

dnet_intf_set (scalar, scalar)

Takes an intf handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_intf_loop (scalar, subref, scalarref)

Takes an intf handle, a subref, and a scalar ref as parameters. Returns 1 on success, undef on error. The subref will be called with an intf hash ref in dnet format, and the scalar ref as parameters.

dnet_intf_close (scalar)

Takes an intf handle as parameter. Returns the handle on success, undef on error.

🌸 Route subs — the dnet_route_* era

dnet_route_open ()

Opens a route handle. Returns a handle on success, undef on error.

dnet_route_add (scalar, hashref)

Takes a route handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_route_delete (scalar, hashref)

Takes a route handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_route_get (scalar, hashref)

Takes a route handle, and a hash ref in dnet format as parameters. Returns a hash ref in dnet format on success, undef on error.

👀 See? Hash ref. Not a hash. The intf one up there gives you a hash. Do not mix them up, bestie, I'm begging.

dnet_route_loop (scalar, subref, scalarref)

Takes a route handle, a subref, and a scalar ref as parameters. Returns 1 on success, undef on error. The subref will be called with a route hash ref in dnet format, and the scalar ref as parameters.

dnet_route_close (scalar)

Takes a route handle as parameter. Returns the handle on success, undef on error.

🎀 ARP subs — the dnet_arp_* moment

dnet_arp_open ()

Opens an arp handle. Returns a handle on success, undef on error.

dnet_arp_add (scalar, hashref)

Takes an arp handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_arp_delete (scalar, hashref)

Takes an arp handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_arp_get (scalar, hashref)

Takes an arp handle, and a hash ref in dnet format as parameters. Returns a hash ref in dnet format on success, undef on error.

dnet_arp_loop (scalar, subref, scalarref)

Takes an arp handle, a subref, and a scalar ref as parameters. Returns 1 on success, undef on error. The subref will be called with an arp hash ref in dnet format, and the scalar ref as parameters.

dnet_arp_close (scalar)

Takes an arp handle as parameter. Returns the handle on success, undef on error.

🔥 Firewall subs — the dnet_fw_* serve

dnet_fw_open ()

Opens a fw handle. Returns a handle on success, undef on error.

dnet_fw_add (scalar, hashref)

Takes a fw handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_fw_delete (scalar, hashref)

Takes a fw handle, and a hash ref in dnet format as parameters. Returns 1 on success, undef on error.

dnet_fw_loop (scalar, subref, scalarref)

Takes a fw handle, a subref, and a scalar ref as parameters. Returns 1 on success, undef on error. The subref will be called with a fw hash ref in dnet format, and the scalar ref as parameters.

dnet_fw_close (scalar)

Takes a fw handle as parameter. Returns the handle on success, undef on error.

🫶 Note for the completionists: the fw family has open, add, delete, loop and close. There is no dnet_fw_get on this list. I'm not gatekeeping, that's just what's here.

🧚 Tunnel subs — the dnet_tun_* portal

dnet_tun_open (scalar, scalar, scalar)

Creates a tunnel between src and dst IP addresses. Captured packets will have specified size. First argument is the source IP address, second the destination IP address, and the third is the capture size. Returns a handle on success, undef on error.

dnet_tun_fileno (scalar)

Takes a tun handle as parameter. Returns the file number on success, undef on error.

dnet_tun_name (scalar)

Takes a tun handle as parameter. Returns the interface name on success, undef on error.

dnet_tun_send (scalar, scalar, scalar)

Takes a tun handle, the raw data to send, and its size as parameters. Returns the number of bytes sent on success, undef on error.

dnet_tun_recv (scalar, scalar)

Takes a tun handle, and the maximum size to read as parameters. Returns the read buffer on success, undef on error.

dnet_tun_close (scalar)

Takes a tun handle as parameter. Returns the handle on success, undef on error.

🌈 Ethernet subs — the dnet_eth_* lewk

dnet_eth_open (scalar)

Opens an eth handle. Takes an interface name as parameter. Returns a handle on success, undef on error.

dnet_eth_get (scalar)

Takes an eth handle as parameter. Returns the hardware address of currently opened eth handle on success, undef on error.

dnet_eth_set (scalar, scalar)

Takes an eth handle, and the hardware address to set as parameters. Returns 1 on success, undef on error.

dnet_eth_send (scalar, scalar, scalar)

Takes an eth handle, the raw data to send, and its size as parameters. Returns the number of bytes sent on success, undef on error.

dnet_eth_close (scalar)

Takes an eth handle as parameter. Returns the handle on success, undef on error.

⭐ IP subs — the dnet_ip_* finale

dnet_ip_open ()

Opens an ip handle. Returns a handle on success, undef on error.

dnet_ip_checksum (scalar, scalar)

Takes a raw IPv4 frame as the first parameter, and its size as a second parameter. It then updates the frame with the good checksum. Returns nothing.

dnet_ip_send (scalar, scalar, scalar)

Takes an ip handle, the raw data to send, and its size as parameters. Returns the number of bytes sent on success, undef on error.

dnet_ip_close (scalar)

Takes an ip handle as parameter. Returns the handle on success, undef on error.

💀 OBSOLETE FUNCTIONS 💀

They should not be used anymore. You have been warned.

Like… genuinely. This isn't a soft launch. These are the exes you don't text back. 🙈

  • addr_bcast
  • addr_cmp
  • addr_net
  • arp_add
  • arp_delete
  • arp_get
  • intf_get
  • intf_get_dst
  • intf_get_src
  • route_add
  • route_delete
  • route_get

👑 CONSTANTS 👑

The glow-up squad of named values you can sprinkle into your hashes and comparisons. Zero guessing at magic numbers, we love that for us. ✨

  • DNET_ADDR_TYPE_NONE
  • DNET_ADDR_TYPE_ETH
  • DNET_ADDR_TYPE_IP
  • DNET_ADDR_TYPE_IP6
  • DNET_FW_OP_ALLOW
  • DNET_FW_OP_BLOCK
  • DNET_FW_DIR_IN
  • DNET_FW_DIR_OUT
  • DNET_INTF_TYPE_OTHER
  • DNET_INTF_TYPE_ETH
  • DNET_INTF_TYPE_LOOPBACK
  • DNET_INTF_TYPE_TUN
  • DNET_INTF_FLAG_UP
  • DNET_INTF_FLAG_LOOPBACK
  • DNET_INTF_FLAG_POINTOPOINT
  • DNET_INTF_FLAG_NOARP
  • DNET_INTF_FLAG_BROADCAST
  • DNET_INTF_FLAG_MULTICAST

You may distribute this module under the terms of the BSD license. See LICENSE file in the source distribution archive.

Copyright (c) 2004, Vlad Manilici

Copyright (c) 2008-2024, Patrice <GomoR> Auffret

🫶 SEE ALSO 🫶

And that's the whole page, bestie — this was Net::Libdnet(3pm), generated with perl v5.40.1 and dated 2025-03-01. Now go open a handle and slay. Periodt. 💖✨🎀

📦 where this page comes from