NAME
Net::Ping - check a remote host for reachability
检查远程主机是否可达
SYNOPSIS
简介
use Net::Ping;
$p = Net::Ping->new();
print "$host is alive.
" if $p->ping($host);
$p->close();
$p = Net::Ping->new("icmp");
$p->bind($my_addr); # Specify source interface of pings
foreach $host (@host_array)
{
print "$host is ";
print "NOT " unless $p->ping($host, 2);
print "reachable.
";
sleep(1);
}
$p->close();
$p = Net::Ping->new("tcp", 2);
# Try connecting to the www port instead of the echo port
$p->port_number(getservbyname("http", "tcp"));
while ($stop_time > time())
{
print "$host not reachable ", scalar(localtime()), "
"
unless $p->ping($host);
sleep(300);
}
undef($p);
# Like tcp protocol, but with many hosts
$p = Net::Ping->new("syn");
$p->port_number(getservbyname("http", "tcp"));
foreach $host (@host_array) {
$p->ping($host);
}
while (($host,$rtt,$ip) = $p->ack) {
print "HOST: $host [$ip] ACKed in $rtt seconds.
";
}
# High precision syntax (requires Time::HiRes)
$p = Net::Ping->new();
$p->hires();
($ret, $duration, $ip) = $p->ping($host, 5.5);
printf("$host [ip: $ip] is alive (packet return time: %.2f ms)
", 1000 * $duration)
if $ret;
$p->close();
# For backward compatibility
print "$host is alive.
" if pingecho($host);
DESCRIPTION
This module contains methods to test the reachability of remote hosts on
a network. A ping object is first created with optional parameters, a
variable number of hosts may be pinged multiple times and then the
connection is closed.
描述:这个模块包括测试远程主机连通性的方法,ping对象首先创建一些额外的参数,
hosts的一些变量可以Ping多次,然后关闭。
You may choose one of six different protocols to use for the ping. The
"tcp" protocol is the default. Note that a live remote host may still
fail to be pingable by one or more of these protocols. For example,
www.microsoft.com is generally alive but not "icmp" pingable.
你可以现则6种不同协议中的一个,tcp是默认的协议,注意一个互动的主机可能会Ping失败,通过其中的协议,比如www.microsoft.com不能通过icmp ping检测。
With the "tcp" protocol the ping() method attempts to establish a
connection to the remote host's echo port. If the connection is
successfully established, the remote host is considered reachable. No
data is actually echoed. This protocol does not require any special
privileges but has higher overhead than the "udp" and "icmp" protocols.
Ping 方法尝试用tcp协议和远程主机建立TCP连接。
如果连接被成功建立,远程的主机被认为是可达的。没有实际数据响应,
这个协议没有使用特别的权限,但是相比udp和icmp有较高的开销，
Specifying the "udp" protocol causes the ping() method to send a udp
packet to the remote host's echo port. If the echoed packet is received
from the remote host and the received packet contains the same data as
the packet that was sent, the remote host is considered reachable. This
protocol does not require any special privileges. It should be borne in
mind that, for a udp ping, a host will be reported as unreachable if it
is not running the appropriate echo service. For Unix-like systems see
inetd(8) for more information.
指定udp协议导致ping()方法发送一个udp包到远程主机的响应端口。
如果echod的包被远程主机接收,接收的包包含相当的数据和发送的包一样
远程主机认为是active的,这个协议通常不需要特定的权限,应当记住 udp ping
一个主机会被报告为不可能如果他不运行相应的echo服务
If the "icmp" protocol is specified, the ping() method sends an icmp
echo message to the remote host, which is what the UNIX ping program
does. If the echoed message is received from the remote host and the
echoed information is correct, the remote host is considered reachable.
Specifying the "icmp" protocol requires that the program be run as root
or that the program be setuid to root.
如果icmp 协议被指定,ping()方法发送一个icmp到远程主机,如果返回的信息从远程主机收到且是正确的,那么远端的主机被认为是active的,icmp 协议需要root执行
If the "external" protocol is specified, the ping() method attempts to
use the "Net::Ping::External" module to ping the remote host.
"Net::Ping::External" interfaces with your system's default "ping"
utility to perform the ping, and generally produces relatively accurate
results. If "Net::Ping::External" if not installed on your system,
specifying the "external" protocol will result in an error.
如果外部协议被指定,ping()方法使用"Net::Ping::External" 模块去ping 远端的机器。
"Net::Ping::External" 接口使用系统默认的ping去执行,通常产生相对准确的结果.
If the "syn" protocol is specified, the ping() method will only send a
TCP SYN packet to the remote host then immediately return. If the syn
packet was sent successfully, it will return a true value, otherwise it
will return false. NOTE: Unlike the other protocols, the return value
does NOT determine if the remote host is alive or not since the full
TCP three-way handshake may not have completed yet. The remote host is only considered reachable if it receives a TCP ACK within the timeout
specified.
如果syn协议被指定,ping()方法只会发送一个TCP SYN包到远程的机器然后立即返回,
如果syn包发送成功,会返回一个真值,否则会返回一个假值。
注意:不像其他协议,syn返回的值不决定远端的主机是alive还是没有,由于TCP3次握手
没有完成,远端的主机只能认为是可能的 如果他收到TCP ACK 在超时时间内。
To begin waiting for the ACK packets, use the ack() method as
explained below. Use the "syn" protocol instead the "tcp" protocol to
determine reachability of multiple destinations simultaneously by
sending parallel TCP SYN packets. It will not block while testing each
remote host. demo/fping is provided in this distribution to demonstrate
the "syn" protocol as an example. This protocol does not require any
special privileges.
在开始等待ACK包时,使用ack()方法解释如下:
使用syn协议代替tcp协议决定同时监控多个目的,通过发送并行的TCP SYN 包。
在测试每个远端的主机的时候不会被堵塞
Functions
Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device [, $tos
]]]]]);
Create a new ping object. All of the parameters are optional. $proto
specifies the protocol to use when doing a ping. The current choices
are "tcp", "udp", "icmp", "stream", "syn", or "external". The
default is "tcp".
创建一个新的ping 对象,所有的参数都是可选的,$proto 指定了ping使用的协议 当前的选择是
"tcp", "udp", "icmp", "stream", "syn", or "external" 默认是tcp.
If a default timeout ($def_timeout) in seconds is provided, it is
used when a timeout is not given to the ping() method (below). The
timeout must be greater than 0 and the default, if not specified, is
5 seconds.
如果默认的超时参数($def_timeout)以秒为单位,用于当超时没有被设置,超时参数必须大于0 默认5秒
If the number of data bytes ($bytes) is given, that many data bytes
are included in the ping packet sent to the remote host. The number
of data bytes is ignored if the protocol is "tcp". The minimum (and
default) number of data bytes is 1 if the protocol is "udp" and 0
otherwise. The maximum number of data bytes that can be specified is
1024.
发送包的大小,Ping包发送到远端主机的字节发小。如果是tcp协议那么字节数被忽略 最小的字节数是1 如果是udp 是0
最大是1024
If $device is given, this device is used to bind the source endpoint
before sending the ping packet. I believe this only works with
superuser privileges and with udp and icmp protocols at this time.
如果$deivce被指定,这个设备时用于绑定源和终点在开始发送ping 包前
If $tos is given, this ToS is configured into the socket.
$p->ping($host [, $timeout]);
Ping the remote host and wait for a response. $host can be either
the hostname or the IP number of the remote host. The optional
timeout must be greater than 0 seconds and defaults to whatever was
specified when the ping object was created. Returns a success flag.
If the hostname cannot be found or there is a problem with the IP
number, the success flag returned will be undef. Otherwise, the
success flag will be 1 if the host is reachable and 0 if it is not.
For most practical purposes, undef and 0 and can be treated as the
same case. In array context, the elapsed time as well as the string
form of the ip the host resolved to are also returned. The elapsed
time value will be a float, as returned by the Time::HiRes::time()
function, if hires() has been previously called, otherwise it is
returned as an integer.
Ping 远端的主机等待响应,$host 可以是主机名或者IP地址。超时选项必须大于0,当ping对象创建后,
返回一个成功的标志,如果主机名不存在或者IP地址有问题,返回的标志位undef
其他情况返回的标志位1 1表示主机可达0表示不能。大多数情况下,undef和0 都当相同处理。
在数组背景下,消耗的时间以及主机解析的IP地址窜 消耗的时间是float型号
$p->source_verify( { 0 | 1 } );
Allows source endpoint verification to be enabled or disabled. This
is useful for those remote destinations with multiples interfaces
where the response may not originate from the same endpoint that the
original destination endpoint was sent to. This only affects udp and
icmp protocol pings.
This is enabled by default.
此方法是允许源地址检测多网络接口的远程主机返回数据的‘有效性’的。此方法只影响UDP与ICMP。默认此方法所对应的功能是启动的。
$p->service_check( { 0 | 1 } );
Set whether or not the connect behavior should enforce remote
service availability as well as reachability. Normally, if the
remote server reported ECONNREFUSED, it must have been reachable
because of the status packet that it reported. With this option
enabled, the full three-way tcp handshake must have been established
successfully before it will claim it is reachable.
NOTE: It still
does nothing more than connect and disconnect. It does not speak any
protocol (i.e., HTTP or FTP) to ensure the remote server is sane in
any way.
The remote server CPU could be grinding to a halt and
unresponsive to any clients connecting, but if the kernel throws the
ACK packet, it is considered alive anyway. To really determine if
the server is responding well would be application specific and is
beyond the scope of Net::Ping. For udp protocol, enabling this
option demands that the remote server replies with the same udp data
that it was sent as defined by the udp echo service.
This affects the "udp", "tcp", and "syn" protocols.
This is disabled by default.
设置这个属性表示是否连接行为强调远程服务可用.通常,如果远程服务表示为连接拒绝
表示数据包已经到达。 当这个属性启动时， 3次握手必须建立成功在要求可到达性前
注意:它只做了连接和断开连接,它没有说任何协议来确认远端服务器是正常的
$p->tcp_service_check( { 0 | 1 } );
Deprecated method, but does the same as service_check() method.
$p->hires( { 0 | 1 } );
Causes this module to use Time::HiRes module, allowing milliseconds
to be returned by subsequent calls to ping().
This is disabled by default.
$p->bind($local_addr);
Sets the source address from which pings will be sent. This must be
the address of one of the interfaces on the local host. $local_addr
may be specified as a hostname or as a text IP address such as
"192.168.1.1".
If the protocol is set to "tcp", this method may be called any
number of times, and each call to the ping() method (below) will use
the most recent $local_addr. If the protocol is "icmp" or "udp",
then bind() must be called at most once per object, and (if it is
called at all) must be called before the first call to ping() for
that object.
$p->open($host);
When you are using the "stream" protocol, this call pre-opens the
tcp socket. It's only necessary to do this if you want to provide a
different timeout when creating the connection, or remove the
overhead of establishing the connection from the first ping. If you
don't call "open()", the connection is automatically opened the
first time "ping()" is called. This call simply does nothing if you
are using any protocol other than stream.
$p->ack( [ $host ] );
When using the "syn" protocol, use this method to determine the
reachability of the remote host. This method is meant to be called
up to as many times as ping() was called. Each call returns the host
(as passed to ping()) that came back with the TCP ACK. The order in
which the hosts are returned may not necessarily be the same order
in which they were SYN queued using the ping() method. If the
timeout is reached before the TCP ACK is received, or if the remote
host is not listening on the port attempted, then the TCP connection
will not be established and ack() will return undef. In list
context, the host, the ack time, and the dotted ip string will be
returned instead of just the host. If the optional $host argument is
specified, the return value will be pertaining to that host only.
This call simply does nothing if you are using any protocol other
than syn.
$p->nack( $failed_ack_host );
The reason that host $failed_ack_host did not receive a valid ACK.
Useful to find out why when ack( $fail_ack_host ) returns a false
value.
$p->close();
Close the network connection for this ping object. The network
connection is also closed by "undef $p". The network connection is
automatically closed if the ping object goes out of scope (e.g. $p
is local to a subroutine and you leave the subroutine).
$p->port_number([$port_number])
When called with a port number, the port number used to ping is set
to $port_number rather than using the echo port. It also has the
effect of calling "$p->service_check(1)" causing a ping to return a
successful response only if that specific port is accessible. This
function returns the value of the port that "ping()" will connect
to.
pingecho($host [, $timeout]);
To provide backward compatibility with the previous version of
Net::Ping, a pingecho() subroutine is available with the same
functionality as before. pingecho() uses the tcp protocol. The
return values and parameters are the same as described for the
ping() method. This subroutine is obsolete and may be removed in a
future version of Net::Ping.
NOTES
There will be less network overhead (and some efficiency in your
program) if you specify either the udp or the icmp protocol. The tcp
protocol will generate 2.5 times or more traffic for each ping than
either udp or icmp. If many hosts are pinged frequently, you may wish to
implement a small wait (e.g. 25ms or more) between each ping to avoid
flooding your network with packets.
The icmp protocol requires that the program be run as root or that it be
setuid to root. The other protocols do not require special privileges,
but not all network devices implement tcp or udp echo.
Local hosts should normally respond to pings within milliseconds.
However, on a very congested network it may take up to 3 seconds or
longer to receive an echo packet from the remote host. If the timeout is
set too low under these conditions, it will appear that the remote host
is not reachable (which is almost the truth).
Reachability doesn't necessarily mean that the remote host is actually
functioning beyond its ability to echo packets. tcp is slightly better
at indicating the health of a system than icmp because it uses more of
the networking stack to respond.
Because of a lack of anything better, this module uses its own routines
to pack and unpack ICMP packets. It would be better for a separate
module to be written which understands all of the different kinds of
ICMP packets.
INSTALL
The latest source tree is available via cvs:
cvs -z3 -q -d :pserver:anonymous@cvs.roobik.com.:/usr/local/cvsroot/freeware checkout Net-Ping
cd Net-Ping
The tarball can be created as follows:
perl Makefile.PL ; make ; make dist
The latest Net::Ping release can be found at CPAN:
$CPAN/modules/by-module/Net/
1) Extract the tarball
gtar -zxvf Net-Ping-xxxx.tar.gz
cd Net-Ping-xxxx
2) Build:
make realclean
perl Makefile.PL
make
make test
3) Install
make install
Or install it RPM Style:
rpm -ta SOURCES/Net-Ping-xxxx.tar.gz
rpm -ih RPMS/noarch/perl-Net-Ping-xxxx.rpm
BUGS
For a list of known issues, visit:
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping
To report a new bug, visit:
https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-Ping
AUTHORS
Current maintainer:
bbb@cpan.org (Rob Brown)
External protocol:
colinm@cpan.org (Colin McMillen)
Stream protocol:
bronson@trestle.com (Scott Bronson)
Original pingecho():
karrer@bernina.ethz.ch (Andreas Karrer)
pmarquess@bfsec.bt.co.uk (Paul Marquess)
Original Net::Ping author:
mose@ns.ccsn.edu (Russell Mosemann)
COPYRIGHT
Copyright (c) 2002-2003, Rob Brown. All rights reserved.
Copyright (c) 2001, Colin McMillen. All rights reserved.
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.