Description

A simple Ruby interface to the 'ping' command.

Synopsis

require 'net/ping'
include Net

Ping::TCP.service_check = true

pt = Net::Ping::TCP.new(host)
pu = Net::Ping::UDP.new(host)
pe = Net::Ping::External.new(host)
ph = Net::Ping::HTTP.new(uri)

if pt.ping
   puts "TCP ping successful"
else
   puts "TCP ping unsuccessful: " +  pt.exception
end

if pu.ping
   puts "UDP ping successful"
else
   puts "UDP ping unsuccessful: " +  pu.exception
end

if pe.ping
   puts "External ping successful"
else
   puts "External ping unsuccessful: " +  pe.exception
end

if ph.ping?
   puts "HTTP ping successful"
else
   puts "HTTP ping unsuccessful: " + ph.exception
end

Ping Classes

* Ping::TCP
* Ping::UDP
* Ping::External
* Ping::HTTP
* Ping::ICMP
* Ping::WMI
* Ping::LDAP

All Ping classes are children of the Ping parent class (which should
never be instantiated directly).

The Ping::ICMP class requires root/administrative privileges.

The Ping::WMI class only works on MS Windows.

Net::Ping

Net::Ping.new(host=nil, port=7, timeout=5)

Creates and returns a new Ping object.  If the host is not specified
in the constructor then it must be specified in the ping method.

Net::Ping::TCP

Ping::TCP.service_check

Returns the setting for how ECONNREFUSED is handled. By default, this is
set to false, i.e. an ECONNREFUSED error is considered a failed ping.

Ping::TCP.service_check=(bool)

Sets the behavior for how ECONNREFUSED is handled. By default, this is
set to false, i.e. an ECONNREFUSED error is considered a failed ping.

Ping::TCP#ping(host=nil)

Attempts to open a connection using TCPSocket with a +host+ specified
either here or in the constructor.  A successful open means the ping was
successful and true is returned.  Otherwise, false is returned.

Net::Ping::UDP

Ping::UDP#ping

Attempts to open a connection using UDPSocket and sends the value of
Ping::UDP#data as a string across the socket.  If the return string matches,
then the ping was successful and true is returned.  Otherwise, false is
returned.

Ping::UDP#data

Returns the string that is sent across the UDP socket.

Ping::UDP#data=(string)

Sets the string that is sent across the UDP socket.  The default is "ping".
Note that the +string+ cannot be larger than MAX_DATA (64 characters).

Net::Ping::External

Ping::External#ping

Uses the 'open3' module and calls your system's local 'ping' command with
various options, depending on platform.  If nothing is sent to stderr, the
ping was successful and true is returned.  Otherwise, false is returned.

The MS Windows platform requires the 'win32-open3' package.

Ping::HTTP

Ping::HTTP.new(uri=nil, port=80, timeout=5)

Identical to Net::Ping.new except that, instead of a host, the first
argument is a URI.

Ping::HTTP#ping

Checks for a response against +uri+.  As long as kind of Net::HTTPSuccess
response is returned, the ping is successful and true is returned.
Otherwise, false is returned and Ping::HTTP#exception is set to the error
message.

Note that redirects are automatically followed unless the
Ping::HTTP#follow_redirects method is set to false.

Ping::HTTP#follow_redirect

Indicates whether or not a redirect should be followed in a ping attempt.
By default this is set to true.

Ping::HTTP#follow_redirect=(bool)

Sets whether or not a redirect should be followed in a ping attempt.  If
set to false, then any redirect is considered a failed ping.

Ping::HTTP#uri

An alias for Ping::HTTP#host.

Ping::HTTP#uri=(uri)

An alias for Ping::HTTP#host=.

Ping::ICMP

Ping::ICMP#duration

The time it took to ping the host.  Not a precise value but a good estimate.

Ping::WMI

Ping::WMI#ping(host, options={})

Unlike other Ping classes, this method returns a PingStatus struct that
contains various bits of information about the ping itself. The PingStatus
struct is a wrapper for the Win32_PingStatus WMI class.

In addition, you can pass options that will be interpreted as WQL parameters.

Ping::WMI#ping?(host, options={})

Returns whether or not the ping succeeded.

Common Instance Methods

Ping#exception

Returns the error string that was set if a ping call failed.  If an exception
is raised, it is caught and stored in this attribute.  It is not raised in
your code.

This should be nil if the ping succeeded.

Ping#host

Returns the host name that ping attempts will ping against.

Ping#host=(hostname)

Sets the host name that ping attempts will ping against.

Ping#port

Returns the port number that ping attempts will use.

Ping#port=(port)

Set the port number to open socket connections on.  The default is 7 (or
whatever your 'echo' port is set to).  Note that you can also specify a
string, such as "http".

Ping#timeout

Returns the amount of time before the timeout module raises a TimeoutError
during connection attempts.  The default is 5 seconds.

Ping#timeout=(time)

Sets the amount of time before the timeout module raises a TimeoutError.
during connection attempts.

Ping#warning

Returns a warning string that was returned during the ping attempt.  This
typically occurs only in the Ping::External class, or the Ping::HTTP class
if a redirect occurred.

Notes

If a host is down *IT IS CONSIDERED A FAILED PING*, and the 'no answer from
+host+' text is assigned to the 'exception' attribute.  You may disagree with
this behavior, in which case you need merely check the exception attribute
against a regex as a simple workaround.

Pre-emptive FAQ

Q: "Why don't you return exceptions if a connection fails?"

A: Because ping is only meant to return one of two things - success or
   failure. It's very simple. If you want to find out *why* the ping
   failed, you can check the 'exception' attribute.

Q: "I know the host is alive, but a TCP or UDP ping tells me otherwise. What
   gives?"

A: It's possible that the echo port has been disabled on the remote
   host for security reasons. Your best best is to specify a different port
   or to use Ping::ICMP or Ping::External instead.

   In the case of UDP pings, they are often actively refused. It may be
   more pragmatic to set Ping::UDP.service_check = false.

Q: "Why does a TCP ping return false when I know it should return true?"

A: By default ECONNREFUSED errors will return a value of false. This is
   contrary to what most other folks do for TCP pings. The problem with
   their philosophy is that you can get false positives if a firewall blocks
   the route to the host. The problem with my philosophy is that you can
   get false negatives if there is no firewall (or it's not blocking the
   route). Given the alternatives I chose the latter.

   You can always change the default behavior by using the +service_check+
   class method.

   A similar situation is true for UDP pings.

Q: "Couldn't you use traceroute information to tell for sure?"

A: I could but I won't so don't bug me about it. It's far more effort than
   it's worth. If you want something like that, please port the
   Net::Traceroute Perl module by Daniel Hagerty.

Known Bugs

You may see a test failure from the test_net_ping_tcp test case. You can
ignore these.

UDP pings may not work with older versions of Ruby 1.9.x.

Please report any bugs on the project page at
https://github.com/djberg96/net-ping

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

Artistic 2.0

Copyright

(C) 2003-2014 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