Provided by: libnet-traceroute-perl_1.15-1_all 
NAME
Net::Traceroute - traceroute(1) functionality in perl
SYNOPSIS
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) . "\n";
}
}
DESCRIPTION
This module implements a parser for various traceroute implementations. At present, it
can parse most LBL traceroute derivatives used on typical unixes, and the traceroute of
cisco IOS. Traceroutes known not to be supported include that of Microsoft Windows and
HP-UX.
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.
OVERVIEW
A new Net::Traceroute object must be created with the new method. Depending on exactly
how the constructor is invoked, it may perform some tracing and/or parsing actions
immediately, or it may return a "template" object that can be used to set parameters for
several subsequent traceroutes.
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.
To trace a route, UDP packets are sent with a small TTL (time-to-live) field in an attempt
to get intervening routers to generate ICMP TIME_EXCEEDED messages.
CONSTRUCTOR AND CLONING
$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]);
This is the constructor for a new Net::Traceroute object. If given "host", it will
immediately perform the traceroute. If given "text", it will parse that text as
traceroute output.
Given an existing Net::Traceroute object $obj as a template, you can call $obj->clone()
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
"host =" undef, text => undef> to clone.
Possible options are:
host - 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 IP addresses internally and will attempt
to lookup host names via inet_aton.
text - Output from a previously run traceroute. If set, and host isn't, the given text
will be parsed.
base_port - Base port number to use for the UDP queries. Traceroute assumes that nothing
is listening to port "base_port" to "base_port + (nhops - 1)" where nhops is the number of
hops required to reach the destination address. Default is what the system traceroute
uses (normally 33434). "Traceroute"'s "-p" option.
debuglvl - A number indicating how verbose debug information should be. Please include
debug=>9 output in bug reports.
max_ttl - Maximum number of hops to try before giving up. Default is what the system
traceroute uses (normally 30). "Traceroute"'s "-m" option.
queries - Number of times to send a query for a given hop. Defaults to whatever the
system traceroute uses (3 for most traceroutes). "Traceroute"'s "-q" option.
query_timeout - How many seconds to wait for a response to each query sent. Uses the
system traceroute's default value of 5 if unspecified. "Traceroute"'s "-w" option.
timeout - 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 ("max_ttl" * "queries" * "query_timeout"). Note that this option is
implemented by Net::Traceroute, not the underlying traceroute command.
source_address - Select the source address that traceroute wil use.
tos - Specify a ToS value for traceroute to use.
packetlen - Length of packets to use. Traceroute tries to make the IP packet exactly this
long.
trace_program - Name of the traceroute program. Defaults to traceroute. You can pass
traceroute6 to do IPv6 traceroutes.
no_fragment - Set the IP don't fragment bit. Some traceroute programs will perform path
mtu discovery with this option.
use_icmp - Request that traceroute perform probes with ICMP echo packets, rather than UDP.
use_tcp - Request that traceoute perform probes with TCP SYNs.
METHODS
traceroute
Run system traceroute, and parse the results. Will fill in the rest of the object for
informational queries.
parse
Parse the previously provided "text", filling in the rest of the object for queries.
argv
Returns a list of arguments that traceroute will be invoked with. For debugging
and/or overriding by subclasses.
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.
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.
See the constructor documentation for information about methods that aren't documented
here.
base_port([PORT])
max_ttl([PORT])
queries([QUERIES])
query_timeout([TIMEOUT])
host([HOST])
text([TEXT])
timeout([TIMEOUT])
source_address([SRC])
packetlen([LEN])
trace_program([PROGRAM])
no_fragment([PROGRAM])
Obtaining information about a Trace
These methods return information about a traceroute that has already been performed.
Any of the methods in this section that return a count of something or want an Nth type
count to identify something employ one based counting.
stat
Returns the status of a given traceroute object. One of TRACEROUTE_OK,
TRACEROUTE_TIMEOUT, or TRACEROUTE_UNKNOWN (each defined as an integer). TRACEROUTE_OK
will only be returned if the host was actually reachable.
found
Attempt to return 1 if the host was found, undef otherwise. This test is a poor
heuristic, and will frequently give wrong answers.
pathmtu
If your traceroute supports MTU discovery, this method will return the MTU in some
circumstances. You must set no_fragment, and must use a packetlen larger than the
path mtu for this to be set.
hops
Returns the number of hops that it took to reach the host.
hop_queries(HOP)
Returns the number of queries that were sent for a given hop. This should normally be
the same for every query.
hop_query_stat(HOP, QUERY)
Return the status of the given HOP's QUERY. 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):
QUERY can be zero, in which case the first successful query will be returned.
TRACEROUTE_OK
Reached the host, no problems.
TRACEROUTE_TIMEOUT
This query timed out.
TRACEROUTE_UNKNOWN
Your guess is as good as mine. Shouldn't happen too often.
TRACEROUTE_UNREACH_NET
This hop returned an ICMP Network Unreachable.
TRACEROUTE_UNREACH_HOST
This hop returned an ICMP Host Unreachable.
TRACEROUTE_UNREACH_PROTO
This hop returned an ICMP Protocol unreachable.
TRACEROUTE_UNREACH_PORT
Use in cisco and traceroute6 parsing. In cisco, "!U", in traceroute6, a "!".
TRACEROUTE_UNREACH_ADDR
This hop returned an ICMP6 address unreachable.
TRACEROUTE_UNREACH_NEEDFRAG
Indicates that you can't reach this host without fragmenting your packet further.
Shouldn't happen in regular use.
TRACEROUTE_UNREACH_SRCFAIL
A source routed packet was rejected for some reason. Shouldn't happen.
TRACEROUTE_UNREACH_FILTER_PROHIB
A firewall or similar device has decreed that your traffic is disallowed by
administrative action. Suspect sheer, raving paranoia.
TRACEROUTE_BSDBUG
The destination machine appears to exhibit the 4.[23]BSD time exceeded bug.
TRACEROUTE_SOURCE_QUENCH
Some machine has generated an ICMP Source Quench message, asking you to slow down.
TRACEROUTE_INTERRUPTED
"User interrupted test". Cisco's traceroute does this. Its unclear how to
produce it.
hop_query_host(HOP, QUERY)
Return the dotted quad IP address of the host that responded to HOP's QUERY.
QUERY can be zero, in which case the first successful query will be returned.
hop_query_time(HOP, QUERY)
Return the round trip time associated with the given HOP's query. If your system's
traceroute supports fractional second timing, so will Net::Traceroute.
QUERY can be zero, in which case the first successful query will be returned.
CLONING SUPPORT BEFORE 1.04
Net::Traceroute Versions before 1.04 used new to clone objects. This has been deprecated
in favor of the clone() method.
If you have code of the form:
my $template = Net::Traceroute->new();
my $tr = $template->new(host => "localhost");
You need to change the $template->new to $template->clone.
This behavior was changed because it interfered with subclassing.
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, HPUX) could be
done, although currently the code assumes there is "One true traceroute".
The actual functionality of traceroute could also be implemented natively in perl or
linked in from a C library.
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.
SEE ALSO
traceroute(1)
AUTHOR
Daniel Hagerty <hag@ai.mit.edu>
COPYRIGHT
Copyright 1998, 1999 Massachusetts Institute of Technology Copyright 2000, 2001 Daniel
Hagerty
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 "as is" without express or implied warranty.