NAME

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

SYNOPSIS 

  use NetAddr::IP qw(
	Compact
	Coalesce
	Zero
	Ones
	V4mask
	V4net
	:aton
	:old_storable
	:old_nth
  );

  my $ip = new NetAddr::IP 'loopback';

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

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

  use NetAddr::IP qw(:aton);

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

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' complier 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 NetAdder::IP will will work older versions of Perl and does not use Math::BigInt as in previous versions.

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 in to 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 the 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 cidr portion of the masks are compared.
Addition of a constant

Adding a constant to a NetAddr::IP object changes its address part to point to the one so many hosts above the start address. For instance, this code: 

    print NetAddr::IP->new('127.0.0.1') + 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.

Substraction of a constant
The complement of the addition of a constant.
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 ]])
->new6([$addr, [ $mask]])

These methods 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 marks the address as being in ipV6 address space even if the format would suggest otherwise. 

  i.e.	->new6('1.2.3.4') will result in ::102:304

  addresses submitted to ->new in ipV6 notation will
  remain in that notation permanently. i.e.
	->new('::1.2.3.4') will result in ::102:304
  whereas new('1.2.3.4') would print out as 1.2.3.4

  See "STRINGIFICATION" below.

$addr can be almost anything that can be resolved to an IP address in all the notations I have seen over time. It can optionally contain the mask in CIDR notation.

prefix notation is understood, with the limitation that the range speficied by the prefix must match with a valid subnet.

Addresses in the same format returned by inet_aton or gethostbyname can also be understood, although no mask can be specified for them. The default is to not attempt to recognize this format, as it seems to be seldom used.

To accept addresses in that format, invoke the module as in 

  use NetAddr::IP ':aton'

If called with no arguments, 'default' is assumed.

$addr can be any of the following and possibly more... 

  n.n
  n.n/mm
  n.n.n
  n.n.n/mm
  n.n.n.n
  n.n.n.n/mm		32 bit cidr notation
  n.n.n.n/m.m.m.m
  loopback, localhost, broadcast, any, default
  x.x.x.x/host
  0xABCDEF, 0b111111000101011110, (a bcd number)
  a netaddr as returned by 'inet_aton'

Any RFC1884 notation 

  ::n.n.n.n
  ::n.n.n.n/mmm		128 bit cidr notation
  ::n.n.n.n/::m.m.m.m
  ::x:x
  ::x:x/mmm
  x:x:x:x:x:x:x:x
  x:x:x:x:x:x:x:x/mmm
  x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation
  loopback, localhost, unspecified, any, default
  ::x:x/host
  0xABCDEF, 0b111111000101011110 within the limits
  of perl's number resolution
  123456789012  a 'big' bcd number i.e. Math::BigInt

If called with no arguments, 'default' is assumed.

->broadcast()
Returns a new object refering to the broadcast address of a given subnet. The broadcast address has all ones in all the bit positions where the netmask has zero bits. This is normally used to address all the hosts in a given subnet.
->network()
Returns a new object refering to the network address of a given subnet. A network address has all zero bits where the bits of the netmask are zero. Normally this is used to refer to a subnet.
->addr()
Returns a scalar with the address part of the object as an IPv4 or IPv6 text string as appropriate. This is useful for printing or for passing the address part of the NetAddr::IP object to other components that expect an IP address. If the object is an ipV6 address or was created using ->new6($ip) it will be reported in ipV6 hex format otherwise it will be reported in dot quad format only if it resides in ipV4 address space.
->mask()
Returns a scalar with the mask as an IPv4 or IPv6 text string as described above.
->masklen()
Returns a scalar the number of one bits in the mask.
->bits()
Returns the width of the address in bits. Normally 32 for v4 and 128 for v6.
->version()
Returns the version of the address or subnet. Currently this can be either 4 or 6.
->cidr()
Returns a scalar with the address and mask in CIDR notation. A NetAddr::IP object stringifies to the result of this function. (see comments about ->new6() and ->addr() for output formats)
->aton()
Returns the address part of the NetAddr::IP object in the same format as the inet_aton() or ipv6_aton function respectively. If the object was created using ->new6($ip), the address returned will always be in ipV6 format, even for addresses in ipV4 address space.
->range()
Returns a scalar with the base address and the broadcast address separated by a dash and spaces. This is called range notation.
->prefix()

Returns a scalar with the address and mask in ipV4 prefix representation. This is useful for some programs, which expect its input to be in this format. This method will include the broadcast address in the encoding.

->nprefix()

Just as ->prefix(), but does not include the broadcast address.

->numeric()

When called in a scalar context, will return a numeric representation of the address part of the IP address. When called in an array contest, it returns a list of two elements. The first element is as described, the second element is the numeric representation of the netmask.

This method is essential for serializing the representation of a subnet.

->wildcard()

When called in a scalar context, returns the wildcard bits corresponding to the mask, in dotted-quad or ipV6 format as applicable.

When called in an array context, returns a two-element array. The first element, is the address part. The second element, is the wildcard translation of the mask.

->short()

Returns the address part in a short or compact notation. 

  (ie, 127.0.0.1 becomes 127.1).

Works with both, V4 and V6.

$me->contains($other)
Returns true when $me completely contains $other. False is returned otherwise and undef is returned if $me and $other are not both NetAddr::IP objects.
$me->within($other)

The complement of ->contains(). Returns true when $me is completely con tained within $other.

Note that $me and $other must be NetAddr::IP objects.

->split($bits)

Returns a list of objects, representing subnets of $bits mask produced by splitting the original object, which is left unchanged. Note that $bits must be longer than the original mask in order for it to be splittable.

Note that $bits can be given as an integer (the length of the mask) or as a dotted-quad. If omitted, a host mask is assumed.

->splitref($bits)

A (faster) version of ->split() that returns a reference to a list of objects instead of a real list. This is useful when large numbers of objects are expected.

Return undef if the number of subnets > 2 ** 32

->hostenum()

Returns the list of hosts within a subnet.

->hostenumref()
Faster version of ->hostenum(), returning a reference to a list.
$me->compact($addr1, $addr2, ...)
@compacted_object_list = Compact(@object_list)

Given a list of objects (including $me), this method will compact all the addresses and subnets into the largest (ie, least specific) subnets possible that contain exactly all of the given objects.

Note that in versions prior to 3.02, if fed with the same IP subnets multiple times, these subnets would be returned. From 3.02 on, a more "correct" approach has been adopted and only one address would be returned.

Note that $me and all $addr's must be NetAddr::IP objects.

$me->compactref(\@list)

As usual, a faster version of =item ->compact() that returns a reference to a list. Note that this method takes a reference to a list instead.

Note that $me must be a NetAddr::IP object.

$me->coalesce($masklen, $number, @list_of_subnets)
$arrayref = Coalesce($masklen,$number,@list_of_subnets)

Will 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.

Subnets from @list_of_subnets with a mask shorter than $masklen are passed "as is" to the return list.

Subnets from @list_of_subnets with a mask longer than $masklen will be counted (actually, the number of IP addresses is counted) towards $number.

Called as a method, the array will include $me.

WARNING: the list of subnet must be the same type. i.e ipV4 or ipV6

->first()
Returns a new object representing the first usable IP address within the subnet (ie, the first host address).
->last()
Returns a new object representing the last usable IP address within the subnet (ie, one less than the broadcast address).
->nth($index)

Returns a new object representing the n-th usable IP address within the subnet (ie, the n-th host address). If no address is available (for example, when the network is too small for $index hosts), undef is returned.

Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite implements ->nth($index) and ->num() exactly as the documentation states. Previous versions behaved slightly differently and not in a consistent manner. See the README file for details.

To use the old behavior for ->nth($index) and ->num(): 

  use NetAddr::IP::Lite qw(:old_nth);
->num()

Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite Returns the number of usable addresses IP addresses within the subnet, not counting the broadcast or network address. Previous versions returned th number of IP addresses not counting the broadcast address.

To use the old behavior for ->nth($index) and ->num(): 

  use NetAddr::IP::Lite qw(:old_nth);
->re()

Returns a Perl regular expression that will match an IP address within the given subnet. Defaults to ipV4 notation. Will return an ipV6 regex if the address in not in ipV4 space.

->re6()

Returns a Perl regular expression that will match an IP address within the given subnet. Always returns an ipV6 regex.

EXPORT_OK 

	Compact
	Coalesce
	Zero
	Ones
	V4mask
	V4net

HISTORY

$Id: IP.pm,v 4.7 2007/06/06 20:43:38 luisemunoz Exp $

0.01
0.02
0.03
1.00
1.10
1.20
1.21
2.00
2.10
2.20
2.21
2.22
2.23
2.24
3.00

This is a major rewrite, supposed to fix a number of issues pointed out in earlier versions.

The goals for this version include getting rid of BigInts, speeding up and also cleaning up the code, which is written in a modular enough way so as to allow IPv6 functionality in the future, taking benefit from most of the methods.

Note that no effort has been made to remain backwards compatible with earlier versions. In particular, certain semantics of the earlier versions have been removed in favor of faster performance.

This version was tested under Win98/2K (ActiveState 5.6.0/5.6.1), HP-UX11 on PA-RISC (5.6.0), RedHat Linux 6.2 (5.6.0), Digital Unix on Alpha (5.6.0), Solaris on Sparc (5.6.0) and possibly others.

3.01
3.02
3.03
3.04
3.05
3.06
3.07
3.08
3.09
3.10
3.11
3.12
3.13
3.14
3.14_1

This is an interim release just to incorporate the v6 patches contributed. No extensive testing has been done with this support yet. More tests are needed.

3.14_2

Minor development release.

3.14_3

Fixed a bug pointed out by Brent Imhoff related to the implicit comparison that happens within Compact(). The netmask was being ignored in the comparison (ie, 10/8 was considered the same as 10.0/16). Since some people have requested that 10.0/16 was considered larger than 10/8, I added this change, which makes the bug go away. This will be the last '_' release, pending new bugs.

Regarding the comparison of subnets, I'm still open to debate so as to wether 10.0/16 > 10/8. Certainly 255.255.0.0 > 255.0.0.0, but 2 ** 24 are more hosts than 2 ** 16. I think we might use gt & friends for this semantic and make everyone happy, but I won't do anything else here without (significant) feedback.

3.14_4
As noted by Michael, 127/8 should be 127.0.0.0/8 and not 0.0.0.128/8. Also, improved docs on the usage of contains() and friends.
3.15

Finally. Added POD tests (and fixed minor doc bug in IP.pm). As reported by Anand Vijay, negative numbers are assumed to be signed ints and converted accordingly to a v4 address. split() and nth() now work with IPv6 addresses (Thanks to Venkata Pingali for reporting). Tests were added for v6 base functionality and splitting. Also tests for bitwise aritmethic with long integers has been added. I'm afraid Math::BigInt is now required.

Note that IPv6 might not be as solid as I would like. Be careful...

3.16
Fixed a couple of (minor) bugs in shipped tests in the last version. Also, fixed a small pod typo that caused code to show up in the documentation.
3.17
Fixed IP.pm so that all test could pass in Solaris machines. Thanks to all who reported this.
3.18
Fixed some bugs pointed out by David Lloyd, having to do with the module packaging and version requirements. Thanks David!
3.19
Fixed a bug pointed out by Andrew D. Clark, regarding proper parsing of IP ranges with non-contiguous masks. Thanks Andrew!
3.20

Suggestion by Reuland Olivier gave birth to short(), which provides for a compact representation of the IP address. Rewrote _compact to find the longest sequence of zeros to compact. Reuland also pointed out a flaw in contains() and within(), which was fixed. Thanks Reuland!

Fixed rt bug #5478 in t/00-load.t.

3.21
Fixed minor v-string problem pointed out by Steve Snodgrass (Thanks Steve!). NetAddr::IP can now collaborate with Storable to serialize itself.
3.22
Fixed bug rt.cpan.org #7070 reported by Grover Browning (auto-inc/dec on v6 fails). Thanks Grover. Ruben van Staveren pointed out a bug in v6 canonicalization, as well as providing a patch that was applied. Thanks Ruben.
3.23
Included support for Module::Signature. Added ->re() as contributed by Laurent Facq (Thanks Laurent!). Added Coalesce() as suggested by Perullo.
3.24
Version bump. Transfer of 3.23 to CPAN ended up in a truncated file being uploaded.
3.25
Some IP specs resembling range notations but not depicting actual CIDR ranges, were being erroneously recognized. Thanks to Steve Snodgrass for reporting a bug with parsing IP addresses in 4-octet binary format. Added optional Pod::Coverage tests. compact_addr has been commented out, after a long time as deprecated. Improved speed of ->new() for the case of a single host IPv4 address, which seems to be the most common one.
4.00

Dependence on Math::BigInt removed, works with earlier versions of Perl. The module was partitioned into three logical pieces as follows:

Util.pm Math and logic operation on bit strings and number that represent IP addresses and masks. Conversions between various number formats. Implemented in C_XS for speed and PURE PERL of transportability.

Lite.pm Operations, simple conversions and comparisons of IP addresses, notations and formats.

IP.pm Complex operations and conversions of IP address notation, nets, subnets, and ranges.

The internal representation of addresses was changed to 128 bit binary strings as returned by inet_pton (ipv6_aton in this module). Both ipV4 and ipV6 notations can be freely mixed and matched.

Additional methods added to force operations into ipV6 space even when ipV4 notation is used.

AUTHORS

Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton <michael@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.

LICENSE

This software is (c) Luis E. Muñoz, 1999 - 2007, and (c) Michael Robinton, 2006 - 2007. It can be used under the terms of the Perl artistic license provided that proper credit for the work of the authors is preserved in the form of this copyright notice and license for this module.

SEE ALSO 

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