NAME

Net::CIDR::Lookup

DESCRIPTION

This class implements a lookup table indexed by IPv4 networks or hosts.

• Addresses are accepted in numeric form (integer with separate netbits argument), as strings in CIDR notation or as IP address ranges

• Overlapping or adjacent networks are automatically coalesced if their associated values are equal.

• The table is implemented as a binary tree so lookup and insertion take O(log n) time.

Methods generally return a true value on success and undef on error. In the latter case, an error message will be available in $Net::CIDR::Lookup::errstr

SYNOPSIS

  use Net::CIDR::Lookup;

  $cidr = Net::CIDR::Lookup->new;
  $cidr->add("192.168.42.0/24",1);    # Add first network, value 1
  $cidr->add_num(167772448,27,2);     # 10.0.1.32/27 => 2
  $cidr->add("192.168.43.0/24",1);    # Automatic coalescing to a /23
  $cidr->add("192.168.41.0/24",2);    # Stays separate due to different value
  $cidr->add("192.168.42.128/25",2);  # Error: overlaps with different value

  $h = $cidr->dump;                   # Convert tree to a hash

  print "$k => $v\n" while(($k,$v) = each %$h);

  # Output (order may vary):
  # 192.168.42.0/23 => 1
  # 10.0.1.32/27 => 2
  # 192.168.41.0/24 => 2

  $cidr->walk(sub {
      my ($addr, $bits, $val) = @_;
      print join('.', unpack 'C*', pack 'N', $addr), "/$bits => $val\n"
    }
  );

  # Output (fixed order):
  # 10.0.1.32/27 => 2
  # 192.168.41.0/24 => 2
  # 192.168.42.0/23 => 1

  $cidr->clear;                                 # Remove all entries
  $cidr->add_range('1.2.3.11 - 1.2.4.234', 42); # Add a range of addresses, automatically split into CIDR blocks
  $h = $cidr->dump;
  print "$k => $v\n" while(($k,$v) = each %$h);

  # Output (order may vary):
  # 1.2.4.128/26 => 42
  # 1.2.3.32/27 => 42
  # 1.2.3.64/26 => 42
  # 1.2.4.234/32 => 42
  # 1.2.4.0/25 => 42
  # 1.2.3.12/30 => 42
  # 1.2.3.128/25 => 42
  # 1.2.3.16/28 => 42
  # 1.2.4.224/29 => 42
  # 1.2.4.232/31 => 42
  # 1.2.3.11/32 => 42
  # 1.2.4.192/27 => 42

HISTORY

v0.3 First CPAN release

v0.3.1

• Replaced the simplistic list-based CIDR block splitting function with bit-fiddling for about a threefold speedup of add_num_range and slightly less in add_range.

• Recursive merging-up up of blocks during add_* works now. If e.g. you had a /24 and an adjacent /25 net with the same value before, adding a new /25 would have merged the new block with the existing /25, resulting in two adjacent /24s with the same value because only single-level merging was possible. Now the two will be merged to a single /23.

• Removed some redundant tests and added new ones.

• Removed some leftover debug code.

• Some small fixes/improvements like stricter range checking in add_range

METHODS

new

Arguments: none

Return Value: new object

add

Arguments: $cidr, $value

Return Value: true for successful completion, undef otherwise

Adds VALUE to the tree under the key CIDR. CIDR must be a string containing an IPv4 address followed by a slash and a number of network bits. Bits to the right of this mask will be ignored.

add_range

Arguments: $range, $value

Return Value: true for successful completion, undef otherwise

Adds VALUE to the tree for each address included in RANGE which must be a hyphenated range of IP addresses in dotted-quad format (e.g. "192.168.0.150-192.168.10.1") and with the first address being numerically smaller the second. This range will be split up into as many CIDR blocks as necessary (algorithm adapted from a script by Dr. Liviu Daia).

add_num

Arguments: $address, $bits, $value

Return Value: true for successful completion, undef otherwise

Like add() but accepts address and bits as separate integer arguments instead of a string.

add_num_range

Arguments: $start, $end, $value

Return Value: true for successful completion, undef otherwise

Like add_range() but accepts addresses as separate integer arguments instead of a range string.

lookup

Arguments: $address

Return Value: value assoiated with this address or undef

Looks up an address and returns the value associated with the network containing it. So far there is no way to tell which network that is though.

lookup_num

Arguments: $address

Return Value: value assoiated with this address or undef

Like lookup() but accepts the address in integer form.

dump

Arguments: none

Return Value: $hashref

Returns a hash representation of the tree with keys being CIDR-style network addresses.

walk

Arguments: $coderef to call for each tree entry. Callback arguments are:

$address

The network address in integer form

$bits

The current CIDR block's number of network bits

$value

The value associated with this block

Return Value: nothing useful

clear

Arguments: none

Return Value: nothing useful

Remove all entries from the tree.

BUGS

• I didn't need deletions yet and deleting parts of a CIDR block is a bit more complicated than anything this class does so far, so it's not implemented.

• Storing an undef value does not work and yields an error. This would be relatively easy to fix at the cost of some memory so that's more a design decision.

• Using a package-global for error reporting was an incredibly stupid idea initially. This will change in the next version.

• IPv6 is not supported, which is a shame.

AUTHORS, COPYRIGHTS & LICENSE

Matthias Bethke <matthias@towiski.de> while working for 1&1 Internet AG

Licensed unter the Artistic License 2.0

SEE ALSO

This module's methods are based loosely on those of Net::CIDR::Lite

cpanm Net::CIDR::Lookup

perl -MCPAN -e shell
install Net::CIDR::Lookup