trippy Documentation

File: README.md Copy Chapter

Quick Start Copy Chapter

See the getting started guide.

Install Copy Section

Trippy runs on Linux, BSD, macOS, and Windows. It can be installed from most package managers, precompiled binaries, or
source.

For example, to install Trippy from cargo:

cargo install trippy --locked

All package managers

Cargo Copy Section

cargo install trippy --locked

APT (Debian) Copy Section

apt install trippy

ⓘ Note:

Only available for Debian 13 (trixie) and later.

PPA (Ubuntu) Copy Section

add-apt-repository ppa:fujiapple/trippy
apt update && apt install trippy

ⓘ Note:

Only available for Ubuntu 24.04 (Noble) and 22.04 (Jammy).

Snap (Linux) Copy Section

snap install trippy

Homebrew (macOS) Copy Section

brew install trippy

WinGet (Windows) Copy Section

winget install trippy

Scoop (Windows) Copy Section

scoop install trippy

Chocolatey (Windows) Copy Section

choco install trippy

NetBSD Copy Section

pkgin install trippy

FreeBSD Copy Section

pkg install trippy

OpenBSD Copy Section

pkg_add trippy

Arch Linux Copy Section

pacman -S trippy

Gentoo Linux Copy Section

emerge -av net-analyzer/trippy

Void Linux Copy Section

xbps-install -S trippy

ALT Sisyphus Copy Section

apt-get install trippy

Chimera Linux Copy Section

apk add trippy

Nix Copy Section

nix-env -iA trippy

Docker Copy Section

docker run -it fujiapple/trippy

All Repositories Copy Section

See the installation guide for details of how to install Trippy on your system.

Run Copy Section

To run a basic trace to example.com with default settings, use the following command:

sudo trip example.com

See the usage examples and CLI reference for
details of how to use Trippy. To use Trippy without elevated privileges, see
the privileges guide.

Documentation Copy Chapter

Full documentation is available at trippy.rs.

documentation links

Getting Started Copy Chapter

See the Getting Started guide.

Features Copy Chapter

See the Features list.

Distributions Copy Chapter

See the Distributions list.

Privileges Copy Chapter

See the Privileges guide.

Usage Examples Copy Chapter

See the Usage Examples.

Command Reference Copy Chapter

See the Command Reference.

Theme Reference Copy Chapter

See the Theme Reference.

Column Reference Copy Chapter

See the Column Reference.

Configuration Reference Copy Chapter

See the Configuration Reference.

Locale Reference Copy Chapter

See the Locale Reference.

Versions Copy Chapter

See the Version Reference.

Frequently Asked Questions Copy Chapter

Why does Trippy show "Awaiting data..."? Copy Section

See the Awaiting Data guide.

How do I allow incoming ICMP traffic in the Windows Defender firewall? Copy Section

See the Windows Defender Firewall guide.

What are the recommended settings for Trippy? Copy Section

See the Recommended Tracing Settings guide.

Acknowledgements Copy Chapter

Trippy is made possible by ratatui (
formerly tui-rs),
crossterm as well
as several foundational Rust libraries.

Trippy draws heavily from mtr and also incorporates ideas
from both libparistraceroute
& Dublin Traceroute.

The Trippy networking code is inspired by pnet and some elements of that codebase
are incorporated in Trippy.

The AS data is retrieved from
the IP to ASN Mapping Service provided
by Team Cymru.

The trippy.cli.rs CNAME hosting is provided by cli.rs.

The Trippy chat room is sponsored by Zulip.

Trippy logo designed by Harun Ocaksiz Design.

License Copy Chapter

This project is distributed under the terms of the Apache License (Version 2.0).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in time by you, as defined
in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

See LICENSE for details.

Copyright 2022 Trippy Contributors

File: crates/README.md Copy Chapter

Crates Copy Chapter

The following is a list of the crates defined by Trippy and their purposes:

`trippy` Copy Section

A binary crate for the Trippy application and a library crate. This is the crate you would use if you wish to install
and run Trippy as a standalone tool.

cargo install --locked trippy

It can also be used as library for crates that wish to use the Trippy tracing functionality.

[!NOTE]
The trippy crate has tui as a default feature and so you should disable default features when using it as a
library.

cargo add trippy --no-default-features --features core,dns

`trippy-core` Copy Section

A library crate providing the core Trippy tracing functionality. This crate is used by the Trippy application and is
the crate you would use if you wish to provide the Trippy tracing functionality in your own application.

cargo add trippy-core

`trippy-packet` Copy Section

A library crate which provides packet wire formats and packet parsing functionality. This crate is used by the Trippy
application and is the crate you would use if you wish to provide packet parsing functionality in your own application.

cargo add trippy-packet

`trippy-dns` Copy Section

A library crate for performing forward and reverse lazy DNS resolution. This crate is designed to be used by the Trippy
application but may also be useful for other applications that need to perform forward and reverse lazy DNS resolution.

cargo add trippy-dns

`trippy-privilege` Copy Section

A library crate for discovering platform privileges. This crate is designed to be used by the Trippy application but
may also be useful for other applications.

cargo add trippy-privilege

`trippy-tui` Copy Section

A library crate for the Trippy terminal user interface.

cargo add trippy-tui

File: docs/src/content/docs/guides/faq.md Copy Chapter

title: Frequently Asked Questions sidebar: order: 6 Copy Chapter

Why does Trippy show "Awaiting data..."? Copy Chapter

:::caution
If you are using Windows you must configure
the Windows Defender firewall to allow incoming ICMP traffic
:::

When Trippy shows “Awaiting data...” it means that it has received zero responses for the probes sent in a trace. This
indicates that either probes are not being sent or, more typically, responses are not being received.

Check that local and network firewalls allow ICMP traffic and that the system traceroute (or tracert.exe on
Windows) works as expected. Note that on Windows, even if tracert.exe works as expected, you
must configure the Windows Defender
firewall to allow incoming ICMP traffic.

For deeper diagnostics you can run tools such as https://www.wireshark.org and https://www.tcpdump.org to verify that
icmp requests and responses are being send and received.

File: docs/src/content/docs/guides/privileges.md Copy Chapter

title: Privileges sidebar: order: 2 Copy Chapter

Trippy normally requires elevated privileges due to the use of raw sockets. Enabling the required privileges for your
platform can be achieved in several ways, as outlined below. Trippy can also be used without elevated privileged on
certain platforms, with some limitations.

Unix Copy Chapter

Run via `sudo` Copy Section

Run as root user via sudo:

sudo trip example.com

:::note
When running trip via sudo you must ensure that the (optional) configuration file is stored relative to the root
user or specify the location of the configuration file via the -c (--config-file) command line argument. See
the configuration reference.
:::

Set the `setuid` bit Copy Section

chown trip as the root user and set the setuid bit:

sudo chown root $(which trip) && sudo chmod +s $(which trip)

[Linux only] Set capabilities Copy Section

Set the CAP_NET_RAW capability:

sudo setcap CAP_NET_RAW+p $(which trip)

:::note
Trippy is a capability aware application and will add CAP_NET_RAW to the effective set if it is present in the allowed
set. Trippy will drop all capabilities after creating the raw sockets.
:::

Windows Copy Chapter

Trippy must be run with Administrator privileges on Windows.

Unprivileged mode Copy Chapter

Trippy allows running in an unprivileged mode for all tracing modes (ICMP, UDP and TCP) on platforms which support
that feature.

:::note
Unprivileged mode is currently only supported on macOS. Linux support is possible and may be added in the future.
Unprivileged mode is not supported on NetBSD, FreeBSD or Windows as these platforms do not support the IPPROTO_ICMP
socket type. See #101 for further information.
:::

The unprivileged mode can be enabled by adding the --unprivileged (-u) command line flag or by adding the
unprivileged entry in the trippy section of the configuration file:

[trippy]
unprivileged = true

:::note
The paris and dublin ECMP strategies are not supported in unprivileged mode as these require manipulating the
UDP and IP and headers which in turn requires the use of a raw socket.
:::

File: docs/src/content/docs/guides/recommendation.md Copy Chapter

title: Recommended Tracing Settings sidebar: order: 3 Copy Chapter

Trippy provides a variety of configurable features which can be used to perform different types of analysis. The choice
of settings will depend on the analysis you wish to perform and the environment in which you are working. This guide
lists some common options along with some basic guidance on when they might be appropriate.

:::note
The Windows tracert tool uses ICMP by default, whereas most Unix traceroute tools use UDP by default.
:::

ICMP Copy Chapter

By default Trippy will run an ICMP trace to the target. This will typically produce a consistent path to the target (a
single flow) for each round of tracing which makes it easy to read and analyse. This is a useful mode for general
network troubleshooting.

However, many routers are configured to rate-limit ICMP traffic which can make it difficult to get an accurate picture
of packet loss. In addition, ICMP traffic is not typically subject to ECMP routing and so may not reflect the path that
would taken by other protocols such as UDP and TCP.

To run a simple ICMP trace:

trip example.com

Due to the rate-limiting of ICMP traffic, some people prefer to hide the Loss% and Recv columns in the Tui as
these are easy to misinterpret.

trip example.com --tui-custom-columns hosavbwdt

These settings can be made permanent by adding them to the Trippy configuration file:

[tui]
custom-columns = "hosavbwdt"

:::note
The Sts column shows different color codes to reflect packet loss at intermediate vs the target hop, see the
Column Reference for more information.
:::

UDP/Dublin with fixed ports

UDP tracing provides a more realistic view of the path taken by traffic that is subject to ECMP routing.

Setting a fixed target port in the range 33434-33534 may allow Trippy to determine that the probe has reached the target
as many routers and firewalls are configured to allow UDP probes in that range and will respond with a Destination
Unreachable response.

However, running a UDP trace with a fixed target port and a variable source port will typically result in different
paths being followed for each probe within each round of tracing. This can make it difficult to interpret the output as
different hosts will reply for a given hop (time-to-live) across rounds.

By using the dublin ECMP strategy, which encodes the sequence number in the IP identifier field, Trippy can fix both
the source and target ports, typically resulting in a single path for each probe within each round of tracing.

:::note
UDP/Dublin for IPv6 encodes the sequence number as the payload length as the IP identifier field is not available in
IPv6.
:::

:::note
Keep in mind that every probe is an independent trial and each may traverse a completely different path. In practice,
ICMP probes often follow a single path, whereas the path of UDP and TCP probes is typically determined by the 5-tuple of
protocol, source and destination IP addresses and ports.

Also beware that the return path may not be the same as the forward path, and may also differ for each probe. Strategies
such as dublin and paris assist in controlling the path taken by the forward probes, but do not help control the
return path. Therefore it is recommended to run a trace in both directions to get a complete picture.
:::

To run a UDP trace with fixed source and target ports using the dublin ECMP strategy:

trip example.com --udp --multipath-strategy dublin --source-port 5000 --target-port 33434

:::note
The source port can be any valid port number, but the target port should usually be in the range 33434-33534 or whatever
range is open to UDP probes on the target host.
:::

These settings can be made permanent by adding them to the Trippy configuration file:

[strategy]
protocol = "udp"
multipath-strategy = "dublin"
source-port = 5000
target-port = 33434

UDP/Dublin with fixed target port and variable source port Copy Chapter

As an extension to the above, if you do not fix the source port when using the dublin ECMP strategy, Trippy will
vary the source port per round of tracing (i.e. each probe within a given round will share the same source port, and
the source port will vary for each round). This will typically result in the same path being followed for each probe
within a given round, but different paths being followed for each round.

These individual flows can be explored in the Trippy Tui by pressing the toggle-flows key binding (f key by
default).

Adding the columns Seq, Sprt and Dprt to the Tui will show the sequence number, source port and destination port
respectively which makes this easier to visualize.

trip example.com --udp --multipath-strategy dublin --target-port 33434 --tui-custom-columns holsravbwdtSPQ

These settings can be made permanent by adding them to the Trippy configuration file:

[strategy]
protocol = "udp"
multipath-strategy = "dublin"
target-port = 33434

[tui]
custom-columns = "holsravbwdtSPQ"

To make the flows easier to visualize, you can generate a Graphviz DOT file report of all tracing flows:

trip example.com --udp --multipath-strategy dublin --target-port 33434 -m dot -C 5

UDP/Paris Copy Chapter

UDP with the paris ECMP strategy offers the same benefits as the dublin strategy with fixed ports and can be used
in the same way.

They differ in the way they encode the sequence number in the probe. The dublin strategy uses the IP identifier
field, whereas the paris strategy uses the UDP checksum field.

To run a UDP trace with fixed source and target ports using the paris ECMP strategy:

trip example.com --udp --multipath-strategy paris --source-port 5000 --target-port 33434

The paris strategy does not work behind NAT as the UDP checksum field is typically modified by NAT devices.
Therefore the dublin strategy is recommended when NAT is present.

:::note
Trippy can detect the presence of NAT devices in some circumstances when using the dublin strategy and the Nat
column can be shown in the Tui to indicate when NAT is detected. See the Column Reference for more
information.
:::

TCP

TCP tracing is similar to UDP tracing in that it provides a more realistic view of the path taken by traffic that is
subject to ECMP routing.

TCP tracing defaults to using a target port of 80 and sets the source port as the sequence number which will typically
result in a different path being followed for each probe within each round of tracing.

To run a TCP trace:

trip example.com --tcp

TCP tracing is useful for diagnosing issues with TCP connections and higher layer protocols such as HTTP. Often UDP
tracing can be used in place of TCP to diagnose IP layer network issues and, as it provides ways to control the path
taken by the probes, it is often preferred.

:::note
Trippy does not support the dublin or paris ECMP strategies for TCP tracing and so you cannot fix both the source
and target ports. See the tracking issue for details.
:::

File: docs/src/content/docs/guides/usage.md Copy Chapter

title: Usage Examples sidebar: order: 1 Copy Chapter

Basic usage with default parameters:

trip example.com

Trace without requiring elevated privileges (supported platforms only, see privileges):

trip example.com --unprivileged

Trace using the udp (or tcp or icmp) protocol (also aliases --icmp, --udp & --tcp):

trip example.com -p udp

Trace to multiple targets simultaneously (icmp protocol only,
see #72):

trip example.com google.com crates.io

Trace with a minimum round time of 250ms and a grace period of 50ms:

trip example.com -i 250ms -g 50ms

Trace with a custom first and maximum time-to-live:

trip example.com --first-ttl 2 --max-ttl 10

Use custom destination port 443 for tcp tracing:

trip example.com -p tcp -P 443

Use custom source port 5000 for udp tracing:

trip example.com -p udp -S 5000

Use the dublin (or paris) ECMP routing strategy for udp with fixed source and destination ports:

trip example.com -p udp -R dublin -S 5000 -P 3500

Trace with a custom source address:

trip example.com -p tcp -A 127.0.0.1

Trace with a source address determined by the IPv4 address for interface en0:

trip example.com -p tcp -I en0

Trace using IPv6:

trip example.com -6

Trace using ipv4-then-ipv6 fallback (or ipv6-then-ipv4 or ipv4 or ipv6):

trip example.com --addr-family ipv4-then-ipv6

Generate a json (or csv, pretty, markdown) tracing report with 5 rounds of data:

trip example.com -m json -C 5

Generate a Graphviz DOT file report of all tracing flows for a TCP trace after 5 rounds:

trip example.com --tcp -m dot -C 5

Generate a textual report of all tracing flows for a UDP trace after 5 rounds:

trip example.com --udp -m flows -C 5

Perform DNS queries using the google DNS resolver (or cloudflare, system, resolv):

trip example.com -r google

Lookup AS information for all discovered IP addresses (not yet available for the system resolver,
see #66):

trip example.com -r google -z

Set the reverse DNS lookup cache time-to-live to be 60 seconds:

trip example.com --dns-ttl 60sec

Lookup and display short (or long or location or off) GeoIp information from a mmdb file:

trip example.com --geoip-mmdb-file GeoLite2-City.mmdb --tui-geoip-mode short

Parse icmp extensions:

trip example.com -e

Hide the IP address, hostname and GeoIp for the first two hops:

trip example.com --tui-privacy-max-ttl 2

Customize Tui columns (see Column Reference):

trip example.com --tui-custom-columns holsravbwdt

Customize the color theme:

trip example.com --tui-theme-colors bg-color=blue,text-color=ffff00

List all Tui items that can have a custom color theme:

trip --print-tui-theme-items

Customize the key bindings:

trip example.com --tui-key-bindings previous-hop=k,next-hop=j,quit=shift-q

List all Tui commands that can have a custom key binding:

trip --print-tui-binding-commands

Specify the location of the Trippy config file:

trip example.com --config-file /path/to/trippy.toml

Generate a template configuration file:

trip --print-config-template > trippy.toml

Generate bash shell completions (or fish, powershell, zsh, elvish):

trip --generate bash

Generate ROFF man page:

trip --generate-man

Use the de Tui locale:

trip example.com --tui-locale de

List supported Tui locales:

trip --print-locales

Set the Tui timezone to UTC:

trip example.com --tui-timezone UTC

Run in silent tracing mode and output compact trace logging with full span events:

trip example.com -m silent -v --log-format compact --log-span-events full

File: docs/src/content/docs/guides/windows_firewall.md Copy Chapter

title: Windows Defender Firewall sidebar: order: 4 Copy Chapter

The Windows Defender firewall rule can be created using PowerShell.

New-NetFirewallRule -DisplayName "ICMPv4 Trippy Allow" -Name ICMPv4_TRIPPY_ALLOW -Protocol ICMPv4 -Action Allow
New-NetFirewallRule -DisplayName "ICMPv6 Trippy Allow" -Name ICMPv6_TRIPPY_ALLOW -Protocol ICMPv6 -Action Allow

The rules can be enabled as follows:

Enable-NetFirewallRule ICMPv4_TRIPPY_ALLOW
Enable-NetFirewallRule ICMPv6_TRIPPY_ALLOW

The rules can be disabled as follows:

Disable-NetFirewallRule ICMPv4_TRIPPY_ALLOW
Disable-NetFirewallRule ICMPv6_TRIPPY_ALLOW

There is a step-by-step guide to manually configure the Windows Defender firewall rule.

File: docs/src/content/docs/development/crates.md Copy Chapter

title: Crates Copy Chapter

The following table lists the crates that are provided by Trippy. See crates for more information.

File: docs/src/content/docs/reference/bindings.md Copy Chapter

title: Key Bindings Reference sidebar: order: 3 Copy Chapter

The following table lists the default Tui command key bindings. These can be overridden with the --tui-key-bindings
command line option or in the bindings section of the configuration file.

The supported modifiers are: shift, ctrl, alt, super, hyper & meta. Multiple modifiers may be specified, for
example ctrl+shift+b.

File: docs/src/content/docs/reference/cli.md Copy Chapter

title: CLI Reference sidebar: order: 1 Copy Chapter

/* Detailed source-code truncated for AI context efficiency. */

:::note
Trippy command line arguments may be given in any order and my occur both before and after the targets. All options can
also be provided via environment variables using the TRIP_ prefix (for example, TRIP_PROTOCOL=tcp). CLI flags take
precedence over environment variables when both are set.
:::