Catchpoint's Pietrasanta traceroute

Introduction

This is an enhanced version of Dmitry Butskoy traceroute developed by Catchpoint.

Traceroute is one of the oldest network diagnostic tools. It was first built to answer the thorny question, where are the packets going? However, various challenges introduced by firewalls and load balancers have made the original traceroute less useful and reliable than it once was.

We did a number of improvements to Dmitry's work. The main ones are enumerated here:

• Support for "TCP InSession" method. This method opens a TCP connection with the destination and sends TCP probes within the opened session with incremental TTL. The aim is to prevent false packet loss introduced by firewall and router configurations related to security and to ensures that packets follow a single flow, akin to a normal TCP session, to bypass load-balanced routers.

• Introduced enhanced TOS (DSCP/ECN) field report. This new option allows to set ToS field in outgoing packets and read the ToS field of the expiring probes. It includes a special output to highlight DSCP and ECN values.
• Introduced the QUIC module to perform QUIC traceroute using --quic. This mode uses QUIC Initial packets as probes.

Full details in ChangeLog here.

Following the convention of naming traceroute after the place where they are developed, we named our traceroute after the tiny town where the Catchpoint Italian branch is based: Pietrasanta traceroute.

Happy (Pietrasanta) tracerouting!

Building & Installation

Since version 0.1.3 (the version that introduced QUIC support), openssl3 (version >= 3.2) is needed to compile traceroute. If openssl3 libraries are not available in your system, you can still build and enjoy traceroute by disabling QUIC by passing the argument DISABLE_OPENSSL=1 to make.

By default the binary and manual are respectively installed in bin and share folders under /usr/local. You can change this directory passing the prefix parameter to make install

Examples

Normal build & default installation

make 
make install

Build without openssl3 & default installation

make DISABLE_OPENSSL=1
make install

Normal build & installation in custom directory

make
make install prefix=custom_dir

Binaries

This tool should build and run on any Linux system running a kernel version 2.6 or higher. This includes systems running on containers, VMs and on the Windows Subsystem for Linux (WSL).

Since version 0.1.14 this tool should also work on MacOS, with the known limitations that TCP and TCP InSession mode are not yet available and Path MTU discovery is not supported for any mode.

Binaries are provided for convenience here for common Linux distributions and they can be directly used into the target system linked against openssl3 runtime libraries provided by the host system.

A way to use the provided binaries is the following:

• Download the binary from https://raw.githubusercontent.com/catchpoint/Networking.traceroute/main/binaries/<distro>/<architecture>/traceroute
• Provide executable permission (e.g. chmod +x <binary>)
• Optionally provide cap_net_raw capability to make it run without the need of being root for privileged commands (e.g. like traceroute TCP), via sudo setcap cap_net_raw+ep <binary>.
• Ensure that openssl3 runtime libraries are available in the system

Building with docker

The binaries provided in the binaries folder are obtained compiling the tool on OS-dedicated dockerfiles. For convenience these dockerfiles are included into the dockerfiles folder and a build (bash) script called build.sh is provided.

The build script takes these options:

• --build: build the binaries.
• --clean: clean docker images and containers created during the build process.
• --platform="<space separated list of platforms>": build and/or clean for the specified platforms: ol8, ol9, debian12 or ubuntu24.
• --arch="<architecture>": target architecture, either x86_64 or arm64 or both (default: x86_64 arm64).

Examples:

./build.sh --build --clean

This will produce the x86_64 and arm64 binaries for Oracle Linux 8, Oracle Linux 9, Debian 12 and Ubuntu 24 and place them into the binaries folder.

Optionally --platform and --arch parameters can be passed to compile for a subset of the presupported platforms and architectures.

To build only the ARM64 binaries:

./build.sh --build --clean --platform="ol8 ol9 debian12 ubuntu24" --arch=arm64

The binary is written to binaries/ol8/arm64/traceroute.

Packaging

A script called package.sh is provided into the build folder, wich produces an RPM that should work on RHEL8/RHEL9 and derivatives and a DEB that should work on Debian12 and derivatives (including Ubuntu). This script takes these options:

• --platform="<space separated list of platforms>": build and/or clean for the specified platforms: ol8, ol9, debian12 or ubuntu24 (default: ol8 ol9 debian12 ubuntu24).
• --arch="<architecture>": target architecture, x86_64 or arm64 or both (default: x86_64 arm64).

If binaries to package are not provided the build script is called automatically.

Examples:

Packages (and possibly builds) binaries for all the pre supported platforms and architectures

./package.sh 

Packages (and possibly builds) binaries for ubuntu24 on all pre supported architectures

./package.sh --platform=ubuntu24 --arch="x86_64 arm64"

Traceroute usage

See traceroute(8) for detailed instructions.

Original Dmitry Butskoy README file

This is a new modern implementation of the traceroute(8) utility for Linux systems.

Traceroute tracks the route packets taken from an IP network on their way to a given host. It utilizes the IP protocol's time to live (TTL) field and attempts to elicit an ICMP TIME_EXCEEDED response from each gateway along the path to the host.

Main features:

• Full support for both IPv4 and IPv6 protocols
• Several tracerouting methods, including:
  • UDP datagrams (including udplite and udp to particlular port)
  • ICMP ECHO packets (including dgram icmp sockets)
  • TCP SYNs (in general, any TCP request with various flags and options)
  • DCCP Request packets
  • Generic IP datagrams
• UDP methods do not require root privileges
• Ability to send several probe packets at a time
• Ability to compute a proper time to wait for each probe
• perform AS path lookups for returned addresses
• show ICMP extensions, including MPLS
• perform path MTU discovery automatically
• show guessed number of hops in backward direction
• command line compatible with the original traceroute
• and much more, see traceroute(8)

This code was written from the scratch, using some ideas of Olaf Kirch's traceroute, the original implementation of Van Jacobson (which was long used before) and some current BSD's ones.

This traceroute requires Linux kernel 2.6 and higher.

You can try to contact the author at .

Good tracerouting!

Dmitry Butskoy