Newer
Older
NetAddr-IP / README
  1. -----BEGIN PGP SIGNED MESSAGE-----
  2. Hash: SHA1
  3.  
  4. NetAddr::IP - Manages IP addresses and subnets
  5.  
  6. * * * * THIS MODULE REQUIRES PERL 5.6.0 OR NEWER. * * * *
  7.  
  8. This module is designed as a help for managing (ranges of) IP
  9. addresses. It includes efficient implementations for most common tasks
  10. done to subnets or ranges of IP addresses, namely verifying if an
  11. address is within a subnet, comparing, looping, splitting subnets into
  12. longer prefixes, compacting addresses to the shortest prefixes, etc.
  13.  
  14. The general idea, is that you should be able to do
  15.  
  16. use NetAddr::IP;
  17.  
  18. my $ip = new NetAddr::IP $something_vaguely_resembling_a_subnet;
  19.  
  20. and as long as $something_vaguely_resembling_a_subnet holds something
  21. that describes a subnet unambiguously, you should receive an object
  22. representing such subnet. Currently this includes various flavors of
  23. CIDR notation, traditional notation in one, two, three and four dotted
  24. octets, hexadecimal, range and subnet notations.
  25.  
  26. Overloading is also used to ease printing and doing simple aritmetic
  27. and comparisons on the IP addresses. For instance, you can do things
  28. like:
  29.  
  30. use NetAddr::IP;
  31.  
  32. for (my $ip = new NetAddr::IP '10.0.0.1/28';
  33. $ip < $ip->broadcast;
  34. $ip ++)
  35. {
  36. print "$ip\n";
  37. }
  38.  
  39. This will print out something like...
  40.  
  41. 10.0.0.1/28
  42. 10.0.0.2/28
  43. 10.0.0.3/28
  44. 10.0.0.4/28
  45. 10.0.0.5/28
  46. (and so on...)
  47.  
  48. ...which is quite useful for generating config files and the
  49. such. This works even for huge ranges of IP addresses.
  50.  
  51. As of version 3.14_1, it is able to handle some representations of v6
  52. subnets thanks to Kadlecsik Jozsi. Note that this support is still
  53. preliminary and has not been widely tested.
  54.  
  55. This module is entirely written in Perl, so you do not need access to
  56. a compiler to use it. It has been extensively tested in a variety of
  57. platforms. An extensive test suite is provided with the module to
  58. verify correct results.
  59.  
  60. The lastest version of this module should be preferred. You can obtain
  61. it on http://www.cpan.org/authors/id/L/LU/LUISMUNOZ/ or one of the
  62. many CPAN mirrors. Please find a mirror near you to help spread the
  63. load.
  64.  
  65. Note that version 3 and above is not completely backwards compatible
  66. with version 2. Version 2 was a somewhat unstable work that grew too
  67. fast. If you're upgrading from 2.xx, please review your code as some
  68. methods no longer exist or have changed.
  69.  
  70. **********************************************************************
  71. * VERSIONS EARLIER THAN 3.00 WON'T BE SUPPORTED AT ALL. PLEASE DON'T *
  72. * EVEN ASK. I have very limited time and this module has grown quite *
  73. * popular. Please help me help you by staying up to date with it. If *
  74. * you find a bug, upgrade to the latest version on CPAN prior to *
  75. * contacting me. *
  76. **********************************************************************
  77.  
  78. To install, follow the standard CPAN recipe of:
  79.  
  80. $ perl Makefile.PL
  81. $ make
  82. $ make test
  83.  
  84. If all tests pass, then do
  85.  
  86. $ make install
  87.  
  88. The test suite includes a lot of cases. Note that currently, some
  89. tests require Test::More. Eventually all tests will require it, so you
  90. should really consider installing it if your Perl did not include this
  91. module.
  92.  
  93. Tests related to address compaction could be too resource-intensive in
  94. some environments. If this is your case, you can skip those tests by
  95. setting an environment variable before make'ing test. In a bash-like
  96. shell, you could use the following example:
  97.  
  98. $ LIGHTERIPTESTS=yes; export LIGHTERIPTESTS
  99.  
  100. The module's documentation can be accessed through POD. After
  101. installing the module, you can do
  102.  
  103. $ perldoc NetAddr::IP
  104.  
  105. to access the documentation. There is also a tutorial in HTML. Look
  106. for the file tutorial.htm within the package bundle, which is a
  107. tutorial I submitted to perlmonks.org recently.
  108.  
  109. Bug reports are welcome. Please do not forget to tell me what
  110. version/platform are you running this code on. Providing a small piece
  111. of code that shows the bug helps me a lot in sorting it out and
  112. possibly in writting more tests for the distribution.
  113.  
  114. Also, this code is intended to be strict and -w safe, so please report
  115. cases where warnings are generated so that I can fix them.
  116.  
  117. Report your bugs to me (luismunoz@cpan.org).
  118.  
  119. SECURITY CONSIDERATIONS
  120.  
  121. I have no control on the machanisms involved in the storage or
  122. transport of this distribution. This means that I cannot guarantee
  123. that the distribution you have in your hands is indeed, the same
  124. distribution I packed and uploaded.
  125.  
  126. Starting with v3.14_1, along the distribution file, you should have a
  127. file with the extension ".asc". This contains a GPG "detached
  128. signature" that makes it impossible for anybody to alter this
  129. distribution. If security is of any concern to you, by all means
  130. verify the signature of this file and contact the author if any
  131. discrepancy is detected.
  132.  
  133. You can find more information about this at the following URL
  134.  
  135. http://mipagina.cantv.net/lem/gpg/
  136.  
  137. This information includes the correct keys, fingerprints, etc.Note
  138. that this README file should also be signed.
  139.  
  140. LICENSE AND WARRANTY
  141.  
  142. This software is (c) Luis E. Muñoz. It can be used under the terms of
  143. the perl artistic license provided that proper credit for the work of
  144. the author is preserved in the form of this copyright notice and
  145. license for this module.
  146.  
  147. No warranty of any kind is expressed or implied. This code might make
  148. your computer go up in a puff of black smoke.
  149. -----BEGIN PGP SIGNATURE-----
  150. Version: GnuPG v1.0.6 (Darwin)
  151. Comment: For info see http://www.gnupg.org
  152.  
  153. iD8DBQE99iAmQyDWGRI/hhARAsPlAJ9VFVFGSUHjxDUvXm2x9x20YfhuYQCeJu5A
  154. F5c3pam/zZQiVf7ZaUVs3fc=
  155. =VNNB
  156. -----END PGP SIGNATURE-----