ipadmin 0.1.0

data/README

@@ -0,0 +1,228 @@
+
+ Copyright (c) 2006 Dustin Spinhirne <dspinhir@yahoo.com>
+ Licensed under the same terms as Ruby, No Warranty is provided.
+
+
+ Comments are welcome. Please include 'Ruby - IPAdmin' in the title of
+ any emails. 
+ 
+ Dustin Spinhirne
+ 
+ 
+ 
+ 
+ 
+=Examples:
+ 
+ 
+ require 'rubygems'
+ require_gem 'ipadmin'
+ 
+ 
+ #============================================================================#
+ # IPAdmin::IPAddr
+ #============================================================================#
+ puts "IPAdmin::IPAddr"
+ 
+ begin
+     ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1/24')
+     ip4 = IPAdmin::IPAddr.new(:IPAddr => '192.168.1.1',
+                               :Netmask => '255.255.255.0',
+                               :Tag => {'test' => 'ip4 tag'})
+     ip6 = IPAdmin::IPAddr.new(:IPAddr => 'fec0::1/64')
+     rescue Exception
+     puts 'oops'
+     exit
+ end
+  
+ puts ip4.tag['test']
+ ip4.tag['test'] = 'modified ip4 tag'
+ puts ip4.tag['test']
+ 
+ puts "base addr #{ip4.base()}"
+ puts "base addr #{ip6.base()}"
+
+ puts "bcast addr #{ip4.broadcast()}"
+
+ puts "description #{ip4.desc()}"
+ puts "description #{ip6.desc()}"
+
+ puts "extended hostmask #{ip4.hostmask_ext()}"
+ puts "extended netmask #{ip4.netmask_ext()}"
+
+ puts "ip addr #{ip4.ip()}"
+ puts "ip addr #{ip6.ip()}"
+
+ puts "netmask in bits #{ip4.netmask()}"
+ puts "netmask in bits #{ip6.netmask()}"
+
+ print "\n\n\n"
+ #=====================================#
+ #     
+ #=====================================#
+
+
+ #============================================================================#
+ # IPAdmin::CIDR
+ #============================================================================#
+ puts "IPAdmin::CIDR"
+
+ begin
+    cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+    cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0',
+                              :Netmask => '255.255.255.0',
+                              :Tag => {'test' => 'cidr4 tag'})
+    cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
+    rescue Exception
+    puts 'oops'
+    exit
+ end
+ 
+ puts cidr4.tag['test']
+ cidr4.tag['test'] = 'modified cidr4 tag'
+ puts cidr4.tag['test']
+
+ puts "cidr4 contains ip4" if ( cidr4.contains(ip4) )
+ puts "cidr6 contains ip6" if ( cidr6.contains(ip6) )
+ 
+ puts "description #{cidr4.desc()}"
+ puts "description #{cidr6.desc()}"
+ 
+ puts "extended hostmask #{cidr4.hostmask_ext()}"
+ puts "extended netmask #{cidr4.netmask_ext()}"
+ 
+ puts "netmask in bits #{cidr4.netmask()}"
+ puts "netmask in bits #{cidr6.netmask()}"
+ 
+ puts "network address #{cidr4.network()}"
+ puts "network address #{cidr6.network()}"
+ 
+ puts "1st ip is #{cidr4.nth(:Index => 1)}"
+ puts "1st ip is #{(cidr6.nth(:Index => 1, :Objectify => 1)).desc}"
+ 
+ puts "cidr4 size is #{cidr4.size()}"
+ puts "cidr6 size is #{cidr6.size()}"
+ 
+ cidr4.enumerate(:Limit => 4, :BitStep => 32) {|addr| puts addr}
+ cidr6.enumerate(:Limit => 4, :BitStep => 32, :Objectify => 1) {|addr| puts  addr.desc()}
+ 
+ cidr4.subnet(:Subnet => 28, :MinCount => 3) {|cidr| puts cidr.desc()}
+ cidr6.subnet(:Subnet => 66, :MinCount => 4) {|cidr| puts cidr.desc()}
+ 
+ print "\n\n\n" 
+ #=====================================#
+ #     
+ #=====================================#
+
+
+ #============================================================================#
+ # IPAdmin::CIDRTable
+ #============================================================================#
+ puts "IPAdmin::CIDRTable"
+
+ cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+ cidr4_2 = IPAdmin::CIDR.new(:CIDR => '10.1.0.0/24')
+ cidr4_3 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
+ cidr4_4 =IPAdmin::CIDR.new(:CIDR => '192.168.1.0/30')
+ cidr4_5 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
+ cidr4_6 = IPAdmin::CIDR.new(:CIDR => '192.168.1.128/26')
+ cidr4_7 = IPAdmin::CIDR.new(:CIDR => '192.168.1.192/26')
+         
+ cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::/10')
+ cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fe80::/10')
+ cidr6_3 = IPAdmin::CIDR.new(:CIDR => 'fec0::/64')
+ cidr6_4 =IPAdmin::CIDR.new(:CIDR => 'fec0::/126')
+ 
+ begin
+    table4 = IPAdmin::CIDRTable.new(4)
+    table6 = IPAdmin::CIDRTable.new(6)
+    rescue Exception
+    puts 'oops'
+    exit
+ end
+         
+ table4.add_cidr(cidr4_1)
+ table4.add_cidr(cidr4_2)
+ table4.add_cidr(cidr4_3)
+ table4.add_cidr(cidr4_4)
+ table4.add_cidr(cidr4_5)
+ table4.add_cidr(cidr4_6)
+ table4.add_cidr(cidr4_7)
+ 
+ table6.add_cidr(cidr6_1)
+ table6.add_cidr(cidr6_2)
+ table6.add_cidr(cidr6_3)
+ table6.add_cidr(cidr6_4)
+
+ puts "ip4 belongs in #{table4.find_ip(ip4).desc}"
+ puts "ip6 belongs in #{table6.find_ip(ip6).desc}"
+ 
+ puts "all blocks that can hold a /27"
+ list4 = table4.find_space(:Size => 27)
+ list4.each do |cidr|
+    puts "  #{cidr.desc()}"
+ end
+ 
+ puts "first block that can hold a /64"
+ list6 = table6.find_space(:Size => 64, :Limit => 1)
+ list6.each do |cidr|
+    puts "  #{cidr.desc()}"
+ end
+ 
+ 
+ puts 'dump table4...'
+ dump4 = table4.dump 
+ dump4.each do |cidr|
+    puts "  #{cidr.desc}"
+ end
+ puts 'dump table6...'
+ dump6 = table6.dump 
+ dump6.each do |cidr|
+     puts "  #{cidr.desc}"
+ end
+
+ print "\n\n\n"
+ #=====================================#
+ #     
+ #=====================================#
+
+
+ #============================================================================#
+ # IPAdmin Misc Methods
+ #============================================================================#
+ puts "Misc Methods"
+
+ puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv4_addr('192.168.1.0') )
+ puts "192.168.1.0 is valid" if ( IPAdmin.validate_ipv6_addr('fec0::0') )
+ 
+ puts "255.255.255.0 is valid" if (IPAdmin.validate_ipv4_netmask('255.255.255.0') )
+ puts "/24 is valid" if ( IPAdmin.validate_ipv4_netmask(24) )
+ puts "/64 is valid" if ( IPAdmin.validate_ipv6_netmask(64) )
+ 
+ cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+ cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/25')
+ cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/10')
+ cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
+ 
+ comp1 = IPAdmin.compare_cidr(cidr4_1,cidr4_2)
+ comp2 = IPAdmin.compare_cidr(cidr6_1,cidr6_2)
+ puts "#{(comp1[0]).desc} is the supernet of #{(comp1[1]).desc}"
+ puts "#{(comp2[0]).desc} is the supernet of #{(comp2[1]).desc}"
+ 
+ cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+ cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.0.0/24')
+ cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/128')
+ cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::1/128')
+ 
+ puts "192.168.1.0/24 and 192.168.0.0/24 merge into #{IPAdmin.merge_cidr([cidr4_1,cidr4_2]).desc}"
+ puts "fec0::0/128 and fec0::1/128 merge into #{IPAdmin.merge_cidr([cidr6_1,cidr6_2]).desc}"
+ 
+ print "\n\n\n"
+ #=====================================#
+ #     
+ #=====================================#
+ 
+
+
+
+

data/lib/ip_admin.rb

@@ -0,0 +1,2317 @@
+module IPAdmin
+
+
+
+#============================================================================#
+# compare_cidr()
+#============================================================================#
+
+# Compare cidr addresses of two IPAdmin::CIDR objects.
+# - Arguments:
+#   * Two IPAdmin::CIDR objects
+# 
+# - Returns:
+#   * if one object is a subnet of another, then return an array in order of
+#     [supernet,subnet]
+#   * if both are equal, return 1
+#   * if neither is a subnet of the other, return nil
+#
+def compare_cidr(cidr1,cidr2)
+    
+    # we only accept CIDR objects
+    unless ( (cidr1.kind_of? IPAdmin::CIDR)&&(cidr2.kind_of? IPAdmin::CIDR) )
+        raise "Expected IPAdmin::CIDR, but #{options.class} provided."
+    end
+    
+    # make sure both are same version
+    unless (cidr1.version == cidr2.version )
+        raise "Provider CIDR objects are incompatible: " +
+              "#{cidr1.desc}/ and #{cidr2.desc}."
+    end
+    
+    network1 = cidr1.packed_network
+    network2 = cidr2.packed_network
+    netmask1 = cidr1.packed_netmask
+    netmask2 = cidr2.packed_netmask
+    
+    
+    # make sure cidr's arent equal. return 1's if they are
+    if ( (network1 == network2) && (netmask1 == netmask2) )
+        return(1)
+    end
+    
+    
+    # whichever netmask is smaller will be the supernet
+    # if we '&' both networks by the supernet, and they are
+    # equal, then the supernet is the parent of the other network
+    if (netmask1 > netmask2)
+        if ( (netmask2 & network1) == (netmask2 & network2) )
+            supernet = cidr2
+            subnet = cidr1
+        end
+
+    else
+        if ( (netmask1 & network1) == (netmask1 & network2) )
+            supernet = cidr1
+            subnet = cidr2
+        end
+
+    end
+    
+        
+    if (supernet)
+        return([supernet,subnet])
+    else
+        return(nil)
+    end
+    
+end
+module_function :compare_cidr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# merge_cidr()
+#============================================================================#
+
+# Merge (supernet) contiguous IPAdmin::CIDR blocks into a single block.
+# Blocks must be contiguous, and must be able to form a single supernet.
+# 
+# - Arguments:
+#   * array of IPAdmin::CIDR objects to merge
+# 
+# - Returns:
+#   * IPAdmin::CIDR object
+#
+def merge_cidr(cidr_list)
+    
+    # make sure we have an array with at least 2 objects
+    unless ( (cidr_list.kind_of? Array) && (cidr_list.length > 1) )
+        raise "Array of at least two IPAdmin::CIDR objects required."
+    end
+    
+    
+    # make sure all are CIDR objects of the same version
+    version = {}
+    cidr_list.each do |cidr|
+        unless (cidr.kind_of? IPAdmin::CIDR)
+            raise "Expected IPAdmin::CIDR, but #{options.class} provided."
+        end
+        version[cidr.version] = 1
+    end
+    if (version.length > 1)
+        raise "Provided CIDR objects must all be of the same version."
+    end
+    
+    
+    # cidr_list.length should be a power of 2
+    multiplier = 1
+    while (1)
+        if ( (2**multiplier) < cidr_list.length)
+            multiplier = multiplier + 1
+        elsif ( (2**multiplier) == cidr_list.length)
+            break
+        elsif ( (2**multiplier) > cidr_list.length)
+            raise "Provided CIDR objects will not merge into " +
+                  "a single supernet"
+        end
+    end
+    
+    
+    # take each netmask of the cidr_list items, supernet them by
+    # 'multiplier' bits, and store them.
+    netmasks = {}
+    cidr_list.each do |cidr|
+        netmask = cidr.packed_netmask
+        netmask = netmask << multiplier
+        netmasks[netmask] = 1
+    end
+    
+    
+    # if we have multiple, different netmasks then the provided
+    # cidr objects are not part of the same supernet
+    if (netmasks.length > 1)
+        raise "Provided CIDR objects will not merge into " +
+              "a single supernet"
+    end
+    new_netmask = (netmasks.keys)[0]
+    
+    
+    # make new supernet by combining network with new netmask
+    # if we have multiple, different supernets, then the provided
+    # cidr objects are not part of the same supernet
+    supernets = {}
+    cidr_list.each do |cidr|
+        network = cidr.packed_network
+        supernets[network & new_netmask] = 1
+    end
+    
+    if (supernets.length > 1)
+        raise "Provided CIDR objects will not merge into " +
+              "a single supernet"
+    
+    else
+        supernet = (supernets.keys)[0]
+    end
+    
+    
+    # unpack our supernet addr
+    if (version.has_key?(4) )
+        supernet = unpack_ipv4_addr(supernet)
+        new_netmask = unpack_ipv4_netmask(new_netmask)
+    else
+        supernet = unpack_ipv6_addr(supernet)
+        new_netmask = unpack_ipv6_netmask(new_netmask)
+    end
+    
+    
+    new_cidr = IPAdmin::CIDR.new(:CIDR => "#{supernet}/#{new_netmask}")
+    
+    return(new_cidr)
+    
+end
+module_function :merge_cidr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# pack_ipv4_addr()
+#============================================================================#
+
+# Pack IPv4 addresses into a single byte field. No attempt at validation
+# is performed.
+# - Arguments:
+#   * IPv4 address
+# 
+# - Returns:
+#   * packed IPv4 address or exception on error.
+# 
+def pack_ipv4_addr(ip)
+ 
+    # is this a string?
+    unless (ip.kind_of? String)
+        raise "Expected String, but #{ip.class} provided."
+    end
+    
+    # pack our ip
+    octets = ip.split( /\./ ).reverse    
+    packed_ip = 0
+    
+    (0..3).each do |x|
+        octets[x] = (octets[x]).to_i            
+        octets[x] =  octets[x] << 8*x 
+        packed_ip = packed_ip | octets[x]            
+    end
+    
+    
+    return(packed_ip)
+end
+module_function :pack_ipv4_addr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+
+#============================================================================#
+# pack_ipv4_netmask()
+#============================================================================#
+
+# Pack IPv4 netmask into a single byte field.  No attempt at validation
+# is performed.
+# - Arguments:
+#   * IPv4 netmask in cidr or extended notation
+# 
+# - Returns:
+#   * packed IPv4 netmask or exception on error.
+#
+def pack_ipv4_netmask(netmask)
+    
+    all_f = 2**32-1
+    
+    
+    # is this a CIDR or Extended mask?
+    if(netmask =~ /\./)
+        # pack extended mask
+        begin
+            packed_netmask = pack_ipv4_addr(netmask)
+            packed_hostmask = packed_netmask ^ all_f    
+            rescue Exception 
+            raise "#{netmask} is invalid."
+        end
+            
+    elsif (netmask !~ /\D/)
+        if (netmask.kind_of? String)
+            netmask = netmask.to_i            
+        end
+                       
+        packed_hostmask = all_f >> netmask   
+        packed_netmask = all_f ^ packed_hostmask
+        
+    else
+        raise "#{netmask} is unrecognized."
+        
+    end
+    
+    ret_vals = [packed_netmask,packed_hostmask]    
+    
+    return(ret_vals)
+end
+module_function :pack_ipv4_netmask
+  
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# pack_ipv6_addr()
+#============================================================================#
+
+# Pack IPv6 addresses into a single byte field. No attempt at validation
+# is performed.
+# - Arguments:
+#   * IPv6 address
+# 
+# - Returns:
+#   * packed IPv6 address or exception on error.
+#
+def pack_ipv6_addr(ip)
+    
+    # is this a string?
+    unless (ip.kind_of? String)
+        raise "Expected String, but #{ip.class} provided."
+    end       
+     
+        
+    
+    # look for a '::' to see if this address is in shorthand
+    # if found, split on it
+    hex_fields = []
+    if (ip =~ /::/)
+        shrthnd = ip.split( /::/ )
+        if (ip =~  /^::/)           
+            sec_half = shrthnd[1].split( /:/ )
+            zero_pads = 8 - sec_half.length        
+            (1..zero_pads).each {hex_fields.push('0')}
+            sec_half.each {|field| hex_fields.push(field)}            
+        elsif (ip =~  /::$/)
+            hex_fields = shrthnd[0].split( /:/ )
+            zero_pads = 8 - hex_fields.length
+            (1..zero_pads).each {hex_fields.push('0')}
+        else
+            first_half = shrthnd[0].split( /:/ )
+            sec_half = shrthnd[1].split( /:/ )
+            zero_pads = 8 - (first_half.length + sec_half.length)        
+            first_half.each {|field| hex_fields.push(field)}
+            (1..zero_pads).each {hex_fields.push('0')}
+            sec_half.each {|field| hex_fields.push(field)}
+        end        
+        
+    else
+        hex_fields = ip.split( /:/ )
+    end
+        
+        
+        
+    # pack
+    hex_fields.reverse!
+    packed_ip = 0
+    (0..7).each do |x|
+        hex = hex_fields[x]
+        base16 = hex.to_i(16)            
+            
+        base16 =  base16 << 16*x 
+        packed_ip = packed_ip | base16            
+    end
+
+    
+    return(packed_ip)
+end
+module_function :pack_ipv6_addr
+  
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# pack_ipv6_netmask()
+#============================================================================#
+
+# Pack IPv6 netmask into a single byte field. No attempt at validation
+# is performed.
+# - Arguments:
+#   * IPv6 netmask in cidr notation
+# 
+# - Returns:
+#   * packed IPv6 netmask or exception on error.
+#
+def pack_ipv6_netmask(netmask)
+
+    all_f = 2**128-1    
+    
+    
+    if (netmask !~ /\D/)   
+        # pack
+        if (netmask.kind_of? String)
+            netmask = netmask.to_i            
+        end        
+          
+        packed_hostmask = all_f >> netmask   
+        packed_netmask = all_f ^ packed_hostmask
+        
+    else
+        raise "#{netmask} is unrecognized."
+        
+    end
+    
+    
+    ret_vals = [packed_netmask,packed_hostmask]    
+    
+    return(ret_vals)
+    
+end
+module_function :pack_ipv6_netmask
+  
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv4_addr()
+#============================================================================#
+
+# Unack IPv4 address back into a printable string. No attempt at validation
+# is performed.
+# - Arguments:
+#   * Byte-packed IPv4 address
+# 
+# - Returns:
+#   * IPv4 address.
+#
+def unpack_ipv4_addr(packed_ip)
+    
+    octets = []
+    (0..3).each do |x|
+        octets[x] = packed_ip & 0xFF
+        octets[x] = (octets[x]).to_s
+        packed_ip = packed_ip >> 8
+    end
+    
+    octets.reverse!
+    ip = octets.join('.')
+    
+    return(ip)
+end
+module_function :unpack_ipv4_addr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv4_netmask()
+#============================================================================#
+
+# Unack IPv4 netmask into a integer representing the number of
+# bits in the CIDR mask. No attempt at validation is performed.
+# - Arguments:
+#   * Byte-packed IPv4 netmask
+# 
+# - Returns:
+#   * IPv4 netmask as number of bits (cidr format).
+#
+def unpack_ipv4_netmask(packed_mask)
+    
+    mask = 32
+    32.times do    
+        if ( (packed_mask & 1) != 0)
+            break
+        end
+        packed_mask = packed_mask >> 1
+        mask = mask - 1
+    end    
+    
+    return(mask)
+end
+module_function :unpack_ipv4_netmask 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv6_addr()
+#============================================================================#
+
+# Unack IPv6 address back into a printable string. No attempt at validation
+# is performed.
+# - Arguments:
+#   * Byte-packed IPv6 address
+# 
+# - Returns:
+#   * IPv6 address.
+#
+def unpack_ipv6_addr(packed_ip)
+    hex_fields = []
+    (0..7).each do |x|
+        hex_fields[x] = packed_ip & 0xFFFF
+        hex_fields[x] = (hex_fields[x]).to_s(16)
+        packed_ip = packed_ip >> 16
+        
+        # if hex_fields[x] < 4 characters, then pad with 0's
+        (4 - hex_fields[x].length).times do
+            hex_fields[x] = '0' << hex_fields[x]
+        end
+    end
+    
+    hex_fields.reverse!
+    ip = hex_fields.join(':')
+    
+    return(ip)
+end
+module_function :unpack_ipv6_addr 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# unpack_ipv6_netmask()
+#============================================================================#
+
+# Unack IPv6 netmask into a integer representing the number of
+# bits in the CIDR mask. No attempt at validation is performed.
+# - Arguments:
+#   * Byte-packed IPv6 netmask
+# 
+# - Returns:
+#   * IPv6 netmask as number of bits (cidr format).
+#
+def unpack_ipv6_netmask(packed_mask)
+    
+    mask = 128
+    128.times do
+        if ( (packed_mask & 1) == 1)
+            break
+        end
+        mask = mask - 1
+        packed_mask = packed_mask >> 1
+    end
+    
+    return(mask)
+end
+module_function :unpack_ipv6_netmask 
+ 
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# validate_ipv4_addr()
+#============================================================================#
+
+# Validate IPv4 addresses.
+# - Arguments:
+#   * IPv4 address
+# 
+# - Returns:
+#   * 1 on valid IP or exception on error.
+# 
+def validate_ipv4_addr(ip)
+
+    # is this a string?
+    unless (ip.kind_of? String)
+        raise "Expected String, but #{ip.class} provided."
+    end
+    octets = ip.split( /\./ )
+    
+    
+    
+    # check validity of characters in the addr
+    if ( (ip =~ /\.{2,}?/ ) || (ip =~ /[^0-9\.]/) )
+        raise "#{ip} is invalid."
+    end
+    
+    
+    
+    # do we have 4 octets?
+    if (octets.length != 4)
+        raise "#{ip} is invalid."
+    end
+
+    
+    
+    # are octets in range 0..255?
+    (0..3).each do |x|
+        octets[x] = octets[x].to_i        
+        unless ( (octets[x] >= 0) && (octets[x] < 256 ) )
+            raise "#{ip} is invalid." 
+        end
+    end
+        
+    
+    # dont allow first octet to be 0
+    if (octets[0] == 0)
+        raise "#{ip} is invalid." 
+    end
+    
+    return(1)
+    
+end
+module_function :validate_ipv4_addr
+    
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# validate_ipv4_netmask()
+#============================================================================#
+
+# Validate IPv4 Netmask.
+# - Arguments:
+#   * IPv4 netmask in cidr or extended notation
+# 
+# - Returns:
+#   * 1 on valid IP or exception on error.
+# 
+def validate_ipv4_netmask(netmask)
+    
+    all_f = (2**32)-1
+    
+    
+    # is this a CIDR or Extended mask?
+    if(netmask =~ /\./)
+        # validate & pack extended mask
+        begin
+            validate_ipv4_addr(netmask)
+            packed_mask = pack_ipv4_addr(netmask)
+                
+            rescue Exception 
+            raise "#{netmask} is invalid."
+        end
+            
+        # cycle through the bits of hostmask and compare
+        # with packed_mask. when we hit the firt '1' within
+        # packed_mask (our netmask boundary), xor hostmask and
+        # packed_mask. the result should be all 1's. this whole
+        # process is in place to make sure that we dont have
+        # and crazy masks such as 255.254.255.0
+        hostmask = 1
+        32.times do 
+            check = packed_mask & hostmask
+            if ( check != 0)
+                hostmask = hostmask >> 1
+                unless ( (packed_mask ^ hostmask) == all_f)
+                    raise "#{netmask} is invalid." 
+                end
+                break
+            else
+                hostmask = hostmask << 1
+                hostmask = hostmask | 1
+            end
+        end
+        
+    else 
+        
+        # check if we have any non numeric characters
+        if (netmask =~ /\D/)
+            raise "#{netmask} is invalid."
+        end          
+        
+        
+        # are we between 1 and 32 inclusive
+        if (netmask.kind_of? String)
+            netmask = netmask.to_i            
+        end
+            
+        if ( (netmask > 32) || (netmask == 0) )
+            raise "#{netmask} is invalid." 
+        end
+        
+    end
+    
+    return(1)
+    
+end
+module_function :validate_ipv4_netmask
+
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# validate_ipv6_addr()
+#============================================================================#
+
+# Validate IPv6 addresses.
+# - Arguments:
+#   * IPv6 address
+# 
+# - Returns:
+#   * 1 on valid IP or exception on error.
+# 
+def validate_ipv6_addr(ip)
+    # is this a string?
+    unless (ip.kind_of? String)
+        raise "Expected String, but #{ip.class} provided."
+    end
+    
+    
+    
+    # check validity of characters in the addr
+    if ( (ip =~ /:{3,}?/ ) || (ip =~ /[^0-9a-fA-F:]/) )
+        raise "#{ip} is invalid."
+    end    
+      
+        
+        
+    # look for a '::' to see if this address is in shorthand
+    # if found, split on it & make sure that we have at most
+    # two elements
+    if (ip =~ /::/)
+        shrthnd = ip.split( /::/ ) 
+        unless ( (shrthnd.length > 0) && (shrthnd.length < 3) )
+            raise "#{ip} is invalid."
+        end
+    end
+        
+        
+    
+    if (shrthnd)
+        # if shorthand, we should have between 1 and 7
+        # hex fields
+        hex_fields = []
+        shrthnd.each do |x|
+            elements = x.split( /:/ )
+            elements.each {|x| hex_fields.push(x)}
+        end
+        if ( (hex_fields.length < 1) || (hex_fields.length > 7) )
+            raise "#{ip} is invalid."
+        end
+        
+     else
+        # since no shorthand notation was detected we should
+        # have exactly 8 hex fields        
+        hex_fields = ip.split( /:/ )
+        if (hex_fields.length != 8)
+            raise "#{ip} is invalid."
+        end
+        
+    end
+    
+    
+    
+    # check that we have no more than 4 characters in each 
+    # hex field
+    hex_fields.each do |x|
+        if (x.length > 4)
+            raise "#{ip} is invalid."
+        end
+    end
+
+    
+    return(1)
+    
+end
+module_function :validate_ipv6_addr
+
+#=====================================#
+#     
+#=====================================#
+
+
+
+#============================================================================#
+# validate_ipv6_netmask()
+#============================================================================#
+
+# Validate IPv6 netmask.
+# - Arguments:
+#   * IPv6 netmask in cidr notation
+# 
+# - Returns:
+#   * 1 on valid IP or exception on error.
+# 
+def validate_ipv6_netmask(netmask)
+
+    if (netmask =~ /\D/)
+        raise "#{netmask} is invalid."
+        
+    else
+        # are we between 1 and 128 inclusive    
+        if (netmask.kind_of? String)
+            netmask = netmask.to_i            
+        end
+                    
+        if ( (netmask > 128) || (netmask == 0) )
+            raise "#{netmask} is invalid." 
+        end
+        
+    end
+    
+    return(1)
+    
+end
+module_function :validate_ipv6_netmask
+
+#=====================================#
+#     
+#=====================================#
+
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  BEGIN class CIDR
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+=begin rdoc
+A class & series of methods for creating and manipulating CIDR network
+addresses. Both IPv4 and IPv6 are supported.
+=end
+
+class CIDR
+
+
+
+#============================================================================#
+# attr_reader/attr_writer
+#============================================================================#
+
+    # @network - packed cidr network
+    # @netmask - packet cidr netmask
+    # @hostmask - inverse packed netmask    
+    
+    # ip version 4 or 6
+    attr_reader :version
+    
+    # hash of custom tags. should be in the format tag => value
+    attr_reader :tag
+    attr_writer :tag
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# initialize()
+#============================================================================#
+
+# - Arguments:
+#   * Hash with the following fields:
+#       :CIDR -- IPv4 or IPv6 cidr block
+#       :Netmask -- IPv4 netmask in extended format (if not provided in :CIDR)
+#       :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#
+    def initialize(options)
+    
+        unless (options.kind_of? Hash)
+            raise "Expected Hash, but #{options.class} provided."
+        end
+        
+
+        if ( options.has_key?(:CIDR) )
+            network =  options[:CIDR]
+            
+            
+            if (network =~/\./) # assume IPv4
+                @version = 4
+                
+                if (network =~ /\//)
+                    ip,netmask = network.split(/\//)
+                    
+                    # validate
+                    IPAdmin.validate_ipv4_addr(ip)
+                    IPAdmin.validate_ipv4_netmask(netmask)
+                    
+                    # pack
+                    @network = IPAdmin.pack_ipv4_addr(ip)
+                    @netmask,@hostmask = IPAdmin.pack_ipv4_netmask(netmask)
+                        
+                elsif ( options.has_key?(:Netmask) )
+                    ip = network
+                    netmask = options[:Netmask]
+                
+                    # validate
+                    IPAdmin.validate_ipv4_addr(ip)
+                    IPAdmin.validate_ipv4_netmask(netmask)
+                    
+                    # pack
+                    @network = IPAdmin.pack_ipv4_addr(ip)
+                    @netmask,@hostmask = IPAdmin.pack_ipv4_netmask(netmask)
+                
+                else
+                    raise "Missing Netmask or invalid CIDR format." 
+                    
+                end                
+                
+
+            elsif (network =~/:/) # assume IPv6
+                @version = 6
+                
+                if (network =~ /\//)
+                    ip,netmask = network.split(/\//)
+                    
+                    # validate
+                    IPAdmin.validate_ipv6_addr(ip)
+                    IPAdmin.validate_ipv6_netmask(netmask)
+                    
+                    # pack
+                    @network = IPAdmin.pack_ipv6_addr(ip)
+                    @netmask,@hostmask = IPAdmin.pack_ipv6_netmask(netmask)
+                        
+                else
+                    raise "Missing Netmask or invalid CIDR format."
+                    
+                end
+                
+            else
+                raise "Invalid CIDR address format: #{network}."
+            end
+            
+        else
+            raise ArgumentError, "Missing arguments: CIDR."
+            
+        end
+        
+        
+        # make sure that this is a valid address/mask pair
+        masked_val = (@network & @netmask)
+        if (masked_val != @network )
+            raise "Invalid address/netmask pair. Did you provide "+
+                  "an IP address instead of a CIDR block?"
+        end
+        
+        
+        # set tag if present
+        if ( options.has_key?(:Tag) )
+            @tag = options[:Tag]
+        end
+
+        
+    end
+  
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# contains()
+#============================================================================#
+
+# Determines if cidr block of IPAdmin::CIDR contains IP address
+# of provided IPAdmin:IPAddr object.
+# - Arguments:
+#   * IPAdmin:IPAddr object
+# 
+# - Returns:
+#   * 1 on true, nil on false
+#
+    def contains(ip_obj)
+                
+        if ( (ip_obj.version == 4) && (@version == 4) )
+            v4_all_f = (2**32)-1        
+            hostmask = @netmask ^ v4_all_f
+            if ( (ip_obj.packed_ip | hostmask) == (@network | hostmask) )
+                return(1)
+            end
+            
+        elsif ( (ip_obj.version == 6) && (@version == 6) )
+            v6_all_f = (2**128)-1
+            hostmask = @netmask ^ v6_all_f
+            if ( (ip_obj.packed_ip | hostmask) == (@network | hostmask) )
+                return(1)
+            end
+        
+        else
+            raise "Attempted to compare a version #{ip_obj.version} IP " +
+                  "with a version #{@version} network."
+        end
+        
+        return(nil)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# desc()
+#============================================================================#
+
+# Displays network/netmask of an IPAdmin::CIDR object
+# of provided IPAdmin:IPAddr object.
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Description in network/netmask format
+#
+    def desc()
+        
+        if (@version == 4)
+            ip = IPAdmin.unpack_ipv4_addr(@network)
+            mask = IPAdmin.unpack_ipv4_netmask(@netmask)
+        else
+            ip = IPAdmin.unpack_ipv6_addr(@network)
+            mask = IPAdmin.unpack_ipv6_netmask(@netmask)
+        end
+
+        return("#{ip}/#{mask}")
+        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# enumerate()
+#============================================================================#
+
+# Provide all IP addresses within a CIDR block
+# (warning: this can be quite large for big blocks)
+# 
+# - Arguments:
+#   * Hash with the following fields
+#   - :BitStep -- enumerate in X sized steps
+#   - :Objectify -- return IPAdmin::IPAddr objects
+#   - :Limit -- limit returned list to X number of items
+# 
+# - Returns:
+#   * array of IP addresses or IPAdmin::IPAddr objects
+#
+    def enumerate(options=nil)
+        bitstep = 1
+        objectify = nil
+        limit = nil
+        v4_all_f = (2**32)-1
+        v6_all_f = (2**128)-1
+        
+        if (options)
+            if( options.has_key?(:BitStep) )
+                bitstep = options[:BitStep]
+            end
+        
+            if( options.has_key?(:Objectify) )
+                objectify = 1
+            end
+            
+            if( options.has_key?(:Limit) )
+                limit = options[:Limit]
+            end
+        end
+        
+        
+        list = []
+        if ( (@version == 4) && !objectify)
+            my_ip = @network
+            hostmask = @netmask ^ v4_all_f
+            change_mask = hostmask | my_ip
+
+            until ( change_mask != (hostmask | @network) ) 
+                list.push( IPAdmin.unpack_ipv4_addr(my_ip) )
+                my_ip = my_ip + bitstep
+                change_mask = hostmask | my_ip
+                if (limit)
+                    limit = limit -1
+                    break if (limit == 0)
+                end
+            end
+             
+        elsif ( (@version == 4) && objectify)
+            my_ip = @network
+            hostmask = @netmask ^ v4_all_f
+            change_mask = hostmask | my_ip
+
+            until ( change_mask != (hostmask | @network) )
+                my_ip_s = IPAdmin.unpack_ipv4_addr(my_ip)
+                list.push( IPAdmin::IPAddr.new(:IPAddr => my_ip_s) )
+                my_ip = my_ip + bitstep
+                change_mask = hostmask | my_ip
+                if (limit)
+                    limit = limit -1
+                    break if (limit == 0)
+                end
+            end
+            
+        elsif ( (@version == 6) && !objectify)
+            my_ip = @network
+            hostmask = @netmask ^ v6_all_f
+            change_mask = hostmask | my_ip
+
+            until ( change_mask != (hostmask | @network) ) 
+                list.push( IPAdmin.unpack_ipv6_addr(my_ip) )
+                my_ip = my_ip + bitstep
+                change_mask = hostmask | my_ip
+                if (limit)
+                    limit = limit -1
+                    break if (limit == 0)
+                end
+            end
+             
+        elsif ( (@version == 6) && objectify)
+            my_ip = @network
+            hostmask = @netmask ^ v6_all_f
+            change_mask = hostmask | my_ip
+
+            until ( change_mask != (hostmask | @network) )
+                my_ip_s = IPAdmin.unpack_ipv6_addr(my_ip)
+                list.push( IPAdmin::IPAddr.new(:IPAddr => my_ip_s) )
+                my_ip = my_ip + bitstep
+                change_mask = hostmask | my_ip
+                if (limit)
+                    limit = limit -1
+                    break if (limit == 0)
+                end
+            end
+        
+        else
+            list = nil
+            
+        end     
+        
+        
+        return(list)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# hostmask_ext()
+#============================================================================#
+
+# Provide IPv4 Hostmask in extended format.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Hostmask in extended (y.y.y.y) format.
+#
+    def hostmask_ext()    
+        if (@version == 4)
+            hostmask = IPAdmin.unpack_ipv4_addr(@hostmask)
+        else
+            raise "IPv6 does not support extended hostmask notation." 
+        end
+        
+        return(hostmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# netmask()
+#============================================================================#
+
+# Provide Netmask in cidr format.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Number of bits in the netmask.
+#
+    def netmask()    
+        if (@version == 4)
+            bits = IPAdmin.unpack_ipv4_netmask(@netmask)
+        else
+            bits = IPAdmin.unpack_ipv6_netmask(@netmask)
+        end
+        
+        return(bits)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# netmask_ext()
+#============================================================================#
+
+# Provide IPv4 Netmask in extended format.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Netmask in extended (y.y.y.y) format.
+#
+    def netmask_ext()    
+        if (@version == 4)
+            netmask = IPAdmin.unpack_ipv4_addr(@netmask)
+        else
+            raise "IPv6 does not support extended netmask notation. " +
+                  "Use bits() method instead."
+        end
+        
+        return(netmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# network()
+#============================================================================#
+
+# Provide base Network address.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Base network address.
+#
+    def network()
+        if (@version == 4)
+            formatted = IPAdmin.unpack_ipv4_addr(@network)
+        else
+            formatted = IPAdmin.unpack_ipv6_addr(@network)
+        end
+        
+        return(formatted)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# nth()
+#============================================================================#
+
+# Provide the nth IP within the cidr block of an IPAdmin::CIDR object.
+# 
+# - Arguments:
+#   * Hash with the following fields
+#   - :Index -- index of the address to return
+#   - :Objectify -- return IPAdmin::IPAddr objects
+# 
+# - Returns:
+#   * IP address or IPAdmin::IPAddr object.
+#
+    def nth(options)
+        objectify = nil
+        v4_all_f = (2**32)-1
+        v6_all_f = (2**128)-1
+        
+        unless( options.has_key?(:Index) )
+            raise ArgumentError, "Missing arguments: Index."
+        end
+        index = options[:Index]
+        
+        
+        if( options.has_key?(:Objectify) )
+                objectify = 1
+        end
+        
+        
+
+        if ( (@version == 4) && !objectify)
+            my_ip = @network + index
+            hostmask = @netmask ^ v4_all_f
+
+            if ( (hostmask | my_ip) == (hostmask | @network) )
+                my_ip = IPAdmin.unpack_ipv4_addr(my_ip)
+                return(my_ip)
+            end
+             
+        elsif ( (@version == 4) && objectify)
+            my_ip = @network + index
+            hostmask = @netmask ^ v4_all_f
+            
+            if ( (hostmask | my_ip) == (hostmask | @network) )
+                my_ip_s = IPAdmin.unpack_ipv4_addr(my_ip)
+                return( IPAdmin::IPAddr.new(:IPAddr => my_ip_s) )
+            end
+            
+        elsif ( (@version == 6) && !objectify)
+            my_ip = @network + index
+            hostmask = @netmask ^ v6_all_f
+
+            if ( (hostmask | my_ip) == (hostmask | @network) )
+                my_ip = IPAdmin.unpack_ipv6_addr(my_ip)
+                return(my_ip)
+            end
+             
+        elsif ( (@version == 6) && objectify)
+            my_ip = @network + index
+            hostmask = @netmask ^ v6_all_f
+            
+            if ( (hostmask | my_ip) == (hostmask | @network) )
+                my_ip_s = IPAdmin.unpack_ipv6_addr(my_ip)
+                return( IPAdmin::IPAddr.new(:IPAddr => my_ip_s) )
+            end
+        
+        end
+        
+        raise "Index of #{index} returns IP that is out of " +
+              "bounds of CIDR network."
+                
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_hostmask()
+#============================================================================#
+
+# Provide byte-packed Hostmask of cidr block of an IPAdmin::CIDR object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Byte-packed Hostmask.
+#
+    def packed_hostmask()    
+        return(@hostmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_netmask()
+#============================================================================#
+
+# Provide byte-packed Netmask of cidr block of an IPAdmin::CIDR object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Byte-packed Netmask.
+#
+    def packed_netmask()
+        return(@netmask)        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_network()
+#============================================================================#
+
+# Provide byte-packed Network address of cidr block of an IPAdmin::CIDR object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Byte-packed Network Address.
+#
+    def packed_network()
+        return(@network)        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# size()
+#============================================================================#
+
+# Provide number of addresses within cidr block of an IPAdmin::CIDR object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Number of IP addresses in this CIDR block.
+#
+    def size()
+        return(@hostmask + 1)        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# subnet()
+#============================================================================#
+
+# Subnet cidr block within an IPAdmin::CIDR object according to user
+# specifications.
+# 
+# - Arguments:
+#   * Hash with the following fields:
+#       :Subnet --  number of bits of new subnet to create (24,26, etc...)
+#       :MinCount -- minimum number of subnets of size :Subnet to return
+# 
+# - Returns:
+#   * array of IPAdmin::CIDR objects
+#
+    def subnet(options)
+        subnet = options[:Subnet]
+        min_count = options[:MinCount]
+        mymask = self.netmask        
+        num_avail = 2**(subnet - mymask)
+        new_subnets = []
+        
+        
+        
+        # make sure subnet isnt bigger than available bits
+        if (@version == 4)
+            max_bits = 32            
+        else
+            max_bits = 128
+        end
+        
+        if (subnet > max_bits)
+            raise "Requested subnet #{subnet} does not fit " +
+                  "within available CIDR space."
+        end
+                
+        
+        # make sure subnet is larger than mymask
+        if (subnet < mymask)
+            raise "Requested subnet #{subnet} does not fit " +
+                  "within available CIDR space."
+        end
+        
+        
+        # make sure MinCount is smaller than available subnets
+        if (min_count > num_avail)
+            raise "Requested subnet count exceeds subnets available for " +
+                  "allocation."
+        end        
+        
+        
+        # list all 'subnet' sized subnets of this cidr block       
+        bitstep = 2**(max_bits - subnet)
+        subs = self.enumerate(:BitStep => bitstep)
+        subs.each do |sub|
+            cidr = "#{sub}/#{subnet}"
+            new_subnets.push(IPAdmin::CIDR.new(:CIDR => cidr))
+        end
+        
+        
+        # combine any unneeded subnets into as few
+        # supernets as possible
+        supernets = []
+        supernet_groups = []
+        if (min_count < num_avail )
+            cidr_list = []
+            num_left = num_avail - min_count            
+            multiplier = 1
+            until (num_left < 2)
+                if ( (2**multiplier) < num_left)
+                    multiplier = multiplier + 1
+                elsif ( (2**multiplier) == num_left)
+                    supernet_groups.push( (2**multiplier) )
+                    num_left = num_left - (2**multiplier)
+                    break
+                elsif ( (2**multiplier) > num_left)
+                    multiplier = multiplier -1
+                    supernet_groups.push( (2**multiplier) )
+                    num_left = num_left - (2**multiplier)
+                    multiplier = 1
+                end
+            end
+        end
+        
+        
+        supernet_groups.each do |group|
+            cidr_list = []
+            (1..group).each do
+                cidr_list.push(new_subnets.pop)
+            end
+            supernets.push( IPAdmin.merge_cidr(cidr_list) )
+        end
+        
+        
+        # add supernets to new_subnets        
+        (1..supernets.length).each do 
+            new_subnets.push(supernets.pop)
+        end
+        
+        return(new_subnets)        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+end  
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  END class CIDR
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+
+
+
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  BEGIN class CIDRTable
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+=begin rdoc
+A class & series of methods for creating and manipulating CIDR-based
+heirarchical tables. Both IPv4 and IPv6 are supported.
+=end
+
+class CIDRTable
+
+
+
+#============================================================================#
+# attr_reader / attr_writer
+#============================================================================#
+
+    
+    # ip table version (4 or 6)
+    attr_reader :version
+    
+    # contains IPAdmin::CIDR entries. hash (IPAdmin::CIDR => IPAdmin::CIDRTable)
+    attr_reader :cidr_table
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# initialize()
+#============================================================================#
+
+# - Arguments:
+#   * Table version (4 or 6)
+# 
+    def initialize(version)
+        
+        unless ( version.kind_of? Fixnum )
+            raise "Expected Fixnum, but #{version.class} provided."
+        end
+        
+        unless ( version == 4 || version == 6 )
+            raise "Version should be either 4 or 6."
+        end
+               
+        @version = version
+        @cidr_table = {}
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# add_cidr()
+#============================================================================#
+
+# Add an IPAdmin::CIDR object to this table
+# 
+# - Arguments:
+#   * IPAdmin::CIDR object
+# 
+# - Returns:
+#   * nil
+#
+    def add_cidr(new_cidr)
+        
+        unless (new_cidr.version == @version )
+            raise "CIDR version #{new_cidr.version} is incompatible with " +
+                  "CIDRTable version #{@version}."
+        end
+         
+        
+        
+        # compare new cidr with existing cidr's
+        # determine if this is a parent or child of an existing cidr.
+        # if neither, add @networks. if child of existing, add to that
+        # child's @networks. if parent of existing, make existing child
+        # of new cidr
+        duplicate = nil
+        parent_of = []
+        child_of = nil
+        @cidr_table.each_key do |old_cidr|
+            parent,child = IPAdmin.compare_cidr(new_cidr,old_cidr)
+            
+            if (parent)                        
+                if (new_cidr == parent)
+                    parent_of.push(child)
+                    @cidr_table.delete(child)
+                    
+                elsif (new_cidr == child)
+                    child_of = parent
+                    break
+                    
+                elsif (parent == 1)               
+                    duplicate = 1
+                    break
+                end
+            end        
+        end
+        
+
+        
+        if (parent_of.length != 0)
+            new_entry = IPAdmin::CIDRTable.new(@version)            
+            parent_of.each do |old_cidr|
+                new_entry.add_cidr(old_cidr)
+                @cidr_table.delete(old_cidr)
+            end
+            @cidr_table[new_cidr] = new_entry
+             
+        elsif (child_of)            
+            if (@cidr_table[child_of] == 0)
+                new_entry = IPAdmin::CIDRTable.new(@version)
+                @cidr_table[child_of] = new_entry
+               (@cidr_table[child_of]).add_cidr(new_cidr)
+            else
+                (@cidr_table[child_of]).add_cidr(new_cidr)
+            end            
+            
+        elsif (!duplicate)
+            @cidr_table[new_cidr] = 0
+        end
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# dump()
+#============================================================================#
+
+# Dump contents of this table
+# 
+# - Arguments:
+#   * nil
+# 
+# - Returns:
+#   * ordered array of IPAdmin::CIDR objects within this table
+#
+    def dump()
+    
+        list = []
+        sorted_parents = []
+        parent_hash = {}                
+        @cidr_table.each_key do |parent|
+            parent_hash[parent.packed_network] = parent
+        end
+        sorted_parents = (parent_hash.keys).sort
+        
+        
+        sorted_parents.each do |parent|            
+            parent_obj = parent_hash[parent]
+            list.push(parent_obj)
+            if (@cidr_table[parent_obj] != 0)
+                children = (@cidr_table[parent_obj]).dump
+                children.each do |child|
+                    list.push(child)
+                end            
+            end
+                    
+        end               
+        
+        return(list)
+        
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# find_ip()
+#============================================================================#
+
+# Find longest matching IPAdmin::CIDR object whose cidr block contains the IP  
+# address within the provided IPAdmin::IPAddr object
+# 
+# - Arguments:
+#   * IPAdmin::IPAddr object
+# 
+# - Returns:
+#   * IPAdmin::CIDR object, or nil on no match
+#
+    def find_ip(ip_obj)
+        
+        unless (ip_obj.kind_of? IPAdmin::IPAddr)
+            raise "Expected IPAdmin::IPAddr, but #{options.class} provided."
+        end
+        
+        unless (ip_obj.version == @version )
+            raise "IPAddr version #{ip_addr.version} is incompatible with " +
+                  "CIDRTable version #{@version}."
+        end
+        
+        belongs_to = nil
+        @cidr_table.each_key do |parent|            
+            if ( parent.contains(ip_obj) )
+                if (@cidr_table[parent] != 0)                
+                    belongs_to = (@cidr_table[parent]).find_ip(ip_obj)
+                end
+                
+                if (!belongs_to)
+                    belongs_to = parent
+                end
+            end        
+        end
+        
+        return(belongs_to)
+        
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# find_space()
+#============================================================================#
+
+# Find CIDR blocks of at least X size. Returns only the smallest matching
+# subnets of each supernet. 
+# 
+# - Arguments:
+#   * Hash with the following fields:
+#       :Size -- subnet size (number of bits)
+#       :Limit -- max entries to return
+# 
+# - Returns:
+#   * ordered array of IPAdmin::CIDR objects, or nil on no match
+#
+    def find_space(options)
+        limit = nil
+        list = []
+        sorted_parents = []
+        parent_hash = {}               
+        
+        
+        
+        # validate options
+        unless (options.kind_of? Hash)
+            raise "Expected Hash, but #{options.class} provided."
+        end
+        
+        unless ( options.has_key?(:Size) )
+            raise "Missing argument :Size."
+        end
+        subnet_size = options[:Size]
+        
+        if ( options.has_key?(:Limit) )
+            limit = options[:Limit]
+        end
+        
+        
+        
+        # check that subnet_size is a valid size
+        if (@version == 4)
+            unless ( (subnet_size > 0) && (subnet_size < 33) )
+                raise "#{subnet_size} is out of range for this CIDRTable."
+            end
+            
+        else
+            unless ( (subnet_size > 0) && (subnet_size < 129) )
+                raise "#{subnet_size} is out of range for this CIDRTable."
+            end
+        end
+        
+        
+        # order cidr objects
+        @cidr_table.each_key do |parent|
+            parent_hash[parent.packed_network] = parent
+        end
+        sorted_parents = (parent_hash.keys).sort
+        
+        
+        
+        # find space
+        sorted_parents.each do |key|
+            parent = parent_hash[key]            
+            if ( parent.netmask() < subnet_size )
+                if (@cidr_table[parent] != 0)
+                    child_list = []
+                    child_list = (@cidr_table[parent]).find_space(:Size => subnet_size)
+                    child_list.each do |child|
+                        list.push(child)
+                        if ( (limit) && (list.length == limit) )
+                            break
+                        end
+                    
+                    end
+                
+                else
+                    list.push(parent)
+                    
+                end
+                
+            elsif ( (parent_hash[key].netmask() == subnet_size) &&
+                    (@cidr_table[parent] == 0) )
+                list.push(parent)
+                
+            end
+            
+            
+            if ( (limit) && (list.length == limit) )
+                break
+            end 
+                   
+        end
+        
+        return(list)
+        
+    end
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+
+end
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  END class CIDRTable
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+
+
+
+
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  BEGIN class IPAddr
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+=begin rdoc
+A class & series of methods for creating and manipulating IP
+addresses. Both IPv4 and IPv6 are supported.
+=end
+
+class IPAddr
+
+
+
+#============================================================================#
+# attr_reader/attr_writer
+#============================================================================#
+
+    # @ip - packed ip address
+    # @netmask - packed netmask
+    # @hostmask - inverse packed netmask
+    
+    # ip version 4 or 6
+    attr_reader :version
+    
+    # hash of custom tags. should be in the format tag => value
+    attr_reader :tag
+    attr_writer :tag
+
+    
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# initialize()
+#============================================================================#
+
+# - Arguments:
+#   * Hash with the following fields
+#       :IPAddr -- IPv4 or IPv6 address (assume host address by default)
+#       :Netmask -- IPv4 netmask in extended format ( if not part of IPAddr)
+#       :Tag -- Custom descriptor tag for object. Should be Hash (tag => value)
+#
+    def initialize(options)
+    
+        unless (options.kind_of? Hash)
+            raise "Expected Hash, but #{options.class} provided."
+        end
+        
+        if ( options.has_key?(:IPAddr) )
+            ip_addr =  options[:IPAddr]
+            
+            
+            if (ip_addr =~/\./) # assume IPv4
+                @version = 4
+                
+                if (ip_addr =~ /\//)
+                    ip,netmask = ip_addr.split(/\//)
+                    
+                    # validate
+                    IPAdmin.validate_ipv4_addr(ip)
+                    IPAdmin.validate_ipv4_netmask(netmask)
+                    
+                    # pack
+                    @ip = IPAdmin.pack_ipv4_addr(ip)
+                    @netmask,@hostmask = IPAdmin.pack_ipv4_netmask(netmask)
+                        
+                else
+                    # validate
+                    IPAdmin.validate_ipv4_addr(ip_addr)
+                    
+                    # pack
+                    @ip = IPAdmin.pack_ipv4_addr(ip_addr)
+                    
+                    # check if netmask provided separately
+                    if ( options.has_key?(:Netmask) )
+                        netmask = options[:Netmask]
+                        
+                        # validate
+                        IPAdmin.validate_ipv4_netmask(netmask)
+                        
+                        # pack
+                        @netmask,@hostmask =
+                                         IPAdmin.pack_ipv4_netmask(netmask)
+                    
+                    else                    
+                        @netmask,@hostmask = IPAdmin.pack_ipv4_netmask('32')
+                         
+                    end
+                    
+                end                
+                
+
+            elsif (ip_addr =~/:/) # assume IPv6
+                @version = 6
+                
+                if (ip_addr =~ /\//)
+                    ip,netmask = ip_addr.split(/\//)
+                    
+                    # validate
+                    IPAdmin.validate_ipv6_addr(ip)
+                    IPAdmin.validate_ipv6_netmask(netmask)
+                    
+                    # pack
+                    @ip = IPAdmin.pack_ipv6_addr(ip)
+                    @netmask,@hostmask = IPAdmin.pack_ipv6_netmask(netmask)
+                        
+                else
+                    # validate
+                    IPAdmin.validate_ipv6_addr(ip_addr)
+                    
+                    # pack
+                    @ip = IPAdmin.pack_ipv6_addr(ip_addr)
+                    @netmask,@hostmask = IPAdmin.pack_ipv6_netmask('128') 
+                    
+                end
+                
+            else
+                raise "Invalid IPAddr address format: #{ip_addr}."
+            end
+            
+        else
+            raise ArgumentError, "Missing arguments: IPAddr."
+            
+        end        
+        
+        
+        # set tag if present
+        if ( options.has_key?(:Tag) )
+            @tag = options[:Tag]
+        end
+
+        
+    end
+  
+  
+  
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# base()
+#============================================================================#
+
+# Provide base network address for address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * base network address.
+#
+    def base()
+        if (@version == 4)
+            packed_base = @ip & @netmask
+            base = IPAdmin.unpack_ipv4_addr(packed_base)
+        else
+            packed_base = @ip & @netmask
+            base = IPAdmin.unpack_ipv6_addr(packed_base)
+        end
+        
+        return(base)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# broadcast()
+#============================================================================#
+
+# Provide IPv4 broadcast address for address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * broadcast address.
+#
+    def broadcast()
+        if (@version == 4)
+            inverse_mask = ~ @netmask
+            packed_bcast = @ip | inverse_mask
+            bcast = IPAdmin.unpack_ipv4_addr(packed_bcast)
+        else
+            raise "IPv6 does not support IP broadcast addresses."
+        end
+        
+        return(bcast)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# desc()
+#============================================================================#
+
+# Provide description for IP address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * ip/netmask.
+#
+    def desc()
+        if (@version == 4)
+            ip = IPAdmin.unpack_ipv4_addr(@ip)
+            netmask = IPAdmin.unpack_ipv4_netmask(@netmask)
+            formatted = "#{ip}/#{netmask}"
+        else
+            ip = IPAdmin.unpack_ipv6_addr(@ip)
+            netmask = IPAdmin.unpack_ipv6_netmask(@netmask)
+            formatted = "#{ip}/#{netmask}"
+        end
+        
+        return(formatted)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# hostmask_ext()
+#============================================================================#
+
+# Provide IPv4 Hostmask for address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * IPv4 Hostmask in extended (y.y.y.y) format.
+#
+    def hostmask_ext()    
+        if (@version == 4)
+            hostmask = IPAdmin.unpack_ipv4_addr(@hostmask)
+        else
+            raise "IPv6 does not support extended hostmask notation."
+        end
+        
+        return(hostmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# ip()
+#============================================================================#
+
+# Provide IP address of IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * IP address.
+#
+    def ip()
+        if (@version == 4)
+            formatted = IPAdmin.unpack_ipv4_addr(@ip)
+        else
+            formatted = IPAdmin.unpack_ipv6_addr(@ip)
+        end
+        
+        return(formatted)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# netmask()
+#============================================================================#
+
+# Provide Netmask for address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * Number of bits in the netmask.
+#
+    def netmask()    
+        if (@version == 4)
+            bits = IPAdmin.unpack_ipv4_netmask(@netmask)
+        else
+            bits = IPAdmin.unpack_ipv6_netmask(@netmask)
+        end
+        
+        return(bits)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# netmask_ext()
+#============================================================================#
+
+# Provide IPv4 Netmask for address within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * IPv4 Netmask in extended (y.y.y.y) format.
+#
+    def netmask_ext()    
+        if (@version == 4)
+            netmask = IPAdmin.unpack_ipv4_addr(@netmask)
+        else
+            raise "IPv6 does not support extended netmask notation. " +
+                  "Use bits() method instead."
+        end
+        
+        return(netmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_hostmask()
+#============================================================================#
+
+# Provide byte-packed Hostmask within IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * byte-packed Hostmask.
+#
+    def packed_hostmask()    
+        return(@hostmask)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_ip()
+#============================================================================#
+
+# Provide byte-packed IP address of IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * byte-packed IP address.
+#
+    def packed_ip()
+        return(@ip)
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+#============================================================================#
+# packed_netmask()
+#============================================================================#
+
+# Provide byte-packed Netmask for IP address of IPAdmin::IPAddr object.
+# 
+# - Arguments:
+#   * none
+# 
+# - Returns:
+#   * byte-packed Netask.
+#
+    def packed_netmask()
+        return(@netmask)        
+    end
+
+#=====================================#
+#        
+#=====================================#
+
+
+
+end  
+
+
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#
+#  END class IPAddr
+#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+#++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++#
+
+
+end # module IPAdmin
+
+
+
+__END__
+