Module: IPAdmin

Defined in:

lib/eui.rb,
lib/cidr.rb,
lib/tree.rb,
lib/methods.rb

Defined Under Namespace

Classes: CIDR, EUI, NetStruct, Tree

Class Method Summary

• .compare(obj1, obj2) ⇒ Object

  Compare CIDR or NetStruct objects, and determine if one is the supernet of the other.

• .create_net_struct(object) ⇒ Object

  Create a NetStruct object from an CIDR or NetStruct object.

• .merge(options) ⇒ Object

  Given a list of CIDR or NetStruct objects merge (supernet) them in the most efficient way possible.

• .minimum_size(options) ⇒ Object

  Given the number of IP addresses required in a subnet, return the minimum netmask required for that subnet.

• .pack_ip_addr(options) ⇒ Object

  Convert IP addresses into an integer.

• .pack_ip_netmask(options) ⇒ Object

  Convert IP netmask into an integer.

• .range(options) ⇒ Object

  Given two IPAdmin::CIDR objects of the same version, return all IP addresses between them (non-inclusive).

• .shorten(addr) ⇒ Object

  Take a standard IPv6 address, and format it in short-hand notation.

• .sort(list) ⇒ Object

  Given a list of IPAdmin::CIDR or NetStruct objects sort them from lowest to highest by Network/Netmask.

• .unpack_ip_addr(options) ⇒ Object

  Unack a packed IP address back into a printable string.

• .unpack_ip_netmask(options) ⇒ Object

  Unack a packed IP netmask into a integer representing the number of bits in the CIDR mask.

• .unshorten(addr) ⇒ Object

  Take an IPv6 address in short-hand format, and expand it into standard notation.

• .validate_eui(options) ⇒ Object

  Validate an EUI-48 or EUI-64 address.

• .validate_ip_addr(options) ⇒ Object

  Validate an IP address.

• .validate_ip_netmask(options) ⇒ Object

  Validate IP Netmask.

Class Method Details

.compare(obj1, obj2) ⇒ Object

Compare CIDR or NetStruct objects, and determine if one is the supernet of the other.

• Arguments:

  • Two CIDR or NetStruct 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 supernet of the other, return nil

Example:

supernet,subnet = IPAdmin.compare(cidr1,cidr2)

# File 'lib/methods.rb', line 30

def compare(obj1,obj2)
    ret_val = nil

    # validate arguments
    if ( !obj1.kind_of?(IPAdmin::CIDR) &&
         !obj1.kind_of?(IPAdmin::NetStruct) )
        raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
                             "as first argument, but #{obj1.class} provided."
    end

    if ( !obj2.kind_of?(IPAdmin::CIDR) &&
         !obj2.kind_of?(IPAdmin::NetStruct) )
         raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
                              "as second argument, but #{obj2.class} provided."
    end

    # make sure both are same version
    if (obj1.version != obj2.version )
        raise ArgumentError, "Provided objects are of different IP versions."
    end


    # get network/netmask of each
    objects = [obj1,obj2]
    networks = []
    netmasks = []
    for obj in objects
        if ( obj.kind_of?(IPAdmin::CIDR) )
            networks.push(obj.packed_network)
            netmasks.push(obj.packed_netmask)

        elsif ( obj.kind_of?(IPAdmin::NetStruct) )
            networks.push(obj.network)
            netmasks.push(obj.netmask)

        end
    end

    # return 1's if objects are equal otherwise
    # 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 ( (networks[0] == networks[1]) && (netmasks[0] == netmasks[1]) )
        ret_val = 1
    elsif (netmasks[0] < netmasks[1])
        if ( (netmasks[0] & networks[0]) == (netmasks[0] & networks[1]) )
            ret_val = [obj1,obj2]
        end
    elsif (netmasks[1] < netmasks[0])
        if ( (netmasks[1] & networks[0]) == (netmasks[1] & networks[1]) )
            ret_val = [obj2,obj1]
        end
    end

    return(ret_val)
end

.create_net_struct(object) ⇒ Object

Create a NetStruct object from an CIDR or NetStruct object. This type of Struct is used internally for various tasks, and is not likely to be useful to anyone.

• Arguments:

  • CIDR or NetStruct object

• Returns:

  • NetStruct object

Example:

net_struct = IPAdmin.create_net_struct(object)

# File 'lib/methods.rb', line 110

def create_net_struct(object)

    if ( object.kind_of?(IPAdmin::CIDR) )
        network = object.packed_ip
        netmask = object.packed_netmask

    elsif ( object.kind_of?(IPAdmin::NetStruct) )
        network = object.network
        netmask = object.netmask
    else
        raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct "+
                             "object, but #{object.class} provided."
    end

    version = object.version
    net_struct = NetStruct.new(network,netmask,version,object,[])

    return(net_struct)
end

.merge(options) ⇒ Object

Given a list of CIDR or NetStruct objects merge (supernet) them in the most efficient way possible. Supernetting will only occur when the newly created supernet will not result in the ‘creation’ of additional space. For example the following blocks (192.168.0.0/24, 192.168.1.0/24, and 192.168.2.0/24) would merge into 192.168.0.0/23 and 192.168.2.0/24 rather than into 192.168.0.0/22

• Arguments:

  • Hash with the following fields:

    - :List -- Array of CIDR or NetStruct objects
    - :NetStruct -- if true, return IPAdmin::NetStruct objects (optional)
    - :Objectify -- if true, return IPAdmin::CIDR objects (optional)
    - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
    

• Returns:

  • Array of CIDR or NetStruct objects

• Notes:

  • I have designed this with enough flexibility that you can pass in CIDR addresses that arent even related (ex. 192.168.1.0/26, 192.168.1.64/26, 10.1.0.0/26, 10.1.0.64/26) and they will be merged properly (ie 192.168.1.0/25, and 10.1.0.0/25 would be returned).

Example:

supernets = IPAdmin.merge(:List => list)

# File 'lib/methods.rb', line 166

def merge(options)
    version = nil
    short = false
    objectify = false

    # validate options
    if ( !options.kind_of?(Hash) )
        raise ArgumentError, "Hash expected but #{options.class} provided."
    end

    if (!options.has_key?(:List))
        raise ArgumentError, "Missing argument: List."
    end
    
    if (options.has_key?(:Short) && options[:Short] == true)
        short = true
    end
    
    if (options.has_key?(:Objectify) && options[:Objectify] == true)
        objectify = true
    end

    list = options[:List]
    ret_struct = 1 if (options.has_key?(:NetStruct))

    # make sure list is an array
    if ( !list.kind_of?(Array) )
        raise ArgumentError, "Expected Array for option :List, " +
                             "but #{list.class} provided."
    end

    # make sure all are valid types of the same IP version
    list.each do |obj|
        if (!obj.kind_of?(IPAdmin::CIDR) && !obj.kind_of?(IPAdmin::NetStruct) )
            raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
                                 "object but #{obj.class} provided."
        end

        version = obj.version if (!version)
        if (!obj.version == version)
            raise "Provided objects must be of the same IP version."
        end 
    end

    # make all_f    
    if (version == 4)
        all_f = 2**32 - 1
    else
        all_f = 2**128 - 1
    end

    # make sure that our list is in order, and contains no duplicates
    list = IPAdmin.sort(list)
    index = 0
    (list.length).times do
        if ((index > 0)&&(IPAdmin.compare(list[index],list[index-1]) == 1))
            list.delete_at(index)
        else
            index += 1
        end
    end

    # create supernet_list from list
    supernet_list = []
    list.each do |obj|
        if (obj.kind_of?(IPAdmin::CIDR))
            supernet_list.push(IPAdmin.create_net_struct(obj))

        elsif ( obj.kind_of?(IPAdmin::NetStruct) )
            if (obj.subnets && obj.subnets.length > 0)
                # get all child subnets of this branch entry
                children = merge(:List => obj.subnets, :NetStruct => 1)

                # if any child subnets are equal to the parent subnet
                # then copy the grandchild subnets and delete the child
                children.each do |child|
                    if ( (obj.network == child.network) &&
                         (obj.netmask == child.netmask) )
                        if (child.subnets && child.subnets.length > 0)
                            grandchildren = child.subnets
                            children.concat(grandchildren)
                        end
                        children.delete(child)
                        children =  IPAdmin.sort(children)
                        break
                    end
                end

                obj.subnets.clear
                obj.subnets.concat(children)
            end

            supernet_list.push(obj)
        end
    end

    # merge subnets of this new branch by removing them from 'supernet_list',
    # and categorizing them into hash of arrays (key=netmask) 
    # within each categorization we merge contiguous subnets
    # and then remove them from that category & put them back into
    # 'supernet_list'. we do this until our list stops getting any shorter
    categories = {}
    supernet_list_length = 0
    until (supernet_list_length == supernet_list.length)
        supernet_list_length = supernet_list.length

        # categorize
        supernet_list.each do |entry|
            netmask = entry.netmask
            if (categories.has_key?(netmask) )
                (categories[netmask]).push(entry)
            else
                categories[netmask] = [entry]
            end
        end
        supernet_list.clear

        categories.each_key do |netmask|
            entries = categories[netmask]
            bitstep = (all_f + 1) - netmask

            # this entire process depends on the list being in order
            until (entries.length == 0)
                to_merge = []
                multiplier = 1
                first = entries[0]
                num_required = 2**multiplier
                supermask = (netmask << multiplier) & all_f
                supernet = supermask & first.network
                if (first.network == supernet)
                    # take first entry and use it to form a base
                    # supernet address. this supernet should have
                    # x number of subnets in it, so we look for
                    # those subnets & if found store them
                    expected = first.network
                    entries.each do |entry|
                        if ( (entry.network == expected) && (first.network == supernet) )
                            to_merge.push(entry)
                            expected = expected + bitstep
                            if ( (to_merge.length == num_required) &&
                                 (entries.length > num_required ) )
                                multiplier += 1
                                num_required = 2**multiplier
                                supermask = (netmask << multiplier) & all_f
                                supernet = supermask & first.network
                            end
                        else
                            # if entry is a duplicate, then kill it
                            if (IPAdmin.compare(entry,to_merge.last) == 1)
                                entries.delete(entry)
                            end
                            break 
                        end
                    end
                else
                   to_merge.push(first)
                end

                # make sure we actually have all of our subnets
                # create our new supernet
                if (to_merge.length != num_required)
                    multiplier -= 1
                    supermask = (netmask << multiplier) & all_f
                    supernet = supermask & first.network
                end
                net_struct = NetStruct.new(supernet,supermask,version,nil,[])

                # now that we have the child members of our new supernet
                # take any grandchild subnets that they may have and 
                # add them to the new supernet. then kill the children
                (2**multiplier).times do
                    to_kill = to_merge.shift
                    net_struct.subnets.concat(to_kill.subnets) if (to_kill.subnets)
                    entries.delete(to_kill)
                end
                supernet_list.push(net_struct)
            end
        end
        categories.clear
        supernet_list = IPAdmin.sort(supernet_list)
    end

    # if '!ret_struct', return CIDR's
    if (!ret_struct)
        supernets = []
        supernet_list.each do |entry|
            if (!objectify)
                network = IPAdmin.unpack_ip_addr(:Integer => entry.network, :Version => version)
                network = IPAdmin.shorten(network) if (short && version == 6)
                netmask = IPAdmin.unpack_ip_netmask(:Integer => entry.netmask, :Version => version)
                supernets.push("#{network}/#{netmask}")
            else
                supernets.push(IPAdmin::CIDR.new(:PackedIP => entry.network, 
                                                 :PackedNetmask => entry.netmask, 
                                                 :Version => version))
            end
        end
    else
        supernets = supernet_list
    end

    return(supernets)
end

.minimum_size(options) ⇒ Object

Given the number of IP addresses required in a subnet, return the minimum netmask required for that subnet.

• Arguments:

  • Hash with the following fields:

    - :IPCount -- the number of IP addresses required - Integer
    - :Version -- IP version - Integer(optional)
    

• Returns:

  • Integer

• Notes:

  • Version is assumed to be 4 unless specified otherwise.

Example:

netmask = IPAdmin.minumum_size(:IPCount => 14) -> 28

# File 'lib/methods.rb', line 397

def minimum_size(options)
    version = 4

    if ( !options.kind_of?(Hash) )
        raise ArgumentError, "Hash expected but #{options.class} provided."
    end

    if ( !options.has_key?(:IPCount) )
        raise ArgumentError, "Missing argument: List."
    end
    ipcount = options[:IPCount]
    
    if (options.has_key?(:Version))
        version = options[:Version]
    end
    
    if (version == 4)
        max_bits = 32        
    else
        max_bits = 128
    end
    
    
    if (ipcount > 2**max_bits) 
        raise "Required IP count exceeds number of IP addresses available " +
              "for IPv#{version}."
    end

    
    bits_needed = 0
    until (2**bits_needed >= ipcount)
        bits_needed += 1
    end
    subnet_bits = max_bits - bits_needed
    
    return(subnet_bits)
end

.pack_ip_addr(options) ⇒ Object

Convert IP addresses into an integer. No attempt at validation is performed.

• Arguments:

  • Hash with the following fields:

    - :IP -- IP address - String
    - :Version -- IP version - Integer
    

• Returns:

  • Integer

• Notes:

  • Will attempt to auto-detect IP version if not provided

Example:

pack_ip_addr(IP => '192.168.1.1')
pack_ip_addr(IP => 'ffff::1')
pack_ip_addr(IP => '::192.168.1.1')

# File 'lib/methods.rb', line 464

def pack_ip_addr(options)
    
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:IP))
        raise ArgumentError, "Missing argument: IP."
    end
    ip = options[:IP]
    
    if (options.has_key?(:Version))
        version = options[:Version]
        if (version != 4 && version != 6)
            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
        end
    end
    
        
    if ( ip.kind_of?(String) )
        
        # determine version if not provided
        if (!version)
            if ( ip =~ /\./ && ip !~ /:/ )
                version = 4
            else
                version = 6
            end
        end
        
        packed_ip = 0
        if ( version == 4)
            octets = ip.split('.')            
            (0..3).each do |x|
                octet = octets.pop.to_i
                octet = octet << 8*x 
                packed_ip = packed_ip | octet
            end
            
        else
            # if ipv4-mapped ipv6 addr
            if (ip =~ /\./)
                dotted_dec = true                 
            end            
            
            # split up by ':'
            fields = []
            if (ip =~ /::/)
                shrthnd = ip.split( /::/ )
                if (shrthnd.length == 0)
                    return(0) 
                else                    
                    first_half = shrthnd[0].split( /:/ ) if (shrthnd[0])
                    sec_half = shrthnd[1].split( /:/ ) if (shrthnd[1])
                    first_half = [] if (!first_half)
                    sec_half = [] if (!sec_half)
                end
                missing_fields = 8 - first_half.length - sec_half.length
                missing_fields -= 1 if dotted_dec
                fields = fields.concat(first_half)
                missing_fields.times {fields.push('0')}
                fields = fields.concat(sec_half)               
                
            else
               fields = ip.split(':')  
            end
           
            if (dotted_dec)
                ipv4_addr = fields.pop
                packed_v4 = IPAdmin.pack_ip_addr(:IP => ipv4_addr, :Version => 4)
                octets = []
                2.times do
                    octet = packed_v4 & 0xFFFF
                    octets.unshift(octet.to_s(16))
                    packed_v4 = packed_v4 >> 16
                end
                fields.concat(octets)
            end

            # pack
            (0..7).each do |x|
                field = fields.pop.to_i(16)
                field = field << 16*x 
                packed_ip = packed_ip | field
            end
            
        end

    else
        raise ArgumentError, "Argument :IP should be a String, but is a #{ip.class}."    
    end

    return(packed_ip)
end

.pack_ip_netmask(options) ⇒ Object

Convert IP netmask into an integer. No validation is performed. Netmask may be in either CIDR (/yy) or extended (y.y.y.y) format. CIDR formatted netmasks may either be a String or an Integer.

• Arguments

  • Hash with the following fields:

    - :Netmask -- Netmask - String or Integer
    - :Version -- IP version - Integer (optional)
    

• Returns:

  • Integer

• Notes:

  • Version defaults to 4

Example:

packed = IPAdmin.pack_ip_netmask(Netmask => '255.255.255.0')
packed = IPAdmin.pack_ip_netmask(Netmask => '24')
packed = IPAdmin.pack_ip_netmask(Netmask => 24)
packed = IPAdmin.pack_ip_netmask(Netmask => '/24')
packed = IPAdmin.pack_ip_netmask(Netmask => '64', :Version => 6)

# File 'lib/methods.rb', line 591

def pack_ip_netmask(options)
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:Netmask))
        raise ArgumentError, "Missing argument: Netmask."
    end
    netmask = options[:Netmask]
    
    if (options.has_key?(:Version))
        version = options[:Version]
        if (version != 4 && version != 6)
            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
        elsif (version == 6)
            all_f = 2**128-1
        else
            all_f = 2**32-1
        end
    else
        all_f = 2**32-1
    end
    
    
    if (netmask.kind_of?(String))
        if(netmask =~ /\./)
            packed_netmask = IPAdmin.pack_ip_addr(:IP => netmask)

        else
            # remove '/' if present
            if (netmask =~ /^\// )
                netmask[0] = " "
                netmask.lstrip!
            end
            netmask = netmask.to_i
            packed_netmask = all_f ^ (all_f >> netmask)
        end
    elsif (netmask.kind_of?(Integer))
        packed_netmask = all_f ^ (all_f >> netmask)
    
    else
        raise ArgumentError, "Argument :Netmask should be a String or Integer, but is a #{netmask.class}."
    
    end
    
    return(packed_netmask)
end

.range(options) ⇒ Object

Given two IPAdmin::CIDR objects of the same version, return all IP addresses between them (non-inclusive).

• Arguments:

  • Hash with the following fields:

    - :Bitstep -- enumerate in X sized steps - Integer (optional)
    - :Boundaries -- array of (2) CIDR objects
    - :Limit -- limit returned list to X number of items - Integer (optional)
    - :Objectify -- if true, return CIDR objects (optional)
    - :Short -- if true, return IPv6 addresses in short-hand notation (optional)
    

• Returns:

  • Array of Strings or CIDR objects

• Notes:

  • IPAdmin.range will use the original IP address passed during the initialization of the CIDR objects. This IP can be found using the CIDR.ip() method.

Example:

list = IPAdmin.range(:Boundaries => [cidr1,cidr2])

# File 'lib/methods.rb', line 670

def range(options)
    list = []
    bitstep = 1
    objectify = false
    short = false
    limit = nil

    # check options
    if (options)
        if ( !options.has_key?(:Boundaries) ) 
            raise ArgumentError, "Missing argument: Boundaries."
        end

        if (options[:Boundaries].length == 2)
            (cidr1,cidr2) = options[:Boundaries]
        else
            raise ArgumentError, "Two IPAdmin::CIDR ojects are required. " +
                                 "as Boundaries."
        end

        if( options.has_key?(:Bitstep) )
            bitstep = options[:Bitstep]
        end

        if( options.has_key?(:Objectify) && options[:Objectify] == true )
            objectify = true
        end
        
        if( options.has_key?(:Short) && options[:Short] == true )
            short = true
        end

        if( options.has_key?(:Limit) )
            limit = options[:Limit]
        end
    end

    # check our objects
    if (!cidr1.kind_of?(IPAdmin::CIDR) && !cidr2.kind_of?(IPAdmin::CIDR))
        raise ArgumentError, "One or more values provided under :Boundaries "+
                             "is not a valid IPAdmin::CIDR object."
    end

    # check version, store & sort
    if (cidr1.version == cidr2.version)
        version = cidr1.version
        boundaries = [cidr1.packed_ip, cidr2.packed_ip]
        boundaries.sort
    else
        raise ArgumentError, "Provided IPAdmin::CIDR objects are of different IP versions."
    end

    # dump our range
    my_ip = boundaries[0] + 1
    until (my_ip >= boundaries[1]) 
        if (!objectify)
            my_ip_s = IPAdmin.unpack_ip_addr(:Integer => my_ip, :Version => version)
            my_ips = IPAdmin.shorten(my_ips) if (short && version == 6)
            list.push(my_ip_s)
        else
            list.push( IPAdmin::CIDR.new(:PackedIP => my_ip, :Version => version) )
        end

        my_ip = my_ip + bitstep
        if (limit)
            limit = limit -1
            break if (limit == 0)
        end
    end

    return(list)
end

.shorten(addr) ⇒ Object

Take a standard IPv6 address, and format it in short-hand notation. The address should not contain a netmask.

• Arguments:

  • String

• Returns:

  • String

Example:

short = IPAdmin.shorten('fec0:0000:0000:0000:0000:0000:0000:0001') --> 'fec0::1'

# File 'lib/methods.rb', line 765

def shorten(addr)

    # is this a string?
    if (!addr.kind_of? String)
        raise ArgumentError, "Expected String, but #{addr.class} provided."
    end

    validate_ip_addr(:IP => addr, :Version => 6)

    # make sure this isnt already shorthand
    if (addr =~ /::/)
        return(addr)
    end

    # split into fields
    fields = addr.split(":")
    
    # check last field for ipv4-mapped addr
    if (fields.last() =~ /\./ )
        ipv4_mapped = fields.pop()
    end
    
    # look for most consecutive '0' fields
    start_field,end_field = nil,nil
    start_end = []
    consecutive,longest = 0,0
        
    (0..(fields.length-1)).each do |x|
        fields[x] = fields[x].to_i(16)

        if (fields[x] == 0)
            if (!start_field)
                start_field = x
                end_field = x
            else
                end_field = x
            end
            consecutive += 1
        else
            if (start_field)
                if (consecutive > longest)
                    longest = consecutive
                    start_end = [start_field,end_field]
                    start_field,end_field = nil,nil                    
                end
                consecutive = 0
            end
        end

        fields[x] = fields[x].to_s(16)
    end
    
    # if our longest set of 0's is at the end, then start & end fields
    # are already set. if not, then make start & end fields the ones we've
    # stored away in start_end
    if (consecutive > longest) 
        longest = consecutive
    else
        start_field = start_end[0]
        end_field = start_end[1]
    end

    if (longest > 1)        
        fields[start_field] = ''
        start_field += 1
        fields.slice!(start_field..end_field)
    end 
    fields.push(ipv4_mapped) if (ipv4_mapped)   
    short = fields.join(':')    
    short << ':' if (short =~ /:$/)
    
    return(short)
end

.sort(list) ⇒ Object

Given a list of IPAdmin::CIDR or NetStruct objects sort them from lowest to highest by Network/Netmask.

• Arguments:

  • Array of CIDR or NetStruct objects

• Returns:

  • Array

• Notes:

  • IPAdmin.sort will use the original IP address passed during the initialization of the CIDR objects. This IP can be found using the CIDR.ip() method.

Example:

sorted = IPAdmin.sort(list)

# File 'lib/methods.rb', line 865

def sort(list)

    # make sure list is an array
    if ( !list.kind_of?(Array) )
        raise ArgumentError, "Array of IPAdmin::CIDR or NetStruct " +
                             "objects expected, but #{list.class} provided."
    end

    # make sure all are valid types of the same IP version
    version = nil
    list.each do |obj|
        unless (obj.kind_of?(IPAdmin::CIDR) || obj.kind_of?(IPAdmin::NetStruct) )
            raise ArgumentError, "Expected IPAdmin::CIDR or NetStruct " +
                                 "object but #{obj.class} provided."
        end

        version = obj.version if (!version)
        unless (obj.version == version)
            raise "Provided objects must all be of the same IP version."
        end 
    end

    # create unsorted_list from list
    unsorted_list = []
    list.each do |obj|
        unsorted_list.push(IPAdmin.create_net_struct(obj))
    end

    # sort by network. if networks are equal, sort by netmask.
    sorted_list = []
    unsorted_list.each do |entry|
        index = 0
        sorted_list.each do
            if(entry.network < (sorted_list[index]).network)
                break
            elsif (entry.network == (sorted_list[index]).network)
                if (entry.netmask < (sorted_list[index]).netmask)
                    break
                end
            end
            index += 1
        end
        sorted_list.insert(index, entry)
    end

    # replace sorted_list entries with their .object
    index = 0
    sorted_list.length.times do
        sorted_list[index] = (sorted_list[index]).object
        index += 1
    end

    return(sorted_list)
end

.unpack_ip_addr(options) ⇒ Object

Unack a packed IP address back into a printable string. No attempt at validation is performed.

• Arguments:

  • Hash with the following fields:

    - :Integer -- Integer representaion of an IP address
    - :Version -- IP version - Integer (optional)
    - :IPv4Mapped -- if true, unpack IPv6 as an IPv4 mapped address (optional)
    

• Returns:

  • String

• Notes:

  • IP version will attempt to be auto-detected if not provided

Example:

unpacked = IPAdmin.unpack_ip_addr(:Integer => packed)

# File 'lib/methods.rb', line 948

def unpack_ip_addr(options)
    ipv4_mapped = false
    
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:Integer))
        raise ArgumentError, "Missing argument: Integer."
    end
    packed_ip = options[:Integer]
    
    if (!packed_ip.kind_of?(Integer))
        raise ArgumentError, "Expected Integer, but #{options.class} provided for argument: Integer."
    end
    
    if (options.has_key?(:Version))
        version = options[:Version]
        if (version != 4 && version != 6)
            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
        end
    end
    
    if (options.has_key?(:IPv4Mapped) && options[:IPv4Mapped] == true)
        ipv4_mapped = true
    end
    
    # set version if not set
    if (!version)
        if (packed_ip < 2**32)
            version = 4
        else
            version = 6
        end
    end
    
    if (version == 4)
        octets = []
        4.times do
            octet = packed_ip & 0xFF
            octets.unshift(octet.to_s)
            packed_ip = packed_ip >> 8
        end
        ip = octets.join('.')
    else
        fields = []
        if (!ipv4_mapped)
            loop_count = 8
        else
            loop_count = 6
            packed_v4 = packed_ip & 0xffffffff
            ipv4_addr = IPAdmin.unpack_ip_addr(:Integer => packed_v4, :Version => 4)
            fields.unshift(ipv4_addr)
            packed_ip = packed_ip >> 32
        end
        
        loop_count.times do 
            octet = packed_ip & 0xFFFF
            octet = octet.to_s(16)
            packed_ip = packed_ip >> 16

            # if octet < 4 characters, then pad with 0's
            (4 - octet.length).times do
                octet = '0' << octet
            end
            fields.unshift(octet)
        end        
        ip = fields.join(':')
    end
    

    return(ip)
end

.unpack_ip_netmask(options) ⇒ Object

Unack a packed IP netmask into a integer representing the number of bits in the CIDR mask. No attempt at validation is performed.

• Arguments:

  • Hash with the following fields:

    - :Integer -- Integer representation of an IP Netmask
    

• Returns:

  • Integer

Example:

unpacked = IPAdmin.unpack_ip_netmask(:Integer => packed)

# File 'lib/methods.rb', line 1045

def unpack_ip_netmask(options)
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:Integer))
        raise ArgumentError, "Missing argument: Integer."
    end
    packed_netmask = options[:Integer]
    
    if (!packed_netmask.kind_of?(Integer))
        raise ArgumentError, "Argument :Integer should be an Integer, but is a #{packed_netmask.class}."
    end
    
    if (packed_netmask < 2**32)
        mask = 32
    else
        mask = 128
    end
    
    mask.times do    
        if ( (packed_netmask & 1) == 1)
            break
        end
        packed_netmask = packed_netmask >> 1
        mask = mask - 1
    end

    return(mask)
end

.unshorten(addr) ⇒ Object

Take an IPv6 address in short-hand format, and expand it into standard notation. The address should not contain a netmask.

• Arguments:

  • String

• Returns:

  • String

Example:

long = IPAdmin.unshorten('fec0::1') --> 'fec0:0000:0000:0000:0000:0000:0000:0001'

# File 'lib/methods.rb', line 1098

def unshorten(addr)

    # is this a string?
    if (!addr.kind_of? String)
        raise ArgumentError, "Expected String, but #{addr.class} provided."
    end

    validate_ip_addr(:IP => addr, :Version => 6)
    ipv4_mapped = true if (addr =~ /\./)
    
    packed = pack_ip_addr(:IP => addr, :Version => 6)    
    if (!ipv4_mapped)
        long = unpack_ip_addr(:Integer => packed, :Version => 6)
    else
        long = unpack_ip_addr(:Integer => packed, :Version => 6, :IPv4Mapped => true)
    end
    
    return(long)
end

.validate_eui(options) ⇒ Object

Validate an EUI-48 or EUI-64 address.

• Arguments

  • Hash with the following fields:

    - :EUI -- Address to validate - String
    

• Returns:

  • True

• Example:

  • IPAdmin.validate_eui(:EUI => ‘01-00-5e-12-34-56’)

# File 'lib/methods.rb', line 1140

def validate_eui(options)
    if (!options.kind_of? Hash)
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
        
    if (!options.has_key?(:EUI))
        raise ArgumentError, "Missing argument: EUI."
    end
    eui = options[:EUI]
        
    if (eui.kind_of?(String))
        # check for invalid characters
        if (eui =~ /[^0-9a-fA-f\.\-\:]/)
            raise "#{eui} is invalid (contains invalid characters)."
        end
            
        # split on formatting characters & check lengths
        if (eui =~ /\-/)
            fields = eui.split('-')
            if (fields.length != 6 && fields.length != 8)
                raise "#{eui} is invalid (unrecognized formatting)."
            end 
        elsif (eui =~ /\:/)
            fields = eui.split(':')
            if (fields.length != 6 && fields.length != 8)
                raise "#{eui} is invalid (unrecognized formatting)."
            end
        elsif (eui =~ /\./)
            fields = eui.split('.')
            if (fields.length != 3 && fields.length != 4)
                raise "#{eui} is invalid (unrecognized formatting)."
            end
        else
            raise "#{eui} is invalid (unrecognized formatting)."
        end

    else
        raise ArgumentError, "Expected String, but #{eui.class} " +
                             "provided for argument :EUI."
    end
    return(true)
end

.validate_ip_addr(options) ⇒ Object

Validate an IP address. The address should not contain a netmask.

• Arguments

  • Hash with the following fields:

    - :IP -- IP address to validate - String or Integer
    - :Version -- IP version - Integer (optional)
    

• Returns:

  • True

• Notes:

  • IP version will attempt to be auto-detected if not provided

Example:

validate_ip_addr(IP => '192.168.1.1')
validate_ip_addr(IP => 'ffff::1')
validate_ip_addr(IP => '::192.168.1.1')
validate_ip_addr(IP => 0xFFFFFF)
validate_ip_addr(IP => 2**128-1)
validate_ip_addr(IP => 2**32-1, :Version => 4)

# File 'lib/methods.rb', line 1214

def validate_ip_addr(options)
    
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:IP))
        raise ArgumentError, "Missing argument: IP."
    end
    ip = options[:IP]
    
    if (options.has_key?(:Version))
        version = options[:Version]
        if (version != 4 && version != 6)
            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
        end
    end
    
    if ( ip.kind_of?(String) )
        
        # check validity of charaters
        if (ip =~ /[^0-9a-fA-F\.:]/)
            raise "#{ip} is invalid (contains invalid characters)."
        end
        
        # determine version if not specified
        if (!version && (ip =~ /\./ && ip !~ /:/ ) )
            version = 4
        elsif (!version && ip =~ /:/)
            version = 6
        end        
        
        if (version == 4)
            octets = ip.split('.')            
            raise "#{ip} is invalid (IPv4 requires (4) octets)." if (octets.length != 4)
            
            # are octets in range 0..255?
            octets.each do |octet|
                raise "#{ip} is invalid (IPv4 dotted-decimal format " +
                      "should not contain non-numeric characters)." if (octet =~ /[^0-9]/ )                
                octet = octet.to_i()                
                if ( (octet < 0) || (octet >= 256) )
                    raise "#{ip} is invalid (IPv4 octets should be between 0 and 255)."
                end
            end        
        
        elsif (version == 6)
            # make sure we only have at most (2) colons in a row, and then only
            # (1) instance of that
            if ( (ip =~ /:{3,}/) || (ip.split("::").length > 2) )
                raise "#{ip} is invalid (IPv6 field separators (:) are bad)."
            end            
            
            # set flags
            shorthand = false
            if (ip =~ /\./)
                dotted_dec = true 
            else
                dotted_dec = false
            end            
            
            # split up by ':'
            fields = []
            if (ip =~ /::/)
                shorthand = true
                ip.split('::').each do |x|
                    fields.concat( x.split(':') )
                end
            else
               fields.concat( ip.split(':') ) 
            end
            
            # make sure we have the correct number of fields
            if (shorthand)
                if ( (dotted_dec && fields.length > 6) || (!dotted_dec && fields.length > 7) )
                    raise "#{ip} is invalid (IPv6 shorthand notation has " +
                          "incorrect number of fields)." 
                end                
            else
                if ( (dotted_dec && fields.length != 7 ) || (!dotted_dec && fields.length != 8) )
                    raise "#{ip} is invalid (IPv6 address has " +
                          "incorrect number of fields)." 
                end
            end
            
            # if dotted_dec then validate the last field
            if (dotted_dec)
                dotted = fields.pop()
                octets = dotted.split('.')
                raise "#{ip} is invalid (Legacy IPv4 portion of IPv6 " +
                      "address should contain (4) octets)." if (octets.length != 4)
                octets.each do |x|
                    raise "#{ip} is invalid (egacy IPv4 portion of IPv6 " +
                          "address should not contain non-numeric characters)." if (x =~ /[^0-9]/ )
                    x = x.to_i
                    if ( (x < 0) || (x >= 256) )
                        raise "#{ip} is invalid (Octets of a legacy IPv4 portion of IPv6 " +
                              "address should be between 0 and 255)."
                    end
                end
            end
            
            # validate hex fields
            fields.each do |x|
                if (x =~ /[^0-9a-fA-F]/)
                    raise "#{ip} is invalid (IPv6 address contains invalid hex characters)."
                else
                    x = x.to_i(16)
                    if ( (x < 0) || (x >= 2**16) )
                        raise "#{ip} is invalid (Fields of an IPv6 address " +
                              "should be between 0x0 and 0xFFFF)."
                    end
                end
            end
            
        else
            raise "#{ip} is invalid (Did you mean to pass an Integer instead of a String?)."        
        end

    elsif ( ip.kind_of?(Integer) )
        if (version && version == 4)
            raise "#{ip} is invalid (Integer is out of bounds)." if ( (ip < 0) || (ip > 2**32) )
        else
            raise "#{ip} is invalid (Integer is out of bounds)." if ( (ip < 0) || (ip > 2**128) )
        end
        
    else
        raise ArgumentError, "Expected String or Integer, but #{ip.class} provided."    
    end

    
    return(true)
end

.validate_ip_netmask(options) ⇒ Object

Validate IP Netmask.

• Arguments:

  • Hash with the following fields:

    - :Netmask -- Netmask to validate - String or Integer
    - :Packed -- if true, the provided Netmask is a packed Integer
    - :Version -- IP version - Integer (optional)
    

• Returns:

  • True or exception.

• Notes:

  • Version defaults to 4 if not specified.

Example:

IPAdmin.validate_ip_netmask(:Netmask => '/32')
IPAdmin.validate_ip_netmask(:Netmask => 32)
IPAdmin.validate_ip_netmask(:Netmask => 0xffffffff, :Packed => true)

# File 'lib/methods.rb', line 1377

def validate_ip_netmask(options)
    packed = false
    
    if (!options.kind_of?(Hash))
        raise ArgumentError, "Expected Hash, but #{options.class} provided."
    end
    
    if (!options.has_key?(:Netmask))
        raise ArgumentError, "Missing argument: Netmask."
    end
    netmask = options[:Netmask]
    
    if (options.has_key?(:Packed) && options[:Packed] == true)
        packed = true
    end
    
    if (options.has_key?(:Version))
        version = options[:Version]
        if (version != 4 && version != 6)
            raise ArgumentError, ":Version should be 4 or 6, but was '#{version}'."
        elsif (version == 6)
            max_bits = 128
        else
            max_bits = 32
        end
    else
        version = 4
        max_bits = 32
    end
    

    if (netmask.kind_of?(String))
        if(netmask =~ /\./)
            all_f = 2**32-1
            packed_netmask = 0
        
            # validate & pack extended mask
            begin
                validate_ip_addr(:IP => netmask)
                packed_netmask = pack_ip_addr(:IP => netmask)
            rescue Exception
                raise "#{netmask} is an improperly formed IPv4 address."
            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_netmask & hostmask
                if ( check != 0)
                    hostmask = hostmask >> 1
                    unless ( (packed_netmask ^ hostmask) == all_f)
                        raise "#{netmask} contains '1' bits within the host portion of the netmask." 
                    end
                    break
                else
                    hostmask = hostmask << 1
                    hostmask = hostmask | 1
                end
            end

        else
            # remove '/' if present
            if (netmask =~ /^\// )
                netmask[0] = " "
                netmask.lstrip!
            end

            # check if we have any non numeric characters
            if (netmask =~ /\D/)
                raise "#{netmask} contains invalid characters."
            end

            netmask = netmask.to_i
            if (netmask > max_bits || netmask == 0 )
                raise "Netmask, #{netmask}, is out of bounds for IPv#{version}." 
            end

        end
        
    elsif (netmask.kind_of?(Integer) )
        if (!packed)
            if (netmask > max_bits || netmask == 0 )
                raise "Netmask, #{netmask}, is out of bounds for IPv#{version}." 
            end
        else
            if (netmask >= 2**max_bits || netmask == 0 )
                raise "Packed netmask, #{netmask}, is out of bounds for IPv#{version}."
            end
        end
        
    else
        raise ArgumentError, "Expected String or Integer, but #{netmask.class} provided."
    end

    return(true)
end