.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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 >0, 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
.\" ========================================================================
.\"
.IX Title "PurePerl 3pm"
.TH PurePerl 3pm "2022-07-03" "perl v5.34.0" "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:PurePerl \- traceroute(1) functionality in perl via raw sockets
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.10 of Net::Traceroute::PurePerl.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Net::Traceroute::PurePerl;
\&
\& my $t = new Net::Traceroute::PurePerl(
\& backend => \*(AqPurePerl\*(Aq, # this optional
\& host => \*(Aqwww.openreach.com\*(Aq,
\& debug => 0,
\& max_ttl => 12,
\& query_timeout => 2,
\& packetlen => 40,
\& protocol => \*(Aqudp\*(Aq, # Or icmp
\& );
\& $t\->traceroute;
\& $t\->pretty_print;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements \fBtraceroute\fR\|(1) functionality for perl5.
It allows you to trace the path \s-1IP\s0 packets take to a destination.
It is implemented by using raw sockets to act just like the regular traceroute.
.PP
You must also be root to use the raw sockets.
.SH "INSTALLATION"
.IX Header "INSTALLATION"
.SS "Basic Installation"
.IX Subsection "Basic Installation"
Net::Traceroute::PurePerl may be installed through the \s-1CPAN\s0 shell
in the usual \s-1CPAN\s0 shell manner. This typically is:
.PP
.Vb 1
\& $ perl \-MCPAN \-e \*(Aqinstall Net::Traceroute::PurePerl\*(Aq
.Ve
.PP
You can also read this \s-1README\s0 from the \s-1CPAN\s0 shell:
.PP
.Vb 2
\& $ perl \-MCPAN \-e shell
\& cpan> readme Net::Traceroute::PurePerl
.Ve
.PP
And you can install the module from the \s-1CPAN\s0 prompt as well:
.PP
.Vb 1
\& cpan> install Net::Traceroute::PurePerl
.Ve
.SS "Manual Installation"
.IX Subsection "Manual Installation"
Net::Traceroute::PurePerl can also be installed manually.
or a
similarly named directory at your favorite \s-1CPAN\s0 mirror should hold the
latest version.
.PP
Downloading and unpacking the distribution are left up to the reader.
.PP
To build and test it:
.PP
.Vb 3
\& perl Makefile.PL
\& make
\& make test
.Ve
.PP
The test program, t/01_trace.t, makes an excellent sample program. It was
adapted from the code used to test and develop this module. There may be
additional sample programs in the examples folder.
.PP
When you are ready to install the module:
.PP
.Vb 1
\& make install
.Ve
.PP
It should now be ready to use.
.SH "OVERVIEW"
.IX Header "OVERVIEW"
A new Net::Traceroute::PurePerl object must be created with the \fInew\fR method.
This will not perform the traceroute immediately, unlike Net::Traceroute.
It will 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 or \s-1ICMP\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 "VERSION CHANGES"
.IX Header "VERSION CHANGES"
This version of Net::Traceroute::PurePerl is a complete rewrite of the internal
traceroute code used in the 0.02 release. As such a number of new capabilities
have been introduced, and probably a number of bugs as well.
.PP
The public methods have remained unchanged, and this should be a drop in
replacement for the older version.
.PP
This version no longer resolves router IPs to host names in the traceroute
code. If you need the \s-1IP\s0 resolved you have to do it from your code, or use
the pretty_print method with a positive value passed as an argument.
.PP
The current version does not correctly detect network unreachable and
other nonstandard \s-1ICMP\s0 errors. This can lead to problems on networks where
these errors are sent instead of a port unreachable or ttl exceeded packet.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Vb 10
\& $obj = Net::Traceroute::PurePerl\->new(
\& [base_port => $base_port,]
\& [debug => $debuglvl,]
\& [max_ttl => $max_ttl,]
\& [host => $host,]
\& [queries => $queries,]
\& [query_timeout => $query_timeout,]
\& [source_address => $srcaddr,]
\& [packetlen => $packetlen,]
\& [concurrent_hops => $concurrent,]
\& [first_hop => $first_hop,]
\& [device => $device,]
\& [protocol => $protocol,]
\& );
.Ve
.PP
This is the constructor for a new Net::Traceroute object.
If given \f(CW\*(C`host\*(C'\fR, it will \s-1NOT\s0 actually perform the traceroute.
You \s-1MUST\s0 call the traceroute method later.
.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
\&\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 * nqueries \- 1)\*(C'\fR
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)
\&\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 \- unused here
.PP
\&\fBsource_address\fR \- Select the source address that traceroute will use.
\&\f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-S\*(C'\fR option.
.PP
\&\fBpacketlen\fR \- Length of packets to use. Traceroute tries to make the
\&\s-1IP\s0 packet exactly this long.
.PP
\&\fBtrace_program\fR \- unused here
.PP
\&\fBno_fragment\fR \- unused at the moment
.PP
\&\fBuse_alarm\fR \- unused in this version
.PP
\&\fBprotocol\fR \- Either \s-1ICMP\s0 or \s-1UDP. ICMP\s0 uses \s-1ICMP\s0 echo packets with incrementing
sequence numbers, while \s-1UDP\s0 uses \s-1USP\s0 packets with incrementing ports. It
defaults to udp.
.PP
\&\fBconcurrent_hops\fR \- This is the maximum number of outstanding packets sent
at one time. Setting this to a high number may overflow your socket receive
buffer and slightly delay the processing of response packets, making the
round trip time reported slightly higher, however it will significantly
decrease the amount of time it takes to run a traceroute. Defaults to 6.
\f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-N\*(C'\fR option.
.PP
\&\fBfirst_hop\fR \- This is the lowest \s-1TTL\s0 to use. Setting this will skip the
first x routers in the path, especially useful if they never change. Defaults
to 1. \f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-f\*(C'\fR option.
.PP
\&\fBdevice\fR \- The device to send the packet from. Normally this is determined
by the system's routing table, but it can be overridden. It defaults to undef.
\f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-I\*(C'\fR option.
.SH "METHODS"
.IX Header "METHODS"
.IP "traceroute" 4
.IX Item "traceroute"
Run the traceroute.
Will fill in the rest of the object for informational queries.
.Sp
The traceroute method is a blocking call. It will not return until the max_ttl
is reached or the host is reached. As such, if your program is time dependent
the call should be wrapped in an eval with an \s-1ALARM\s0 set.
.Sp
.Vb 7
\& eval {
\& local $SIG{ALRM} = sub { die "alarm" };
\& alarm $timeout;
\& $success = $t\->traceroute();
\& alarm 0;
\& }
\& warn "Traceroute timed out\en" if ($@ and $@ eq "alarm");
.Ve
.Sp
Returns 1 if the host was reached, or 0 if it wasn't.
.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 "source_address([\s-1SRC\s0])" 4
.IX Item "source_address([SRC])"
.IP "packetlen([\s-1LEN\s0])" 4
.IX Item "packetlen([LEN])"
.IP "use_alarm([0|1])" 4
.IX Item "use_alarm([0|1])"
.IP "protocl([\s-1PROTOCOL\s0])" 4
.IX Item "protocl([PROTOCOL])"
.IP "concurrent_hops([\s-1CONCURRENT\s0])" 4
.IX Item "concurrent_hops([CONCURRENT])"
.IP "first_hop([\s-1FIRST_HOP\s0])" 4
.IX Item "first_hop([FIRST_HOP])"
.IP "device([\s-1DEVICE\s0])" 4
.IX Item "device([DEVICE])"
.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 "pretty_print" 4
.IX Item "pretty_print"
Prints to stdout a traceroute-like text. Tries to mimic \fBtraceroute\fR\|(1)'s
output as close as possible with a few exceptions. First, the columns are
easier to read, and second, a new line is started if the host \s-1IP\s0 changes
instead of printing the new \s-1IP\s0 inline. The first column stays the same hop
number, only the host changes.
.Sp
Passing in an argument of 1 will make pretty_print resolve the names of the
router ips, otherwise they are printed as raw ip addresses, like
\&\f(CW\*(C`Traceroute\*(C'\fR's \f(CW\*(C`\-n\*(C'\fR option.
.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"
Returns 1 if the host was found, undef otherwise.
.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.
.Sp
\&\s-1NOTE:\s0 This doesn't work with this version.
.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_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.
.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 "BUGS and LIMITATIONS"
.IX Header "BUGS and LIMITATIONS"
I have not tested the cloning functions of Net::Traceroute::PurePerl.
It ought to work, but if not, \s-1BUG\s0 me.
.PP
This module requires root or administrative privileges to run. It opens a raw
socket to listen for \s-1TTL\s0 exceeded messages. Take appropriate precautions.
.PP
Windows only supports \s-1ICMP\s0 traceroutes. This may change in a future release,
but it is a real pain since Windows doesn't send \s-1ICMP\s0 error messages to
applications for other protocols unless the socket is in promiscous mode. :(
.PP
The current version does not correctly detect network unreachable and
other nonstandard \s-1ICMP\s0 errors. This can lead to problems on networks where
these errors are sent instead of a port unreachable or ttl exceeded packet.
.PP
The current version does not support Net::Traceroute's clone method.
Calling clone will create an object that is unusable at this point.
.SH "TODO"
.IX Header "TODO"
.IP "\(bu" 2
Implement IPv6 capability.
.IP "\(bu" 2
Implement \s-1TCP\s0 traceroute.
.IP "\(bu" 2
Fix bugs listed above.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBtraceroute\fR\|(1)
.PP
This module's traceroute code was heavily influenced by \f(CW\*(C`Net::Ping\*(C'\fR.
.PP
See the examples folder and the test programs for more examples of this module
in action.
.SH "AUTHOR"
.IX Header "AUTHOR"
Tom Scanlan owner Net::Traceroute::PurePerl
.PP
Andrew Hoying current co-maintainer of
Net::Traceroute::PurePerl. Any bugs in this release are mine, please send me
the bug reports.
.PP
Daniel Hagerty owner of Net::Traceroute and input on this fella
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Go right ahead and copy it. 2002 Tom Scanlan. Copyright 2006 by Andrew Hoying.
Don't blame me for damages, just the bugs.
.PP
Net::Traceroute::PurePerl is free software; you may redistribute it and or modify it under the same terms as Perl itself.