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

FreeBSD Manual Pages

  
 
  

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

NAME
       Net::Traceroute:PurePerl	- traceroute(1)	functionality in perl via raw
       sockets

VERSION
       This document describes version 0.10 of Net::Traceroute::PurePerl.

SYNOPSIS
	   use Net::Traceroute::PurePerl;

	   my $t = new Net::Traceroute::PurePerl(
		backend	       => 'PurePerl', #	this optional
		host	       => 'www.openreach.com',
		debug	       => 0,
		max_ttl	       => 12,
		query_timeout  => 2,
		packetlen      => 40,
		protocol       => 'udp', # Or icmp
	   );
	   $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	also be	root to	use the	raw sockets.

INSTALLATION
   Basic Installation
       Net::Traceroute::PurePerl may be	installed through the CPAN shell in
       the usual CPAN shell manner. This typically is:

	  $ perl -MCPAN	-e 'install Net::Traceroute::PurePerl'

       You can also read this README from the CPAN shell:

	  $ perl -MCPAN	-e shell
	  cpan>	readme Net::Traceroute::PurePerl

       And you can install the module from the CPAN prompt as well:

	  cpan>	install	Net::Traceroute::PurePerl

   Manual Installation
       Net::Traceroute::PurePerl can also be installed manually.
       <ftp://ftp-mirror.internap.com/pub/CPAN/authors/id/A/AH/AHOYING/> or a
       similarly named directory at your favorite CPAN mirror should hold the
       latest version.

       Downloading and unpacking the distribution are left up to the reader.

       To build	and test it:

	  perl Makefile.PL
	  make
	  make test

       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.

       When you	are ready to install the module:

	  make install

       It should now be	ready to use.

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 or	ICMP packets are sent with a small TTL (time-
       to-live)	field in an attempt to get intervening routers to generate
       ICMP TIME_EXCEEDED messages.

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.

       The public methods have remained	unchanged, and this should be a	drop
       in replacement for the older version.

       This version no longer resolves router IPs to host names	in the
       traceroute code.	If you need the	IP resolved you	have to	do it from
       your code, or use the pretty_print method with a	positive value passed
       as an argument.

       The current version does	not correctly detect network unreachable and
       other nonstandard ICMP errors. This can lead to problems	on networks
       where these errors are sent instead of a	port unreachable or ttl
       exceeded	packet.

CONSTRUCTOR
	   $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,]
	   );

       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.

       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 will use.
       "Traceroute"'s "-S" option.

       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 - unused in this version

       protocol	- Either ICMP or UDP. ICMP uses	ICMP echo packets with
       incrementing sequence numbers, while UDP	uses USP packets with
       incrementing ports. It defaults to udp.

       concurrent_hops - 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.
	"Traceroute"'s "-N" option.

       first_hop - This	is the lowest TTL to use. Setting this will skip the
       first x routers in the path, especially useful if they never change.
       Defaults	to 1.  "Traceroute"'s "-f" option.

       device -	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.
	"Traceroute"'s "-I" option.

METHODS
       traceroute
	   Run the traceroute.	Will fill in the rest of the object for
	   informational queries.

	   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 ALARM set.

	     eval {
	       local $SIG{ALRM}	= sub {	die "alarm" };
	       alarm $timeout;
	       $success	= $t->traceroute();
	       alarm 0;
	     }
	     warn "Traceroute timed out\n" if ($@ and $@ eq "alarm");

	   Returns 1 if	the host was reached, or 0 if it wasn't.

   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])
       use_alarm([0|1])
       protocl([PROTOCOL])
       concurrent_hops([CONCURRENT])
       first_hop([FIRST_HOP])
       device([DEVICE])

   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. Tries to mimic
	   traceroute(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 IP changes instead of printing the new IP
	   inline. The first column stays the same hop number, only the	host
	   changes.

	   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 "Traceroute"'s "-n" option.

       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.

	   NOTE: This doesn't work with	this version.

       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.

BUGS and LIMITATIONS
       I have not tested the cloning functions of Net::Traceroute::PurePerl.
       It ought	to work, but if	not, BUG me.

       This module requires root or administrative privileges to run. It opens
       a raw socket to listen for TTL exceeded messages. Take appropriate
       precautions.

       Windows only supports ICMP traceroutes. This may	change in a future
       release,	but it is a real pain since Windows doesn't send ICMP error
       messages	to applications	for other protocols unless the socket is in
       promiscous mode.	:(

       The current version does	not correctly detect network unreachable and
       other nonstandard ICMP errors. This can lead to problems	on networks
       where these errors are sent instead of a	port unreachable or ttl
       exceeded	packet.

       The current version does	not support Net::Traceroute's clone method.
       Calling clone will create an object that	is unusable at this point.

TODO
       o Implement IPv6	capability.

       o Implement TCP traceroute.

       o Fix bugs listed above.

SEE ALSO
       traceroute(1)

       This module's traceroute	code was heavily influenced by "Net::Ping".

       See the examples	folder and the test programs for more examples of this
       module in action.

AUTHOR
       Tom Scanlan <tscanlan@openreach.com> owner Net::Traceroute::PurePerl

       Andrew Hoying <ahoying@cpan.org>	current	co-maintainer of
       Net::Traceroute::PurePerl. Any bugs in this release are mine, please
       send me the bug reports.

       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. Copyright	2006 by	Andrew
       Hoying.	Don't blame me for damages, just the bugs.

       Net::Traceroute::PurePerl is free software; you may redistribute	it and
       or modify it under the same terms as Perl itself.

perl v5.32.0			  2006-08-28			   PurePerl(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | INSTALLATION | OVERVIEW | VERSION CHANGES | CONSTRUCTOR | METHODS | BUGS and LIMITATIONS | TODO | SEE ALSO | AUTHOR | COPYRIGHT

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

home | help