icmp4em 0.0.2 → 1.0.0

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in icmp4em.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,28 @@
+PATH
+  remote: .
+  specs:
+    icmp4em (1.0.0)
+      eventmachine (>= 1.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.2.4)
+    eventmachine (1.0.3)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.1)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.1)
+    yard (0.8.6.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  icmp4em!
+  rspec
+  yard

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Norman Elton
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,82 @@
+= ICMP Library for EventMachine
+
+== Summary
+
+This gem allows you to send ICMP echo requests and handle ICMP echo replies.
+
+
+== Features
+
+Version 0.2.0 supports:
+
+* Sending and receiving ICMP echo requests / replies
+* A configurable timeout / retry count
+* A separate proxy process that, running as root, can send ICMP packets on behalf of other non-root processes. See below.
+
+Future revisions of this library will support:
+
+* Ruby fibers
+
+
+== Simple Example
+
+  EM.run {
+    manager = ICMP4EM::Manager.new
+  
+    request = manager.ping "8.8.8.8"
+
+    request.callback { puts "SUCCESS" }
+    request.errback { |e| puts "FAILURE, got error #{e}" }
+  }
+
+
+== ICMP Proxy
+
+Typically, sending ICMP packets requires a process to have root privileges. This is often less than ideal. Work arounds are also less than wonderful, often involving sending a TCP or UDP packet in the hopes of receiving a response.
+
+This library supports the notion of an ICMP proxy via the included +icmp-proxy+ script. Running as root, it accepts UDP requests from non-root processes to handle the sending of ICMP packets.
+
+With the +icmp-proxy+ running on the local host, it's trivial to configure:
+
+  manager = ICMP4EM::Manager.new(:proxy => true)
+
+*Note* - The +icmp-proxy+ must run as root, and accepts incoming connections. By default, it binds to the localhost and will not accept connections from other hosts. This is configurable (run the proxy with +--help+ to see options). While it is possible to accept requests from other hosts, any root-owned process accepting packets from the Internet is an inherent security risk. Help improve the proxy by familiarizing yourself with its code before trusting it to the Internet.
+
+
+== Running tests
+
+A simple rspec test is included.
+
+
+== Configuration parameters
+
+The following parameters may be passed to the ICMP4EM::Manager constructor (to affect all pings) or as arguments following the IP address when pinging an individual host:
+
+* *timeout* - Number of seconds to wait for a response
+* *retries* - Number of retries before eventually failing
+
+The following parameter may be passed to the ICMP4EM::Manager constructor to enable use of the ICMP proxy (see above):
+
+* *proxy* - Set to <tt>true</tt> to use a proxy on the localhost, or <tt>host:port</tt> to use a proxy on another host.
+
+
+== Acknowledgements
+
+* The previous library, https://github.com/jakedouglas/icmp4em
+* EventMachine[http://rubyeventmachine.com], by Francis Cianfrocca and Aman Gupta
+* All the helpful folks on the Freenode #eventmachine channel
+
+
+== Change Log
+
+Version 0.2.0:
+
+* ICMP proxy support
+
+Version 0.1.0:
+
+* First import
+
+== Credits
+
+Author: Norman Elton  mailto:normelton@gmail.com

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/icmp-proxy

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+
+require "icmp4em"
+require "optparse"
+require "pp"
+
+options = {:bind_host => "127.0.0.1", :bind_port => 63312}
+
+OptionParser.new do |opts|
+  opts.on("-d", "--debug", "Debug mode") do |v|
+    $debug = true
+  end
+
+  opts.on("-h", "--host [HOST]", "Bind to a specific host") do |v|
+    options[:bind_host] = v
+  end
+
+  opts.on("-p", "--port [PORT]", "Bind to a specific port") do |v|
+    options[:bind_port] = v.to_i
+  end
+end.parse!
+
+EventMachine.run do
+  @pending_requests = {}
+  @icmp_socket = Socket.new(Socket::PF_INET, Socket::SOCK_RAW, Socket::IPPROTO_ICMP)
+
+  EventMachine.watch(@icmp_socket, ICMP4EM::Proxy::IcmpHandler, :pending_requests => @pending_requests) {|c| c.notify_readable = true}
+
+  @udp_socket = EventMachine::open_datagram_socket(options[:bind_host], options[:bind_port], ICMP4EM::Proxy::UdpHandler, :pending_requests => @pending_requests, :icmp_socket => @icmp_socket)
+end

data/lib/icmp4em.rb

@@ -1,6 +1,16 @@
-$:.unshift File.expand_path(File.dirname(File.expand_path(__FILE__)))
-require 'eventmachine'
-require 'socket'
-require 'icmp4em/common'
-require 'icmp4em/handler'
-require 'icmp4em/icmpv4'
+require "eventmachine"
+
+require "icmp4em/version"
+require "icmp4em/manager"
+require "icmp4em/udp_handler"
+require "icmp4em/icmp_handler"
+require "icmp4em/packet"
+require "icmp4em/request"
+require "icmp4em/timeout"
+
+require "icmp4em/proxy/udp_handler"
+require "icmp4em/proxy/icmp_handler"
+require "icmp4em/proxy/request"
+
+module ICMP4EM
+end

data/lib/icmp4em/icmp_handler.rb

@@ -0,0 +1,21 @@
+module ICMP4EM
+  module IcmpHandler
+    def initialize args = {}
+      @manager = args[:manager]
+    end
+
+    def notify_readable
+      data, host = @io.recvfrom(1500)
+      icmp_data = data[20, data.length]
+      
+      begin
+        @manager.handle_reply Packet.from_bytes(icmp_data)
+      rescue ArgumentError
+      end
+    end
+
+    def unbind
+      @socket.close if @socket
+    end
+  end
+end

data/lib/icmp4em/manager.rb

@@ -0,0 +1,102 @@
+module ICMP4EM
+  class Manager
+    # The first 16 bits of the header data is unique to this particular ping process
+    MAX_IDENTIFIER = 2**16 - 1
+
+    # We use the next 12 bits as the request identifier, regardless of the retry ...
+    MAX_SEQUENCE = 2**12 - 1
+
+    # ... and the remaining 4 bits to identify the retry
+    MAX_RETRIES = 2**4 - 1
+
+    @pending_requests = {}
+    @socket = nil
+
+    attr_accessor :id
+    attr_accessor :socket
+    attr_accessor :timeout
+    attr_accessor :retries
+
+    def initialize args = {}
+      @timeout = args[:timeout] || 1
+      @retries = args[:retries] || 3
+      @id = rand(MAX_IDENTIFIER)
+      @pending_requests = {}
+      @next_request_id = 0
+
+      if args[:proxy]
+        if args[:proxy].is_a?(String)
+          proxy_host = args[:proxy].split(":")[0]
+          proxy_port = args[:proxy].split(":")[1] || 63312
+          @proxy_addr = Socket.pack_sockaddr_in(proxy_port, proxy_host)
+        else
+          @proxy_addr = Socket.pack_sockaddr_in(63312, "127.0.0.1")
+        end
+
+        @socket = Socket.new(Socket::PF_INET, Socket::SOCK_DGRAM)
+        EventMachine.watch(@socket, UdpHandler, :manager => self) {|c| c.notify_readable = true}
+
+      else
+        @socket = Socket.new(Socket::PF_INET, Socket::SOCK_RAW, Socket::IPPROTO_ICMP)
+        EventMachine.watch(@socket, IcmpHandler, :manager => self) {|c| c.notify_readable = true}
+      end
+    end
+
+    def proxy_enabled?
+      @proxy_addr
+    end
+
+    def ping host, args = {}
+      while @pending_requests.include?(@next_request_id)
+        @next_request_id += 1
+        @next_request_id %= MAX_SEQUENCE
+      end
+
+      request = Request.new args.merge(:host => host, :manager => self, :id => @next_request_id)
+
+      @pending_requests[request.id] = request
+
+      request.callback do
+        @pending_requests.delete request.id
+      end
+
+      request.errback do
+        @pending_requests.delete request.id
+      end
+
+      request.send
+      
+      request
+    end
+
+    def handle_reply reply
+      return unless reply.valid_checksum?
+      return unless reply.is_reply?
+
+      request = @pending_requests.delete(reply.request_id)
+      return if request.nil?
+
+      request.succeed
+    end
+
+    def send_packet args = {}
+      begin
+        if proxy_enabled?
+          proxy_request = ICMP4EM::Proxy::Request.new
+          proxy_request.dest_ip = args[:to]
+          proxy_request.packet = args[:packet]
+
+          @socket.send proxy_request.to_bytes, 0, @proxy_addr
+
+        else
+          sock_addr = Socket.pack_sockaddr_in(0, args[:to])
+          @socket.send args[:packet].to_bytes, 0, sock_addr
+        end
+      rescue
+        puts "Got exception #{$!}"
+        fail $!
+      end
+
+    end
+  end
+end

data/lib/icmp4em/packet.rb

@@ -0,0 +1,106 @@
+module ICMP4EM
+  class Packet
+    ICMP_CODE           = 0
+    ICMP_ECHO_REQUEST   = 8
+    ICMP_ECHO_REPLY     = 0
+
+    attr_accessor :type
+    attr_accessor :code
+    attr_accessor :checksum
+    attr_accessor :manager_id
+    attr_accessor :request_id
+    attr_accessor :retry_id
+    attr_accessor :payload
+
+    def self.from_bytes data
+      raise ArgumentError, "Must provide at least eight bytes in order to craft an ICMP packet" unless data.length >= 8
+
+      packet = Packet.new
+      fields = data.unpack("C2 n3 A*")
+
+      packet.type = fields.shift
+      packet.code = fields.shift
+      packet.checksum = fields.shift
+      packet.manager_id = fields.shift
+
+      sequence = fields.shift
+      packet.request_id = sequence >> 4
+      packet.retry_id = sequence & (2**4 - 1)
+
+      packet.payload = fields.shift
+
+      packet
+    end
+
+    def initialize args = {}
+      @type         = args[:type] || ICMP_ECHO_REQUEST
+      @code         = args[:code] || ICMP_CODE
+      @manager_id   = args[:manager_id]
+      @request_id   = args[:request_id]
+      @retry_id     = args[:retry_id]
+
+      if args[:payload].nil?
+        @payload = ""
+      elsif args[:payload].is_a? Integer
+        @payload = "A" * args[:payload]
+      else
+        @payload = args[:payload]
+      end
+    end
+
+    def is_request?
+      @type == ICMP_ECHO_REQUEST
+    end
+
+    def is_reply?
+      @type == ICMP_ECHO_REPLY
+    end
+
+    def valid_checksum?
+      @checksum == compute_checksum
+    end
+
+    def to_bytes
+      [@type, @code, compute_checksum, @manager_id, sequence, @payload].pack("C2 n3 A*")
+    end
+
+    def sequence
+      (@request_id << 4) + @retry_id
+    end
+
+    def key
+      [@manager_id, sequence].pack("n2")
+    end
+
+    def key_string
+      key.unpack("H*").first
+    end
+
+    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 the old icmp4em - normelton
+    # ... which was stolen directly from net-ping - yaki
+
+    def compute_checksum
+      msg = [@type, @code, 0, @manager_id, sequence, @payload].pack("C2 n3 A*")
+
+      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
+end

data/lib/icmp4em/proxy/icmp_handler.rb

@@ -0,0 +1,43 @@
+module ICMP4EM
+  module Proxy
+    module IcmpHandler
+      def initialize args = {}
+        @pending_requests = args[:pending_requests]
+      end
+
+      def log msg
+        puts "[#{Time.now}] #{msg}" if $debug
+      end
+
+      def notify_readable
+        data, host = @io.recvfrom(1500)
+        icmp_data = data[20, data.length]
+        
+        log "Received ICMP response from #{host.ip_address}"
+
+        begin
+          packet = Packet.from_bytes(icmp_data)
+        rescue ArgumentError
+          log "  Got exception while parsing packet: #{$!}"
+          return
+        end
+
+        log "  Key = #{packet.key_string}"
+
+        request = @pending_requests.delete(packet.key)
+
+        if request.nil?
+          log "  Unexpected packet, dropping"
+          return
+        end
+
+        request.succeed packet
+      end
+
+      def unbind
+        @socket.close if @socket
+      end
+      
+    end
+  end
+end

data/lib/icmp4em/proxy/request.rb

@@ -0,0 +1,46 @@
+module ICMP4EM
+  module Proxy
+    class Request
+      include EM::Deferrable
+
+      attr_accessor :source_ip
+      attr_accessor :source_port
+      attr_accessor :dest_ip
+      attr_accessor :packet
+
+      def self.from_bytes args = {}
+        request = Request.new
+
+        data = args[:data]
+        address_length = data.unpack("n").first
+
+        request.source_ip = args[:source_ip]
+        request.source_port = args[:source_port]
+        request.dest_ip = data[2,address_length]
+        request.packet = Packet.from_bytes data[address_length + 2, data.length]
+
+        request
+      end
+
+      def initialize args = {}
+      end
+
+      def to_bytes
+        [@dest_ip.length].pack("n") + @dest_ip + @packet.to_bytes
+      end
+
+      def key
+        @packet.key
+      end
+
+      def key_string
+        key.unpack("H*").first
+      end
+
+      def send args = {}
+        sock_addr = Socket.pack_sockaddr_in(0, @dest_ip)
+        args[:socket].send @packet.to_bytes, 0, sock_addr
+      end
+    end
+  end
+end

data/lib/icmp4em/proxy/udp_handler.rb

@@ -0,0 +1,60 @@
+module ICMP4EM
+  module Proxy
+    module UdpHandler
+      def initialize args
+        @icmp_socket      = args[:icmp_socket]
+        @pending_requests = args[:pending_requests]
+
+        log "Listening for incoming requests"
+      end
+
+      def log msg
+        puts "[#{Time.now}] #{msg}" if $debug
+      end
+
+      def receive_data data
+        source_port, source_ip = Socket.unpack_sockaddr_in(get_peername)
+
+        log "Received incoming request from #{source_ip}:#{source_port}"
+
+        begin
+          request = Request.from_bytes :source_ip => source_ip, :source_port => source_port, :data => data
+        rescue ArgumentError
+          log "  Received error - #{$!}"
+          return
+        end
+
+        unless request.packet.is_request?
+          log "  Incoming packet is not an ICMP request"
+          return
+        end
+
+        log "  Key = #{request.key_string}"
+        log "  Sending to #{request.dest_ip}"
+
+        begin
+          request.send :socket => @icmp_socket
+        rescue
+          log "  Got exception while sending packet #{request.dest_ip} #{$!}"
+          return
+        end
+
+        request.timeout(30)
+
+        request.callback do |packet|
+          log "  Got reply for request #{request.key_string}"
+          log "  Sending reply back to #{source_ip}:#{source_port}"
+          send_datagram packet.to_bytes, source_ip, source_port
+          @pending_requests.delete request.key
+        end
+
+        request.errback do
+          log "Request #{request.key_string} has timed out"
+          @pending_requests.delete request.key
+        end
+
+        @pending_requests[request.key] = request
+      end
+    end
+  end
+end

data/lib/icmp4em/request.rb

@@ -0,0 +1,42 @@
+module ICMP4EM
+  class Request
+    include EM::Deferrable
+
+    attr_reader :id
+
+    def initialize args = {}
+      @host         = args[:host]
+      @manager      = args[:manager]
+      @id           = args[:id]
+      @max_retries  = args[:retries] || @manager.retries
+      @timeout      = args[:timeout] || @manager.timeout
+
+      @retry_id = 0
+      @timeout_timer = nil
+
+      callback do
+        @timeout_timer.cancel
+      end
+      
+      errback do
+        @timeout_timer.cancel
+      end      
+    end
+
+    def send
+      @timeout_timer.cancel if @timeout_timer.is_a?(EventMachine::Timer)
+
+      @timeout_timer = EventMachine::Timer.new(@timeout) do
+        if @max_retries > @retry_id
+          send
+          @retry_id += 1
+        else
+          fail Timeout.new
+        end
+      end
+
+      packet = Packet.new(:type => Packet::ICMP_ECHO_REQUEST, :manager_id => @manager.id, :request_id => @id, :retry_id => @retry_id)
+      @manager.send_packet :packet => packet, :to => @host
+    end
+  end
+end

data/lib/icmp4em/timeout.rb

@@ -0,0 +1,4 @@
+module ICMP4EM
+  class Timeout < Exception
+  end
+end

data/lib/icmp4em/udp_handler.rb

@@ -0,0 +1,20 @@
+module ICMP4EM
+  module UdpHandler
+    def initialize args = {}
+      @manager = args[:manager]
+    end
+
+    def notify_readable
+      data, host = @io.recvfrom(1500)
+      
+      begin
+        @manager.handle_reply Packet.from_bytes(data)
+      rescue ArgumentError
+      end
+    end
+
+    def unbind
+      @socket.close if @socket
+    end
+  end
+end

data/lib/icmp4em/version.rb

@@ -0,0 +1,3 @@
+module ICMP4EM
+  VERSION = "1.0.0"
+end

metadata

@@ -1,68 +1,113 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: icmp4em
-version: !ruby/object:Gem::Version 
-  version: 0.0.2
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
 platform: ruby
-authors: 
-- Jake Douglas
+authors:
+- Norman Elton
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2009-04-03 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2013-06-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: eventmachine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
   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: []
-
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A high-performance ICMP engine build on EventMachine
+email:
+- normelton@gmail.com
+executables:
+- icmp-proxy
 extensions: []
-
-extra_rdoc_files: []
-
-files: 
-- README
-- examples/simple_example.rb
-- examples/stateful_example.rb
+extra_rdoc_files:
+- README.rdoc
+files:
+- lib/icmp4em/icmp_handler.rb
+- lib/icmp4em/manager.rb
+- lib/icmp4em/packet.rb
+- lib/icmp4em/proxy/icmp_handler.rb
+- lib/icmp4em/proxy/request.rb
+- lib/icmp4em/proxy/udp_handler.rb
+- lib/icmp4em/request.rb
+- lib/icmp4em/timeout.rb
+- lib/icmp4em/udp_handler.rb
+- lib/icmp4em/version.rb
 - lib/icmp4em.rb
-- lib/icmp4em/common.rb
-- lib/icmp4em/handler.rb
-- lib/icmp4em/icmpv4.rb
-has_rdoc: true
-homepage: http://www.github.com/yakischloba/icmp4em
+- bin/icmp-proxy
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- Rakefile
+- README.rdoc
+homepage: ''
+licenses: []
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+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: 
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
-rubyforge_project: icmp4em
-rubygems_version: 1.3.1
+rubyforge_project: 
+rubygems_version: 1.8.25
 signing_key: 
-specification_version: 2
-summary: Asynchronous implementation of ICMP ping using EventMachine
+specification_version: 3
+summary: A high-performance ICMP engine build on EventMachine
 test_files: []
-
+has_rdoc: 

data/README

@@ -1,60 +0,0 @@
-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 (or 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. Still planning on adding ICMPv6 sometime..
-
-Should work fine with Ruby 1.9.1.
-
-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
-============================================================================
-
-One issue may run into is that when using this with a lot of hosts, or using EventMachine for other things, 
-extra apparent latency will be added. This is simply due to other operations blocking the receipt of the ICMP 
-response. For when accurate latency measurement is important, and you can afford to block the reactor, I have 
-added a blocking receive mode. To use this simply pass :block => true to the constructor. This will wait for 
-the response for the duration of the timeout before passing control back to EventMachine.
-
-
-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. See their README for detailed acknowledgements.

data/examples/simple_example.rb

@@ -1,22 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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

@@ -1,140 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,173 +0,0 @@
-module ICMP4EM
-
-  class ICMPv4
-
-    include Common
-    include HostCommon
-    
-    @instances = {}
-    @recvsocket = nil
-    
-    class << self
-      
-      attr_reader :instances
-      attr_accessor :recvsocket, :handler
-      
-    end
-    
-    attr_accessor :bind_host, :interval, :threshold, :timeout, :data, :block
-    attr_reader :id, :failures_required, :recoveries_required, :seq
-
-    # Create a new ICMP object (host). This takes a host and an optional hash of options for modifying the behavior. They are:
-    # * :bind_host
-    # Bind the socket to this address. The operating system will figure this out on it's own unless you need to set it for a special situation.
-    # * :timeout
-    # Timeout, in seconds, before the ping is considered expired and the appropriate callbacks are executed. This should be a numeric class.
-    # * :block
-    # True or false, default is false. True enables a blocking receive mode, for when accurate latency measurement is important. Due to the nature
-    # of event loop architecture, a noticable delay in latency can be added when other things are going on in the reactor.
-    # * :interval
-    # Interval, in seconds, for how often the ping should be sent. Should be a numeric class.
-    # * :stateful
-    # True or false, default is false. Indicates whether or not this ping object should keep track of it's successes and failures and execute
-    # the on_failure/on_recovery callbacks when the specified limits are hit.
-    # * :failures_required
-    # Indicates how many consequtive failures are required to switch to the 'failed' state and execute the on_failure callback. Applies only when :stateful => true
-    # * :recoveries_required
-    # Indicates how many consequtive successes are required to switch to the 'recovered' state and execute the on_recovery callback. Applies only when :stateful => true
-    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
-      @block      =   options[:block] || false
-      @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 hash that is searched for recipients when
-    # an ICMP echo comes in. Also cancels the periodic timer. Better way to do this whole thing?...
-    def stop
-      @ptimer.cancel if @ptimer
-      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
-      if @block
-        blocking_receive
-      else
-        EM.add_timer(@timeout) { self.send(:expire, @seq, Timeout.new("Ping timed out")) } unless @timeout == 0
-      end
-      @seq
-    end
-
-    # Uses a periodic timer to ping the host at @interval.
-    def schedule
-      raise "EM not running" unless EM.reactor_running?
-      @ptimer = EM::PeriodicTimer.new(@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 = self.class.recvsocket
-
-      # 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 so we can expire properly if there is an exception raised during #send
-      @waiting[seq] = Time.now
-      
-      begin
-        # Fire it off
-        socket.send(msg, 0, @ipv4_sockaddr)
-        # Re-enqueue AFTER sendto() returns. This ensures we aren't adding latency if the socket blocks.
-        @waiting[seq] = Time.now
-        # Return sequence number to caller
-        seq
-      rescue Exception => err
-        expire(seq, err)
-        seq
-      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
-      self.class.handler = 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
-    
-    def blocking_receive
-      r = select([self.class.recvsocket], nil, nil, @timeout)
-      
-      if r and r.first.include?(self.class.recvsocket)
-        self.class.handler.notify_readable
-      else
-        expire(@seq, Timeout.new("Ping timed out"))
-      end
-    end
-
-  end
-  
-end