NAME
Net::Traceroute:PurePerl - traceroute(1) functionality in perl via raw sockets
SYNOPSIS
use Net::Traceroute::PurePerl;
my $t = new Net::Traceroute::PurePerl(
backend => 'PurePerl', # this optional
host => 'www.openreach.com',
debug => 0,
max_ttl => 12,
timeout => 2,
packetlen => 40,
use_alarm => 1,
);
$t->traceroute;
$t->pretty_print;DESCRIPTION
This module implements traceroute(1) functionality for perl5. It allows you to trace the path IP packets take to a destination. It is implemented by using raw sockets to act just like the regular traceroute. You must have Net::RawIP installed. You must also be root to use the raw sockets.
OVERVIEW
A new Net::Traceroute::PurePerl object must be created with the new method. This will not perform the traceroute immediately, unlike Net::Traceroute. It will 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::PurePerl->new([base_port => $base_port,]
[debug => $debuglvl,]
[max_ttl => $max_ttl,]
[host => $host,]
[queries => $queries,]
[query_timeout => $query_timeout,]
[timeout => $timeout,]
[source_address => $srcaddr,]
[packetlen => $packetlen,]
[trace_program => $program,]
[no_fragment => $nofrag,]);
[use_alarm => $use_alarm,]);
$frob = $obj->clone([options]);This is the constructor for a new Net::Traceroute object. If given host, it will NOT actually perform the traceroute. You MUST call the traceroute method later.
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. You can always pass host => 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.
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 * nqueries - 1) where nhops is the number of hops required to reach the destination address and nqueries is the number of queries per hop. 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 - unused here
source_address - Select the source address that traceroute wil use.
packetlen - Length of packets to use. Traceroute tries to make the IP packet exactly this long.
trace_program - unused here
no_fragment - unused at the moment
use_alarm - Used to make sure the queries timeout as needed. If your trace seems to hang with this set to 0, set it to 1 and you should be good to go.
METHODS
- traceroute
-
Run the traceroute. Will fill in the rest of the object for informational queries.
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])
- source_address([SRC])
- packetlen([LEN])
- trace_program([PROGRAM])
- use_alarm([0|1])
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.
- pretty_print
-
Prints to stdout a traceroute-like text.
- 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
-
Returns 1 if the host was found, undef otherwise.
- 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 succesful 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_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.
- 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 succesful 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 succesful query will be returned.
CLONING SUPPORT
BUGS
I have not tested the cloning functions of Net::Traceroute::PurePerl. It ought to work, but if not, BUG me.
This has not been tested on windows, so please let me know if it works there.
You must have Net::RawIP, because I'm too lazy to re-invent the wheel. As such, we have all the bugs that Net::RawIP has.
SEE ALSO
traceroute(1)
AUTHOR
Tom Scanlan <tscanlan@openreach.com> owner Net::Traceroute::PurePerl
Daniel Hagerty <hag@ai.mit.edu> owner of Net::Traceroute and input on this fella
COPYRIGHT
Go right ahead and copy it. 2002 Tom Scanlan. Don't blame me for damages, just the bugs.