Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Traceroute(3)	      User Contributed Perl Documentation	 Traceroute(3)

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 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_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 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	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.

perl v5.32.0			  2014-03-24			 Traceroute(3)

NAME | SYNOPSIS | DESCRIPTION | OVERVIEW | CONSTRUCTOR AND CLONING | METHODS | CLONING SUPPORT BEFORE 1.04 | BUGS | SEE ALSO | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Traceroute&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help