| 1 | NAME |
| 2 | Net::Ping - check a remote host for reachability |
| 3 | |
| 4 | $Id: Ping.pm,v 1.6 2002/06/19 15:23:48 rob Exp $ |
| 5 | |
| 6 | SYNOPSIS |
| 7 | use Net::Ping; |
| 8 | |
| 9 | $p = Net::Ping->new(); |
| 10 | print "$host is alive.\n" if $p->ping($host); |
| 11 | $p->close(); |
| 12 | |
| 13 | $p = Net::Ping->new("icmp"); |
| 14 | $p->bind($my_addr); # Specify source interface of pings |
| 15 | foreach $host (@host_array) |
| 16 | { |
| 17 | print "$host is "; |
| 18 | print "NOT " unless $p->ping($host, 2); |
| 19 | print "reachable.\n"; |
| 20 | sleep(1); |
| 21 | } |
| 22 | $p->close(); |
| 23 | |
| 24 | $p = Net::Ping->new("tcp", 2); |
| 25 | # Try connecting to the www port instead of the echo port |
| 26 | $p->{port_num} = getservbyname("http", "tcp"); |
| 27 | while ($stop_time > time()) |
| 28 | { |
| 29 | print "$host not reachable ", scalar(localtime()), "\n" |
| 30 | unless $p->ping($host); |
| 31 | sleep(300); |
| 32 | } |
| 33 | undef($p); |
| 34 | |
| 35 | # High precision syntax (requires Time::HiRes) |
| 36 | $p = Net::Ping->new(); |
| 37 | $p->hires(); |
| 38 | ($ret, $duration, $ip) = $p->ping($host, 5.5); |
| 39 | printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n", 1000 * $duration) |
| 40 | if $ret; |
| 41 | $p->close(); |
| 42 | |
| 43 | # For backward compatibility |
| 44 | print "$host is alive.\n" if pingecho($host); |
| 45 | |
| 46 | DESCRIPTION |
| 47 | This module contains methods to test the reachability of remote hosts on |
| 48 | a network. A ping object is first created with optional parameters, a |
| 49 | variable number of hosts may be pinged multiple times and then the |
| 50 | connection is closed. |
| 51 | |
| 52 | You may choose one of four different protocols to use for the ping. The |
| 53 | "udp" protocol is the default. Note that a live remote host may still |
| 54 | fail to be pingable by one or more of these protocols. For example, |
| 55 | www.microsoft.com is generally alive but not pingable. |
| 56 | |
| 57 | With the "tcp" protocol the ping() method attempts to establish a |
| 58 | connection to the remote host's echo port. If the connection is |
| 59 | successfully established, the remote host is considered reachable. No |
| 60 | data is actually echoed. This protocol does not require any special |
| 61 | privileges but has higher overhead than the other two protocols. |
| 62 | |
| 63 | Specifying the "udp" protocol causes the ping() method to send a udp |
| 64 | packet to the remote host's echo port. If the echoed packet is received |
| 65 | from the remote host and the received packet contains the same data as |
| 66 | the packet that was sent, the remote host is considered reachable. This |
| 67 | protocol does not require any special privileges. It should be borne in |
| 68 | mind that, for a udp ping, a host will be reported as unreachable if it |
| 69 | is not running the appropriate echo service. For Unix-like systems see |
| 70 | the inetd(8) manpage for more information. |
| 71 | |
| 72 | If the "icmp" protocol is specified, the ping() method sends an icmp |
| 73 | echo message to the remote host, which is what the UNIX ping program |
| 74 | does. If the echoed message is received from the remote host and the |
| 75 | echoed information is correct, the remote host is considered reachable. |
| 76 | Specifying the "icmp" protocol requires that the program be run as root |
| 77 | or that the program be setuid to root. |
| 78 | |
| 79 | If the "external" protocol is specified, the ping() method attempts to |
| 80 | use the `Net::Ping::External' module to ping the remote host. |
| 81 | `Net::Ping::External' interfaces with your system's default `ping' |
| 82 | utility to perform the ping, and generally produces relatively accurate |
| 83 | results. If `Net::Ping::External' if not installed on your system, |
| 84 | specifying the "external" protocol will result in an error. |
| 85 | |
| 86 | Functions |
| 87 | |
| 88 | Net::Ping->new([$proto [, $def_timeout [, $bytes]]]); |
| 89 | Create a new ping object. All of the parameters are optional. $proto |
| 90 | specifies the protocol to use when doing a ping. The current choices |
| 91 | are "tcp", "udp" or "icmp". The default is "udp". |
| 92 | |
| 93 | If a default timeout ($def_timeout) in seconds is provided, it is |
| 94 | used when a timeout is not given to the ping() method (below). The |
| 95 | timeout must be greater than 0 and the default, if not specified, is |
| 96 | 5 seconds. |
| 97 | |
| 98 | If the number of data bytes ($bytes) is given, that many data bytes |
| 99 | are included in the ping packet sent to the remote host. The number |
| 100 | of data bytes is ignored if the protocol is "tcp". The minimum (and |
| 101 | default) number of data bytes is 1 if the protocol is "udp" and 0 |
| 102 | otherwise. The maximum number of data bytes that can be specified is |
| 103 | 1024. |
| 104 | |
| 105 | $p->ping($host [, $timeout]); |
| 106 | Ping the remote host and wait for a response. $host can be either |
| 107 | the hostname or the IP number of the remote host. The optional |
| 108 | timeout must be greater than 0 seconds and defaults to whatever was |
| 109 | specified when the ping object was created. Returns a success flag. |
| 110 | If the hostname cannot be found or there is a problem with the IP |
| 111 | number, the success flag returned will be undef. Otherwise, the |
| 112 | success flag will be 1 if the host is reachable and 0 if it is not. |
| 113 | For most practical purposes, undef and 0 and can be treated as the |
| 114 | same case. In array context, the elapsed time is also returned. The |
| 115 | elapsed time value will be a float, as retuned by the |
| 116 | Time::HiRes::time() function, if hires() has been previously called, |
| 117 | otherwise it is returned as an integer. |
| 118 | |
| 119 | $p->source_verify( { 0 | 1 } ); |
| 120 | Allows source endpoint verification to be enabled or disabled. This |
| 121 | is useful for those remote destinations with multiples interfaces |
| 122 | where the response may not originate from the same endpoint that the |
| 123 | original destination endpoint was sent to. This only affects udp and |
| 124 | icmp protocol pings. |
| 125 | |
| 126 | This is enabled by default. |
| 127 | |
| 128 | $p->hires( { 0 | 1 } ); |
| 129 | Causes this module to use Time::HiRes module, allowing milliseconds |
| 130 | to be returned by subsequent calls to ping(). |
| 131 | |
| 132 | This is disabled by default. |
| 133 | |
| 134 | $p->bind($local_addr); |
| 135 | Sets the source address from which pings will be sent. This must be |
| 136 | the address of one of the interfaces on the local host. $local_addr |
| 137 | may be specified as a hostname or as a text IP address such as |
| 138 | "192.168.1.1". |
| 139 | |
| 140 | If the protocol is set to "tcp", this method may be called any |
| 141 | number of times, and each call to the ping() method (below) will use |
| 142 | the most recent $local_addr. If the protocol is "icmp" or "udp", |
| 143 | then bind() must be called at most once per object, and (if it is |
| 144 | called at all) must be called before the first call to ping() for |
| 145 | that object. |
| 146 | |
| 147 | $p->open($host); |
| 148 | When you are using the stream protocol, this call pre-opens the tcp |
| 149 | socket. It's only necessary to do this if you want to provide a |
| 150 | different timeout when creating the connection, or remove the |
| 151 | overhead of establishing the connection from the first ping. If you |
| 152 | don't call `open()', the connection is automatically opened the |
| 153 | first time `ping()' is called. This call simply does nothing if you |
| 154 | are using any protocol other than stream. |
| 155 | |
| 156 | $p->close(); |
| 157 | Close the network connection for this ping object. The network |
| 158 | connection is also closed by "undef $p". The network connection is |
| 159 | automatically closed if the ping object goes out of scope (e.g. $p |
| 160 | is local to a subroutine and you leave the subroutine). |
| 161 | |
| 162 | pingecho($host [, $timeout]); |
| 163 | To provide backward compatibility with the previous version of |
| 164 | Net::Ping, a pingecho() subroutine is available with the same |
| 165 | functionality as before. pingecho() uses the tcp protocol. The |
| 166 | return values and parameters are the same as described for the |
| 167 | ping() method. This subroutine is obsolete and may be removed in a |
| 168 | future version of Net::Ping. |
| 169 | |
| 170 | WARNING |
| 171 | pingecho() or a ping object with the tcp protocol use alarm() to |
| 172 | implement the timeout. So, don't use alarm() in your program while you |
| 173 | are using pingecho() or a ping object with the tcp protocol. The udp and |
| 174 | icmp protocols do not use alarm() to implement the timeout. |
| 175 | |
| 176 | NOTES |
| 177 | There will be less network overhead (and some efficiency in your |
| 178 | program) if you specify either the udp or the icmp protocol. The tcp |
| 179 | protocol will generate 2.5 times or more traffic for each ping than |
| 180 | either udp or icmp. If many hosts are pinged frequently, you may wish to |
| 181 | implement a small wait (e.g. 25ms or more) between each ping to avoid |
| 182 | flooding your network with packets. |
| 183 | |
| 184 | The icmp protocol requires that the program be run as root or that it be |
| 185 | setuid to root. The other protocols do not require special privileges, |
| 186 | but not all network devices implement tcp or udp echo. |
| 187 | |
| 188 | Local hosts should normally respond to pings within milliseconds. |
| 189 | However, on a very congested network it may take up to 3 seconds or |
| 190 | longer to receive an echo packet from the remote host. If the timeout is |
| 191 | set too low under these conditions, it will appear that the remote host |
| 192 | is not reachable (which is almost the truth). |
| 193 | |
| 194 | Reachability doesn't necessarily mean that the remote host is actually |
| 195 | functioning beyond its ability to echo packets. tcp is slightly better |
| 196 | at indicating the health of a system than icmp because it uses more of |
| 197 | the networking stack to respond. |
| 198 | |
| 199 | Because of a lack of anything better, this module uses its own routines |
| 200 | to pack and unpack ICMP packets. It would be better for a separate |
| 201 | module to be written which understands all of the different kinds of |
| 202 | ICMP packets. |
| 203 | |
| 204 | INSTALL |
| 205 | The latest source tree is available via cvs: |
| 206 | |
| 207 | cvs -z3 -q -d :pserver:anonymous@cvs.roobik.com.:/usr/local/cvsroot/freeware co Net-Ping |
| 208 | cd Net-Ping |
| 209 | |
| 210 | The tarball can be created as follows: |
| 211 | |
| 212 | perl Makefile.PL ; make ; make dist |
| 213 | |
| 214 | The latest Net::Ping release can be found at CPAN: |
| 215 | |
| 216 | $CPAN/modules/by-module/Net/ |
| 217 | |
| 218 | 1) Extract the tarball |
| 219 | |
| 220 | gtar -zxvf Net-Ping-xxxx.tar.gz |
| 221 | cd Net-Ping-xxxx |
| 222 | |
| 223 | 2) Build: |
| 224 | |
| 225 | make realclean |
| 226 | perl Makefile.PL |
| 227 | make |
| 228 | make test |
| 229 | |
| 230 | 3) Install |
| 231 | |
| 232 | make install |
| 233 | |
| 234 | Or install it RPM Style: |
| 235 | |
| 236 | rpm -ta SOURCES/Net-Ping-xxxx.tar.gz |
| 237 | |
| 238 | rpm -ih RPMS/noarch/perl-Net-Ping-xxxx.rpm |
| 239 | |
| 240 | AUTHORS |
| 241 | Current maintainer: |
| 242 | bbb@cpan.org (Rob Brown) |
| 243 | |
| 244 | External protocol: |
| 245 | colinm@cpan.org (Colin McMillen) |
| 246 | |
| 247 | Stream protocol: |
| 248 | bronson@trestle.com (Scott Bronson) |
| 249 | |
| 250 | Original pingecho(): |
| 251 | karrer@bernina.ethz.ch (Andreas Karrer) |
| 252 | pmarquess@bfsec.bt.co.uk (Paul Marquess) |
| 253 | |
| 254 | Original Net::Ping author: |
| 255 | mose@ns.ccsn.edu (Russell Mosemann) |
| 256 | |
| 257 | COPYRIGHT |
| 258 | Copyright (c) 2002, Rob Brown. All rights reserved. |
| 259 | |
| 260 | Copyright (c) 2001, Colin McMillen. All rights reserved. |
| 261 | |
| 262 | This program is free software; you may redistribute it and/or modify it |
| 263 | under the same terms as Perl itself. |
| 264 | |