1
2Net::Traceroute:PurePerl - traceroute(1) functionality in perl via raw sockets
3
4VERSION
5 This document describes version 0.10 of Net::Traceroute::PurePerl.
6
7SYNOPSIS
8 use Net::Traceroute::PurePerl;
9
10 my $t = new Net::Traceroute::PurePerl(
11 backend => 'PurePerl', # this optional
12 host => 'www.openreach.com',
13 debug => 0,
14 max_ttl => 12,
15 query_timeout => 2,
16 packetlen => 40,
17 protocol => 'udp', # Or icmp
18 );
19 $t->traceroute;
20 $t->pretty_print;
21
22DESCRIPTION
23 This module implements traceroute(1) functionality for perl5. It allows
24 you to trace the path IP packets take to a destination. It is
25 implemented by using raw sockets to act just like the regular
26 traceroute.
27
28 You must also be root to use the raw sockets.
29
30INSTALLATION
31 Basic Installation
32 Net::Traceroute::PurePerl may be installed through the CPAN shell in the
33 usual CPAN shell manner. This typically is:
34
35 $ perl -MCPAN -e 'install Net::Traceroute::PurePerl'
36
37 You can also read this README from the CPAN shell:
38
39 $ perl -MCPAN -e shell
40 cpan> readme Net::Traceroute::PurePerl
41
42 And you can install the module from the CPAN prompt as well:
43
44 cpan> install Net::Traceroute::PurePerl
45
46 Manual Installation
47 Net::Traceroute::PurePerl can also be installed manually.
48 <ftp://ftp-mirror.internap.com/pub/CPAN/authors/id/A/AH/AHOYING/> or a
49 similarly named directory at your favorite CPAN mirror should hold the
50 latest version.
51
52 Downloading and unpacking the distribution are left up to the reader.
53
54 To build and test it:
55
56 perl Makefile.PL
57 make
58 make test
59
60 The test program, t/01_trace.t, makes an excellent sample program. It
61 was adapted from the code used to test and develop this module. There
62 may be additional sample programs in the examples folder.
63
64 When you are ready to install the module:
65
66 make install
67
68 It should now be ready to use.
69
70OVERVIEW
71 A new Net::Traceroute::PurePerl object must be created with the *new*
72 method. This will not perform the traceroute immediately, unlike
73 Net::Traceroute. It will return a "template" object that can be used to
74 set parameters for several subsequent traceroutes.
75
76 Methods are available for accessing information about a given traceroute
77 attempt. There are also methods that view/modify the options that are
78 passed to the object's constructor.
79
80 To trace a route, UDP or ICMP packets are sent with a small TTL
81 (time-to-live) field in an attempt to get intervening routers to
82 generate ICMP TIME_EXCEEDED messages.
83
84VERSION CHANGES
85 This version of Net::Traceroute::PurePerl is a complete rewrite of the
86 internal traceroute code used in the 0.02 release. As such a number of
87 new capabilities have been introduced, and probably a number of bugs as
88 well.
89
90 The public methods have remained unchanged, and this should be a drop in
91 replacement for the older version.
92
93 This version no longer resolves router IPs to host names in the
94 traceroute code. If you need the IP resolved you have to do it from your
95 code, or use the pretty_print method with a positive value passed as an
96 argument.
97
98 The current version does not correctly detect network unreachable and
99 other nonstandard ICMP errors. This can lead to problems on networks
100 where these errors are sent instead of a port unreachable or ttl
101 exceeded packet.
102
103CONSTRUCTOR
104 $obj = Net::Traceroute::PurePerl->new(
105 [base_port => $base_port,]
106 [debug => $debuglvl,]
107 [max_ttl => $max_ttl,]
108 [host => $host,]
109 [queries => $queries,]
110 [query_timeout => $query_timeout,]
111 [source_address => $srcaddr,]
112 [packetlen => $packetlen,]
113 [concurrent_hops => $concurrent,]
114 [first_hop => $first_hop,]
115 [device => $device,]
116 [protocol => $protocol,]
117 );
118
119 This is the constructor for a new Net::Traceroute object. If given
120 "host", it will NOT actually perform the traceroute. You MUST call the
121 traceroute method later.
122
123 Possible options are:
124
125 host - A host to traceroute to. If you don't set this, you get a
126 Traceroute object with no traceroute data in it. The module always uses
127 IP addresses internally and will attempt to lookup host names via
128 inet_aton.
129
130 base_port - Base port number to use for the UDP queries. Traceroute
131 assumes that nothing is listening to port "base_port" to "base_port +
132 (nhops * nqueries - 1)" where nhops is the number of hops required to
133 reach the destination address and nqueries is the number of queries per
134 hop. Default is what the system traceroute uses (normally 33434)
135 "Traceroute"'s "-p" option.
136
137 debuglvl - A number indicating how verbose debug information should be.
138 Please include debug=>9 output in bug reports.
139
140 max_ttl - Maximum number of hops to try before giving up. Default is
141 what the system traceroute uses (normally 30). "Traceroute"'s "-m"
142 option.
143
144 queries - Number of times to send a query for a given hop. Defaults to
145 whatever the system traceroute uses (3 for most traceroutes).
146 "Traceroute"'s "-q" option.
147
148 query_timeout - How many seconds to wait for a response to each query
149 sent. Uses the system traceroute's default value of 5 if unspecified.
150 "Traceroute"'s "-w" option.
151
152 timeout - unused here
153
154 source_address - Select the source address that traceroute will use.
155 "Traceroute"'s "-S" option.
156
157 packetlen - Length of packets to use. Traceroute tries to make the IP
158 packet exactly this long.
159
160 trace_program - unused here
161
162 no_fragment - unused at the moment
163
164 use_alarm - unused in this version
165
166 protocol - Either ICMP or UDP. ICMP uses ICMP echo packets with
167 incrementing sequence numbers, while UDP uses USP packets with
168 incrementing ports. It defaults to udp.
169
170 concurrent_hops - This is the maximum number of outstanding packets sent
171 at one time. Setting this to a high number may overflow your socket
172 receive buffer and slightly delay the processing of response packets,
173 making the round trip time reported slightly higher, however it will
174 significantly decrease the amount of time it takes to run a traceroute.
175 Defaults to 6. "Traceroute"'s "-N" option.
176
177 first_hop - This is the lowest TTL to use. Setting this will skip the
178 first x routers in the path, especially useful if they never change.
179 Defaults to 1. "Traceroute"'s "-f" option.
180
181 device - The device to send the packet from. Normally this is determined
182 by the system's routing table, but it can be overridden. It defaults to
183 undef. "Traceroute"'s "-I" option.
184
185METHODS
186 traceroute
187 Run the traceroute. Will fill in the rest of the object for
188 informational queries.
189
190 The traceroute method is a blocking call. It will not return until
191 the max_ttl is reached or the host is reached. As such, if your
192 program is time dependent the call should be wrapped in an eval with
193 an ALARM set.
194
195 eval {
196 local $SIG{ALRM} = sub { die "alarm" };
197 alarm $timeout;
198 $success = $t->traceroute();
199 alarm 0;
200 }
201 warn "Traceroute timed out\n" if ($@ and $@ eq "alarm");
202
203 Returns 1 if the host was reached, or 0 if it wasn't.
204
205 Controlling traceroute invocation
206 Each of these methods return the current value of the option specified
207 by the corresponding constructor option. They will set the object's
208 instance variable to the given value if one is provided.
209
210 Changing an instance variable will only affect newly performed
211 traceroutes. Setting a different value on a traceroute object that has
212 already performed a trace has no effect.
213
214 See the constructor documentation for information about methods that
215 aren't documented here.
216
217 base_port([PORT])
218 max_ttl([PORT])
219 queries([QUERIES])
220 query_timeout([TIMEOUT])
221 host([HOST])
222 source_address([SRC])
223 packetlen([LEN])
224 use_alarm([0|1])
225 protocl([PROTOCOL])
226 concurrent_hops([CONCURRENT])
227 first_hop([FIRST_HOP])
228 device([DEVICE])
229
230 Obtaining information about a Trace
231 These methods return information about a traceroute that has already
232 been performed.
233
234 Any of the methods in this section that return a count of something or
235 want an *N*th type count to identify something employ one based
236 counting.
237
238 pretty_print
239 Prints to stdout a traceroute-like text. Tries to mimic
240 traceroute(1)'s output as close as possible with a few exceptions.
241 First, the columns are easier to read, and second, a new line is
242 started if the host IP changes instead of printing the new IP
243 inline. The first column stays the same hop number, only the host
244 changes.
245
246 Passing in an argument of 1 will make pretty_print resolve the names
247 of the router ips, otherwise they are printed as raw ip addresses,
248 like "Traceroute"'s "-n" option.
249
250 stat
251 Returns the status of a given traceroute object. One of
252 TRACEROUTE_OK, TRACEROUTE_TIMEOUT, or TRACEROUTE_UNKNOWN (each
253 defined as an integer). TRACEROUTE_OK will only be returned if the
254 host was actually reachable.
255
256 found
257 Returns 1 if the host was found, undef otherwise.
258
259 pathmtu
260 If your traceroute supports MTU discovery, this method will return
261 the MTU in some circumstances. You must set no_fragment, and must
262 use a packetlen larger than the path mtu for this to be set.
263
264 NOTE: This doesn't work with this version.
265
266 hops
267 Returns the number of hops that it took to reach the host.
268
269 hop_queries(HOP)
270 Returns the number of queries that were sent for a given hop. This
271 should normally be the same for every query.
272
273 hop_query_stat(HOP, QUERY)
274 Return the status of the given HOP's QUERY. The return status can be
275 one of the following (each of these is actually an integer constant
276 function defined in Net::Traceroute's export list):
277
278 QUERY can be zero, in which case the first succesful query will be
279 returned.
280
281 TRACEROUTE_OK
282 Reached the host, no problems.
283
284 TRACEROUTE_TIMEOUT
285 This query timed out.
286
287 TRACEROUTE_UNKNOWN
288 Your guess is as good as mine. Shouldn't happen too often.
289
290 TRACEROUTE_UNREACH_NET
291 This hop returned an ICMP Network Unreachable.
292
293 TRACEROUTE_UNREACH_HOST
294 This hop returned an ICMP Host Unreachable.
295
296 TRACEROUTE_UNREACH_PROTO
297 This hop returned an ICMP Protocol unreachable.
298
299 TRACEROUTE_UNREACH_NEEDFRAG
300 Indicates that you can't reach this host without fragmenting
301 your packet further. Shouldn't happen in regular use.
302
303 TRACEROUTE_UNREACH_SRCFAIL
304 A source routed packet was rejected for some reason. Shouldn't
305 happen.
306
307 TRACEROUTE_UNREACH_FILTER_PROHIB
308 A firewall or similar device has decreed that your traffic is
309 disallowed by administrative action. Suspect sheer, raving
310 paranoia.
311
312 TRACEROUTE_BSDBUG
313 The destination machine appears to exhibit the 4.[23]BSD time
314 exceeded bug.
315
316 hop_query_host(HOP, QUERY)
317 Return the dotted quad IP address of the host that responded to
318 HOP's QUERY.
319
320 QUERY can be zero, in which case the first succesful query will be
321 returned.
322
323 hop_query_time(HOP, QUERY)
324 Return the round trip time associated with the given HOP's query. If
325 your system's traceroute supports fractional second timing, so will
326 Net::Traceroute.
327
328 QUERY can be zero, in which case the first succesful query will be
329 returned.
330
331BUGS and LIMITATIONS
332 I have not tested the cloning functions of Net::Traceroute::PurePerl. It
333 ought to work, but if not, BUG me.
334
335 This module requires root or administrative privileges to run. It opens
336 a raw socket to listen for TTL exceeded messages. Take appropriate
337 precautions.
338
339 Windows only supports ICMP traceroutes. This may change in a future
340 release, but it is a real pain since Windows doesn't send ICMP error
341 messages to applications for other protocols unless the socket is in
342 promiscous mode. :(
343
344 The current version does not correctly detect network unreachable and
345 other nonstandard ICMP errors. This can lead to problems on networks
346 where these errors are sent instead of a port unreachable or ttl
347 exceeded packet.
348
349 The current version does not support Net::Traceroute's clone method.
350 Calling clone will create an object that is unusable at this point.
351
352TODO
353 * Implement IPv6 capability.
354
355 * Implement TCP traceroute.
356
357 * Fix bugs listed above.
358
359SEE ALSO
360 traceroute(1)
361
362 This module's traceroute code was heavily influenced by "Net::Ping".
363
364 See the examples folder and the test programs for more examples of this
365 module in action.
366
367AUTHOR
368 Tom Scanlan <tscanlan@openreach.com> owner Net::Traceroute::PurePerl
369
370 Andrew Hoying <ahoying@cpan.org> current co-maintainer of
371 Net::Traceroute::PurePerl. Any bugs in this release are mine, please
372 send me the bug reports.
373
374 Daniel Hagerty <hag@ai.mit.edu> owner of Net::Traceroute and input on
375 this fella
376
377COPYRIGHT
378 Go right ahead and copy it. 2002 Tom Scanlan. Copyright 2006 by Andrew
379 Hoying. Don't blame me for damages, just the bugs.
380
381 Net::Traceroute::PurePerl is free software; you may redistribute it and
382 or modify it under the same terms as Perl itself.
383
384