1 |
NAME |
2 |
Net::FPing - quickly ping a large number of hosts |
3 |
|
4 |
SYNOPSIS |
5 |
use Net::FPing; |
6 |
|
7 |
DESCRIPTION |
8 |
This module was written for a single purpose only: sendinf ICMP EHCO |
9 |
REQUEST packets as quickly as possible to a large number of hosts |
10 |
(thousands to millions). |
11 |
|
12 |
It employs a sending thread and is fully event-driven (using AnyEvent), |
13 |
so you have to run an event model supported by AnyEvent to use this |
14 |
module. |
15 |
|
16 |
FUNCTIONS |
17 |
Net::FPing::ipv4_supported |
18 |
Returns true if IPv4 is supported in this module and on this system. |
19 |
|
20 |
Net::FPing::ipv6_supported |
21 |
Returns true if IPv6 is supported in this module and on this system. |
22 |
|
23 |
Net::FPing::icmp4_pktsize |
24 |
Returns the number of bytes each IPv4 ping packet has. |
25 |
|
26 |
Net::FPing::icmp6_pktsize |
27 |
Returns the number of bytes each IPv4 ping packet has. |
28 |
|
29 |
Net::FPing::icmp_ping [ranges...], $send_interval, $payload, \&callback |
30 |
Ping the given IPv4 address ranges. Each range is an arrayref of the |
31 |
form "[lo, hi, interval]", where "lo" and "hi" are octet strings |
32 |
with either 4 octets (for IPv4 addresses) or 16 octets (for IPV6 |
33 |
addresses), representing the lowest and highest address to ping (you |
34 |
can convert a dotted-quad IPv4 address to this format by using |
35 |
"inet_aton $address". The range "interval" is the minimum time in |
36 |
seconds between pings to the given range. If omitted, defaults to |
37 |
$send_interval. |
38 |
|
39 |
The $send_interval is the minimum interval between sending any two |
40 |
packets and is a way to make an overall rate limit. If omitted, |
41 |
pings will be send as fast as possible. |
42 |
|
43 |
The $payload is a 32 bit unsigned integer given as the ICMP ECHO |
44 |
REQUEST ident and sequence numbers (in unspecified order :). |
45 |
|
46 |
The request will be queued and all requests will be served by a |
47 |
background thread in order. When all ranges have been pinged, the |
48 |
"callback" will be called. |
49 |
|
50 |
Algorithm: Each range has an associated "next time to send packet" |
51 |
time. The algorithm loops as long as there are ranges with hosts to |
52 |
be pinged and always serves the range with the most urgent packet |
53 |
send time. It will at most send one packet every $send_interval |
54 |
seconds. |
55 |
|
56 |
This will ensure that pings to the same range are nicely interleaved |
57 |
with other ranges - this can help reduce per-subnet bandwidth while |
58 |
maintaining an overall high packet rate. |
59 |
|
60 |
The algorithm to send each packet is O(log n) on the number of |
61 |
ranges, so even a large number of ranges (many thousands) is |
62 |
managable. |
63 |
|
64 |
No storage is allocated per address. |
65 |
|
66 |
Performance: On my 2 GHz Opteron system with a pretty average nvidia |
67 |
gigabit network card I can ping around 60k to 200k adresses per |
68 |
second, depending on routing decisions. |
69 |
|
70 |
Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and |
71 |
11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however, |
72 |
exceed 1000 packets/s overall: |
73 |
|
74 |
my $done = AnyEvent->condvar; |
75 |
|
76 |
Net::FPing::icmp_ping |
77 |
[v10.0.0.1, v10.0.0.15, .01], |
78 |
[v11.0.0.1, v11.0.255.255, .001], |
79 |
.001, 0x12345678, |
80 |
sub { |
81 |
warn "all ranges pinged\n"; |
82 |
$done->broadcast; |
83 |
} |
84 |
; |
85 |
|
86 |
$done->wait; |
87 |
|
88 |
Net::FPing::register_cb \&cb |
89 |
Register a callback that is called for every received ping reply |
90 |
(regardless of whether a ping is still in process or not and |
91 |
regardless of whether the reply is actually a reply ot a ping sent |
92 |
earlier). |
93 |
|
94 |
The code reference gets a single parameter - an arrayref with an |
95 |
entry for each received packet (replies are beign batched for |
96 |
greater efficiency). Each packet is represented by an arrayref with |
97 |
three members: the source address (an octet string of either 4 |
98 |
(IPv4) or 16 (IPv6) octets length), the payload as passed to |
99 |
"icmp_ping" and the round trip time in seconds. |
100 |
|
101 |
Example: a single ping reply with payload of 1 from "::1" gets |
102 |
passed like this: |
103 |
|
104 |
[ [ |
105 |
"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1", |
106 |
"0.000280141830444336", |
107 |
1 |
108 |
] ] |
109 |
|
110 |
Example: ping replies for 127.0.0.1 and 127.0.0.2, with a payload of |
111 |
0x12345678: |
112 |
|
113 |
[ |
114 |
[ |
115 |
"\177\0\0\1", |
116 |
"0.00015711784362793", |
117 |
305419896 |
118 |
], |
119 |
[ |
120 |
"\177\0\0\2", |
121 |
"0.00090184211731", |
122 |
305419896 |
123 |
] |
124 |
] |
125 |
|
126 |
Net::FPing::unregister_cb \&cb |
127 |
Unregister the callback again (make sure you pass the same |
128 |
codereference as to "register_cb"). |
129 |
|
130 |
AUTHOR |
131 |
Marc Lehmann <schmorp@schmorp.de> |
132 |
http://home.schmorp.de/ |
133 |
|
134 |
AUTHOR |
135 |
This software is distributed under the GENERAL PUBLIC LICENSE, version 2 |
136 |
or any later version or, at your option, the Artistic License. |
137 |
|