.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Traceroute 3pm" .TH Traceroute 3pm "2014-04-06" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Traceroute \- traceroute(1) functionality in perl .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 9 \& use Net::Traceroute; \& $tr = Net::Traceroute\->new(host => "life.ai.mit.edu"); \& if($tr\->found) { \& my $hops = $tr\->hops; \& if($hops > 1) { \& print "Router was " . \& $tr\->hop_query_host($tr\->hops \- 1, 0) . "\en"; \& } \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module implements a parser for various traceroute implementations. At present, it can parse most \s-1LBL\s0 traceroute derivatives used on typical unixes, and the traceroute of cisco \s-1IOS.\s0 Traceroutes known not to be supported include that of Microsoft Windows and HP-UX. .PP This module has two basic modes of operation, one, where it will run traceroute for you, and the other where you provide text from previously runing traceroute to parse. .SH "OVERVIEW" .IX Header "OVERVIEW" A new Net::Traceroute object must be created with the \fInew\fR method. Depending on exactly how the constructor is invoked, it may perform some tracing and/or parsing actions immediately, or it may return a \&\*(L"template\*(R" object that can be used to set parameters for several subsequent traceroutes. .PP Methods are available for accessing information about a given traceroute attempt. There are also methods that view/modify the options that are passed to the object's constructor. .PP To trace a route, \s-1UDP\s0 packets are sent with a small \s-1TTL \s0(time-to-live) field in an attempt to get intervening routers to generate \s-1ICMP TIME_EXCEEDED\s0 messages. .SH "CONSTRUCTOR AND CLONING" .IX Header "CONSTRUCTOR AND CLONING" .Vb 10 \& $obj = Net::Traceroute\->new([base_port => $base_port,] \& [debug => $debuglvl,] \& [max_ttl => $max_ttl,] \& [host => $host,] \& [text => $text,] \& [queries => $queries,] \& [query_timeout => $query_timeout,] \& [timeout => $timeout,] \& [source_address => $srcaddr,] \& [tos => $tos,] \& [packetlen => $packetlen,] \& [trace_program => $program,] \& [no_fragment => $nofrag,] \& [use_icmp => $useicmp,] \& [use_tcp => $usetcp,] \& ); \& $frob = $obj\->clone([options]); .Ve .PP This is the constructor for a new Net::Traceroute object. If given \&\f(CW\*(C`host\*(C'\fR, it will immediately perform the traceroute. If given \f(CW\*(C`text\*(C'\fR, it will parse that text as traceroute output. .PP Given an existing Net::Traceroute object \f(CW$obj\fR as a template, you can call \f(CW$obj\fR\->\fIclone()\fR with the usual constructor parameters. The same rules apply about defining host; that is, traceroute will be run if it is defined, or text will be parsed. You can always pass \&\f(CW\*(C`host =\*(C'\fR undef, text => undef> to clone. .PP Possible options are: .PP \&\fBhost\fR \- A host to traceroute to. If you don't set this, you get a Traceroute object with no traceroute data in it. The module always uses \s-1IP\s0 addresses internally and will attempt to lookup host names via inet_aton. .PP \&\fBtext\fR \- Output from a previously run traceroute. If set, and host isn't, the given text will be parsed. .PP \&\fBbase_port\fR \- Base port number to use for the \s-1UDP\s0 queries. Traceroute assumes that nothing is listening to port \f(CW\*(C`base_port\*(C'\fR to \&\f(CW\*(C`base_port + (nhops \- 1)\*(C'\fR where nhops is the number of hops required to reach the destination address. Default is what the system traceroute uses (normally 33434). \&\f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-p\*(C'\fR option. .PP \&\fBdebuglvl\fR \- A number indicating how verbose debug information should be. Please include debug=>9 output in bug reports. .PP \&\fBmax_ttl\fR \- Maximum number of hops to try before giving up. Default is what the system traceroute uses (normally 30). \f(CW\*(C`Traceroute\*(C'\fR's \&\f(CW\*(C`\-m\*(C'\fR option. .PP \&\fBqueries\fR \- Number of times to send a query for a given hop. Defaults to whatever the system traceroute uses (3 for most traceroutes). \f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-q\*(C'\fR option. .PP \&\fBquery_timeout\fR \- How many seconds to wait for a response to each query sent. Uses the system traceroute's default value of 5 if unspecified. \f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-w\*(C'\fR option. .PP \&\fBtimeout\fR \- Maximum time, in seconds, to wait for the traceroute to complete. If not specified, the traceroute will not return until the host has been reached, or traceroute counts to infinity (\f(CW\*(C`max_ttl\*(C'\fR * \&\f(CW\*(C`queries\*(C'\fR * \f(CW\*(C`query_timeout\*(C'\fR). Note that this option is implemented by Net::Traceroute, not the underlying traceroute command. .PP \&\fBsource_address\fR \- Select the source address that traceroute wil use. .PP \&\fBtos\fR \- Specify a ToS value for traceroute to use. .PP \&\fBpacketlen\fR \- Length of packets to use. Traceroute tries to make the \&\s-1IP\s0 packet exactly this long. .PP \&\fBtrace_program\fR \- Name of the traceroute program. Defaults to traceroute. You can pass traceroute6 to do IPv6 traceroutes. .PP \&\fBno_fragment\fR \- Set the \s-1IP\s0 don't fragment bit. Some traceroute programs will perform path mtu discovery with this option. .PP \&\fBuse_icmp\fR \- Request that traceroute perform probes with \s-1ICMP\s0 echo packets, rather than \s-1UDP.\s0 .PP \&\fBuse_tcp\fR \- Request that traceoute perform probes with \s-1TCP\s0 SYNs. .SH "METHODS" .IX Header "METHODS" .IP "traceroute" 4 .IX Item "traceroute" Run system traceroute, and parse the results. Will fill in the rest of the object for informational queries. .IP "parse" 4 .IX Item "parse" Parse the previously provided \f(CW\*(C`text\*(C'\fR, filling in the rest of the object for queries. .IP "argv" 4 .IX Item "argv" Returns a list of arguments that traceroute will be invoked with. For debugging and/or overriding by subclasses. .SS "Controlling traceroute invocation" .IX Subsection "Controlling traceroute invocation" Each of these methods return the current value of the option specified by the corresponding constructor option. They will set the object's instance variable to the given value if one is provided. .PP Changing an instance variable will only affect newly performed traceroutes. Setting a different value on a traceroute object that has already performed a trace has no effect. .PP See the constructor documentation for information about methods that aren't documented here. .IP "base_port([\s-1PORT\s0])" 4 .IX Item "base_port([PORT])" .PD 0 .IP "max_ttl([\s-1PORT\s0])" 4 .IX Item "max_ttl([PORT])" .IP "queries([\s-1QUERIES\s0])" 4 .IX Item "queries([QUERIES])" .IP "query_timeout([\s-1TIMEOUT\s0])" 4 .IX Item "query_timeout([TIMEOUT])" .IP "host([\s-1HOST\s0])" 4 .IX Item "host([HOST])" .IP "text([\s-1TEXT\s0])" 4 .IX Item "text([TEXT])" .IP "timeout([\s-1TIMEOUT\s0])" 4 .IX Item "timeout([TIMEOUT])" .IP "source_address([\s-1SRC\s0])" 4 .IX Item "source_address([SRC])" .IP "packetlen([\s-1LEN\s0])" 4 .IX Item "packetlen([LEN])" .IP "trace_program([\s-1PROGRAM\s0])" 4 .IX Item "trace_program([PROGRAM])" .IP "no_fragment([\s-1PROGRAM\s0])" 4 .IX Item "no_fragment([PROGRAM])" .PD .SS "Obtaining information about a Trace" .IX Subsection "Obtaining information about a Trace" These methods return information about a traceroute that has already been performed. .PP Any of the methods in this section that return a count of something or want an \fIN\fRth type count to identify something employ one based counting. .IP "stat" 4 .IX Item "stat" Returns the status of a given traceroute object. One of \&\s-1TRACEROUTE_OK, TRACEROUTE_TIMEOUT,\s0 or \s-1TRACEROUTE_UNKNOWN \s0(each defined as an integer). \s-1TRACEROUTE_OK\s0 will only be returned if the host was actually reachable. .IP "found" 4 .IX Item "found" Attempt to return 1 if the host was found, undef otherwise. This test is a poor heuristic, and will frequently give wrong answers. .IP "pathmtu" 4 .IX Item "pathmtu" If your traceroute supports \s-1MTU\s0 discovery, this method will return the \&\s-1MTU\s0 in some circumstances. You must set no_fragment, and must use a packetlen larger than the path mtu for this to be set. .IP "hops" 4 .IX Item "hops" Returns the number of hops that it took to reach the host. .IP "hop_queries(\s-1HOP\s0)" 4 .IX Item "hop_queries(HOP)" Returns the number of queries that were sent for a given hop. This should normally be the same for every query. .IP "hop_query_stat(\s-1HOP, QUERY\s0)" 4 .IX Item "hop_query_stat(HOP, QUERY)" Return the status of the given \s-1HOP\s0's \s-1QUERY. \s0 The return status can be one of the following (each of these is actually an integer constant function defined in Net::Traceroute's export list): .Sp \&\s-1QUERY\s0 can be zero, in which case the first successful query will be returned. .RS 4 .IP "\s-1TRACEROUTE_OK\s0" 4 .IX Item "TRACEROUTE_OK" Reached the host, no problems. .IP "\s-1TRACEROUTE_TIMEOUT\s0" 4 .IX Item "TRACEROUTE_TIMEOUT" This query timed out. .IP "\s-1TRACEROUTE_UNKNOWN\s0" 4 .IX Item "TRACEROUTE_UNKNOWN" Your guess is as good as mine. Shouldn't happen too often. .IP "\s-1TRACEROUTE_UNREACH_NET\s0" 4 .IX Item "TRACEROUTE_UNREACH_NET" This hop returned an \s-1ICMP\s0 Network Unreachable. .IP "\s-1TRACEROUTE_UNREACH_HOST\s0" 4 .IX Item "TRACEROUTE_UNREACH_HOST" This hop returned an \s-1ICMP\s0 Host Unreachable. .IP "\s-1TRACEROUTE_UNREACH_PROTO\s0" 4 .IX Item "TRACEROUTE_UNREACH_PROTO" This hop returned an \s-1ICMP\s0 Protocol unreachable. .IP "\s-1TRACEROUTE_UNREACH_PORT\s0" 4 .IX Item "TRACEROUTE_UNREACH_PORT" Use in cisco and traceroute6 parsing. In cisco, \*(L"!U\*(R", in traceroute6, a \*(L"!\*(R". .IP "\s-1TRACEROUTE_UNREACH_ADDR\s0" 4 .IX Item "TRACEROUTE_UNREACH_ADDR" This hop returned an \s-1ICMP6\s0 address unreachable. .IP "\s-1TRACEROUTE_UNREACH_NEEDFRAG\s0" 4 .IX Item "TRACEROUTE_UNREACH_NEEDFRAG" Indicates that you can't reach this host without fragmenting your packet further. Shouldn't happen in regular use. .IP "\s-1TRACEROUTE_UNREACH_SRCFAIL\s0" 4 .IX Item "TRACEROUTE_UNREACH_SRCFAIL" A source routed packet was rejected for some reason. Shouldn't happen. .IP "\s-1TRACEROUTE_UNREACH_FILTER_PROHIB\s0" 4 .IX Item "TRACEROUTE_UNREACH_FILTER_PROHIB" A firewall or similar device has decreed that your traffic is disallowed by administrative action. Suspect sheer, raving paranoia. .IP "\s-1TRACEROUTE_BSDBUG\s0" 4 .IX Item "TRACEROUTE_BSDBUG" The destination machine appears to exhibit the 4.[23]BSD time exceeded bug. .IP "\s-1TRACEROUTE_SOURCE_QUENCH\s0" 4 .IX Item "TRACEROUTE_SOURCE_QUENCH" Some machine has generated an \s-1ICMP\s0 Source Quench message, asking you to slow down. .IP "\s-1TRACEROUTE_INTERRUPTED\s0" 4 .IX Item "TRACEROUTE_INTERRUPTED" \&\*(L"User interrupted test\*(R". Cisco's traceroute does this. Its unclear how to produce it. .RE .RS 4 .RE .IP "hop_query_host(\s-1HOP, QUERY\s0)" 4 .IX Item "hop_query_host(HOP, QUERY)" Return the dotted quad \s-1IP\s0 address of the host that responded to \s-1HOP\s0's \&\s-1QUERY.\s0 .Sp \&\s-1QUERY\s0 can be zero, in which case the first successful query will be returned. .IP "hop_query_time(\s-1HOP, QUERY\s0)" 4 .IX Item "hop_query_time(HOP, QUERY)" Return the round trip time associated with the given \s-1HOP\s0's query. If your system's traceroute supports fractional second timing, so will Net::Traceroute. .Sp \&\s-1QUERY\s0 can be zero, in which case the first successful query will be returned. .SH "CLONING SUPPORT BEFORE 1.04" .IX Header "CLONING SUPPORT BEFORE 1.04" Net::Traceroute Versions before 1.04 used new to clone objects. This has been deprecated in favor of the \fIclone()\fR method. .PP If you have code of the form: .PP .Vb 2 \& my $template = Net::Traceroute\->new(); \& my $tr = $template\->new(host => "localhost"); .Ve .PP You need to change the \f(CW$template\fR\->new to \f(CW$template\fR\->clone. .PP This behavior was changed because it interfered with subclassing. .SH "BUGS" .IX Header "BUGS" Net::Traceroute parses the output of the system traceroute command. As such, it may not work on your system. Support for more traceroute outputs (e.g. Windows, \s-1HPUX\s0) could be done, although currently the code assumes there is \*(L"One true traceroute\*(R". .PP The actual functionality of traceroute could also be implemented natively in perl or linked in from a C library. .PP Versions prior to 1.04 had some interface issues for subclassing. These issues have been addressed, but required a public interface change. If you were relying on the behavior of new to clone existing objects, your code needs to be fixed. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fItraceroute\fR\|(1) .SH "AUTHOR" .IX Header "AUTHOR" Daniel Hagerty .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 1998, 1999 Massachusetts Institute of Technology Copyright 2000, 2001 Daniel Hagerty .PP Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided \*(L"as is\*(R" without express or implied warranty.