Commit | Line | Data |
---|---|---|
3226bbec JH |
1 | NAME |
2 | Net::Ping - check a remote host for reachability | |
3 | ||
4 | $Id: Ping.pm,v 1.5 2001/11/19 09:44:18 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 | foreach $host (@host_array) | |
15 | { | |
16 | print "$host is "; | |
17 | print "NOT " unless $p->ping($host, 2); | |
18 | print "reachable.\n"; | |
19 | sleep(1); | |
20 | } | |
21 | $p->close(); | |
22 | ||
23 | $p = Net::Ping->new("tcp", 2); | |
24 | # Try connecting to the www port instead of the echo port | |
25 | $p->{port_num} = getservbyname("http", "tcp"); | |
26 | while ($stop_time > time()) | |
27 | { | |
28 | print "$host not reachable ", scalar(localtime()), "\n" | |
29 | unless $p->ping($host); | |
30 | sleep(300); | |
31 | } | |
32 | undef($p); | |
33 | ||
34 | # For backward compatibility | |
35 | print "$host is alive.\n" if pingecho($host); | |
36 | ||
37 | DESCRIPTION | |
38 | This module contains methods to test the reachability of remote hosts on | |
39 | a network. A ping object is first created with optional parameters, a | |
40 | variable number of hosts may be pinged multiple times and then the | |
41 | connection is closed. | |
42 | ||
43 | You may choose one of three different protocols to use for the ping. | |
44 | With the "tcp" protocol the ping() method attempts to establish a | |
45 | connection to the remote host's echo port. If the connection is | |
46 | successfully established, the remote host is considered reachable. No | |
47 | data is actually echoed. This protocol does not require any special | |
48 | privileges but has higher overhead than the other two protocols. | |
49 | ||
50 | Specifying the "udp" protocol causes the ping() method to send a udp | |
51 | packet to the remote host's echo port. If the echoed packet is received | |
52 | from the remote host and the received packet contains the same data as | |
53 | the packet that was sent, the remote host is considered reachable. This | |
54 | protocol does not require any special privileges. | |
55 | ||
56 | If the "icmp" protocol is specified, the ping() method sends an icmp | |
57 | echo message to the remote host, which is what the UNIX ping program | |
58 | does. If the echoed message is received from the remote host and the | |
59 | echoed information is correct, the remote host is considered reachable. | |
60 | Specifying the "icmp" protocol requires that the program be run as root | |
61 | or that the program be setuid to root. | |
62 | ||
63 | Functions | |
64 | ||
65 | Net::Ping->new([$proto [, $def_timeout [, $bytes]]]); | |
66 | Create a new ping object. All of the parameters are optional. $proto | |
67 | specifies the protocol to use when doing a ping. The current choices | |
68 | are "tcp", "udp" or "icmp". The default is "udp". | |
69 | ||
70 | If a default timeout ($def_timeout) in seconds is provided, it is | |
71 | used when a timeout is not given to the ping() method (below). The | |
72 | timeout must be greater than 0 and the default, if not specified, is | |
73 | 5 seconds. | |
74 | ||
75 | If the number of data bytes ($bytes) is given, that many data bytes | |
76 | are included in the ping packet sent to the remote host. The number | |
77 | of data bytes is ignored if the protocol is "tcp". The minimum (and | |
78 | default) number of data bytes is 1 if the protocol is "udp" and 0 | |
79 | otherwise. The maximum number of data bytes that can be specified is | |
80 | 1024. | |
81 | ||
82 | $p->ping($host [, $timeout]); | |
83 | Ping the remote host and wait for a response. $host can be either | |
84 | the hostname or the IP number of the remote host. The optional | |
85 | timeout must be greater than 0 seconds and defaults to whatever was | |
86 | specified when the ping object was created. If the hostname cannot | |
87 | be found or there is a problem with the IP number, undef is | |
88 | returned. Otherwise, 1 is returned if the host is reachable and 0 if | |
89 | it is not. For all practical purposes, undef and 0 and can be | |
90 | treated as the same case. | |
91 | ||
92 | $p->close(); | |
93 | Close the network connection for this ping object. The network | |
94 | connection is also closed by "undef $p". The network connection is | |
95 | automatically closed if the ping object goes out of scope (e.g. $p | |
96 | is local to a subroutine and you leave the subroutine). | |
97 | ||
98 | pingecho($host [, $timeout]); | |
99 | To provide backward compatibility with the previous version of | |
100 | Net::Ping, a pingecho() subroutine is available with the same | |
101 | functionality as before. pingecho() uses the tcp protocol. The | |
102 | return values and parameters are the same as described for the | |
103 | ping() method. This subroutine is obsolete and may be removed in a | |
104 | future version of Net::Ping. | |
105 | ||
106 | WARNING | |
107 | pingecho() or a ping object with the tcp protocol use alarm() to | |
108 | implement the timeout. So, don't use alarm() in your program while you | |
109 | are using pingecho() or a ping object with the tcp protocol. The udp and | |
110 | icmp protocols do not use alarm() to implement the timeout. | |
111 | ||
112 | NOTES | |
113 | There will be less network overhead (and some efficiency in your | |
114 | program) if you specify either the udp or the icmp protocol. The tcp | |
115 | protocol will generate 2.5 times or more traffic for each ping than | |
116 | either udp or icmp. If many hosts are pinged frequently, you may wish to | |
117 | implement a small wait (e.g. 25ms or more) between each ping to avoid | |
118 | flooding your network with packets. | |
119 | ||
120 | The icmp protocol requires that the program be run as root or that it be | |
121 | setuid to root. The tcp and udp protocols do not require special | |
122 | privileges, but not all network devices implement the echo protocol for | |
123 | tcp or udp. | |
124 | ||
125 | Local hosts should normally respond to pings within milliseconds. | |
126 | However, on a very congested network it may take up to 3 seconds or | |
127 | longer to receive an echo packet from the remote host. If the timeout is | |
128 | set too low under these conditions, it will appear that the remote host | |
129 | is not reachable (which is almost the truth). | |
130 | ||
131 | Reachability doesn't necessarily mean that the remote host is actually | |
132 | functioning beyond its ability to echo packets. | |
133 | ||
134 | Because of a lack of anything better, this module uses its own routines | |
135 | to pack and unpack ICMP packets. It would be better for a separate | |
136 | module to be written which understands all of the different kinds of | |
137 | ICMP packets. | |
138 | ||
139 | AUTHOR(S) | |
140 | Original pingecho(): | |
141 | Andreas Karrer (karrer@bernina.ethz.ch) | |
142 | Paul Marquess (pmarquess@bfsec.bt.co.uk) | |
143 | ||
144 | Net::Ping base code: | |
145 | Russell Mosemann (mose@ns.ccsn.edu) | |
146 | ||
147 | Compatibility porting so ping_tcp() | |
148 | can work with most remote systems: | |
149 | Rob Brown (rob@roobik.com) | |
150 | ||
151 | COPYRIGHT | |
152 | Copyright (c) 2001 Rob Brown. All rights reserved. | |
153 | ||
154 | Copyright (c) 1996 Russell Mosemann. All rights reserved. | |
155 | ||
156 | This program is free software; you may redistribute it and/or modify it | |
157 | under the same terms as Perl itself. | |
158 |