
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 *N*th 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
    * Implement IPv6 capability.

    * Implement TCP traceroute.

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

