PurePerl(3pm)

💖 NAME 💖

Net::Traceroute:PurePerl — it's giving traceroute(1) functionality in perl, via raw sockets 🦋

---

🌸 VERSION 🌸

This doc describes version 0.10 of Net::Traceroute::PurePerl. periodt 💅

---

✨ 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;

okay bestie, that's literally the whole vibe right there 👑

---

💜 DESCRIPTION 💜

This module implements traceroute(1) functionality for perl5. It lets you trace the path IP packets take to a destination. It's implemented by using raw sockets to act just like the regular traceroute. no cap ✨

⚠️ You must also be root to use the raw sockets. like, it's not optional, it's the law 🫶

---

🎀 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. (yes, that's on you, bestie 💅)

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. slay ✨

---

⭐ OVERVIEW ⭐

A new Net::Traceroute::PurePerl object must be created with the new method. This will not perform the traceroute immediately, unlike Net::Traceroute. Instead it returns a "template" object that can be used to set parameters for several subsequent traceroutes. it's giving reusable, it's giving organized 💅

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. that's the whole trick, iykyk 🔥

---

💀 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. 😭 not the bugs

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. so like, heads up, fr fr 💀

---

👑 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. no skipping steps, bestie ✨

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). That's "Traceroute"'s -p option. 💅
• debuglvl — A number indicating how verbose debug information should be. Please include debug=>9 output in bug reports. 🐛 (do it for me, pls)
• max_ttl — Maximum number of hops to try before giving up. Default is what the system traceroute uses (normally 30). That's "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). That's "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. That's "Traceroute"'s -w option. ⏳
• timeout — unused here 🙈
• source_address — Select the source address that traceroute will use. That's "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 UDP 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. That's "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. That's "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. That's "Traceroute"'s -I option. 🦋

💖 METHODS 💖

---

traceroute — the main character, literally

Run the traceroute. Bestie, this fills in the rest of the object for your informational queries. ✨

okay so warning time: the traceroute method is a blocking call. It will NOT return until the max_ttl is reached or the host is reached. So if your program is time dependent (and honestly, whose isn't 😭) you should wrap that call in an eval with an ALARM set. Like this:

  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. That's it, that's the vibe check. 🫶

---

Controlling traceroute invocation 🎀

Each of these methods returns the current value of the option specified by the corresponding constructor option. And if you hand one a value, it will set the object's instance variable to that value. Iconic.

heads up bestie: changing an instance variable will only affect newly performed traceroutes. Setting a different value on a traceroute object that has already performed a trace? No effect. None. Zero. Nada. 💀

See the constructor documentation for info about methods that aren't documented here. iykyk.

• 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. So do the trace first, bestie, then come ask questions.

Any of the methods in this section that return a count of something, or that want an Nth type count to identify something, employ one based counting. Periodt.

pretty_print

Prints to stdout a traceroute-like text. It tries to mimic traceroute(1)'s output as close as possible, with a few exceptions. First: the columns are easier to read. 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. slay 💅

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. No fake OKs here, we don't do that. 🙈

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 successful query will be returned. cute 🎀

• TRACEROUTE_OK — Reached the host, no problems. the dream fr fr ✨
• 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 successful 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 successful query will be returned.

---

💀 BUGS and LIMITATIONS 💀

ngl, this is the part where we get real.

• 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 🌈

the girlies have plans, okay?

1. Implement IPv6 capability. 🦋
2. Implement TCP traceroute.
3. 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.

---

and that's the whole page bestie!! 🫶 this beauty ships as part of perl v5.34.0, dated 2022-07-03, and lives at PurePerl(3pm). go forth and trace responsibly, mwah 💖✨