ipadmin 0.3.0 → 0.4.0

data/README

@@ -1,11 +1,10 @@
-
 =Introduction
 
  IPAdmin arose from a work-related project to create a Rails IP 
  Administration package. I needed a back-end module that could easily
  handle such advanced tasks as automating the subnetting/supernetting
  of IP space, performing calculations on IP CIDR blocks, and other
- various tasks. At the current time there were no modules that could
+ various items. At that time there were no modules that could
  do any of the things that I needed, so I set out to create my own. 
  Since it proved to be fairly useful to me, I decided to share the
  code with the Ruby community. 
@@ -20,14 +19,9 @@
  your life easier. Comments are also welcome (positive ones in particular).  
  
  Dustin Spinhirne
- 
- 
- Copyright (c) 2006 Dustin Spinhirne - http://www.spinhirne.com
- Licensed under the same terms as Ruby, No Warranty is provided.
 
- 
 
-=CIDR:
+=CIDR - Classless Inter-Domain Routing
 
  A class & series of methods for creating and manipulating CIDR network
  addresses. Both IPv4 and IPv6 are supported.
@@ -43,7 +37,7 @@
  methods for modifying the CIDR or creating new derivative CIDR's.
  
  An example CIDR object is as follows:
-    IPAdmin::CIDR.new(:CIDR => '192.168.1.20/24')
+    IPAdmin::CIDR.new('192.168.1.20/24')
  
  This would create a CIDR object (192.168.1.0/24) with the following properties:
     version = 4
@@ -69,14 +63,14 @@
  print "\n"
 
  # new
- cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
+ cidr4 = IPAdmin::CIDR.new('192.168.1.0/24')
  cidr4 = IPAdmin::CIDR.new(:CIDR => '192.168.1.1',
                            :Netmask => '255.255.255.0',
                            :Tag => {'test' => 'cidr4 tag'})
- cidr6 = IPAdmin::CIDR.new(:CIDR => 'fec0::1/64')
+ cidr6 = IPAdmin::CIDR.new('fec0::1/64')
  
- cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26')
- cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/96')
+ cidr4_2 = IPAdmin::CIDR.new('192.168.1.0/26')
+ cidr6_2 = IPAdmin::CIDR.new('fec0::0/96')
 
  # reader/writer
  puts "reader/writer"
@@ -121,6 +115,12 @@
  cidr6.enumerate(:Limit => 4, :Bitstep => 32, :Objectify => true).each {|x| puts "  #{x.desc}"}
  print "\n"
 
+ # fill_in
+ puts "fill_in"
+ puts "#{cidr4.desc} filled-in is:"
+ cidr4.fill_in([cidr4_2]).each {|x| puts x}
+ print "\n"
+ 
  # hostmask_ext
  puts "hostmask_ext"
  puts "cidr4 extended hostmask #{cidr4.hostmask_ext()}"
@@ -139,8 +139,8 @@
  print "\n"
  
  # multicast_mac
- mcast = IPAdmin::CIDR.new(:CIDR => '224.0.0.6')
- mcast2 = IPAdmin::CIDR.new(:CIDR => 'ff00::abcd')
+ mcast = IPAdmin::CIDR.new('224.0.0.6')
+ mcast2 = IPAdmin::CIDR.new('ff00::abcd')
  puts "multicast_mac"
  puts "#{mcast.ip} multicast mac is #{mcast.multicast_mac()}"
  puts "#{mcast2.ip} multicast mac is #{mcast2.multicast_mac()}"
@@ -177,7 +177,7 @@
 
  # nth
  puts "nth"
- puts "cidr4 1st ip is #{cidr4.nth(:Index => 1)}"
+ puts "cidr4 1st ip is #{cidr4.nth(1)}"
  puts "cidr6 1st ip is #{(cidr6.nth(:Index => 1, :Objectify => true)).base}"
  print "\n"
  
@@ -207,15 +207,15 @@
  
  # remainder
  puts "remainder"
- cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26')
+ cidr4_2 = IPAdmin::CIDR.new('192.168.1.64/26')
  puts "The remainder of #{cidr4.desc} after subtracting #{cidr4_2.desc} is:"
- cidr4.remainder(:Exclude => cidr4_2).each {|x| puts x}
+ cidr4.remainder(cidr4_2).each {|x| puts x}
  print "\n" 
   
  # resize!
  puts "resize!"
- cidr4.resize!(:Subnet => 25)
- cidr6.resize!(:Subnet => 65)
+ cidr4.resize!(25)
+ cidr6.resize!(:Netmask => 65)
  puts "cidr4 resized is #{cidr4.desc}"
  puts "cidr6 resized is #{cidr6.desc}"
  print "\n"
@@ -234,12 +234,11 @@
  puts "#{cidr6.desc(:Short => true)} subnetted into at least 4 /67 ranges"
  cidr6.subnet(:Subnet => 67, :MinCount => 4, :Short => true).each {|x| puts "  #{x}"}
 
- 
- 
- 
- 
-=EUI:
 
+
+
+=EUI - Extended Unique Identifier
+ 
  A class & series of methods for creating and manipulating Extended Unique Identifier
  (EUI) addresses. Two types of address formats are supported EUI-48 and EUI-64. The 
  most common use for this class will be to manipulate MAC addresses (which are essentially
@@ -254,8 +253,7 @@
  is to help automate certain address assignments within IP. For example, IPv6
  Link Local addresses use MAC addresses for IP auto-assignment and multicast MAC addresses
  are determined based on the multicast IP address.
- 
- 
+
 ====Examples: 
 
  #!/usr/bin/ruby
@@ -266,8 +264,8 @@
  puts "IPAdmin::EUI"
  print "\n"
  
- eui1 = IPAdmin::EUI.new(:EUI => 'aa-bb-cc-dd-ee-ff')
- eui2 = IPAdmin::EUI.new(:EUI => '12-34-56-78-9a-bc-de-f0')
+ eui1 = IPAdmin::EUI48.new('aa-bb-cc-dd-ee-ff')
+ eui2 = IPAdmin::EUI64.new('12-34-56-78-9a-bc-de-f0')
  
  # oui
  puts "oui"
@@ -294,38 +292,33 @@
  print "\n"
  
  # type
- puts "type"
- puts "eui 1 type is #{eui1.type}"
- puts "eui 2 type is #{eui2.type}"
- 
+ puts "class"
+ puts "eui 1 is a #{eui1.class}"
+ puts "eui 2 is a #{eui2.class}"
+
+
 
 
-=Tree:
+=Tree
 
  A class & series of methods for creating and manipulating IP-based
  heirarchical trees. Both IPv4 and IPv6 are supported.
-
- Tree's are useful for creating mini 'routing tables' of CIDR address space.
- Using a tree, you can quickly determine the 'route' of another CIDR via
- the standard longest-match algorithm.
- 
- Tree's are not dynamic, in that if you modify any of the CIDR objects
- contained within, the Tree will not automatically adjust itself accordingly.
- For example if you have a tree like the following:
- 
-    192.168.0.0/24
-        192.168.0.0/26
-    192.168.1.0/24
-    
- You decide to resize 192.168.0.0/24 to 192.168.0.0/23. The tree will now
- be incorrect:
- 
-    192.168.0.0/23
-        192.168.0.0/26
-    192.168.1.0/24
  
- You would need to remove and re-add the CIDR 192.168.0.0/23 in order for the
- tree to rebuild itself properly.
+ A sample tree would look like:
+ 192.168.1.0/24
+   192.168.1.0/26
+      192.168.1.0/27
+         192.168.1.0/28
+         192.168.1.16/29
+            192.168.1.16/30
+         192.168.1.24/30
+            192.168.1.25/32
+         192.168.1.28/30
+      192.168.1.32/27
+   192.168.1.64/26
+      192.168.1.64/27
+   192.168.1.128/26
+   192.168.1.192/26
  
  
 ====Examples: 
@@ -338,124 +331,154 @@
  puts "IPAdmin::Tree"
  print "\n"
 
- cidr4 = [IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.0/26'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.64/26'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.128/26'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.192/26'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.0/27'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.0/28'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.16/28'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.16/29'),
-          IPAdmin::CIDR.new(:CIDR => '192.168.1.32/27')]
- 
- cidr6 = [IPAdmin::CIDR.new(:CIDR => 'fec0::/64'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::/66'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::4000:0:0:0/66'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::8000:0:0:0/66'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::c000:0:0:0/66'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::c000:0:0:0/67'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::/67'),
-          IPAdmin::CIDR.new(:CIDR => 'fec0::2000:0:0:0/67')]
+ cidr4 = ['192.168.1.0/24','192.168.1.0/26','192.168.1.64/26',
+          '192.168.1.128/26','192.168.1.192/26','192.168.1.0/27',
+          '192.168.1.0/28','192.168.1.16/30','192.168.1.16/29',
+          '192.168.1.32/27','192.168.1.24/30','192.168.1.28/30',
+          '192.168.1.64/27','192.168.1.25']
+ 
+ cidr6 = ['fec0::/60','fec0::/66','fec0::4000:0:0:0/66',
+          'fec0::8000:0:0:0/66','fec0::c000:0:0:0/66','fec0::c000:0:0:0/67',
+          'fec0::/67','fec0::2000:0:0:0/67','fec0::8000:0:0:0/67','fec0::4000:0:0:0/69']
 
  # new
- tree4 = IPAdmin::Tree.new(:Version => 4)
- tree6 = IPAdmin::Tree.new(:Version => 6)
+ tree = IPAdmin::Tree.new()
+
 
- # add
- puts "add"
+ # add!
+ puts "add!"
  cidr4.each do |x| 
-    puts "adding #{x.desc}..."
-    tree4.add(x)
+    puts "adding #{x}..."
+    tree.add!(x)
  end
  cidr6.each do |x| 
-    puts "adding #{x.desc}..."
-    tree6.add(x)
+    puts "adding #{x}..."
+    tree.add!(x)
  end
  print "\n"
  
-  # dump
+ # ancestors
+ puts "ancestors"
+ puts "ancestors for 192.168.1.16/28 are..."
+ tree.ancestors('192.168.1.16/28').each {|x| puts x.desc}
+ print "\n"
+ 
+ # children
+ puts "children"
+ puts "children of 192.168.1.0/24 are..."
+ tree.children('192.168.1.0/24').each {|x| puts x.desc}
+ print "\n"
+ 
+ # delete!
+ puts "delete!"
+ puts "deleting 192.168.1.16/29"
+ tree.delete!('192.168.1.16/29')
+ print "\n"
+
+ # descendants
+ puts "descendants"
+ puts "descendants of 192.168.1.0/26 are..."
+ tree.descendants('192.168.1.0/26').each {|x| puts x.desc}
+ print "\n"
+
+ # dump
  puts "dump"
- puts "dumping & printing tree4"
- dumped = tree4.dump()
+ puts "dumping & printing tree"
+ dumped = tree.dump()
  dumped.each do |val|
-    obj = val[:Object]
+    cidr = val[:CIDR]
     depth = val[:Depth]
     if (depth > 0)
         indent = " " * (depth*3)
-        puts indent << obj.desc()
+        puts indent << cidr.desc()
     else
-        puts obj.desc()
+        puts cidr.desc()
     end
  end
+ print "\n"  
+
+ # exists?
+ puts "exists?"
+ puts "192.168.1.32/27 is in the tree." if tree.exists?('192.168.1.32/27')
  print "\n"
- puts "dumping & printing tree6"
- dumped = tree6.dump()
- dumped.each do |val|
-    obj = val[:Object]
-    depth = val[:Depth]
-    if (depth > 0)
-        indent = " " * (depth*3)
-        puts indent << obj.desc()
-    else
-        puts obj.desc()
-    end
- end
+ 
+ # fill_in
+ puts "fill_in!"
+ puts "filling in subnets of 192.168.1.64/26."
+ tree.fill_in!('192.168.1.64/26')
+ tree.children('192.168.1.64/26').each {|x| puts x.desc}
  print "\n"
-  
- # find space
- puts "find_space with at least 28 IP's in it"
- puts "available space with at least 28 IPs"
- space = tree4.find_space(:IPCount => 28)
- space.each do |obj|
-    puts "  #{obj.desc}"
- end
+ 
+ # find
+ puts "find"
+ puts "finding and setting a tag for 192.168.1.64/26..."
+ tree.find('192.168.1.64/26').tag[:test] = 'testing'
  print "\n"
- puts "available /67 space"
- space = tree6.find_space(:Subnet => 67)
- space.each do |obj|
-    puts "  #{obj.desc}"
- end
+ 
+ # find_space
+ puts "find_space"
+ puts "finding version 4 subnets with at least 16 ips..."
+ tree.find_space(:IPCount => 16, :Version => 4).each {|x| puts x.desc}
+ print "\n"
+
+ # longest_match
+ puts "longest_match"
+ puts "192.168.1.33 belongs in #{tree.longest_match('192.168.1.33').desc}"
+ print "\n"  
+
+ # merge_subnets
+ puts "merge_subnets!"
+ puts "merging the subnets of 192.168.1.0/27"
+ tree.merge_subnets!('192.168.1.0/27')
+ puts tree.show
+ print "\n"
+ 
+ # prune
+ puts "prune!"
+ puts "pruning subnets of 192.168.1.0/27"
+ tree.prune!('192.168.1.0/27') 
  print "\n"
  
  # remove
- puts "remove"
- puts "removing #{cidr4[8].desc}"
- tree4.remove(cidr4[8])
- puts tree4.show()
+ puts "remove!"
+ puts "removing fec0::c000:0:0:0/67, and all of its subnets"
+ tree.remove!('fec0::c000:0:0:0/67')
  print "\n"
- puts "removing #{cidr6[5].desc}"
- tree6.remove(cidr6[5])
- puts tree6.show()
+ 
+ # resize
+ puts "resize!"
+ puts "resizing fec0::/60 into a /65"
+ tree.resize!('fec0::/60', 65)
  print "\n"
  
- # prune
- puts "prune"
- puts "pruning #{cidr4[4].desc}"
- tree4.prune(cidr4[4])
- puts tree4.show()
+ # root
+ puts "root"
+ puts "root of 192.168.1.32/27 is #{tree.root('192.168.1.32/27').desc}"
  print "\n"
- puts "pruning #{cidr6[1].desc}"
- tree6.prune(cidr6[1])
- puts tree6.show()
+ 
+ # siblings
+ puts "siblings"
+ puts "siblings of 192.168.1.0/26 are..."
+ tree.siblings('192.168.1.0/26').each {|x| puts x.desc}
  print "\n"
  
-  # collapse
- puts "collapse"
- puts "collapsed tree4 is..."
- new_tree4 = tree4.collapse()
- puts new_tree4.show()
+ # supernets
+ puts "supernets"
+ puts "supernets of this tree are..."
+ tree.supernets.each {|x| puts x.desc}
  print "\n"
- puts "collapsed tree6 is..."
- new_tree6 = tree6.collapse()
- puts new_tree6.show()
-
+ 
+ # show
+ puts "show"
+ puts "showing tree..."
+ puts tree.show
+ 
 
 
-= IPAdmin General Methods
+=General Methods
 
  A collection of general purpose methods that dont really fit within
- a particular class. 
+ any particular class.
   
 
 ====Examples: 
@@ -470,22 +493,22 @@
  
  # validate ip
  puts "validate ip"
- puts "192.168.1.0 is valid" if ( IPAdmin.validate_ip_addr(:IP => '192.168.1.0') )
- puts "fec0::0 is valid" if ( IPAdmin.validate_ip_addr(:IP => 'fec0::0') )
- puts "::ffff:10.1.0.1 is valid" if ( IPAdmin.validate_ip_addr(:IP => '::ffff:10.1.0.1') )
+ puts "192.168.1.0 is valid" if ( IPAdmin.validate_ip_addr('192.168.1.0') )
+ puts "fec0::0 is valid" if ( IPAdmin.validate_ip_addr('fec0::0') )
+ puts "::ffff:10.1.0.1 is valid" if ( IPAdmin.validate_ip_addr('::ffff:10.1.0.1') )
  print "\n"
 
  # validate netmask
  puts "validate netmask"
- puts "255.255.255.0 is valid" if (IPAdmin.validate_ip_netmask(:Netmask => '255.255.255.0') )
- puts "/24 is valid" if ( IPAdmin.validate_ip_netmask(:Netmask => '/24') )
+ puts "255.255.255.0 is valid" if (IPAdmin.validate_ip_netmask('255.255.255.0') )
+ puts "/24 is valid" if ( IPAdmin.validate_ip_netmask('/24') )
  puts "/64 is valid" if ( IPAdmin.validate_ip_netmask(:Netmask => 64, :Version => 6) )
 
- cidr4_1 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/24')
- cidr4_2 = IPAdmin::CIDR.new(:CIDR => '192.168.1.0/25')
- cidr4_3 = IPAdmin::CIDR.new(:CIDR => '192.168.1.50')
- cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/10')
- cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/64')
+ cidr4_1 = IPAdmin::CIDR.new('192.168.1.0/24')
+ cidr4_2 = IPAdmin::CIDR.new('192.168.1.0/25')
+ cidr4_3 = IPAdmin::CIDR.new('192.168.1.50')
+ cidr6_1 = IPAdmin::CIDR.new('fec0::0/10')
+ cidr6_2 = IPAdmin::CIDR.new('fec0::0/64')
  print "\n"
 
  # compare
@@ -500,6 +523,17 @@
  cidr6_1 = IPAdmin::CIDR.new(:CIDR => 'fec0::0/128')
  cidr6_2 = IPAdmin::CIDR.new(:CIDR => 'fec0::1/128')
  print "\n"
+ 
+ # merge
+ puts "merge"
+ puts "merging 192.168.1.0/27, 192.168.1.32/27, 192.168.1.64/26, and 192.168.1.128/25..."
+ IPAdmin.merge(['192.168.1.0/27','192.168.1.32/27','192.168.1.64/26','192.168.1.128/25']).each {|x| puts x}
+ print "\n"
+ 
+ # minimum_size
+ puts "minimum_size"
+ puts "The subnet size (in bits) for IPv4 that would fit 22 addresses is /#{IPAdmin.minimum_size(22)}"
+ print "\n"
 
  # range
  puts "range"
@@ -510,6 +544,12 @@
  end
  print "\n"
  
+ # sort
+ puts "sort"
+ puts " 192.168.1.0/24, 192.168.1.0/30, 192.168.2.0/32, 10.10.10.10 sorted are..."
+ IPAdmin.sort(['192.168.1.0/24','192.168.1.0/30','192.168.2.0/32','10.10.10.10']).each {|x| puts x}
+ print "\n"
+ 
  # shorten
  puts "shorten"
  puts "shorthand notation for  #{cidr6_1.network()} is #{IPAdmin.shorten(cidr6_1.network)}"
@@ -518,5 +558,4 @@
  # unshorten
  puts "unshorten"
  puts "expanded notation for  fec0:: is #{IPAdmin.unshorten('fec0::')}"
-
-
+