Commit | Line | Data |
505f3f16 |
1 | NAME |
2 | Net::Ping - check a remote host for reachability |
3 | |
9c36735d |
4 | $Id: Ping.pm,v 1.69 2003/01/23 17:21:29 rob Exp $ |
505f3f16 |
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"); |
ddbbf559 |
14 | $p->bind($my_addr); # Specify source interface of pings |
505f3f16 |
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 | |
9c36735d |
35 | # Like tcp protocol, but with many hosts |
36 | $p = Net::Ping->new("syn"); |
37 | $p->{port_num} = getservbyname("http", "tcp"); |
38 | foreach $host (@host_array) { |
39 | $p->ping($host); |
40 | } |
41 | while (($host,$rtt,$ip) = $p->ack) { |
42 | print "HOST: $host [$ip] ACKed in $rtt seconds.\n"; |
43 | } |
44 | |
e82f584b |
45 | # High precision syntax (requires Time::HiRes) |
46 | $p = Net::Ping->new(); |
47 | $p->hires(); |
48 | ($ret, $duration, $ip) = $p->ping($host, 5.5); |
49 | printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n", 1000 * $duration) |
50 | if $ret; |
51 | $p->close(); |
52 | |
505f3f16 |
53 | # For backward compatibility |
54 | print "$host is alive.\n" if pingecho($host); |
55 | |
56 | DESCRIPTION |
57 | This module contains methods to test the reachability of remote hosts on |
58 | a network. A ping object is first created with optional parameters, a |
59 | variable number of hosts may be pinged multiple times and then the |
60 | connection is closed. |
61 | |
9c36735d |
62 | You may choose one of six different protocols to use for the ping. The |
63 | "tcp" protocol is the default. Note that a live remote host may still |
505f3f16 |
64 | fail to be pingable by one or more of these protocols. For example, |
9c36735d |
65 | www.microsoft.com is generally alive but not "icmp" pingable. |
505f3f16 |
66 | |
67 | With the "tcp" protocol the ping() method attempts to establish a |
68 | connection to the remote host's echo port. If the connection is |
69 | successfully established, the remote host is considered reachable. No |
70 | data is actually echoed. This protocol does not require any special |
9c36735d |
71 | privileges but has higher overhead than the "udp" and "icmp" protocols. |
505f3f16 |
72 | |
73 | Specifying the "udp" protocol causes the ping() method to send a udp |
74 | packet to the remote host's echo port. If the echoed packet is received |
75 | from the remote host and the received packet contains the same data as |
76 | the packet that was sent, the remote host is considered reachable. This |
77 | protocol does not require any special privileges. It should be borne in |
78 | mind that, for a udp ping, a host will be reported as unreachable if it |
79 | is not running the appropriate echo service. For Unix-like systems see |
80 | the inetd(8) manpage for more information. |
81 | |
82 | If the "icmp" protocol is specified, the ping() method sends an icmp |
83 | echo message to the remote host, which is what the UNIX ping program |
84 | does. If the echoed message is received from the remote host and the |
85 | echoed information is correct, the remote host is considered reachable. |
86 | Specifying the "icmp" protocol requires that the program be run as root |
87 | or that the program be setuid to root. |
88 | |
89 | If the "external" protocol is specified, the ping() method attempts to |
9c36735d |
90 | use the "Net::Ping::External" module to ping the remote host. |
91 | "Net::Ping::External" interfaces with your system's default "ping" |
505f3f16 |
92 | utility to perform the ping, and generally produces relatively accurate |
9c36735d |
93 | results. If "Net::Ping::External" if not installed on your system, |
505f3f16 |
94 | specifying the "external" protocol will result in an error. |
95 | |
9c36735d |
96 | If the "syn" protocol is specified, the ping() method will only send a |
97 | TCP SYN packet to the remote host then immediately return. If the syn |
98 | packet was sent successfully, it will return a true value, otherwise it |
99 | will return false. NOTE: Unlike the other protocols, the return value |
100 | does NOT determine if the remote host is alive or not since the full TCP |
101 | three-way handshake may not have completed yet. The remote host is only |
102 | considered reachable if it receives a TCP ACK within the timeout |
103 | specifed. To begin waiting for the ACK packets, use the ack() method as |
104 | explained below. Use the "syn" protocol instead the "tcp" protocol to |
105 | determine reachability of multiple destinations simultaneously by |
106 | sending parallel TCP SYN packets. It will not block while testing each |
107 | remote host. demo/fping is provided in this distribution to demonstrate |
108 | the "syn" protocol as an example. This protocol does not require any |
109 | special privileges. |
110 | |
505f3f16 |
111 | Functions |
112 | |
9c36735d |
113 | Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device ]]]]); |
505f3f16 |
114 | Create a new ping object. All of the parameters are optional. $proto |
115 | specifies the protocol to use when doing a ping. The current choices |
9c36735d |
116 | are "tcp", "udp", "icmp", "stream", "syn", or "external". The |
117 | default is "tcp". |
505f3f16 |
118 | |
119 | If a default timeout ($def_timeout) in seconds is provided, it is |
120 | used when a timeout is not given to the ping() method (below). The |
121 | timeout must be greater than 0 and the default, if not specified, is |
122 | 5 seconds. |
123 | |
124 | If the number of data bytes ($bytes) is given, that many data bytes |
125 | are included in the ping packet sent to the remote host. The number |
126 | of data bytes is ignored if the protocol is "tcp". The minimum (and |
127 | default) number of data bytes is 1 if the protocol is "udp" and 0 |
128 | otherwise. The maximum number of data bytes that can be specified is |
129 | 1024. |
130 | |
9c36735d |
131 | If $device is given, this device is used to bind the source endpoint |
132 | before sending the ping packet. I beleive this only works with |
133 | superuser privileges and with udp and icmp protocols at this time. |
134 | |
5d20095f |
135 | $p->ping($host [, $timeout]); |
136 | Ping the remote host and wait for a response. $host can be either |
137 | the hostname or the IP number of the remote host. The optional |
138 | timeout must be greater than 0 seconds and defaults to whatever was |
139 | specified when the ping object was created. Returns a success flag. |
140 | If the hostname cannot be found or there is a problem with the IP |
141 | number, the success flag returned will be undef. Otherwise, the |
142 | success flag will be 1 if the host is reachable and 0 if it is not. |
143 | For most practical purposes, undef and 0 and can be treated as the |
9c36735d |
144 | same case. In array context, the elapsed time as well as the string |
145 | form of the ip the host resolved to are also returned. The elapsed |
146 | time value will be a float, as retuned by the Time::HiRes::time() |
147 | function, if hires() has been previously called, otherwise it is |
148 | returned as an integer. |
5d20095f |
149 | |
15d96390 |
150 | $p->source_verify( { 0 | 1 } ); |
151 | Allows source endpoint verification to be enabled or disabled. This |
152 | is useful for those remote destinations with multiples interfaces |
153 | where the response may not originate from the same endpoint that the |
5d20095f |
154 | original destination endpoint was sent to. This only affects udp and |
155 | icmp protocol pings. |
15d96390 |
156 | |
157 | This is enabled by default. |
158 | |
9c36735d |
159 | $p->tcp_service_check( { 0 | 1 } ); |
160 | Set whether or not the tcp connect behavior should enforce remote |
161 | service availability as well as reachability. Normally, if the |
162 | remote server reported ECONNREFUSED, it must have been reachable |
163 | because of the status packet that it reported. With this option |
164 | enabled, the full three-way tcp handshake must have been established |
165 | successfully before it will claim it is reachable. NOTE: It still |
166 | does nothing more than connect and disconnect. It does not speak any |
167 | protocol (i.e., HTTP or FTP) to ensure the remote server is sane in |
168 | any way. The remote server CPU could be grinding to a halt and |
169 | unresponsive to any clients connecting, but if the kernel throws the |
170 | ACK packet, it is considered alive anyway. To really determine if |
171 | the server is responding well would be application specific and is |
172 | beyond the scope of Net::Ping. |
173 | |
174 | This only affects "tcp" and "syn" protocols. |
175 | |
176 | This is disabled by default. |
177 | |
e82f584b |
178 | $p->hires( { 0 | 1 } ); |
179 | Causes this module to use Time::HiRes module, allowing milliseconds |
180 | to be returned by subsequent calls to ping(). |
181 | |
15d96390 |
182 | This is disabled by default. |
183 | |
ddbbf559 |
184 | $p->bind($local_addr); |
185 | Sets the source address from which pings will be sent. This must be |
186 | the address of one of the interfaces on the local host. $local_addr |
187 | may be specified as a hostname or as a text IP address such as |
188 | "192.168.1.1". |
189 | |
190 | If the protocol is set to "tcp", this method may be called any |
191 | number of times, and each call to the ping() method (below) will use |
192 | the most recent $local_addr. If the protocol is "icmp" or "udp", |
193 | then bind() must be called at most once per object, and (if it is |
194 | called at all) must be called before the first call to ping() for |
195 | that object. |
196 | |
505f3f16 |
197 | $p->open($host); |
9c36735d |
198 | When you are using the "stream" protocol, this call pre-opens the |
199 | tcp socket. It's only necessary to do this if you want to provide a |
505f3f16 |
200 | different timeout when creating the connection, or remove the |
201 | overhead of establishing the connection from the first ping. If you |
9c36735d |
202 | don't call "open()", the connection is automatically opened the |
203 | first time "ping()" is called. This call simply does nothing if you |
505f3f16 |
204 | are using any protocol other than stream. |
205 | |
9c36735d |
206 | $p->ack( [ $host ] ); |
207 | When using the "syn" protocol, use this method to determine the |
208 | reachability of the remote host. This method is meant to be called |
209 | up to as many times as ping() was called. Each call returns the host |
210 | (as passed to ping()) that came back with the TCP ACK. The order in |
211 | which the hosts are returned may not necessarily be the same order |
212 | in which they were SYN queued using the ping() method. If the |
213 | timeout is reached before the TCP ACK is received, or if the remote |
214 | host is not listening on the port attempted, then the TCP connection |
215 | will not be established and ack() will return undef. In list |
216 | context, the host, the ack time, and the dotted ip string will be |
217 | returned instead of just the host. If the optional $host argument is |
218 | specified, the return value will be partaining to that host only. |
219 | This call simply does nothing if you are using any protocol other |
220 | than syn. |
221 | |
222 | $p->nack( $failed_ack_host ); |
223 | The reason that host $failed_ack_host did not receive a valid ACK. |
224 | Useful to find out why when ack( $fail_ack_host ) returns a false |
225 | value. |
226 | |
505f3f16 |
227 | $p->close(); |
228 | Close the network connection for this ping object. The network |
229 | connection is also closed by "undef $p". The network connection is |
230 | automatically closed if the ping object goes out of scope (e.g. $p |
231 | is local to a subroutine and you leave the subroutine). |
232 | |
233 | pingecho($host [, $timeout]); |
234 | To provide backward compatibility with the previous version of |
235 | Net::Ping, a pingecho() subroutine is available with the same |
236 | functionality as before. pingecho() uses the tcp protocol. The |
237 | return values and parameters are the same as described for the |
238 | ping() method. This subroutine is obsolete and may be removed in a |
239 | future version of Net::Ping. |
240 | |
505f3f16 |
241 | NOTES |
242 | There will be less network overhead (and some efficiency in your |
243 | program) if you specify either the udp or the icmp protocol. The tcp |
244 | protocol will generate 2.5 times or more traffic for each ping than |
245 | either udp or icmp. If many hosts are pinged frequently, you may wish to |
246 | implement a small wait (e.g. 25ms or more) between each ping to avoid |
247 | flooding your network with packets. |
248 | |
249 | The icmp protocol requires that the program be run as root or that it be |
250 | setuid to root. The other protocols do not require special privileges, |
251 | but not all network devices implement tcp or udp echo. |
252 | |
253 | Local hosts should normally respond to pings within milliseconds. |
254 | However, on a very congested network it may take up to 3 seconds or |
255 | longer to receive an echo packet from the remote host. If the timeout is |
256 | set too low under these conditions, it will appear that the remote host |
257 | is not reachable (which is almost the truth). |
258 | |
259 | Reachability doesn't necessarily mean that the remote host is actually |
260 | functioning beyond its ability to echo packets. tcp is slightly better |
261 | at indicating the health of a system than icmp because it uses more of |
262 | the networking stack to respond. |
263 | |
264 | Because of a lack of anything better, this module uses its own routines |
265 | to pack and unpack ICMP packets. It would be better for a separate |
266 | module to be written which understands all of the different kinds of |
267 | ICMP packets. |
268 | |
5d20095f |
269 | INSTALL |
270 | The latest source tree is available via cvs: |
271 | |
9c36735d |
272 | cvs -z3 -q -d :pserver:anonymous@cvs.roobik.com.:/usr/local/cvsroot/freeware checkout Net-Ping |
5d20095f |
273 | cd Net-Ping |
274 | |
275 | The tarball can be created as follows: |
276 | |
277 | perl Makefile.PL ; make ; make dist |
278 | |
279 | The latest Net::Ping release can be found at CPAN: |
280 | |
281 | $CPAN/modules/by-module/Net/ |
282 | |
283 | 1) Extract the tarball |
284 | |
285 | gtar -zxvf Net-Ping-xxxx.tar.gz |
286 | cd Net-Ping-xxxx |
287 | |
288 | 2) Build: |
289 | |
290 | make realclean |
291 | perl Makefile.PL |
292 | make |
293 | make test |
294 | |
295 | 3) Install |
296 | |
297 | make install |
298 | |
299 | Or install it RPM Style: |
300 | |
301 | rpm -ta SOURCES/Net-Ping-xxxx.tar.gz |
302 | |
303 | rpm -ih RPMS/noarch/perl-Net-Ping-xxxx.rpm |
304 | |
ddbbf559 |
305 | AUTHORS |
e82f584b |
306 | Current maintainer: |
ddbbf559 |
307 | bbb@cpan.org (Rob Brown) |
505f3f16 |
308 | |
e82f584b |
309 | External protocol: |
310 | colinm@cpan.org (Colin McMillen) |
311 | |
505f3f16 |
312 | Stream protocol: |
313 | bronson@trestle.com (Scott Bronson) |
314 | |
315 | Original pingecho(): |
316 | karrer@bernina.ethz.ch (Andreas Karrer) |
317 | pmarquess@bfsec.bt.co.uk (Paul Marquess) |
318 | |
319 | Original Net::Ping author: |
320 | mose@ns.ccsn.edu (Russell Mosemann) |
321 | |
505f3f16 |
322 | COPYRIGHT |
9c36735d |
323 | Copyright (c) 2002-2003, Rob Brown. All rights reserved. |
ddbbf559 |
324 | |
e82f584b |
325 | Copyright (c) 2001, Colin McMillen. All rights reserved. |
505f3f16 |
326 | |
327 | This program is free software; you may redistribute it and/or modify it |
328 | under the same terms as Perl itself. |
329 | |