perldoc > NetAddr::IP

man perldoc info pydoc3 ri search

📖 NAME

NetAddr::IP — Manages IPv4 and IPv6 addresses and subnets

🚀 Quick Reference

Use Case	Command	Description
Create IP object	my $ip = NetAddr::IP->new('192.168.1.1/24');	🎯 Create an IP object with address and optional mask
Check subnet containment	$ip->contains($other)	🔍 Returns true if $ip completely contains $other
Compact subnets	Compact(@subnets)	📦 Returns minimal set of subnets covering all given
Split subnet	$ip->split(28)	✂️ Split subnet into smaller subnets of specified mask length
Get broadcast address	$ip->broadcast()	📡 Returns broadcast address of subnet
Enumerate hosts	$ip->hostenum()	👥 Returns list of all host addresses in subnet
Get nth host	$ip->nth(5)	🔢 Returns 5th usable host address
Check RFC1918	$ip->is_rfc1918()	🏠 Returns true if address is private (RFC1918)
Stringify to CIDR	print "$ip\n"	🖨️ Prints address in CIDR notation (e.g., 192.168.1.1/24)

📋 SYNOPSIS

use NetAddr::IP qw(
      Compact
      Coalesce
      Zeros
      Ones
      V4mask
      V4net
      netlimit
      :aton           DEPRECATED
      :lower
      :upper
      :old_storable
      :old_nth
      :rfc3021
      :nofqdn
);

NOTE: NetAddr::IP::Util has a full complement of network address utilities to convert back and forth between binary and text.

inet_aton, inet_ntoa, ipv6_aton, ipv6_ntoa
ipv6_n2x, ipv6_n2d inet_any2d, inet_n2dx,
inet_n2ad, inetanyto6, ipv6to4

See NetAddr::IP::Util

my $ip = new NetAddr::IP '127.0.0.1';
     or if you prefer
my $ip = NetAddr::IP->new('127.0.0.1);
    or from a packed IPv4 address
my $ip = new_from_aton NetAddr::IP (inet_aton('127.0.0.1'));
    or from an octal filtered IPv4 address
my $ip = new_no NetAddr::IP '127.012.0.0';

print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ;

if ($ip->within(new NetAddr::IP "127.0.0.0", "255.0.0.0")) {
    print "Is a loopback address\n";
}

                                    # This prints 127.0.0.1/32
print "You can also say $ip...\n";

* The following four functions return ipV6 representations of:

::                                       = Zeros();
FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF  = Ones();
FFFF:FFFF:FFFF:FFFF:FFFF:FFFF::          = V4mask();
::FFFF:FFFF                              = V4net();

Will also return an ipV4 or ipV6 representation of a resolvable Fully Qualified Domain Name (FQDN).

###### DEPRECATED, will be removed in version 5 ############

* To accept addresses in the format as returned by inet_aton, invoke the module as:

use NetAddr::IP qw(:aton);

###### USE new_from_aton instead ##########################

* To enable usage of legacy data files containing NetAddr::IP objects stored using the Storable module.

use NetAddr::IP qw(:old_storable);

* To compact many smaller subnets (see: "$me->compact($addr1,$addr2,...)"

@compacted_object_list = Compact(@object_list)

* Return a reference to list of "NetAddr::IP" subnets of $masklen mask length, when $number or more addresses from @list_of_subnets are found to be contained in said subnet.

$arrayref = Coalesce($masklen, $number, @list_of_subnets)

* By default NetAddr::IP functions and methods return string IPv6 addresses in uppercase. To change that to lowercase:

NOTE: the AUGUST 2010 RFC5952 states:

4.3. Lowercase
The characters "a", "b", "c", "d", "e", and "f" in an IPv6 address MUST be represented in lowercase.

It is recommended that all NEW applications using NetAddr::IP be invoked as shown on the next line.

use NetAddr::IP qw(:lower);

* To ensure the current IPv6 string case behavior even if the default changes:

use NetAddr::IP qw(:upper);

* To set a limit on the size of nets processed or returned by NetAddr::IP.

Set the maximum number of nets beyond which NetAddr::IP will return an error as a power of 2 (default 16 or 65536 nets). Each 2**16 consumes approximately 4 megs of memory. A 2**20 consumes 64 megs of memory, A 2**24 consumes 1 gigabyte of memory.

use NetAddr::IP qw(netlimit);
netlimit 20;

The maximum netlimit allowed is 2**24. Attempts to set limits below the default of 16 or above the maximum of 24 are ignored.

Returns true on success, otherwise "undef".

🛠️ INSTALLATION

Un-tar the distribution in an appropriate directory and type:

perl Makefile.PL
make
make test
make install

NetAddr::IP depends on NetAddr::IP::Util which installs by default with its primary functions compiled using Perl's XS extensions to build a C library. If you do not have a C compiler available or would like the slower Pure Perl version for some other reason, then type:

perl Makefile.PL -noxs
make
make test
make install

📝 DESCRIPTION

This module provides an object-oriented abstraction on top of IP addresses or IP subnets that allows for easy manipulations. Version 4.xx of NetAddr::IP will work with older versions of Perl and is compatible with Math::BigInt.

The internal representation of all IP objects is in 128 bit IPv6 notation. IPv4 and IPv6 objects may be freely mixed.

⚡ Overloaded Operators

Many operators have been overloaded, as described below:

• Assignment ("=") — Has been optimized to copy one NetAddr::IP object to another very quickly.
• "->copy()" — The assignment ("=") operation is only put into operation when the copied object is further mutated by another overloaded operation. See overload SPECIAL SYMBOLS FOR "use overload" for details. "->copy()" actually creates a new object when called.
• Stringification — An object can be used just as a string. For instance, the following code:

  my $ip = new NetAddr::IP '192.168.1.123';
  print "$ip\n";

  Will print the string 192.168.1.123/32.
• Equality — You can test for equality with either "eq" or "==". "eq" allows comparison with arbitrary strings as well as NetAddr::IP objects. The following example:

  if (NetAddr::IP->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8')
     { print "Yes\n"; }

  will print out "Yes". Comparison with "==" requires both operands to be NetAddr::IP objects. In both cases, a true value is returned if the CIDR representation of the operands is equal.
• Comparison via >, <, >=, <=, <=> and "cmp" — Internally, all network objects are represented in 128 bit format. The numeric representation of the network is compared through the corresponding operation. Comparisons are tried first on the address portion of the object and if that is equal then the NUMERIC cidr portion of the masks are compared. This leads to the counterintuitive result that /24 > /16. Comparison should not be done on netaddr objects with different CIDR as this may produce indeterminate - unexpected results, rather the determination of which netblock is larger or smaller should be done by comparing $ip1->masklen <=> $ip2->masklen.
• Addition of a constant ("+") — Add a 32 bit signed constant to the address part of a NetAddr object. This operation changes the address part to point so many hosts above the current objects start address. For instance, this code:

  print NetAddr::IP->new('127.0.0.1/8') + 5;

  will output 127.0.0.6/8. The address will wrap around at the broadcast back to the network address. This code:

  print NetAddr::IP->new('10.0.0.1/24') + 255;

  outputs 10.0.0.0/24. Returns the unchanged object when the constant is missing or out of range: 2147483647 <= constant >= -2147483648.
• Subtraction of a constant ("-") — The complement of the addition of a constant.
• Difference ("-") — Returns the difference between the address parts of two NetAddr::IP objects address parts as a 32 bit signed number. Returns undef if the difference is out of range.
• Auto-increment — Auto-incrementing a NetAddr::IP object causes the address part to be adjusted to the next host address within the subnet. It will wrap at the broadcast address and start again from the network address.
• Auto-decrement — Auto-decrementing a NetAddr::IP object performs exactly the opposite of auto-incrementing it, as you would expect.

💾 Serializing and Deserializing

This module defines hooks to collaborate with Storable for serializing "NetAddr::IP" objects, through compact and human readable strings. You can revert to the old format by invoking this module as

use NetAddr::IP ':old_storable';

You must do this if you have legacy data files containing NetAddr::IP objects stored using the Storable module.

🔧 Methods

• ->new([$addr, [ $mask|IPv6 ]]) — Creates a new address with the supplied address in $addr and an optional netmask $mask, which can be omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses respectively.
• ->new6([$addr, [ $mask]]) — Same as new but marks the address as IPv6 address space.
• ->new_no([$addr, [ $mask]]) — Exclusively for IPv4 addresses, filters improperly formatted dot quad strings for leading 0's that would normally be interpreted as octal format.
• ->new_from_aton($netaddr) — Takes a packed IPv4 address and assumes a /32 mask. Replaces the DEPRECATED :aton functionality.
• ->new_cis("$addr $mask") — (DEPRECATED) Accepts Cisco-style address notation with space separator. Now included in other "new" methods.
• ->new_cis6("$addr $mask") — (DEPRECATED) Same as new_cis but for IPv6.
• ->broadcast() — Returns a new object referring to the broadcast address of a given subnet.
• ->network() — Returns a new object referring to the network address of a given subnet.
• ->addr() — Returns the address part as an IPv4 or IPv6 text string.
• ->mask() — Returns the mask as an IPv4 or IPv6 text string.
• ->masklen() — Returns the number of one bits in the mask.
• ->bits() — Returns the width of the address in bits (32 for v4, 128 for v6).
• ->version() — Returns the version of the address (4 or 6).
• ->cidr() — Returns the address and mask in CIDR notation.
• ->aton() — Returns the address part in the same format as inet_aton() or ipv6_aton.
• ->range() — Returns the base address and broadcast address separated by a dash (range notation).
• ->prefix() — Returns the address and mask in IPv4 prefix representation (includes broadcast).
• ->nprefix() — Same as prefix but does not include broadcast.
• ->numeric() — In scalar context returns numeric representation of address; in array context returns (address, netmask).
• ->bigint() — Returns Math::BigInt representation of address (or address and netmask in array context).
• ->wildcard() — Returns the wildcard bits corresponding to the mask.
• ->short() — Returns the address part in short/compact notation (e.g., 127.1 for 127.0.0.1).
• ->canon() — Returns the address part in canonical notation (RFC5952 for IPv6, dotted quad for IPv4).
• ->full() — Returns the address part in FULL notation (IPv4: 0000:...:127.0.0.1, IPv6: 0000:...:0000).
• ->full6() — Returns the address part in FULL IPv6 notation.
• ->full6m() — Returns the mask part in FULL IPv6 notation.
• $me->contains($other) — Returns true when $me completely contains $other.
• $me->within($other) — Complement of contains, returns true when $me is completely contained within $other.
• ->is_rfc1918() — Returns true when $me is an RFC 1918 address.
• ->is_local() — Returns true when $me is a local network address (127.0.0.0/8 or ::1).
• ->splitref($bits,[optional $bits1,$bits2,...]) — Returns a reference to a list of objects representing subnets of "bits" mask produced by splitting the original object. Returns undef on error, dies on netlimit exceeded.
• ->rsplitref($bits,[optional $bits1,$bits2,...]) — Same as splitref but applies split plan in reverse order.
• ->split($bits,[optional $bits1,$bits2,...]) — Similar to splitref but returns a list (not a reference).
• ->rsplit($bits,[optional $bits1,$bits2,...]) — Reverse order split returning a list.
• ->hostenum() — Returns the list of hosts within a subnet. Dies on netlimit exceeded.
• ->hostenumref() — Faster version returning a reference to a list.
• $me->compact($addr1, $addr2, ...) — Compacts all addresses and subnets into the largest possible subnets that contain exactly all given objects.
• @compacted_object_list = Compact(@object_list) — Exported function version of compact.
• $me->compactref(\@list) — Faster version of compact that takes a reference to a list.
• $compacted_object_list = Compact(\@list) — Exported function version of compactref.
• $me->coalesce($masklen, $number, @list_of_subnets) — Returns a reference to list of subnets of $masklen when $number or more addresses are contained.
• $arrayref = Coalesce($masklen,$number,@list_of_subnets) — Exported function version of coalesce.
• ->first() — Returns the first usable IP address within the subnet.
• ->last() — Returns the last usable IP address within the subnet.
• ->nth($index) — Returns the *n*-th usable IP address within the subnet. Returns undef if not available.
• ->num() — Returns the number of usable IP addresses within the subnet (not counting network/broadcast). For /31 and /127 returns 2.
• ->re() — Returns a Perl regular expression that will match an IP address within the given subnet (IPv4 by default, IPv6 if address is IPv6).
• ->re6() — Returns a Perl regular expression that will match an IP address within the given subnet, always IPv6.

📤 EXPORT_OK

• Compact
• Coalesce
• Zeros
• Ones
• V4mask
• V4net
• netlimit

📝 NOTES / BUGS ... FEATURES

NetAddr::IP only runs in Pure Perl mode on Windows boxes because I don't have the resources or know how to get the "configure" stuff working in the Windows environment. Volunteers WELCOME to port the "C" portion of this module to Windows.

📜 HISTORY

See the Changes file

👤 AUTHORS

Luis E. Muñoz <luismunoz AT cpan.org>, Michael Robinton <michael AT bizsystems.com>

⚖️ WARRANTY

This software comes with the same warranty as Perl itself (ie, none), so by using it you accept any and all the liability.

📄 COPYRIGHT

This software is (c) Luis E. Muñoz, 1999 - 2007, and (c) Michael Robinton, 2006 - 2014.

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

• a) the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or
• b) the "Artistic License" which comes with this distribution.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the

Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301 USA.

or visit their web page on the internet at:

http://www.gnu.org/copyleft/gpl.html.

🔗 SEE ALSO

perl(1), NetAddr::IP::Lite, NetAddr::IP::Util, NetAddr::IP::InetBase

📖 NAME 🚀 Quick Reference 📋 SYNOPSIS 🛠️ INSTALLATION 📝 DESCRIPTION 📤 EXPORT_OK 📝 NOTES / BUGS ... FEATURES 📜 HISTORY 👤 AUTHORS ⚖️ WARRANTY 📄 COPYRIGHT 🔗 SEE ALSO