Commit | Line | Data |
---|---|---|
86530b38 AT |
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 |