@Luis Muñoz Luis Muñoz authored on 11 Sep 2005
Gitpan committed on 21 Oct 2014
t Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
IP.pm Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
MANIFEST Import of LUISMUNOZ/NetAddr-IP-3.24 from CPAN. 19 years ago
MANIFEST.SKIP Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
META.yml Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
Makefile.PL Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
README Import of LUISMUNOZ/NetAddr-IP-3.24 from CPAN. 19 years ago
SIGNATURE Import of LUISMUNOZ/NetAddr-IP-3.25 from CPAN. 18 years ago
TODO Import of LUISMUNOZ/NetAddr-IP-3.24 from CPAN. 19 years ago
README
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1




NetAddr::IP - Manages IP addresses and subnets

     * * * * THIS MODULE REQUIRES PERL 5.6.0 OR NEWER. * * * *

This  module  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.

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.

As of version 3.14_1, it is  able to handle some representations of v6
subnets thanks  to Kadlecsik  Jozsi. Note that  this support  is still
preliminary and has not been widely tested.

This module is entirely written in  Perl, so you do not need access to
a compiler to use it.  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 http://www.cpan.org/authors/id/L/LU/LUISMUNOZ/  or  one of  the
many CPAN  mirrors. Please find a  mirror near you to  help spread the
load.

Note that version  3 and above is not  completely backwards compatible
with version 2.  Version 2 was a somewhat unstable  work that grew too
fast. If you're  upgrading from 2.xx, please review  your code as some
methods no longer exist or have changed.

**********************************************************************
* VERSIONS EARLIER THAN 3.00 WON'T BE SUPPORTED AT ALL. PLEASE DON'T *
* EVEN ASK. I have very limited time and this module has grown quite *
* popular. Please help me help you by staying up to date with it. If *
* you find a bug, upgrade  to the  latest version  on CPAN  prior to *
* contacting me.                                                     *
**********************************************************************

To install, follow the standard CPAN recipe of:

$ perl Makefile.PL
$ make
$ make test

If all tests pass, then do

$ make install

The  test suite includes  a lot  of cases.  Note that  currently, some
tests require Test::More. Eventually all tests will require it, so you
should really consider installing it if your Perl did not include this
module.

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

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

$ perldoc NetAddr::IP

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 of them :)

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

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.  It can be used under the terms of
the perl artistic license provided  that proper credit for the work of
the  author 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)

iD8DBQFCQwzJQyDWGRI/hhARAqd9AJ0XLAPEZ/r0laqAs4XhZ26xf00OAQCgzYxk
IjdkSW+uHhcUXN6nJlo7yqA=
=9Ztj
-----END PGP SIGNATURE-----