1NAME 2 NetAddr::IP::Lite - Manages IPv4 and IPv6 addresses and subnets 3 4SYNOPSIS 5 use NetAddr::IP::Lite qw( 6 Zeros 7 Ones 8 V4mask 9 V4net 10 :aton DEPRECATED ! 11 :old_nth 12 :upper 13 :lower 14 :nofqdn 15 ); 16 17 my $ip = new NetAddr::IP::Lite '127.0.0.1'; 18 or if your prefer 19 my $ip = NetAddr::IP::Lite->new('127.0.0.1); 20 or from a packed IPv4 address 21 my $ip = new_from_aton NetAddr::IP::Lite (inet_aton('127.0.0.1')); 22 or from an octal filtered IPv4 address 23 my $ip = new_no NetAddr::IP::Lite '127.012.0.0'; 24 25 print "The address is ", $ip->addr, " with mask ", $ip->mask, "\n" ; 26 27 if ($ip->within(new NetAddr::IP::Lite "127.0.0.0", "255.0.0.0")) { 28 print "Is a loopback address\n"; 29 } 30 31 # This prints 127.0.0.1/32 32 print "You can also say $ip...\n"; 33 34 The following four functions return ipV6 representations of: 35 36 :: = Zeros(); 37 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FFFF = Ones(); 38 FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:: = V4mask(); 39 ::FFFF:FFFF = V4net(); 40 41 Will also return an ipV4 or ipV6 representation of a 42 resolvable Fully Qualified Domanin Name (FQDN). 43 44INSTALLATION 45 Un-tar the distribution in an appropriate directory and type: 46 47 perl Makefile.PL 48 make 49 make test 50 make install 51 52 NetAddr::IP::Lite depends on NetAddr::IP::Util which installs by default 53 with its primary functions compiled using Perl's XS extensions to build 54 a 'C' library. If you do not have a 'C' complier available or would like 55 the slower Pure Perl version for some other reason, then type: 56 57 perl Makefile.PL -noxs 58 make 59 make test 60 make install 61 62DESCRIPTION 63 This module provides an object-oriented abstraction on top of IP 64 addresses or IP subnets, that allows for easy manipulations. Most of the 65 operations of NetAddr::IP are supported. This module will work with 66 older versions of Perl and is compatible with Math::BigInt. 67 68 * By default NetAddr::IP functions and methods return string IPv6 69 addresses in uppercase. To change that to lowercase: 70 71 NOTE: the AUGUST 2010 RFC5952 states: 72 73 4.3. Lowercase 74 75 The characters "a", "b", "c", "d", "e", and "f" in an IPv6 76 address MUST be represented in lowercase. 77 78 It is recommended that all NEW applications using NetAddr::IP::Lite be 79 invoked as shown on the next line. 80 81 use NetAddr::IP::Lite qw(:lower); 82 83 * To ensure the current IPv6 string case behavior even if the default 84 changes: 85 86 use NetAddr::IP::Lite qw(:upper); 87 88 The internal representation of all IP objects is in 128 bit IPv6 89 notation. IPv4 and IPv6 objects may be freely mixed. 90 91 The supported operations are described below: 92 93 Overloaded Operators 94 95 Assignment ("=") 96 Has been optimized to copy one NetAddr::IP::Lite object to another 97 very quickly. 98 99 "->copy()" 100 The assignment ("=") operation is only put in to operation when the 101 copied object is further mutated by another overloaded operation. 102 See the overload manpage SPECIAL SYMBOLS FOR "use overload" for 103 details. 104 105 "->copy()" actually creates a new object when called. 106 107 Stringification 108 An object can be used just as a string. For instance, the following 109 code 110 111 my $ip = new NetAddr::IP::Lite '192.168.1.123'; 112 print "$ip\n"; 113 114 Will print the string 192.168.1.123/32. 115 116 my $ip = new6 NetAddr::IP::Lite '192.168.1.123'; 117 print "$ip\n"; 118 119 Will print the string 0:0:0:0:0:0:C0A8:17B/128 120 121 Equality 122 You can test for equality with either "eq", "ne", "==" or "!=". 123 "eq", "ne" allows the comparison with arbitrary strings as well as 124 NetAddr::IP::Lite objects. The following example: 125 126 if (NetAddr::IP::Lite->new('127.0.0.1','255.0.0.0') eq '127.0.0.1/8') 127 { print "Yes\n"; } 128 129 Will print out "Yes". 130 131 Comparison with "==" and "!=" requires both operands to be 132 NetAddr::IP::Lite objects. 133 134 Comparison via >, <, >=, <=, <=> and "cmp" 135 Internally, all network objects are represented in 128 bit format. 136 The numeric representation of the network is compared through the 137 corresponding operation. Comparisons are tried first on the address 138 portion of the object and if that is equal then the NUMERIC cidr 139 portion of the masks are compared. This leads to the 140 counterintuitive result that 141 142 /24 > /16 143 144 Comparison should not be done on netaddr objects with different CIDR 145 as this may produce indeterminate - unexpected results, rather the 146 determination of which netblock is larger or smaller should be done 147 by comparing 148 149 $ip1->masklen <=> $ip2->masklen 150 151 Addition of a constant ("+") 152 Add a 32 bit signed constant to the address part of a NetAddr 153 object. This operation changes the address part to point so many 154 hosts above the current objects start address. For instance, this 155 code: 156 157 print NetAddr::IP::Lite->new('127.0.0.1/8') + 5; 158 159 will output 127.0.0.6/8. The address will wrap around at the 160 broadcast back to the network address. This code: 161 162 print NetAddr::IP::Lite->new('10.0.0.1/24') + 255; 163 164 outputs 10.0.0.0/24. 165 166 Returns the the unchanged object when the constant is missing or out 167 of range. 168 169 2147483647 <= constant >= -2147483648 170 171 Subtraction of a constant ("-") 172 The complement of the addition of a constant. 173 174 Difference ("-") 175 Returns the difference between the address parts of two 176 NetAddr::IP::Lite objects address parts as a 32 bit signed number. 177 178 Returns undef if the difference is out of range. 179 180 Auto-increment 181 Auto-incrementing a NetAddr::IP::Lite object causes the address part 182 to be adjusted to the next host address within the subnet. It will 183 wrap at the broadcast address and start again from the network 184 address. 185 186 Auto-decrement 187 Auto-decrementing a NetAddr::IP::Lite object performs exactly the 188 opposite of auto-incrementing it, as you would expect. 189 190 Methods 191 192 "->new([$addr, [ $mask|IPv6 ]])" 193 "->new6([$addr, [ $mask]])" 194 "->new6FFFF([$addr, [ $mask]])" 195 "->new_no([$addr, [ $mask]])" 196 "->new_from_aton($netaddr)" 197 new_cis and new_cis6 are DEPRECATED 198 "->new_cis("$addr $mask)" 199 "->new_cis6("$addr $mask)" 200 The first three methods create a new address with the supplied 201 address in "$addr" and an optional netmask "$mask", which can be 202 omitted to get a /32 or /128 netmask for IPv4 / IPv6 addresses 203 respectively. 204 205 new6FFFF specifically returns an IPv4 address in IPv6 format 206 according to RFC4291 207 208 new6 ::xxxx:xxxx 209 new6FFFF ::FFFF:xxxx:xxxx 210 211 The third method "new_no" is exclusively for IPv4 addresses and 212 filters improperly formatted dot quad strings for leading 0's that 213 would normally be interpreted as octal format by NetAddr per the 214 specifications for inet_aton. 215 216 new_from_aton takes a packed IPv4 address and assumes a /32 mask. 217 This function replaces the DEPRECATED :aton functionality which is 218 fundamentally broken. 219 220 The last two methods new_cis and new_cis6 differ from new and new6 221 only in that they except the common Cisco address notation for 222 address/mask pairs with a space as a separator instead of a slash 223 (/) 224 225 These methods are DEPRECATED because the functionality is now 226 included in the other "new" methods 227 228 i.e. ->new_cis('1.2.3.0 24') 229 or 230 ->new_cis6('::1.2.3.0 120') 231 232 "->new6" and "->new_cis6" mark the address as being in ipV6 address 233 space even if the format would suggest otherwise. 234 235 i.e. ->new6('1.2.3.4') will result in ::102:304 236 237 addresses submitted to ->new in ipV6 notation will 238 remain in that notation permanently. i.e. 239 ->new('::1.2.3.4') will result in ::102:304 240 whereas new('1.2.3.4') would print out as 1.2.3.4 241 242 See "STRINGIFICATION" below. 243 244 "$addr" can be almost anything that can be resolved to an IP address 245 in all the notations I have seen over time. It can optionally 246 contain the mask in CIDR notation. If the OPTIONAL perl module 247 Socket6 is available in the local library it will autoload and ipV6 248 host6 names will be resolved as well as ipV4 hostnames. 249 250 prefix notation is understood, with the limitation that the range 251 specified by the prefix must match with a valid subnet. 252 253 Addresses in the same format returned by "inet_aton" or 254 "gethostbyname" can also be understood, although no mask can be 255 specified for them. The default is to not attempt to recognize this 256 format, as it seems to be seldom used. 257 258 ###### DEPRECATED, will be remove in version 5 ############ To 259 accept addresses in that format, invoke the module as in 260 261 use NetAddr::IP::Lite ':aton' 262 263 ###### USE new_from_aton instead ########################## 264 265 If called with no arguments, 'default' is assumed. 266 267 If called with an empty string as the argument, returns 'undef' 268 269 "$addr" can be any of the following and possibly more... 270 271 n.n 272 n.n/mm 273 n.n mm 274 n.n.n 275 n.n.n/mm 276 n.n.n mm 277 n.n.n.n 278 n.n.n.n/mm 32 bit cidr notation 279 n.n.n.n mm 280 n.n.n.n/m.m.m.m 281 n.n.n.n m.m.m.m 282 loopback, localhost, broadcast, any, default 283 x.x.x.x/host 284 0xABCDEF, 0b111111000101011110, (or a bcd number) 285 a netaddr as returned by 'inet_aton' 286 287 Any RFC1884 notation 288 289 ::n.n.n.n 290 ::n.n.n.n/mmm 128 bit cidr notation 291 ::n.n.n.n/::m.m.m.m 292 ::x:x 293 ::x:x/mmm 294 x:x:x:x:x:x:x:x 295 x:x:x:x:x:x:x:x/mmm 296 x:x:x:x:x:x:x:x/m:m:m:m:m:m:m:m any RFC1884 notation 297 loopback, localhost, unspecified, any, default 298 ::x:x/host 299 0xABCDEF, 0b111111000101011110 within the limits 300 of perl's number resolution 301 123456789012 a 'big' bcd number (bigger than perl likes) 302 and Math::BigInt 303 304 A Fully Qualified Domain Name which returns an ipV4 address or an 305 ipV6 address, embodied in that order. This previously undocumented 306 feature may be disabled with: 307 308 use NetAddr::IP::Lite ':nofqdn'; 309 310 If called with no arguments, 'default' is assumed. 311 312 If called with and empty string as the argument, 'undef' is 313 returned; 314 315 "->broadcast()" 316 Returns a new object referring to the broadcast address of a given 317 subnet. The broadcast address has all ones in all the bit positions 318 where the netmask has zero bits. This is normally used to address 319 all the hosts in a given subnet. 320 321 "->network()" 322 Returns a new object referring to the network address of a given 323 subnet. A network address has all zero bits where the bits of the 324 netmask are zero. Normally this is used to refer to a subnet. 325 326 "->addr()" 327 Returns a scalar with the address part of the object as an IPv4 or 328 IPv6 text string as appropriate. This is useful for printing or for 329 passing the address part of the NetAddr::IP::Lite object to other 330 components that expect an IP address. If the object is an ipV6 331 address or was created using ->new6($ip) it will be reported in ipV6 332 hex format otherwise it will be reported in dot quad format only if 333 it resides in ipV4 address space. 334 335 "->mask()" 336 Returns a scalar with the mask as an IPv4 or IPv6 text string as 337 described above. 338 339 "->masklen()" 340 Returns a scalar the number of one bits in the mask. 341 342 "->bits()" 343 Returns the width of the address in bits. Normally 32 for v4 and 128 344 for v6. 345 346 "->version()" 347 Returns the version of the address or subnet. Currently this can be 348 either 4 or 6. 349 350 "->cidr()" 351 Returns a scalar with the address and mask in CIDR notation. A 352 NetAddr::IP::Lite object *stringifies* to the result of this 353 function. (see comments about ->new6() and ->addr() for output 354 formats) 355 356 "->aton()" 357 Returns the address part of the NetAddr::IP::Lite object in the same 358 format as the "inet_aton()" or "ipv6_aton" function respectively. If 359 the object was created using ->new6($ip), the address returned will 360 always be in ipV6 format, even for addresses in ipV4 address space. 361 362 "->range()" 363 Returns a scalar with the base address and the broadcast address 364 separated by a dash and spaces. This is called range notation. 365 366 "->numeric()" 367 When called in a scalar context, will return a numeric 368 representation of the address part of the IP address. When called in 369 an array context, it returns a list of two elements. The first 370 element is as described, the second element is the numeric 371 representation of the netmask. 372 373 This method is essential for serializing the representation of a 374 subnet. 375 376 "->bigint()" 377 When called in a scalar context, will return a Math::BigInt 378 representation of the address part of the IP address. When called in 379 an array contest, it returns a list of two elements. The first 380 element is as described, the second element is the Math::BigInt 381 representation of the netmask. 382 383 "$me->contains($other)" 384 Returns true when "$me" completely contains "$other". False is 385 returned otherwise and "undef" is returned if "$me" and "$other" are 386 not both "NetAddr::IP::Lite" objects. 387 388 "$me->within($other)" 389 The complement of "->contains()". Returns true when "$me" is 390 completely contained within "$other", undef if "$me" and "$other" 391 are not both "NetAddr::IP::Lite" objects. 392 393 C->is_rfc1918()> 394 Returns true when "$me" is an RFC 1918 address. 395 396 10.0.0.0 - 10.255.255.255 (10/8 prefix) 397 172.16.0.0 - 172.31.255.255 (172.16/12 prefix) 398 192.168.0.0 - 192.168.255.255 (192.168/16 prefix) 399 400 "->is_local()" 401 Returns true when "$me" is a local network address. 402 403 i.e. ipV4 127.0.0.0 - 127.255.255.255 404 or ipV6 === ::1 405 406 "->first()" 407 Returns a new object representing the first usable IP address within 408 the subnet (ie, the first host address). 409 410 "->last()" 411 Returns a new object representing the last usable IP address within 412 the subnet (ie, one less than the broadcast address). 413 414 "->nth($index)" 415 Returns a new object representing the *n*-th usable IP address 416 within the subnet (ie, the *n*-th host address). If no address is 417 available (for example, when the network is too small for "$index" 418 hosts), "undef" is returned. 419 420 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite 421 implements "->nth($index)" and "->num()" exactly as the 422 documentation states. Previous versions behaved slightly differently 423 and not in a consistent manner. 424 425 To use the old behavior for "->nth($index)" and "->num()": 426 427 use NetAddr::IP::Lite qw(:old_nth); 428 429 old behavior: 430 NetAddr::IP->new('10/32')->nth(0) == undef 431 NetAddr::IP->new('10/32')->nth(1) == undef 432 NetAddr::IP->new('10/31')->nth(0) == undef 433 NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/31 434 NetAddr::IP->new('10/30')->nth(0) == undef 435 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.1/30 436 NetAddr::IP->new('10/30')->nth(2) == 10.0.0.2/30 437 NetAddr::IP->new('10/30')->nth(3) == 10.0.0.3/30 438 439 Note that in each case, the broadcast address is represented in the 440 output set and that the 'zero'th index is alway undef except for a 441 point-to-point /31 or /127 network where there are exactly two 442 addresses in the network. 443 444 new behavior: 445 NetAddr::IP->new('10/32')->nth(0) == 10.0.0.0/32 446 NetAddr::IP->new('10.1/32'->nth(0) == 10.0.0.1/32 447 NetAddr::IP->new('10/31')->nth(0) == 10.0.0.0/32 448 NetAddr::IP->new('10/31')->nth(1) == 10.0.0.1/32 449 NetAddr::IP->new('10/30')->nth(0) == 10.0.0.1/30 450 NetAddr::IP->new('10/30')->nth(1) == 10.0.0.2/30 451 NetAddr::IP->new('10/30')->nth(2) == undef 452 453 Note that a /32 net always has 1 usable address while a /31 has 454 exactly two usable addresses for point-to-point addressing. The 455 first index (0) returns the address immediately following the 456 network address except for a /31 or /127 when it return the network 457 address. 458 459 "->num()" 460 As of version 4.42 of NetAddr::IP and version 1.27 of 461 NetAddr::IP::Lite a /31 and /127 with return a net num value of 2 462 instead of 0 (zero) for point-to-point networks. 463 464 Version 4.00 of NetAddr::IP and version 1.00 of NetAddr::IP::Lite 465 return the number of usable IP addresses within the subnet, not 466 counting the broadcast or network address. 467 468 Previous versions worked only for ipV4 addresses, returned a maximum 469 span of 2**32 and returned the number of IP addresses not counting 470 the broadcast address. (one greater than the new behavior) 471 472 To use the old behavior for "->nth($index)" and "->num()": 473 474 use NetAddr::IP::Lite qw(:old_nth); 475 476 WARNING: 477 478 NetAddr::IP will calculate and return a numeric string for network 479 ranges as large as 2**128. These values are TEXT strings and perl 480 can treat them as integers for numeric calculations. 481 482 Perl on 32 bit platforms only handles integer numbers up to 2**32 483 and on 64 bit platforms to 2**64. 484 485 If you wish to manipulate numeric strings returned by NetAddr::IP 486 that are larger than 2**32 or 2**64, respectively, you must load 487 additional modules such as Math::BigInt, bignum or some similar 488 package to do the integer math. 489 490EXPORT_OK 491 Zeros 492 Ones 493 V4mask 494 V4net 495 :aton DEPRECATED 496 :old_nth 497 :upper 498 :lower 499 :nofqdn 500 501AUTHORS 502 Luis E. Muñoz <luismunoz@cpan.org>, Michael Robinton 503 <michael@bizsystems.com> 504 505WARRANTY 506 This software comes with the same warranty as perl itself (ie, none), so 507 by using it you accept any and all the liability. 508 509COPYRIGHT 510 This software is (c) Luis E. Muñoz, 1999 - 2005 511 and (c) Michael Robinton, 2006 - 2014. 512 513 All rights reserved. 514 515 This program is free software; you can redistribute it and/or modify it 516 under the terms of either: 517 518 a) the GNU General Public License as published by the Free 519 Software Foundation; either version 2, or (at your option) any 520 later version, or 521 522 b) the "Artistic License" which comes with this distribution. 523 524 This program is distributed in the hope that it will be useful, but 525 WITHOUT ANY WARRANTY; without even the implied warranty of 526 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU 527 General Public License or the Artistic License for more details. 528 529 You should have received a copy of the Artistic License with this 530 distribution, in the file named "Artistic". If not, I'll be glad to 531 provide one. 532 533 You should also have received a copy of the GNU General Public License 534 along with this program in the file named "Copying". If not, write to 535 the 536 537 Free Software Foundation, Inc., 538 51 Franklin Street, Fifth Floor 539 Boston, MA 02110-1301 USA 540 541 or visit their web page on the internet at: 542 543 http://www.gnu.org/copyleft/gpl.html. 544 545SEE ALSO 546 NetAddr::IP(3), NetAddr::IP::Util(3), NetAddr::IP::InetBase(3) 547 548