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