ipadmin 0.2.2 → 0.3.0

data/README

@@ -1,15 +1,33 @@
 
+=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
+ 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. 
+ 
+ I apologize in advance for the short release cycles, but I am making
+ changes on a constant basis since this is a very active project.
+ I tend to post new releases to rubyforge since it is a very easy
+ way for me to distribute my changes to my co-workers.
+ 
+ I have added things that I find immediately useful for me. I am
+ open to suggestions if there is something that I could add to make
+ 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.
 
-
- Comments are welcome. Please include 'IPAdmin' in the title of
- any emails. 
- 
- Dustin Spinhirne
  
 
-=CIDR
+=CIDR:
 
  A class & series of methods for creating and manipulating CIDR network
  addresses. Both IPv4 and IPv6 are supported.
@@ -38,49 +56,15 @@
  You can see how the CIDR object is based around the entire IP space
  defined by the provided IP/Netmask pair, and not necessarily the individual
  IP address itself.
-
-
-=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.
- 
  
  
- 
-=Examples:
- 
+====Examples: 
 
  #!/usr/bin/ruby
 
  require 'rubygems'
  require_gem 'ipadmin'
 
- #============================================================================#
- # IPAdmin::CIDR
- #============================================================================#
  puts "IPAdmin::CIDR"
  print "\n"
 
@@ -101,8 +85,7 @@
  puts "updated cidr4 tag '#{cidr4.tag['test']}'"
  puts "cidr4 version #{cidr4.version}"
  puts "cidr6 version #{cidr6.version}"
- print "\n"
-  
+ print "\n"  
  
  # arpa
  puts "arpa"
@@ -154,6 +137,14 @@
  puts "cidr4 last ip #{cidr4.last()}"
  puts "cidr6 last ip #{cidr6.last(:Short => true)}"
  print "\n"
+ 
+ # multicast_mac
+ mcast = IPAdmin::CIDR.new(:CIDR => '224.0.0.6')
+ mcast2 = IPAdmin::CIDR.new(:CIDR => 'ff00::abcd')
+ puts "multicast_mac"
+ puts "#{mcast.ip} multicast mac is #{mcast.multicast_mac()}"
+ puts "#{mcast2.ip} multicast mac is #{mcast2.multicast_mac()}"
+ print "\n"
 
  # netmask
  puts "netmask"
@@ -243,15 +234,107 @@
  puts "#{cidr6.desc(:Short => true)} subnetted into at least 4 /67 ranges"
  cidr6.subnet(:Subnet => 67, :MinCount => 4, :Short => true).each {|x| puts "  #{x}"}
 
- print "\n\n\n"
- #=====================================#
- #
- #=====================================#
+ 
+ 
+ 
+ 
+=EUI:
+
+ 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
+ a type of EUI-48 address). 
+ 
+ EUI addresses are separated into two parts, the 
+ Organizationally Unique Identifier (OUI) and the Extended Identifier (EI). The OUI
+ is assigned by the IEEE and is used to identify a particular hardware manufacturer.
+ The EI is assigned by the hardware manufacturer as a per device unique address.
+ 
+ Probably the most useful feature of this class, and thus the reason it was created,
+ 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
+
+ require 'rubygems'
+ require_gem 'ipadmin'
+ 
+ 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')
+ 
+ # oui
+ puts "oui"
+ puts "OUI 1 is #{eui1.oui}"
+ puts "OUI 2 is #{eui2.oui}"
+ print "\n"
+ 
+ # ei
+ puts "ei"
+ puts "EI 1 is #{eui1.ei}"
+ puts "EI 2 is #{eui2.ei}"
+ print "\n"
+ 
+ # address
+ puts "address"
+ puts "address 1 is #{eui1.address(:Delimiter => '.')}"
+ puts "address 2 is #{eui2.address(:Delimiter => '.')}"
+ print "\n"
+ 
+ # link local
+ puts "link local"
+ puts "IPv6 link local 1 is #{eui1.link_local(:Short => true)}"
+ puts "IPv6 link local 2 is #{eui2.link_local(:Short => true)}"
+ print "\n"
+ 
+ # type
+ puts "type"
+ puts "eui 1 type is #{eui1.type}"
+ puts "eui 2 type is #{eui2.type}"
+ 
+
+
+=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.
+ 
+ 
+====Examples: 
 
+ #!/usr/bin/ruby
 
- #============================================================================#
- # IPAdmin::Tree
- #============================================================================#
+ require 'rubygems'
+ require_gem 'ipadmin'
+ 
  puts "IPAdmin::Tree"
  print "\n"
 
@@ -367,15 +450,21 @@
  new_tree6 = tree6.collapse()
  puts new_tree6.show()
 
- print "\n\n\n"
- #=====================================#
- #
- #=====================================#
- 
 
- #============================================================================#
- # IPAdmin Methods
- #============================================================================#
+
+= IPAdmin General Methods
+
+ A collection of general purpose methods that dont really fit within
+ a particular class. 
+  
+
+====Examples: 
+
+ #!/usr/bin/ruby
+
+ require 'rubygems'
+ require_gem 'ipadmin'
+ 
  puts "IPAdmin Methods"
  print "\n"
  
@@ -430,7 +519,4 @@
  puts "unshorten"
  puts "expanded notation for  fec0:: is #{IPAdmin.unshorten('fec0::')}"
 
- #=====================================#
- #
- #=====================================#
 

data/lib/cidr.rb

@@ -364,11 +364,11 @@ class CIDR
                 raise ArgumentError, "Expected Hash, but #{options.class} provided."
             end
             
-            if (options.has_key?(:Short))
+            if (options.has_key?(:Short) && options[:Short] == true)
                 short = true
             end
             
-            if (options.has_key?(:IP))
+            if (options.has_key?(:IP) && options[:IP] == true)
                 orig_ip = true
             end
         end
@@ -424,7 +424,7 @@ class CIDR
                 bitstep = options[:Bitstep]
             end
 
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
 
@@ -432,7 +432,7 @@ class CIDR
                 limit = options[:Limit]
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
         end
@@ -522,11 +522,11 @@ class CIDR
                                      "#{options.class} provided."
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
             
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
         end
@@ -563,7 +563,7 @@ class CIDR
 #   * String or CIDR object.
 #
 # - Notes:
-#   * The broadcast() method is liased to this method, and thus works for
+#   * The broadcast() method is aliased to this method, and thus works for
 #     IPv6 despite the fact that the IPv6 protocol does not support IP
 #     broadcasting.
 #
@@ -580,11 +580,11 @@ class CIDR
                                      "#{options.class} provided."
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
             
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
 
@@ -608,6 +608,69 @@ class CIDR
 #======================================#
 
 
+#==============================================================================#
+# multicast_mac()
+#==============================================================================#
+
+# Assuming this CIDR is a valid multicast address (224.0.0.0/4 for IPv4 
+# and ff00::/8 for IPv6), return its ethernet MAC address (EUI-48) mapping.
+#
+# - Arguments:
+#   * Optional hash with the following fields:
+#       - :Objectify -- if true, return EUI objects (optional)
+#
+# - Returns:
+#   * EUI object
+#
+# - Note:
+#   * MAC address is based on original IP address passed during initialization.
+#
+# Example:
+#   mcast = IPAdmin::CIDR.new(:CIDR => '224.0.0.6')
+#   puts mcast.multicast_mac.address --> 01-00-5e-00-00-06
+#
+    def multicast_mac(options=nil)
+        objectify = false
+        
+        if (options)
+            if (!options.kind_of? Hash)
+                raise ArgumentError, "Expected Hash, but #{options.class} provided."
+            end
+        
+            if (options.has_key?(:Objectify) && options[:Objectify] == true)
+                objectify = true
+            end
+        end
+        
+        if (@version == 4)
+            if (@ip & 0xf0000000 == 0xe0000000)
+                # map low order 23-bits of ip to 01:00:5e:00:00:00
+                mac = @ip & 0x007fffff | 0x01005e000000
+            else
+                raise "#{self.ip} is not a valid multicast address. IPv4 multicast " +
+                      "addresses should be in the range 224.0.0.0/4."
+            end
+        else
+            if (@ip & (0xff << 120) == 0xff << 120)
+                # map low order 32-bits of ip to 33:33:00:00:00:00
+                mac = @ip & (2**32-1) | 0x333300000000
+            else
+                raise "#{self.ip} is not a valid multicast address. IPv6 multicast " +
+                      "addresses should be in the range ff00::/8."
+            end             
+        end
+        
+        eui = IPAdmin::EUI.new(:PackedEUI => mac)
+        eui = eui.address if (!objectify)
+
+        return(eui)
+    end
+
+#======================================#
+#
+#======================================#
+
+
 #==============================================================================#
 # netmask()
 #==============================================================================#
@@ -691,11 +754,11 @@ class CIDR
                                      "#{options.class} provided."
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
             
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
         end
@@ -753,11 +816,11 @@ class CIDR
                 bitstep = options[:Bitstep]
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
         
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
         end
@@ -818,11 +881,11 @@ class CIDR
                 bitstep = options[:Bitstep]
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
         
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end
         end
@@ -883,11 +946,11 @@ class CIDR
         end
         index = options[:Index]
 
-        if( options.has_key?(:Short) )
+        if( options.has_key?(:Short) && options[:Short] == true )
             short = true
         end
         
-        if( options.has_key?(:Objectify) )
+        if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
         end
 
@@ -1057,11 +1120,11 @@ class CIDR
             raise ArgumentError, "Index #{indexes[1]} is out of bounds for this CIDR."
         end
         
-        if( options.has_key?(:Short) )
+        if( options.has_key?(:Short) && options[:Short] == true )
             short = true
         end
         
-        if( options.has_key?(:Objectify) )
+        if( options.has_key?(:Objectify) && options[:Objectify] == true )
             objectify = true
         end
         
@@ -1100,7 +1163,7 @@ class CIDR
 # Given a portion of the current CIDR, provide the remainder of
 # the CIDR. For example if the original CIDR is 192.168.0.0/24 and you
 # provide 192.168.0.64/26 as the portion to exclude, then 192.168.0.0/26,
-# 192.168.0.128/26, and 192.168.0.192/26 will be returned as the remainder.
+# and 192.168.0.128/25 will be returned as the remainder.
 #
 # - Arguments:
 #   * Optional hash with the following fields:
@@ -1134,11 +1197,11 @@ class CIDR
                                  "for option: Exclude."
         end
         
-        if( options.has_key?(:Short) )
+        if( options.has_key?(:Short) && options[:Short] == true )
             short = true
         end
         
-        if( options.has_key?(:Objectify) )
+        if( options.has_key?(:Objectify) && options[:Objectify] == true )
             objectify = true
         end
         
@@ -1321,7 +1384,7 @@ class CIDR
 # of specified size. If :MinCount is provided, then method will return at least 
 # that number of subnets (of size X) and the remainder of the new subnets
 # will be merged together as tightly as possible. If a size is not provided,
-# then the current object will be split in half.
+# then the current CIDR will be split in half.
 #
 # - Arguments:
 #   * Optional hash with the following fields:
@@ -1368,11 +1431,11 @@ class CIDR
                 min_count = options[:MinCount]
             end
             
-            if( options.has_key?(:Short) )
+            if( options.has_key?(:Short) && options[:Short] == true )
                 short = true
             end
         
-            if( options.has_key?(:Objectify) )
+            if( options.has_key?(:Objectify) && options[:Objectify] == true )
                 objectify = true
             end