Class: IPAdmin::Tree

Inherits:
Object
  • Object
show all
Defined in:
lib/tree.rb

Instance Method Summary collapse

Constructor Details

#initialize(options = nil) ⇒ Tree

  • Arguments:

    • none

Examples:

tree = IPAdmin::Tree.new()



20
21
22
23
 
# File 'lib/tree.rb', line 20

def initialize(options=nil)
    # root of our ordered IP tree
    @root = NetStruct.new(nil, nil, [])
end

Instance Method Details

#add!(new) ⇒ Object

Add a CIDR address or IPAdmin::CIDR object to the tree.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • nil

Examples:

tree.add!('192.168.1.0/24')
cidr = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24', :Tag => {:title => 'test net'}
tree.add!(cidr)



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
76
77
78
79
80
81
82
83
84
85
86
87
 
# File 'lib/tree.rb', line 42

def add!(new)
    duplicate = false

    # validate object
    if ( !new.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => new)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    else
        cidr = new.dup
    end

    version = cidr.version
    new_entry = NetStruct.new(cidr, nil, [])

    # find cidr's parent
    new_entry.parent = find_parent(cidr, @root)

    # check parent for subnets of cidr
    new_entry.parent.children.each do |old_entry|
        if (old_entry.cidr.version == version)
            comp = IPAdmin.compare(cidr,old_entry.cidr)
            if (comp && comp[0] == cidr)
                old_entry.parent = new_entry
                new_entry.children.push(old_entry)
            elsif (comp && comp == 1)
                duplicate = true
                break
            end
        end
    end

    if (!duplicate)
        new_entry.children.each do |old_entry|
            new_entry.parent.children.delete(old_entry)
        end

        # add new object as an ordered entry to parent.children
        add_to_parent(new_entry,new_entry.parent)
    end

    return(nil)
end

#ancestors(cidr) ⇒ Object

Returns all the ancestors of the provided CIDR addresses.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • Array of IPAdmin::CIDR objects

Examples:

puts tree.ancestors('192.168.1.0/27')



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/tree.rb', line 104

def ancestors(cidr)
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end
    
    list = []
    parent = find_parent(cidr,@root)
    
    until (parent == @root)
        list.push(parent.cidr)
        parent = parent.parent
    end

    return(list)
end

#children(cidr) ⇒ Object

Returns all the immediate children of the provided CIDR addresses.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • Array of IPAdmin::CIDR objects

Examples:

puts tree.children('192.168.1.0/24')



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/tree.rb', line 141

def children(cidr)
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    list = []
    find_me(cidr).children.each do |child|
        list.push(child.cidr)
    end

    return(list)
end

#delete!(cidr) ⇒ Object

Remove the provided CIDR address from the tree.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true on success or false on fail

Examples:

did_remove = tree.remove!('192.168.1.0/24')



209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/tree.rb', line 209

def delete!(cidr)
    removed = false
    
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    # find matching
    me = find_me(cidr)
    
    # remove
    if (me)
        parent = me.parent
        children = me.children 
        parent.children.delete(me)
        children.each {|x| add_to_parent(x,parent)}
        removed = true
    end

    return(removed)
end

#descendants(cidr) ⇒ Object

Return all descendants of the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • Array of IPAdmin::CIDR objects

Examples:

descendants = tree.descendants('192.168.1.0/24')



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/tree.rb', line 175

def descendants(cidr)
    list = []
    
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)        
    dump_children(me).each {|x| list.push(x[:NetStruct].cidr)} if (me)

    return(list)
end

#dump ⇒ Object

Dump the contents of this tree.

  • Arguments:

    • none

  • Returns:

    • ordered array of hashes with the following fields:

      - :CIDR => IPAdmin::CIDR object
- :Depth => (depth level in tree)

Examples:

dumped = tree.dump()



253
254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/tree.rb', line 253

def dump()
    list = []
    dumped = dump_children(@root)

    dumped.each do |entry|
        depth = entry[:Depth]
        net_struct = entry[:NetStruct]
        list.push({:Depth => depth, :CIDR => net_struct.cidr})
    end

    return(list)
end

#exists?(cidr) ⇒ Boolean

Has a CIDR address already been added to the tree?

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true or false

Examples:

added = tree.exists?('192.168.1.0/24')



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/tree.rb', line 281

def exists?(cidr)
    found = false

    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    found = true if (find_me(cidr))
    return(found)
end

#fill_in!(cidr) ⇒ Object

Fill in the missing subnets of a particular CIDR.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true or false

Examples:

success = tree.fill_in!('192.168.1.0/24')



313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
 
# File 'lib/tree.rb', line 313

def fill_in!(cidr)
    filled = false

    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)        
    if (me && me.children.length != 0)
        list = []
        me.children.each {|x| list.push(x.cidr)}
        me.cidr.fill_in(:List => list, :Objectify => true).each do |cidr|
            self.add!(cidr)
        end
        filled = true
    end
    return(filled)
end

#find(cidr) ⇒ Object

Find and return a CIDR from within the tree.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • IPAdmin::CIDR object, or nil

Examples:

cidr = tree.find('192.168.1.0/24')



353
354
355
356
357
358
359
360
361
362
363
364
 
# File 'lib/tree.rb', line 353

def find(cidr)
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    return(find_me(cidr).cidr)
end

#find_space(options) ⇒ Object

Find subnets that are of at least size X. Only subnets that are not themselves subnetted will be returned.

  • Arguments:

    • Minimum subnet size in bits, or a Hash with the following fields:

      - :Subnet - minimum subnet size in bits for returned subnets
- :IPCount - minimum IP count per subnet required for returned subnets
- :Version - restrict results to IPvX

  • Returns:

    • Array of IPAdmin::CIDR objects

  • Notes:

    • :Subnet takes precedence over :IPCount

Examples:

subnets = tree.find_space(:IPCount => 16)



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
 
# File 'lib/tree.rb', line 388

def find_space(options)
    version = nil
    if (options.kind_of? Integer)
        bits4 = options
        bits6 = options
    elsif (options.kind_of? Hash) 
        if (options.has_key?(:Version))
            version = options[:Version]
            raise "IP version should be 4 or 6, but was #{version}." if (version != 4 && version !=6)
        end

        if (options.has_key?(:Subnet))
            bits4 = options[:Subnet]
            bits6 = options[:Subnet]
        elsif(options.has_key?(:IPCount))
            bits4 = IPAdmin.minimum_size(:IPCount => options[:IPCount], :Version => 4)
            bits6 = IPAdmin.minimum_size(:IPCount => options[:IPCount], :Version => 6)
        else
            raise "Missing arguments: :Subnet/:IPCount"
        end
    else
        raise "Integer or Hash expected, but #{options.class} provided."
    end

    list4 = []
    list6 = []
    dump_children(@root).each do |entry|
        netstruct = entry[:NetStruct]
        if (netstruct.cidr.version == 4)
            if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits4) )
                list4.push(netstruct.cidr)
            end
        else
            if ( (netstruct.children.length == 0) && (netstruct.cidr.bits <= bits6) )
                list6.push(netstruct.cidr)
            end
        end
    end
    
    list = []
    if (!version)
        list.concat(list4)
        list.concat(list6)
    else
        list.concat(list4) if (version == 4)
        list.concat(list6) if (version == 6)
    end

    return(list)
end

#longest_match(cidr) ⇒ Object

Find the longest matching branch of our tree to which a CIDR address belongs. Useful for performing ‘routing table’ style lookups.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • IPAdmin::CIDR object, or nil

Examples:

longest_match = tree.longest_match('192.168.1.1')



455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/tree.rb', line 455

def longest_match(cidr)
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin                
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end
    
    found = find_me(cidr)
    found = find_parent(cidr, @root) if !found

    return(found.cidr)
end

#merge_subnets!(cidr) ⇒ Object

Merge (summarize) all subnets of the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true on success or false on fail

Examples:

tree.merge_subnets!('192.168.1.0/24')



486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
 
# File 'lib/tree.rb', line 486

def merge_subnets!(cidr)
    merged = false
    
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)
    
    if (me)
        to_merge = []
        me.children.each {|x| to_merge.push(x.cidr)}
        to_merge.each {|x| delete!(x)}

        IPAdmin.merge(to_merge).each {|x| add!(x)}            
        merged = true
    end

    return(merged)
end

#prune!(cidr) ⇒ Object

Remove all subnets of the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true on success or false on fail

Examples:

did_prune = tree.prune!('192.168.1.0/24')



528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
 
# File 'lib/tree.rb', line 528

def prune!(cidr)
    pruned = false
    
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)
    
    if (me)
        me.children.clear
        pruned = true
    end

    return(pruned)
end

#remove!(cidr) ⇒ Object

Remove the provided CIDR address, and all of its subnets from the tree.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • true on success or false on fail

Examples:

did_remove = tree.remove!('192.168.1.0/24')



566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
 
# File 'lib/tree.rb', line 566

def remove!(cidr)
    removed = false
    found = nil
    
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)
    
    if (me)
        parent = me.parent
        parent.children.delete(me)
        removed = true
    end
    
    return(removed)
end

#resize!(cidr, bits) ⇒ Object

Resize the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

    • Integer representing the bits of the new netmask

  • Returns:

    • true on success or false on fail

Examples:

resized = tree.resize!('192.168.1.0/24', 23)



607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
 
# File 'lib/tree.rb', line 607

def resize!(cidr,bits)
    resized = false
    
    # validate cidr
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end

    me = find_me(cidr)
    
    if (me)
        new = me.cidr.resize(bits)
        delete!(me.cidr)
        add!(new)
        resized = true
    end
    
    return(resized)
end

#root(cidr) ⇒ Object

Returns the root of the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • IPAdmin::CIDR object

Examples:

puts tree.root('192.168.1.32/27')



647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
 
# File 'lib/tree.rb', line 647

def root(cidr)
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end
    
    parent = find_parent(cidr,@root)
    
    if (parent && parent != @root)
        until (parent.parent == @root)
            parent = parent.parent
        end
    end

    return(parent.cidr)
end

#show ⇒ Object

Print the tree in a nicely formatted string.

  • Arguments:

    • none

  • Returns:

    • String

Examples:

puts tree.show()



684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
 
# File 'lib/tree.rb', line 684

def show()
    printed = ""
    list = dump_children(@root)

    list.each do |entry|
        cidr = entry[:NetStruct].cidr
        depth = entry[:Depth]

        if (depth == 0)
            indent = ""
        else
            indent = " " * (depth*3)
        end

        printed << "#{indent}#{cidr.desc(:Short => true)}\n"
    end

    return(printed)
end

#siblings(cidr) ⇒ Object

Return list of the sibling CIDRs of the provided CIDR address.

  • Arguments:

    • String or IPAdmin::CIDR object

  • Returns:

    • Array of IPAdmin::CIDR objects

Examples:

puts tree.siblings('192.168.1.0/27')



719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
 
# File 'lib/tree.rb', line 719

def siblings(cidr)
    # validate object
    if ( !cidr.kind_of?(IPAdmin::CIDR) )
        begin
            cidr = IPAdmin::CIDR.new(:CIDR => cidr)
        rescue Exception => error
            raise ArgumentError, "Provided argument raised the following " +
                                 "errors: #{error}"
        end
    end
    
    list = []
    find_parent(cidr,@root).children.each do |entry|
        if (!IPAdmin.compare(cidr,entry.cidr))
            list.push(entry.cidr)
        end
    end

    return(list)
end

#supernets ⇒ Object

Return list of the top-level supernets of this tree.

  • Arguments:

    • none

  • Returns:

    • Array of IPAdmin::CIDR objects

Examples:

supernets = tree.supernets()



755
756
757
758
759
 
# File 'lib/tree.rb', line 755

def supernets()
   supernets = []
   @root.children.each {|x| supernets.push(x.cidr)}
   return (supernets)
end