#ttl

Network diagnostic tool that goes beyond traceroute: MTU discovery, NAT detection, route flap alerts, IX identification, and more.

#Quick Start

# Basic usage
ttl 8.8.8.8                          # Linux (after setcap)
sudo ttl 8.8.8.8                     # macOS/BSD (always needs sudo)

# Common options
ttl -p udp google.com                # UDP probes
ttl --flows 8 cloudflare.com         # ECMP path discovery
ttl --pmtud 1.1.1.1                  # Path MTU discovery
ttl 8.8.8.8 1.1.1.1 9.9.9.9          # Multiple targets
ttl --resolve-all google.com         # Trace all resolved IPs

See Installation below for setup instructions.

#Features

• Fast continuous path monitoring with detailed hop statistics
• Multiple simultaneous targets - trace to several destinations at once
• Paris/Dublin traceroute - multi-flow probing for ECMP path enumeration
• ECMP classification - distinguishes per-flow vs per-packet load balancing
• Path MTU discovery - binary search for maximum unfragmented size
• NAT detection - identify when NAT devices rewrite source ports
• Route flap detection - alert on path changes indicating routing instability
• Rich enrichment - ASN, GeoIP, reverse DNS, IX detection (PeeringDB)
• MPLS label detection from ICMP extensions
• Interface and next-hop identification (RFC 5837 ICMP extensions)
• ICMP, UDP, TCP probing with auto-detection
• Great TUI with themes, sparklines, and session export
• Update notifications - in-app banner when new versions are available (opt out via --no-update-check, DO_NOT_TRACK, config, or a --no-default-features build)
• Scriptable - JSON, CSV, text report, and line-delimited JSON streaming output
• Trace diffing - compare two saved sessions for path and latency changes
• Daemon mode + Prometheus exporter - headless continuous monitoring with /metrics and /healthz
• Docker-ready - official Dockerfile, graceful SIGTERM shutdown

See docs/FEATURES.md for detailed documentation, including optional setup for GeoIP and IX detection.

#Installation

#From crates.io (Recommended)

Requires Rust:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Install ttl
cargo install ttl

#Homebrew (macOS/Linux)

brew install ttl

Available directly from Homebrew core. (The lance0/tap/ttl tap also still works and may ship new releases slightly sooner.)

#Alpine Linux

apk add ttl --repository=https://dl-cdn.alpinelinux.org/alpine/edge/testing

Currently in the edge/testing repository (community-maintained).

#Arch Linux (AUR)

yay -S ttl-bin

#Gentoo

emerge net-analyzer/ttl

#NetBSD (pkgsrc)

pkgin install ttl

Or from source: cd /usr/pkgsrc/net/ttl && make install

#NixOS / Nix

# Imperative install
nix-env -iA nixpkgs.ttl

# NixOS configuration
environment.systemPackages = [ pkgs.ttl ];

# Temporary shell
nix-shell -p ttl

Available in nixpkgs unstable (community-maintained).

#Pre-built Binaries

Download from GitHub Releases:

# Download, verify, and install (Linux x86_64 example)
curl -LO https://github.com/lance0/ttl/releases/latest/download/ttl-x86_64-unknown-linux-musl.tar.gz
curl -LO https://github.com/lance0/ttl/releases/latest/download/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing  # macOS: shasum -a 256 -c
tar xzf ttl-*.tar.gz && sudo mv ttl /usr/local/bin/

#Docker

Multi-arch images (amd64/arm64) are published to GHCR on each release:

docker pull ghcr.io/lance0/ttl:latest
docker run --rm -it ghcr.io/lance0/ttl 8.8.8.8

# Headless monitoring with Prometheus metrics
docker run -d -p 9090:9090 ghcr.io/lance0/ttl --daemon --prometheus :9090 8.8.8.8

Docker grants the required NET_RAW capability by default; stricter runtimes may need --cap-add NET_RAW.

#From Source

git clone https://github.com/lance0/ttl
cd ttl && cargo build --release
sudo cp target/release/ttl /usr/local/bin/

#Quick Install Script

Note: Piping scripts from the internet to sh is convenient but bypasses your ability to review the code first. Consider using one of the methods above, or review the script before running.

curl -fsSL https://raw.githubusercontent.com/lance0/ttl/master/install.sh | sh

#Permissions (Linux)

Raw sockets require elevated privileges. The easiest approach is to add the capability once:

# Add capability (works for any install location)
sudo setcap cap_net_raw+ep $(which ttl)

# Then run without sudo:
ttl 8.8.8.8

#Shell Completions

# Bash
ttl --completions bash > ~/.local/share/bash-completion/completions/ttl

# Zsh (add ~/.zfunc to fpath in .zshrc first)
ttl --completions zsh > ~/.zfunc/_ttl

# Fish
ttl --completions fish > ~/.config/fish/completions/ttl.fish

# PowerShell (add to $PROFILE)
ttl --completions powershell >> $PROFILE

#Usage Examples

#Interactive TUI

ttl google.com
ttl 8.8.8.8 1.1.1.1      # Multiple targets (Tab to switch)

#Report and Export

ttl 1.1.1.1 -c 100 --report    # Text report
ttl 1.1.1.1 -c 100 --json      # JSON export
ttl 1.1.1.1 -c 100 --csv       # CSV export
ttl 1.1.1.1 --stream-json      # Stream events as line-delimited JSON
ttl --diff before.json after.json    # Compare two saved sessions
ttl --daemon --prometheus :9090 1.1.1.1   # Headless + Prometheus metrics
ttl --replay results.json      # Replay saved session
ttl --replay results.json --animate  # Animated replay

#Advanced Options

ttl -p tcp --port 443 host     # TCP probes to HTTPS
ttl --flows 4 host             # ECMP path enumeration
ttl --interface eth0 host      # Bind to interface
ttl --size 1400 host           # Large packets for MTU testing
ttl --dscp 46 host             # QoS marking (EF)
ttl --wide host                # Wide mode for wider terminals
ttl --no-update-check host     # Skip the startup release check (see also DO_NOT_TRACK)

See docs/FEATURES.md for full CLI reference.

#Real-World Use Cases

#Find MTU Blackholes in VPNs

VPN tunnels often have lower MTU than expected. Large packets get silently dropped, causing mysterious connection hangs.

sudo ttl --pmtud vpn-gateway.example.com

TTL binary-searches to find the maximum packet size that works. The [MTU: 1400] indicator shows exactly where fragmentation occurs.

#Detect Carrier-Grade NAT Breaking Your Flows

Running multi-flow traceroute but getting inconsistent results? NAT devices may be rewriting your source ports.

sudo ttl --flows 4 target.com

TTL detects when returned source ports don't match what was sent. The [NAT] indicator warns you, and hop details show which device is doing the rewriting.

#Identify Internet Exchange Points

See exactly where your traffic peers with other networks:

sudo ttl cloudflare.com

TTL queries PeeringDB to identify IX points. The hop detail view shows IX name, city, and country. Works out of the box; optionally configure an API key via settings (s key) or PEERINGDB_API_KEY env var for higher rate limits. See docs/FEATURES.md for setup details.

#Catch Flapping Routes

Unstable BGP or failover issues cause intermittent problems that are hard to catch:

sudo ttl -i 0.5 production-server.com

TTL tracks when the responding IP at a hop changes. The ! indicator flags route flaps, and hop details show change history. ECMP load balancing shows E instead, so you can distinguish real instability from expected multi-path behavior.

#Detect Transparent Proxies

Some networks intercept traffic with transparent proxies that manipulate TTL values:

sudo ttl -p tcp --port 80 website.com

The [TTL!] indicator appears when TTL manipulation is detected.

#Distinguish Real Loss from ICMP Rate Limiting

That 30% packet loss at hop 5 might be fake - routers often rate-limit ICMP responses:

sudo ttl target.com

The [RL?] indicator and 50%RL in the loss column tell you it's rate limiting, not actual packet drops.

#Compare Multiple Paths

sudo ttl 8.8.8.8 1.1.1.1 9.9.9.9

Trace multiple destinations at once. Press Tab to switch between them, or l to see a list of all targets.

#Trace All Resolved IPs (Round-Robin DNS)

sudo ttl --resolve-all google.com

When a hostname resolves to multiple IPs (round-robin DNS, CDN load balancing), trace all of them to compare paths. Press l to see all resolved targets with their stats.

#Keybindings

Replay controls are active in --animate replay mode only. See docs/FEATURES.md for the full table.

#Themes

11 built-in themes: default, kawaii, cyber, dracula, monochrome, matrix, nord, gruvbox, catppuccin, tokyo_night, solarized

ttl 1.1.1.1 --theme dracula    # Start with theme
# Press 't' to cycle themes (saved to ~/.config/ttl/config.toml)

#Platform Support

*Pre-built binaries are built on macos-latest (Tahoe). Older macOS versions may have display issues - use cargo install ttl to compile from source.

**FreeBSD/NetBSD support is experimental. Requires sudo. Interface binding (-i) is not supported. Please report issues at https://github.com/lance0/ttl/issues

#Windows via WSL2

wsl --install                    # Install WSL if needed, then restart
wsl                              # Open Ubuntu

Then in Ubuntu:

# Option 1: Install via cargo (recommended)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env
cargo install ttl
sudo ~/.cargo/bin/ttl 8.8.8.8

# Option 2: Pre-built binary via install script
curl -fsSL https://raw.githubusercontent.com/lance0/ttl/master/install.sh | sh
sudo ttl 8.8.8.8

#Known Issues

• iTerm2 on macOS Sequoia: Initial display may render incorrectly. Press r to reset, or use Terminal.app.

#Known Limitations

#Permissions

• Linux: Requires CAP_NET_RAW capability or root (see Permissions)
• macOS/FreeBSD/NetBSD: Requires root (sudo ttl target) - RAW sockets are needed to receive ICMP Time Exceeded messages from intermediate routers

#Protocol Limitations

• ICMP probes: Some networks filter ICMP, try -p udp or -p tcp
• TCP probes: Only SYN (no connection establishment)
• UDP probes: High ports may be filtered by firewalls

#Multi-flow Mode

• NAT devices may rewrite source ports, breaking flow correlation
• The [NAT] indicator warns when this is detected

#Documentation

• Features - Detailed feature documentation and CLI reference
• Scripting - CI/CD integration, JSON parsing, Docker usage
• Architecture - Internal design and module structure
• Contributing - Development setup and guidelines
• Comparison - Comparison with similar tools (including pathping)
• Changelog - Release history
• Roadmap - Planned features

#Troubleshooting

#"sudo: ttl: command not found"

sudo uses a restricted PATH. Use the full path or copy to a sudo-accessible location:

# Option 1: Use full path
sudo ~/.cargo/bin/ttl 8.8.8.8

# Option 2: Copy to /usr/local/bin (one-time)
sudo cp ~/.cargo/bin/ttl /usr/local/bin/

# Option 3: Symlink (updates automatically with cargo install)
sudo ln -sf ~/.cargo/bin/ttl /usr/local/bin/ttl

#Permission errors

Raw ICMP sockets require CAP_NET_RAW or root. See Permissions.

#High packet loss

Try increasing probe interval: ttl target -i 2.0

Some routers rate-limit ICMP - look for the [RL?] indicator in the TUI.

#All hops showing * * *

Check firewall rules, VPN configuration, or try a different protocol: ttl -p udp target

#Theme/config not persisting (macOS)

As of v0.12.1, the config directory on macOS changed from ~/Library/Preferences/ttl/ to ~/Library/Application Support/ttl/ to align with Apple guidelines. If you have an existing config, move it:

mv ~/Library/Preferences/ttl ~/Library/Application\ Support/ttl

#License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.