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