Commit | Line | Data |
505f3f16 |
1 | NAME |
2 | Net::Ping - check a remote host for reachability |
3 | |
b757f218 |
4 | $Id: Ping.pm,v 1.17 2002/02/18 01:25:11 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 | |
35 | # For backward compatibility |
36 | print "$host is alive.\n" if pingecho($host); |
37 | |
38 | DESCRIPTION |
39 | This module contains methods to test the reachability of remote hosts on |
40 | a network. A ping object is first created with optional parameters, a |
41 | variable number of hosts may be pinged multiple times and then the |
42 | connection is closed. |
43 | |
44 | You may choose one of four different protocols to use for the ping. The |
45 | "udp" protocol is the default. Note that a live remote host may still |
46 | fail to be pingable by one or more of these protocols. For example, |
47 | www.microsoft.com is generally alive but not pingable. |
48 | |
49 | With the "tcp" protocol the ping() method attempts to establish a |
50 | connection to the remote host's echo port. If the connection is |
51 | successfully established, the remote host is considered reachable. No |
52 | data is actually echoed. This protocol does not require any special |
53 | privileges but has higher overhead than the other two protocols. |
54 | |
55 | Specifying the "udp" protocol causes the ping() method to send a udp |
56 | packet to the remote host's echo port. If the echoed packet is received |
57 | from the remote host and the received packet contains the same data as |
58 | the packet that was sent, the remote host is considered reachable. This |
59 | protocol does not require any special privileges. It should be borne in |
60 | mind that, for a udp ping, a host will be reported as unreachable if it |
61 | is not running the appropriate echo service. For Unix-like systems see |
62 | the inetd(8) manpage for more information. |
63 | |
64 | If the "icmp" protocol is specified, the ping() method sends an icmp |
65 | echo message to the remote host, which is what the UNIX ping program |
66 | does. If the echoed message is received from the remote host and the |
67 | echoed information is correct, the remote host is considered reachable. |
68 | Specifying the "icmp" protocol requires that the program be run as root |
69 | or that the program be setuid to root. |
70 | |
71 | If the "external" protocol is specified, the ping() method attempts to |
72 | use the `Net::Ping::External' module to ping the remote host. |
73 | `Net::Ping::External' interfaces with your system's default `ping' |
74 | utility to perform the ping, and generally produces relatively accurate |
75 | results. If `Net::Ping::External' if not installed on your system, |
76 | specifying the "external" protocol will result in an error. |
77 | |
78 | Functions |
79 | |
80 | Net::Ping->new([$proto [, $def_timeout [, $bytes]]]); |
81 | Create a new ping object. All of the parameters are optional. $proto |
82 | specifies the protocol to use when doing a ping. The current choices |
83 | are "tcp", "udp" or "icmp". The default is "udp". |
84 | |
85 | If a default timeout ($def_timeout) in seconds is provided, it is |
86 | used when a timeout is not given to the ping() method (below). The |
87 | timeout must be greater than 0 and the default, if not specified, is |
88 | 5 seconds. |
89 | |
90 | If the number of data bytes ($bytes) is given, that many data bytes |
91 | are included in the ping packet sent to the remote host. The number |
92 | of data bytes is ignored if the protocol is "tcp". The minimum (and |
93 | default) number of data bytes is 1 if the protocol is "udp" and 0 |
94 | otherwise. The maximum number of data bytes that can be specified is |
95 | 1024. |
96 | |
ddbbf559 |
97 | $p->bind($local_addr); |
98 | Sets the source address from which pings will be sent. This must be |
99 | the address of one of the interfaces on the local host. $local_addr |
100 | may be specified as a hostname or as a text IP address such as |
101 | "192.168.1.1". |
102 | |
103 | If the protocol is set to "tcp", this method may be called any |
104 | number of times, and each call to the ping() method (below) will use |
105 | the most recent $local_addr. If the protocol is "icmp" or "udp", |
106 | then bind() must be called at most once per object, and (if it is |
107 | called at all) must be called before the first call to ping() for |
108 | that object. |
109 | |
505f3f16 |
110 | $p->ping($host [, $timeout]); |
111 | Ping the remote host and wait for a response. $host can be either |
112 | the hostname or the IP number of the remote host. The optional |
113 | timeout must be greater than 0 seconds and defaults to whatever was |
114 | specified when the ping object was created. If the hostname cannot |
115 | be found or there is a problem with the IP number, undef is |
116 | returned. Otherwise, 1 is returned if the host is reachable and 0 if |
117 | it is not. For all practical purposes, undef and 0 and can be |
118 | treated as the same case. |
119 | |
120 | $p->open($host); |
121 | When you are using the stream protocol, this call pre-opens the tcp |
122 | socket. It's only necessary to do this if you want to provide a |
123 | different timeout when creating the connection, or remove the |
124 | overhead of establishing the connection from the first ping. If you |
125 | don't call `open()', the connection is automatically opened the |
126 | first time `ping()' is called. This call simply does nothing if you |
127 | are using any protocol other than stream. |
128 | |
129 | $p->open($host); |
130 | When you are using the stream protocol, this call pre-opens the tcp |
131 | socket. It's only necessary to do this if you want to provide a |
132 | different timeout when creating the connection, or remove the |
133 | overhead of establishing the connection from the first ping. If you |
134 | don't call `open()', the connection is automatically opened the |
135 | first time `ping()' is called. This call simply does nothing if you |
136 | are using any protocol other than stream. |
137 | |
138 | $p->close(); |
139 | Close the network connection for this ping object. The network |
140 | connection is also closed by "undef $p". The network connection is |
141 | automatically closed if the ping object goes out of scope (e.g. $p |
142 | is local to a subroutine and you leave the subroutine). |
143 | |
144 | pingecho($host [, $timeout]); |
145 | To provide backward compatibility with the previous version of |
146 | Net::Ping, a pingecho() subroutine is available with the same |
147 | functionality as before. pingecho() uses the tcp protocol. The |
148 | return values and parameters are the same as described for the |
149 | ping() method. This subroutine is obsolete and may be removed in a |
150 | future version of Net::Ping. |
151 | |
152 | WARNING |
153 | pingecho() or a ping object with the tcp protocol use alarm() to |
154 | implement the timeout. So, don't use alarm() in your program while you |
155 | are using pingecho() or a ping object with the tcp protocol. The udp and |
156 | icmp protocols do not use alarm() to implement the timeout. |
157 | |
158 | NOTES |
159 | There will be less network overhead (and some efficiency in your |
160 | program) if you specify either the udp or the icmp protocol. The tcp |
161 | protocol will generate 2.5 times or more traffic for each ping than |
162 | either udp or icmp. If many hosts are pinged frequently, you may wish to |
163 | implement a small wait (e.g. 25ms or more) between each ping to avoid |
164 | flooding your network with packets. |
165 | |
166 | The icmp protocol requires that the program be run as root or that it be |
167 | setuid to root. The other protocols do not require special privileges, |
168 | but not all network devices implement tcp or udp echo. |
169 | |
170 | Local hosts should normally respond to pings within milliseconds. |
171 | However, on a very congested network it may take up to 3 seconds or |
172 | longer to receive an echo packet from the remote host. If the timeout is |
173 | set too low under these conditions, it will appear that the remote host |
174 | is not reachable (which is almost the truth). |
175 | |
176 | Reachability doesn't necessarily mean that the remote host is actually |
177 | functioning beyond its ability to echo packets. tcp is slightly better |
178 | at indicating the health of a system than icmp because it uses more of |
179 | the networking stack to respond. |
180 | |
181 | Because of a lack of anything better, this module uses its own routines |
182 | to pack and unpack ICMP packets. It would be better for a separate |
183 | module to be written which understands all of the different kinds of |
184 | ICMP packets. |
185 | |
ddbbf559 |
186 | AUTHORS |
187 | Current maintainers: |
505f3f16 |
188 | colinm@cpan.org (Colin McMillen) |
ddbbf559 |
189 | bbb@cpan.org (Rob Brown) |
505f3f16 |
190 | |
191 | Stream protocol: |
192 | bronson@trestle.com (Scott Bronson) |
193 | |
194 | Original pingecho(): |
195 | karrer@bernina.ethz.ch (Andreas Karrer) |
196 | pmarquess@bfsec.bt.co.uk (Paul Marquess) |
197 | |
198 | Original Net::Ping author: |
199 | mose@ns.ccsn.edu (Russell Mosemann) |
200 | |
505f3f16 |
201 | COPYRIGHT |
ddbbf559 |
202 | Copyright (c) 2001, Colin McMillen. All rights reserved. |
203 | |
204 | Copyright (c) 2001, Rob Brown. All rights reserved. |
505f3f16 |
205 | |
206 | This program is free software; you may redistribute it and/or modify it |
207 | under the same terms as Perl itself. |
208 | |