Module: IPAdmin

Defined in:
lib/ip_admin.rb

Defined Under Namespace

Classes: CIDR, NetStruct, Tree

Class Method Summary collapse

Class Method Details

.arpa(object) ⇒ Object

Using the provided IPAdmin::CIDR object, return either an in-addr.arpa. or ip6.arpa. string. The netmask will be used to determine the length of the returned arpa string.

  • Arguments:

    • IPAdmin::CIDR object

  • Returns:

    • IP address in in-addr.arpa or ip6.arpa format

Note:

IPAdmin.arpa 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:

arpa = IPAdmin.arpa(cidr)



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/ip_admin.rb', line 30

def arpa(object)

    unless (object.kind_of? IPAdmin::CIDR)
        raise ArgumentError, "Expected IPAdmin::CIDR object, " +
                             "but #{object.class} provided."
    end

    base = object.ip()
    netmask = object.bits()

    if (object.version == 4)
        net = base.split('.')

        if (netmask)
            while (netmask < 32)
                net.pop
                netmask = netmask + 8
            end
        end

        arpa = net.reverse.join('.')
        arpa << ".in-addr.arpa."

    elsif (object.version == 6)
        fields = base.split(':')
        net = []
        fields.each do |field|
            (field.split("")).each do |x|
                net.push(x)
            end
        end

        if (netmask)
            while (netmask < 128)
                net.pop
                netmask = netmask + 4
            end
        end

        arpa = net.reverse.join('.')
        arpa << ".ip6.arpa."

    end

    return(arpa)
end

.compare(obj1, obj2) ⇒ Object

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

  • Arguments:

    • Two IPAdmin::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)



103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/ip_admin.rb', line 103

def compare(obj1,obj2)
    ret_val = nil

    # validate arguments
    unless ( 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

    unless ( 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
    unless (obj1.version == obj2.version )
        raise "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 an IPAdmin::NetStruct object from an IPAdmin::CIDR or NetStruct object. This type of Struct is used internally for various tasks, and is not likely to be useful to anyone.

  • Arguments:

    • IPAdmin::CIDR or NetStruct object

  • Returns:

    • IPAdmin::NetStruct object

Example:

net_struct = IPAdmin.create_net_struct(object)



183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/ip_admin.rb', line 183

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 IPAdmin::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 IPAdmin::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 IPAdmin::CIDR or IPAdmin::NetStruct objects

Example:

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



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
 
# File 'lib/ip_admin.rb', line 233

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

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

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

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

    # make sure list is an array
    unless ( 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|
        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 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
                unless (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 (version == 4)
                network = IPAdmin.unpack_ipv4_addr(entry.network)
                netmask = IPAdmin.unpack_ipv4_netmask(entry.netmask)
            else
                network = IPAdmin.unpack_ipv6_addr(entry.network)
                network = IPAdmin.shorten(network) if (short && !objectify)
                netmask = IPAdmin.unpack_ipv6_netmask(entry.netmask)
            end

            if (!objectify)
                supernets.push("#{network}/#{netmask}")
            else
                supernets.push(IPAdmin::CIDR.new(:CIDR => "#{network}/#{netmask}"))
            end
        end
    else
        supernets = supernet_list
    end

    return(supernets)
end

.pack_ipv4_addr(ip) ⇒ Object

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

  • Arguments:

    • IPv4 address

  • Returns:

    • packed IPv4 address or exception on error.

Example:

packed = IPAdmin.pack_ipv4_addr('192.168.1.1')



463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
 
# File 'lib/ip_admin.rb', line 463

def pack_ipv4_addr(ip)

    # is this a string?
    unless (ip.kind_of? String)
        raise ArgumentError, "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

.pack_ipv4_netmask(netmask) ⇒ Object

Convert IPv4 netmask into an integer. Only very basic validation is performed.

  • Arguments:

    • IPv4 netmask in cidr or extended notation

  • Returns:

    • packed IPv4 netmask or exception on error.

Example:

packed = IPAdmin.pack_ipv4_netmask('255.255.255.0')
packed = IPAdmin.pack_ipv4_netmask('24')
packed = IPAdmin.pack_ipv4_netmask('/24')
packed = IPAdmin.pack_ipv4_netmask(24)



508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
 
# File 'lib/ip_admin.rb', line 508

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)
            rescue Exception 
            raise "#{netmask} is not a valid IPv4 netmask."
        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} is not a valid IPv4 netmask."
        end

        if (netmask.kind_of? String)
            netmask = netmask.to_i
        end

        packed_netmask = all_f ^ (all_f >> netmask)
    end

    return(packed_netmask)
end

.pack_ipv6_addr(ip) ⇒ Object

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

  • Arguments:

    • IPv6 address

  • Returns:

    • packed IPv6 address or exception on error.

Example:

packed = IPAdmin.pack_ipv6_addr('fec0::1')



564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
 
# File 'lib/ip_admin.rb', line 564

def pack_ipv6_addr(ip)
    # is this a string?
    unless (ip.kind_of? String)
        raise ArgumentError, "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

.pack_ipv6_netmask(netmask) ⇒ Object

Convert IPv6 netmask into an integer. Only very basic validation is performed.

  • Arguments:

    • IPv6 netmask in cidr notation

  • Returns:

    • packed IPv6 netmask or exception on error.

Example:

packed = IPAdmin.pack_ipv6_netmask('64')
packed = IPAdmin.pack_ipv6_netmask('/64')
packed = IPAdmin.pack_ipv6_netmask(64)



636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
 
# File 'lib/ip_admin.rb', line 636

def pack_ipv6_netmask(netmask)
    all_f = 2**128-1

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

    if (netmask !~ /\D/)   
        # pack
        if (netmask.kind_of? String)
            netmask = netmask.to_i
        end

        packed_netmask = all_f ^ (all_f >> netmask)

    else
        raise "#{netmask} is not a valid IPv6 netmask."

    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 (optional)
- :Boundaries -- array of (2) IPAdmin::CIDR objects
- :Limit -- limit returned list to X number of items (optional)
- :Objectify -- if true, return IPAdmin::CIDR objects (optional)
- :Short -- if true, return IPv6 addresses in short-hand notation (optional)

  • Returns:

    • Array of IP addresses or IPAdmin::CIDR objects

Note:

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])



692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
 
# File 'lib/ip_admin.rb', line 692

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

    # check options
    if (options)
        unless ( 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) )
            objectify = true
        end
        
        if( options.has_key?(:Short) )
            short = true
        end

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

    # check our objects
    unless (cidr1.kind_of?(IPAdmin::CIDR) && cidr2.kind_of?(IPAdmin::CIDR))
        raise "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 "Provided IPAdmin::CIDR objects are of different IP versions."
    end

    # dump our range
    if (version == 4)
        my_ip = boundaries[0] + 1

        until (my_ip >= boundaries[1]) 
            if (!objectify)
                list.push( IPAdmin.unpack_ipv4_addr(my_ip) )
            else
                my_ip_s = IPAdmin.unpack_ipv4_addr(my_ip)
                list.push( IPAdmin::CIDR.new(:CIDR => my_ip_s) )
            end

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

    elsif (version == 6)
        my_ip = boundaries[0] + 1

        until (my_ip == boundaries[1])
            if (!objectify)
                my_ips = IPAdmin.unpack_ipv6_addr(my_ip)
                my_ips = IPAdmin.shorten(my_ips) if (short)
                list.push(my_ips)
                
            else
                my_ip_s = IPAdmin.unpack_ipv6_addr(my_ip)
                list.push( IPAdmin::CIDR.new(:CIDR => my_ip_s) )
            end

            my_ip = my_ip + bitstep
            if (limit)
                limit = limit -1
                break if (limit == 0)
            end
        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:

    • IPv6 address

  • Returns:

    • IPv6 short-hand address.

Example:

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



810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
 
# File 'lib/ip_admin.rb', line 810

def shorten(addr)

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

    validate_ipv6_addr(addr)

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

    # look for most consecutive '0' fields
    start_field,end_field = nil,nil
    start_end = []
    consecutive,longest = 0,0
    fields = addr.split(":")
    
    (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
    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 IPAdmin::CIDR or NetStruct objects

  • Returns:

    • Sorted Array

Note:

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)



902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
 
# File 'lib/ip_admin.rb', line 902

def sort(list)

    # make sure list is an array
    unless ( 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_ipv4_addr(packed_ip) ⇒ Object

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

  • Arguments:

    • Byte-packed IPv4 address

  • Returns:

    • IPv4 address.

Example:

unpacked = IPAdmin.unpack_ipv4_addr(packed)



979
980
981
982
983
984
985
986
987
988
989
990
991
 
# File 'lib/ip_admin.rb', line 979

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

.unpack_ipv4_netmask(packed_mask) ⇒ Object

Unack a packed 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).

Example:

unpacked = IPAdmin.unpack_ipv4_netmask(packed)



1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
 
# File 'lib/ip_admin.rb', line 1015

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

.unpack_ipv6_addr(packed_ip) ⇒ Object

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

  • Arguments:

    • Byte-packed IPv6 address

  • Returns:

    • IPv6 address.

Example:

unpacked = IPAdmin.unpack_ipv6_addr(packed)



1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
 
# File 'lib/ip_admin.rb', line 1050

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

.unpack_ipv6_netmask(packed_mask) ⇒ Object

Unack a packed 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).

Example:

unpacked = IPAdmin.unpack_ipv6_netmask(packed)



1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
 
# File 'lib/ip_admin.rb', line 1091

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

.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:

    • IPv6 address

  • Returns:

    • IPv6 short-hand address.

Example:

long = IPAdmin.unshorten('fec0::1')



1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
 
# File 'lib/ip_admin.rb', line 1127

def unshorten(addr)

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

    packed = validate_ipv6_addr(addr)
    long = unpack_ipv6_addr(packed)

    return(long)
end

.validate_ipv4_addr(ip) ⇒ Object

Validate IPv4 addresses. The address should not contain a netmask.

  • Arguments:

    • IPv4 address

  • Returns:

    • packed IP on valid, or exception on error.

Example:

IPAdmin.validate_ipv4_addr('192.168.1.1')



1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
 
# File 'lib/ip_admin.rb', line 1161

def validate_ipv4_addr(ip)

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

    # check validity of characters in the addr
    if ( (ip =~ /\.{2,}?/ ) || (ip =~ /[^0-9\.]/) )
        raise "#{ip} is not a valid IPv4 address."
    end

    # do we have 4 octets?
    octets = ip.split( /\./ ).reverse
    if (octets.length != 4)
        raise "#{ip} is not a valid IPv4 address."
    end

    # are octets in range 0..255?
    packed_ip = 0
    (0..3).each do |x|
        octets[x] = octets[x].to_i
        unless ( (octets[x] >= 0) && (octets[x] < 256 ) )
            raise "#{ip} is not a valid IPv4 address." 
        end
        octets[x] =  octets[x] << 8*x 
        packed_ip = packed_ip | octets[x]
    end

    # dont allow first octet to be 0
    if (octets[3] == 0)
        raise "#{ip} is not a valid IPv4 address." 
    end

    return(packed_ip)

end

.validate_ipv4_netmask(netmask) ⇒ Object

Validate IPv4 Netmask.

  • Arguments:

    • IPv4 netmask in cidr or extended notation

  • Returns:

    • packed netmask on valid, or exception on error.

Example:

IPAdmin.validate_ipv4_netmask('255.255.255.0')
IPAdmin.validate_ipv4_netmask('24')
IPAdmin.validate_ipv4_netmask('/24')
IPAdmin.validate_ipv4_netmask(24)



1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
 
# File 'lib/ip_admin.rb', line 1223

def validate_ipv4_netmask(netmask)
    all_f = 2**32 - 1
    packed_mask = nil

    # is this a CIDR or Extended mask?
    if(netmask =~ /\./)
        # validate & pack extended mask
        begin
            validate_ipv4_addr(netmask)
            packed_netmask = pack_ipv4_addr(netmask)

            rescue Exception 
            raise "#{netmask} is not a valid IPv4 netmask."
        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} is not a valid IPv4 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} is not a valid IPv4 netmask."
        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 not a valid IPv4 netmask." 
        end

        packed_netmask = all_f ^ (all_f >> netmask)
    end

    return(packed_netmask)
end

.validate_ipv6_addr(ip) ⇒ Object

Validate IPv6 addresses. The address should not contain a netmask.

  • Arguments:

    • IPv6 address

  • Returns:

    • packed IP on valid, or exception on error.

Example:

IPAdmin.validate_ipv6_addr('fec0::')



1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
 
# File 'lib/ip_admin.rb', line 1307

def validate_ipv6_addr(ip)
    # is this a string?
    unless (ip.kind_of? String)
        raise ArgumentError, "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 not a valid IPv6 address."
    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 not a valid IPv6 address."
        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 not a valid IPv6 address."
        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 not a valid IPv6 address."
        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 not a valid IPv6 address."
        end
    end

    packed_ip = IPAdmin.pack_ipv6_addr(ip)
    return(packed_ip)
end

.validate_ipv6_netmask(netmask) ⇒ Object

Validate IPv6 netmask.

  • Arguments:

    • IPv6 netmask in cidr notation

  • Returns:

    • packed netmask on valid, or exception on error.

Example:

IPAdmin.validate_ipv6_netmask('64')
IPAdmin.validate_ipv6_netmask('/64')
IPAdmin.validate_ipv6_netmask(64)



1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
 
# File 'lib/ip_admin.rb', line 1385

def validate_ipv6_netmask(netmask)
    all_f = 2**128 -1

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

    if (netmask =~ /\D/)
        raise "#{netmask} is not a valid IPv6 netmask."

    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 not a valid IPv6 netmask." 
        end

    end

    packed_netmask = all_f ^ (all_f >> netmask)
    return(packed_netmask)
end