icmp4em 0.0.1

data/README

@@ -0,0 +1,78 @@
+icmp4em - ICMP ping using EventMachine
+
+http://www.github.com/yakischloba/icmp4em
+
+Asynchronous implementation of ICMP ping using EventMachine. Can be used to ping many hosts 
+at once in a non-blocking fashion, with callbacks for success, timeout, and host failure/recovery 
+based on specified threshold numbers. It was developed as a component for the purpose of monitoring 
+multiple WAN connections on a Linux gateway host, and altering the routing table accordingly, to 
+provide optimal routing and failover in a situation where only consumer-grade broadband is available.
+Should be useful in many situations. ICMPv6 is to be added soon.
+
+This must be run as effective root user to use the ICMP sockets.
+
+Installation:
+
+git clone git://github.com/yakischloba/icmp4em.git
+cd icmp4em
+gem build icmp4em.gemspec
+sudo gem install icmp4em-<version>.gem
+
+
+Simple example (see the examples/ directory for the cooler stuff):
+============================================================================
+require 'rubygems'
+require 'icmp4em'
+
+Signal.trap("INT") { EventMachine::stop_event_loop }
+
+host = ICMP4EM::ICMPv4.new("127.0.0.1")
+host.on_success {|host, seq, latency| puts "Got echo sequence number #{seq} from host #{host}. It took #{latency}ms." }
+host.on_expire {|host, seq, exception| puts "I shouldn't fail on loopback interface, but in case I did: #{exception.to_s}"}
+
+EM.run { host.schedule }
+=>
+Got echo sequence number 1 from host 127.0.0.1. It took 0.214ms.
+Got echo sequence number 2 from host 127.0.0.1. It took 0.193ms.
+Got echo sequence number 3 from host 127.0.0.1. It took 0.166ms.
+Got echo sequence number 4 from host 127.0.0.1. It took 0.172ms.
+Got echo sequence number 5 from host 127.0.0.1. It took 0.217ms.
+^C
+============================================================================
+
+Please let me know what is wrong with it!
+
+jakecdouglas@gmail.com
+yakischloba on Freenode
+
+
+Thanks to the #eventmachine guys for providing a great tool and always being such patient teachers.
+
+Thanks to imperator and the others that worked on the net-ping library. I used the packet construction and checksum
+code from that implementation. Here is the pertinent information from their README, so that nothing is missed:
+
+Acknowledgements from "net-ping-1.2.2/doc/ping.txt": 
+
+= Acknowledgements
+   The Ping::ICMP#ping method is based largely on the identical method from
+   the Net::Ping Perl module by Rob Brown. Much of the code was ported by
+   Jos Backus on ruby-talk.
+
+= Future Plans
+   Add support for syn pings.
+
+= License
+   Ruby's
+
+= Copyright
+   (C) 2003-2008 Daniel J. Berger, All Rights Reserved
+
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+= Author
+   Daniel J. Berger
+   djberg96 at gmail dot com
+   imperator on IRC (irc.freenode.net)

data/examples/simple_example.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'icmp4em'
+
+# This is an example of non-stateful usage. Only the callbacks provided in on_success and on_expire are used,
+# and the object does not keep track of up/down or execute callbacks on_failure/on_recovery.
+# The data string can be set to anything, as long as the total packet size is less than MTU of the network.
+
+pings = []
+pings << ICMP4EM::ICMPv4.new("google.com")
+pings << ICMP4EM::ICMPv4.new("slashdot.org")
+pings << ICMP4EM::ICMPv4.new("10.99.99.99") # host that will not respond.
+
+Signal.trap("INT") { EventMachine::stop_event_loop }
+
+EM.run {
+  pings.each do |ping| 
+    ping.data = "bar of foozz"
+    ping.on_success {|host, seq, latency| puts "SUCCESS from #{host}, sequence number #{seq}, Latency #{latency}ms"}
+    ping.on_expire {|host, seq, exception| puts "FAILURE from #{host}, sequence number #{seq}, Reason: #{exception.to_s}"}
+    ping.schedule
+  end
+}

data/examples/stateful_example.rb

@@ -0,0 +1,22 @@
+require 'rubygems'
+require 'icmp4em'
+
+# This example shows stateful usage, which tracks up/down state of the host based on consecutive number
+# of successful or failing pings specified in failures_required and recoveries_required. Hosts start in
+# 'up' state.
+
+pings = []
+pings << ICMP4EM::ICMPv4.new("google.com", :stateful => true)
+pings << ICMP4EM::ICMPv4.new("10.1.0.175", :stateful => true) # host that will not respond.
+
+Signal.trap("INT") { EventMachine::stop_event_loop }
+
+EM.run {
+  pings.each do |ping| 
+    ping.on_success {|host, seq, latency, count_to_recovery| puts "SUCCESS from #{host}, sequence number #{seq}, Latency #{latency}ms, Recovering in #{count_to_recovery} more"}
+    ping.on_expire {|host, seq, exception, count_to_failure| puts "FAILURE from #{host}, sequence number #{seq}, Reason: #{exception.to_s}, Failing in #{count_to_failure} more"}
+    ping.on_failure {|host| puts "HOST STATE WENT TO DOWN: #{host} at #{Time.now}"}
+    ping.on_recovery {|host| puts "HOST STATE WENT TO UP: #{host} at #{Time.now}"}
+    ping.schedule
+  end
+}

data/lib/icmp4em/common.rb

@@ -0,0 +1,141 @@
+module ICMP4EM
+
+  class Timeout < Exception; end;
+
+  module Common
+
+    ICMP_ECHOREPLY = 0
+    ICMP_ECHO      = 8
+    ICMP_SUBCODE   = 0
+
+    private
+
+    # Perform a checksum on the message.  This is the sum of all the short
+    # words and it folds the high order bits into the low order bits.
+    # (This method was stolen directly from net-ping - yaki)
+    def generate_checksum(msg)
+      length    = msg.length
+      num_short = length / 2
+      check     = 0
+
+      msg.unpack("n#{num_short}").each do |short|
+        check += short
+      end
+
+      if length % 2 > 0
+        check += msg[length-1, 1].unpack('C').first << 8
+      end
+
+      check = (check >> 16) + (check & 0xffff)
+      return (~((check >> 16) + check) & 0xffff)
+    end
+
+  end
+
+  module HostCommon
+
+    # Set failure callback. The provided Proc or block will be called and yielded the host and sequence number, whenever the failure count exceeds the defined threshold.
+    def on_failure(proc = nil, &block)
+      @failure = proc || block unless proc.nil? and block.nil?
+      @failure
+    end
+
+    # Set recovery callback. The provided Proc or block will be called and yielded the host and sequence number, whenever the recovery count exceeds the defined threshold.
+    def on_recovery(proc = nil, &block)
+      @recovery = proc || block unless proc.nil? and block.nil?
+      @recovery
+    end
+
+    # Set success callback. This will be called and yielded the host, sequence number, and latency every time a ping returns successfully.
+    def on_success(proc = nil, &block)
+      @success = proc || block unless proc.nil? and block.nil?
+      @success
+    end
+
+    # Set 'expiry' callback. This will be called and yielded the host, sequence number, and Exception every time a ping fails. 
+    # This is not just for timeouts! This can be triggered by failure of the ping for any reason.
+    def on_expire(proc = nil, &block)
+      @expiry = proc || block unless proc.nil? and block.nil?
+      @expiry
+    end
+
+    # Set the number of consecutive 'failure' pings required to switch host state to 'down' and trigger failure callback, assuming the host is up.
+    def failures_required=(failures)
+      @failures_required = failures
+    end
+    
+    # Set the number of consecutive 'recovery' pings required to switch host state to 'up' and trigger recovery callback, assuming the host is down.
+    def recoveries_required=(recoveries)
+      @recoveries_required = recoveries
+    end
+    
+    private
+
+    def success(seq, latency)      
+      if @success
+        if @stateful
+          count_to_recover = @up ? 0 : @recoveries_required - @failcount.abs
+          @success.call(@host, seq, latency, count_to_recover)
+        else
+          @success.call(@host, seq, latency)
+        end
+      end
+    end
+
+    def expiry(seq, reason)
+      if @expiry
+        if @stateful
+          count_to_fail = @up ? @failures_required - @failcount : 0
+          @expiry.call(@host, seq, reason, count_to_fail)
+        else
+          @expiry.call(@host, seq, reason)
+        end
+      end
+
+    end
+
+    # Executes specified failure callback, passing the host to the block.
+    def fail
+      @failure.call(@host) if @failure
+      @up = false
+    end
+
+    # Executes specified recovery callback, passing the host to the block.
+    def recover
+      @recovery.call(@host) if @recovery
+      @up = true
+    end
+
+    # Trigger failure/recovery if either threshold is exceeded...
+    def check_for_fail_or_recover
+      if @failcount > 0
+        fail if @failcount >= @failures_required && @up
+      elsif @failcount <= -1
+        recover if @failcount.abs >= @recoveries_required && !@up
+      end
+    end
+
+    # Adjusts the failure counter after each ping. The failure counter is incremented positively to count failures,
+    # and decremented into negative numbers to indicate successful pings towards recovery after a failure.
+    # This is an awful mess..just like the rest of this file.
+    def adjust_failure_count(direction)
+      if direction == :down
+        if @failcount > -1 
+          @failcount += 1
+        elsif @failcount <= -1 
+          @failcount = 1
+        end
+      elsif direction == :up && !@up
+        if @failcount > 0
+          @failcount = -1
+        elsif @failcount <= -1
+          @failcount -= 1
+        end
+      else
+        @failcount = 0
+      end
+    end
+
+  end
+
+end

data/lib/icmp4em/handler.rb

@@ -0,0 +1,53 @@
+module ICMP4EM
+
+  module Handler
+    
+    include Common
+
+    def initialize(socket)
+      @socket = socket
+    end
+
+    def notify_readable
+      receive(@socket)
+    end
+    
+    def unbind
+      @socket.close if @socket
+    end
+    
+    private
+
+    def receive(socket)
+      # The data was available now
+      time = Time.now
+      # Get data
+      host, data = read_socket(socket)
+      # Rebuild message array
+      msg = data[20,30].unpack("C2 n3 A*")
+      # Verify the packet type is echo reply and verify integrity against the checksum it provided
+      return unless msg.first == ICMP_ECHOREPLY && verify_checksum?(msg)
+      # Find which object it is supposed to go to
+      recipient = ICMPv4.instances[msg[3]]
+      # Send time and seq number to recipient object
+      recipient.send(:receive, msg[4], time) unless recipient.nil?
+    end
+
+    def read_socket(socket)
+      # Recieve a common MTU, 1500 bytes.
+      data, sender = socket.recvfrom(1500)
+      # Get the host in case we want to use that later.
+      host = Socket.unpack_sockaddr_in(sender).last
+      [host, data]
+    end
+    
+    def verify_checksum?(ary)
+      cs = ary[2]
+      ary_copy = ary.dup
+      ary_copy[2] = 0
+      cs == generate_checksum(ary_copy.pack("C2 n3 A*"))
+    end
+
+  end
+
+end

data/lib/icmp4em/icmpv4.rb

@@ -0,0 +1,150 @@
+module ICMP4EM
+
+  class ICMPv4
+
+    include Common
+    include HostCommon
+    
+    @instances = {}
+    @recvsocket = nil
+    
+    class << self
+      
+      attr_reader :instances
+      attr_accessor :recvsocket
+      
+    end
+    
+    attr_accessor :bind_host, :interval, :threshold, :timeout, :data
+    attr_reader :id, :failures_required, :recoveries_required, :seq
+
+    # Create a new ICMP object (host). Must be passed either IP address or hostname, and 
+    # optionally the interval at which it should be pinged, and timeout for the pings, in seconds.
+    def initialize(host, options = {})
+      raise 'requires root privileges' if Process.euid > 0
+      @host = host
+      @ipv4_sockaddr = Socket.pack_sockaddr_in(0, @host)
+      @interval   =   options[:interval] || 1
+      @timeout    =   options[:timeout] || 1
+      @stateful   =   options[:stateful] || false
+      @bind_host  =   options[:bind_host] || nil
+      @recoveries_required = options[:recoveries_required] || 5
+      @failures_required   = options[:failures_required] || 5
+      @up = true
+      @waiting = {}
+      set_id
+      @seq, @failcount = 0, 0
+      @data = "Ping from EventMachine"
+    end
+    
+    # This must be called when the object will no longer be used, to remove 
+    # the object from the class variable array that is searched for recipients when
+    # an ICMP echo comes in. Better way to do this whole thing?...
+    def destroy
+      self.class.instances[@id] = nil
+    end
+
+    # Send the echo request to @host and add sequence number to the waiting queue.
+    def ping
+      raise "EM not running" unless EM.reactor_running?
+      init_handler if self.class.recvsocket.nil?
+      seq = ping_send
+      EM.add_timer(@timeout) { self.send(:expire, seq, Timeout.new("Ping timed out")) } unless @timeout == 0
+      @seq
+    end
+
+    # Uses EM.add_periodic_timer to ping the host at @interval.
+    def schedule
+      raise "EM not running" unless EM.reactor_running?
+      EM.add_periodic_timer(@interval) { self.ping }
+    end
+
+    private
+
+    # Expire a sequence number from the waiting queue.
+    # Should only be called by the timer setup in #ping or the rescue Exception in #ping_send.
+    def expire(seq, exception = nil)
+      waiting = @waiting[seq]
+      if waiting
+        @waiting[seq] = nil
+        adjust_failure_count(:down) if @stateful
+        expiry(seq, exception)
+        check_for_fail_or_recover if @stateful
+      end
+    end
+
+    # Should only be called by the Handler. Passes the receive time and sequence number.
+    def receive(seq, time)
+      waiting = @waiting[seq]
+      if waiting
+        latency = (time - waiting) * 1000
+        adjust_failure_count(:up) if @stateful
+        success(seq, latency)
+        check_for_fail_or_recover if @stateful
+        @waiting[seq] = nil
+      end
+    end
+
+    # Construct and send the ICMP echo request packet.
+    def ping_send
+      @seq = (@seq + 1) % 65536
+
+      socket = Socket.new(
+      Socket::PF_INET,
+      Socket::SOCK_RAW,
+      Socket::IPPROTO_ICMP
+      )
+
+      if @bind_host
+        saddr = Socket.pack_sockaddr_in(0, @bind_host)
+        socket.bind(saddr)
+      end
+
+      # Generate msg with checksum
+      msg = [ICMP_ECHO, ICMP_SUBCODE, 0, @id, @seq, @data].pack("C2 n3 A*")
+      msg[2..3] = [generate_checksum(msg)].pack('n')
+      
+      # Enqueue
+      @waiting[seq] = Time.now
+      
+      begin
+        # Fire it off
+        socket.send(msg, 0, @ipv4_sockaddr)
+        # Return sequence number to caller
+        @seq
+      rescue Exception => err
+        expire(@seq, err)
+      ensure
+        socket.close if socket
+      end
+    end
+
+    # Initialize the receiving socket and handler for incoming ICMP packets.
+    def init_handler
+      self.class.recvsocket = Socket.new(
+      Socket::PF_INET,
+      Socket::SOCK_RAW,
+      Socket::IPPROTO_ICMP
+      )
+      if @bind_host
+        saddr = Socket.pack_sockaddr_in(0, @bind_host)
+        self.class.recvsocket.bind(saddr)
+      end
+      EM.attach self.class.recvsocket, Handler, self.class.recvsocket
+    end
+
+    # Sets the instance id to a unique 16 bit integer so it can fit inside relevent the ICMP field.
+    # Also adds self to the pool so that incoming messages that it requested can be delivered.
+    def set_id
+      while @id.nil?
+        id = rand(65535)
+        unless self.class.instances[id]
+          @id = id
+          self.class.instances[@id] = self
+        end
+      end
+    end
+
+  end
+  
+end

data/lib/icmp4em.rb

@@ -0,0 +1,6 @@
+$:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
+require 'eventmachine'
+require 'socket'
+require 'icmp4em/common'
+require 'icmp4em/handler'
+require 'icmp4em/icmpv4'

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification 
+name: icmp4em
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Jake Douglas
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-01-12 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: eventmachine
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: Asynchronous implementation of ICMP ping using EventMachine. Can be used to ping many hosts  at once in a non-blocking fashion, with callbacks for success, timeout, and host failure/recovery  based on specified threshold numbers.
+email: jakecdouglas@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README
+- examples/simple_example.rb
+- examples/stateful_example.rb
+- lib/icmp4em.rb
+- lib/icmp4em/common.rb
+- lib/icmp4em/handler.rb
+- lib/icmp4em/icmpv4.rb
+has_rdoc: false
+homepage: http://www.github.com/yakischloba/icmp4em
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: icmp4em
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Asynchronous implementation of ICMP ping using EventMachine
+test_files: []
+