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_num} = 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_num} = 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 con‐
70 nection to the remote host's echo port. If the connection is success‐
71 fully established, the remote host is considered reachable. No data is
72 actually echoed. This protocol does not require any special privileges
73 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 reach‐
79 able. 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 specifed. 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 demon‐
110 strate 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
116 ]]]]]);
117 Create a new ping object. All of the parameters are optional.
118 $proto specifies the protocol to use when doing a ping. The cur‐
119 rent choices are "tcp", "udp", "icmp", "stream", "syn", or "exter‐
120 nal". The default is "tcp".
121 If a default timeout ($def_timeout) in seconds is provided, it is
123 used when a timeout is not given to the ping() method (below). The
124 timeout must be greater than 0 and the default, if not specified,
125 is 5 seconds.
126 If the number of data bytes ($bytes) is given, that many data bytes
128 are included in the ping packet sent to the remote host. The number
129 of data bytes is ignored if the protocol is "tcp". The minimum
130 (and default) number of data bytes is 1 if the protocol is "udp"
131 and 0 otherwise. The maximum number of data bytes that can be
132 specified is 1024.
133 If $device is given, this device is used to bind the source end‐
135 point before sending the ping packet. I beleive this only works
136 with superuser privileges and with udp and icmp protocols at this
137 time.
138 If $tos is given, this ToS is configured into the soscket.
140 $p->ping($host [, $timeout]);
142 Ping the remote host and wait for a response. $host can be either
143 the hostname or the IP number of the remote host. The optional
144 timeout must be greater than 0 seconds and defaults to whatever was
145 specified when the ping object was created. Returns a success
146 flag. If the hostname cannot be found or there is a problem with
147 the IP number, the success flag returned will be undef. Otherwise,
148 the success flag will be 1 if the host is reachable and 0 if it is
149 not. For most practical purposes, undef and 0 and can be treated
150 as the same case. In array context, the elapsed time as well as
151 the string form of the ip the host resolved to are also returned.
152 The elapsed time value will be a float, as retuned by the
153 Time::HiRes::time() function, if hires() has been previously
154 called, otherwise it is returned as an integer.
155 $p->source_verify( { 0 ⎪ 1 } );
157 Allows source endpoint verification to be enabled or disabled.
158 This is useful for those remote destinations with multiples inter‐
159 faces where the response may not originate from the same endpoint
160 that the original destination endpoint was sent to. This only
161 affects udp and icmp protocol pings.
162 This is enabled by default.
164 $p->service_check( { 0 ⎪ 1 } );
166 Set whether or not the connect behavior should enforce remote ser‐
167 vice availability as well as reachability. Normally, if the remote
168 server reported ECONNREFUSED, it must have been reachable because
169 of the status packet that it reported. With this option enabled,
170 the full three-way tcp handshake must have been established suc‐
171 cessfully before it will claim it is reachable. NOTE: It still
172 does nothing more than connect and disconnect. It does not speak
173 any protocol (i.e., HTTP or FTP) to ensure the remote server is
174 sane in any way. The remote server CPU could be grinding to a halt
175 and unresponsive to any clients connecting, but if the kernel
176 throws the ACK packet, it is considered alive anyway. To really
177 determine if the server is responding well would be application
178 specific and is beyond the scope of Net::Ping. For udp protocol,
179 enabling this option demands that the remote server replies with
180 the same udp data that it was sent as defined by the udp echo ser‐
181 vice.
182 This affects the "udp", "tcp", and "syn" protocols.
184 This is disabled by default.
186 $p->tcp_service_check( { 0 ⎪ 1 } );
188 Depricated method, but does the same as service_check() method.
189 $p->hires( { 0 ⎪ 1 } );
191 Causes this module to use Time::HiRes module, allowing milliseconds
192 to be returned by subsequent calls to ping().
193 This is disabled by default.
195 $p->bind($local_addr);
197 Sets the source address from which pings will be sent. This must
198 be the address of one of the interfaces on the local host.
199 $local_addr may be specified as a hostname or as a text IP address
200 such as "192.168.1.1".
201 If the protocol is set to "tcp", this method may be called any num‐
203 ber of times, and each call to the ping() method (below) will use
204 the most recent $local_addr. If the protocol is "icmp" or "udp",
205 then bind() must be called at most once per object, and (if it is
206 called at all) must be called before the first call to ping() for
207 that object.
208 $p->open($host);
210 When you are using the "stream" protocol, this call pre-opens the
211 tcp socket. It's only necessary to do this if you want to provide
212 a different timeout when creating the connection, or remove the
213 overhead of establishing the connection from the first ping. If
214 you don't call "open()", the connection is automatically opened the
215 first time "ping()" is called. This call simply does nothing if
216 you are using any protocol other than stream.
217 $p->ack( [ $host ] );
219 When using the "syn" protocol, use this method to determine the
220 reachability of the remote host. This method is meant to be called
221 up to as many times as ping() was called. Each call returns the
222 host (as passed to ping()) that came back with the TCP ACK. The
223 order in which the hosts are returned may not necessarily be the
224 same order in which they were SYN queued using the ping() method.
225 If the timeout is reached before the TCP ACK is received, or if the
226 remote host is not listening on the port attempted, then the TCP
227 connection will not be established and ack() will return undef. In
228 list context, the host, the ack time, and the dotted ip string will
229 be returned instead of just the host. If the optional $host argu‐
230 ment is specified, the return value will be partaining to that host
231 only. This call simply does nothing if you are using any protocol
232 other than syn.
233 $p->nack( $failed_ack_host );
235 The reason that host $failed_ack_host did not receive a valid ACK.
236 Useful to find out why when ack( $fail_ack_host ) returns a false
237 value.
238 $p->close();
240 Close the network connection for this ping object. The network
241 connection is also closed by "undef $p". The network connection is
242 automatically closed if the ping object goes out of scope (e.g. $p
243 is local to a subroutine and you leave the subroutine).
244 pingecho($host [, $timeout]);
246 To provide backward compatibility with the previous version of
247 Net::Ping, a pingecho() subroutine is available with the same func‐
248 tionality as before. pingecho() uses the tcp protocol. The return
249 values and parameters are the same as described for the ping()
250 method. This subroutine is obsolete and may be removed in a future
251 version of Net::Ping.
252
254 There will be less network overhead (and some efficiency in your pro‐
255 gram) if you specify either the udp or the icmp protocol. The tcp pro‐
256 tocol will generate 2.5 times or more traffic for each ping than either
257 udp or icmp. If many hosts are pinged frequently, you may wish to
258 implement a small wait (e.g. 25ms or more) between each ping to avoid
259 flooding your network with packets.
260 The icmp protocol requires that the program be run as root or that it
262 be setuid to root. The other protocols do not require special privi‐
263 leges, but not all network devices implement tcp or udp echo.
264 Local hosts should normally respond to pings within milliseconds. How‐
266 ever, on a very congested network it may take up to 3 seconds or longer
267 to receive an echo packet from the remote host. If the timeout is set
268 too low under these conditions, it will appear that the remote host is
269 not reachable (which is almost the truth).
270 Reachability doesn't necessarily mean that the remote host is actually
272 functioning beyond its ability to echo packets. tcp is slightly better
273 at indicating the health of a system than icmp because it uses more of
274 the networking stack to respond.
275 Because of a lack of anything better, this module uses its own routines
277 to pack and unpack ICMP packets. It would be better for a separate
278 module to be written which understands all of the different kinds of
279 ICMP packets.
280
282 The latest source tree is available via cvs:
283 cvs -z3 -q -d :pserver:anonymous@cvs.roobik.com.:/usr/local/cvsroot/freeware checkout Net-Ping
285 cd Net-Ping
286 The tarball can be created as follows:
288 perl Makefile.PL ; make ; make dist
290 The latest Net::Ping release can be found at CPAN:
292 $CPAN/modules/by-module/Net/
294 1) Extract the tarball
296 gtar -zxvf Net-Ping-xxxx.tar.gz
298 cd Net-Ping-xxxx
299 2) Build:
301 make realclean
303 perl Makefile.PL
304 make
305 make test
306 3) Install
308 make install
310 Or install it RPM Style:
312 rpm -ta SOURCES/Net-Ping-xxxx.tar.gz
314 rpm -ih RPMS/noarch/perl-Net-Ping-xxxx.rpm
316
318 For a list of known issues, visit:
319 https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping
321 To report a new bug, visit:
323 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Ping
325
327 Current maintainer:
328 bbb@cpan.org (Rob Brown)
329 External protocol:
331 colinm@cpan.org (Colin McMillen)
332 Stream protocol:
334 bronson@trestle.com (Scott Bronson)
335 Original pingecho():
337 karrer@bernina.ethz.ch (Andreas Karrer)
338 pmarquess@bfsec.bt.co.uk (Paul Marquess)
339 Original Net::Ping author:
341 mose@ns.ccsn.edu (Russell Mosemann)
342
344 Copyright (c) 2002-2003, Rob Brown. All rights reserved.
345 Copyright (c) 2001, Colin McMillen. All rights reserved.
347 This program is free software; you may redistribute it and/or modify it
349 under the same terms as Perl itself.
350 $Id: Ping.pm,v 1.86 2003/06/27 21:31:07 rob Exp $
352perl v5.8.8 2001-09-21 Net::Ping(3pm)