ICMP Library for EventMachine¶ ↑

Summary¶ ↑

This gem allows you to send ICMP echo requests and handle ICMP echo replies.

Note - This library was inspired by github.com/jakedouglas/icmp4em, and the gem shares the same name. While most of the functionality was copied forward, the two libraries are not 100% compatible. If upgrading from the old (0.0.2) to the new (1.0.0+), be sure to read the documentation and test thoroughly.

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 true to use a proxy on the localhost, or host:port to use a proxy on another host.

Acknowledgements¶ ↑

• The previous library, github.com/jakedouglas/icmp4em

• EventMachine, 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 [email protected]