-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1





NetAddr::IP - Manage IP addresses and subnets

This distribution  is designed as a  help for managing  (ranges of) IP
addresses. It includes efficient implementations for most common tasks
done  to subnets or  ranges of  IP addresses,  namely verifying  if an
address is within a subnet, comparing, looping, splitting subnets into
longer prefixes, compacting addresses to the shortest prefixes, etc.

The general idea, is that you should be able to do 

  use NetAddr::IP;

  my $ip = new NetAddr::IP $something_vaguely_resembling_a_subnet;

and as long  as $something_vaguely_resembling_a_subnet holds something
that describes  a subnet unambiguously,  you should receive  an object
representing such  subnet. Currently this includes  various flavors of
CIDR notation, traditional notation in one, two, three and four dotted
octets, hexadecimal, range and subnet notations as well as other, less
used formats. IPv6 addresses are also supported.

Overloading is also  used to ease printing and  doing simple aritmetic
and comparisons on  the IP addresses. For instance,  you can do things
like:

  use NetAddr::IP;

  for (my $ip = new NetAddr::IP '10.0.0.1/28';
       $ip < $ip->broadcast;
       $ip ++) 
  {
    print "$ip\n";
  }

This will print out something like...

10.0.0.1/28
10.0.0.2/28
10.0.0.3/28
10.0.0.4/28
10.0.0.5/28
(and so on...)

...which  is  quite  useful   for  generating  config  files  and  the
such. This works even for huge ranges of IP addresses.

This module can  be installed without compiling any  XS code, although
some  parts are available  as XS  for speed.  It has  been extensively
tested in a variety of platforms.  An extensive test suite is provided
with the module to verify correct results.

The lastest version of this module should be preferred. You can obtain
it on the  nearest CPAN mirror. Please find a mirror  near you to help
spread the load.

Version 4 works with earlier versions of perl at least back to 5.00503 
however overloaded iterative arrays and binary bit strings 0b101010101
are not supported in versions of perl prior to 5.6.0.

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

  use NetAddr::IP::Lite qw(:old_nth);

  old behavior:
  NetAddr::IP->new('10/32')->nth(0) == undef
  NetAddr::IP->new('10/32')->nth(1) == undef
  NetAddr::IP->new('10/31')->nth(0) == undef  
  NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31
  NetAddr::IP->new('10/30')->nth(0) == undef  
  NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30
  NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30
  NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30

Note that  in each case, the  broadcast address is  represented in the
output set and that the 'zero'th index is alway undef.

  new behavior:
  NetAddr::IP->new('10/32')->nth(0)  == 10.0.0.0/32
  NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32
  NetAddr::IP->new('10/31')->nth(0)  == undef  
  NetAddr::IP->new('10/31')->nth(1)  == undef
  NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30
  NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30
  NetAddr::IP->new('10/30')->nth(2) == undef

Note that a /32  net always has 1 usable address while  a /31 has none
since  it   has  a  network   and  broadcast  address,  but   no  host
addresses.  The  first  index  (0)  returns  the  address  immediately
following the network address.

To install, follow the standard CPAN recipe of:

$ perl Makefile.PL
$ make
$ make test

If all tests pass, then do

$ make install

NetAddr::IP depends  on NetAddr::IP::Util which  utilizes perl_xs.  If
you do not  have a C compiler  on your system or you  would prefer the
slower PURE PERL version for some obtuse reason then build as follows:

$ perl Makefile.PL -noxs
$ make
$ make test

$ make install

Tests related to address compaction could be too resource-intensive in
some environments. If  this is your case, you can  skip those tests by
setting an environment variable  before make'ing test.  In a bash-like
shell, you could use the following example:

$ LIGHTERIPTESTS=yes; export LIGHTERIPTESTS
$ make test

The  module's  documentation  can   be  accessed  through  POD.  After
installing the module, you can do

$ perldoc NetAddr::IP
$ perldoc NetAddr::IP::Lite
$ perldoc NetAddr::IP::Util
$ perldoc NetAddr::IP::UtilPP

to access the  documentation. There is also a tutorial  in HTML at the
following URIs

  http://mipagina.cantv.net/lem/perl/iptut.htm
  http://mipagina.cantv.net/lem/perl/ipperf.htm

If  you want to  thank me  for this  module, please  go look  at those
tutorials and if you see banners there, click on a few :)

Bug  reports  are  welcome. Please  do  not  forget  to tell  me  what
version/platform are you running this code on. Providing a small piece
of  code that  shows the  bug helps  me a  lot in  sorting it  out and
possibly in writting more tests for the distribution.

Also, this code is intended to be strict and -w safe, so please report
cases where warnings are generated so that I can fix them.

Report your  bugs to  me (luismunoz@cpan.org) or  through the  CPAN RT
interface at http://rt.cpan.org/.

DO YOU WANT TO THANK ME?

If  you consider this  a valuable  contribution, there  is a  web page
where you can express your gratitude. Please see

	http://mipagina.cantv.net/lem/thanks-en.html (English)
	http://mipagina.cantv.net/lem/thanks-es.html (Spanish)

SECURITY CONSIDERATIONS

I  have  no control  on  the machanisms  involved  in  the storage  or
transport  of this distribution.  This means  that I  cannot guarantee
that  the distribution  you have  in your  hands is  indeed,  the same
distribution I packed and uploaded.

Starting with v3.14_1, along the  distribution file, you should have a
file  with  the  extension  ".asc".  This  contains  a  GPG  "detached
signature"  that  makes  it  impossible  for  anybody  to  alter  this
distribution.  If security  is of  any concern  to you,  by  all means
verify  the signature  of  this file  and  contact the  author if  any
discrepancy is detected.

You can find more information about this at the following URL

             http://mipagina.cantv.net/lem/gpg/

This  information includes  the correct  keys,  fingerprints, etc.Note
that this README file should also be signed.

Additionally,  I am  also  using Module::Signature  to  ease with  the
signature  verification. Module::Signature can  automatically retrieve
the  PGP  keys from  public  keyservers,  as  well as  verifying  each
individual file.

LICENSE AND WARRANTY

This software is (c) Luis E. Muñoz and Michael A. Robinton.  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.

No warranty of any kind is  expressed or implied. This code might make
your computer go up in a puff of black smoke.

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.1 (Darwin)

iD8DBQFE4KXRQyDWGRI/hhARAqjSAJ4/MnV9e01zLfrIJ1CtfwfaJiKUDwCePdhb
djsPkRD3CRKuxz5d+9oX9zc=
=srrF
-----END PGP SIGNATURE-----