| Path: | ping.txt |
| Last Update: | Sun Jul 17 15:37:22 Mountain Daylight Time 2005 |
A simple Ruby interface to the 'ping' command.
require "net/ping"
include Net
PingTCP.econnrefused = true
pt = Net::PingTCP.new(host)
pu = Net::PingUDP.new(host)
pe = Net::PingExternal.new(host)
ph = Net::PingHTTP.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
* PingTCP * PingUDP * PingExternal * PingHTTP All Ping classes are children of the Ping parent class (which should never be instantiated directly).
PingTCP.new(host, port=7, timeout=5)
Creates and returns a new PingTCP object.
PingTCP.econnrefused
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.
PingTCP.econnrefused=(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.
PingTCP#ping PingTCP#ping?
Attempts to open a connection using TCPSocket. A successful open means
the ping was successful and true is returned. Otherwise, false is returned.
PingUDP.new(host, port=7, timeout=5)
Creates and returns a new PingUDP object.
PingUDP#ping PingUDP#ping?
Attempts to open a connection using UDPSocket and sends the value of
PingUDP#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.
PingUDP#data
Returns the string that is sent across the UDP socket.
PingUDP#data=(string)
Sets the string that is sent across the UDP socket. The default is "ping"
PingExternal.new(host, port=7, timeout=5)
Creates and returns a new PingExternal object.
PingExternal#ping PingExternal#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.
PingHTTP.new(uri, port=80, timeout=5)
Creates and returns a new PingHTTP object.
PingHTTP#ping PingHTTP#ping?
Checks for a response against +uri+. As long as a Net::HTTPSuccess or
Net::HTTPOK response is returned, the ping is successful and true is
returned. Otherwise, false is returned and PingHTTP#exception is set to
the error message.
PingHTTP#uri
An alias for PingHTTP#host.
PingHTTP#uri=(uri)
An alias for PingHTTP#host=.
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 PingExternal class.
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.
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 PingExternal instead.
Q: "Why does 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 philosphy 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 +econnrefused+
class method.
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.
You may see a test failure from the tc_pingtcp test case. You can ignore this. Please report any bugs on the project page at http://www.rubyforge.org/projects/shards.
Add an PingICMP class (help wanted) (Though see arton's icmpping package on the RAA)
Ruby's
(C) 2003-2005 Daniel J. Berger, All Rights Reserved
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.
Daniel J. Berger djberg96 at yahoo dot com imperator on IRC (irc.freenode.net)