{"id":38161111,"url":"https://github.com/lance0/ttl","last_synced_at":"2026-02-12T18:00:59.929Z","repository":{"id":332138132,"uuid":"1132876680","full_name":"lance0/ttl","owner":"lance0","description":"Fast, modern traceroute with real-time TUI, per-hop stats, ASN/geo lookup, ECMP detection, and MPLS label parsing. A better mtr.","archived":false,"fork":false,"pushed_at":"2026-02-04T11:52:06.000Z","size":1876,"stargazers_count":727,"open_issues_count":5,"forks_count":47,"subscribers_count":7,"default_branch":"master","last_synced_at":"2026-02-04T23:48:36.258Z","etag":null,"topics":["asn-lookup","cli","geolocation","icmp","latency","latency-test","mtr","network-visualization","networking","ratatui","rust","terminal","traceroute","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lance0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"lance0"}},"created_at":"2026-01-12T15:16:32.000Z","updated_at":"2026-02-04T18:48:02.000Z","dependencies_parsed_at":"2026-01-18T17:00:53.883Z","dependency_job_id":null,"html_url":"https://github.com/lance0/ttl","commit_stats":null,"previous_names":["lance0/ttl"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/lance0/ttl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance0%2Fttl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance0%2Fttl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance0%2Fttl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance0%2Fttl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lance0","download_url":"https://codeload.github.com/lance0/ttl/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lance0%2Fttl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29375591,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["asn-lookup","cli","geolocation","icmp","latency","latency-test","mtr","network-visualization","networking","ratatui","rust","terminal","traceroute","tui"],"created_at":"2026-01-16T23:14:56.073Z","updated_at":"2026-02-12T18:00:59.915Z","avatar_url":"https://github.com/lance0.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"ttl.png\" alt=\"ttl logo\" width=\"200\"\u003e\n\u003c/p\u003e\n\n# ttl\n\nNetwork diagnostic tool that goes beyond traceroute: MTU discovery, NAT detection, route flap alerts, IX identification, and more.\n\n![ttl screenshot](ttlss.png)\n\n[![Crates.io](https://img.shields.io/crates/v/ttl.svg)](https://crates.io/crates/ttl)\n[![CI](https://github.com/lance0/ttl/actions/workflows/ci.yml/badge.svg)](https://github.com/lance0/ttl/actions/workflows/ci.yml)\n[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)\n[![Ko-fi](https://img.shields.io/badge/Ko--fi-tip-ff5e5b?logo=ko-fi)](https://ko-fi.com/lance0)\n\n## Quick Start\n\n```bash\n# Basic usage\nttl 8.8.8.8                          # Linux (after setcap)\nsudo ttl 8.8.8.8                     # macOS (always needs sudo)\n\n# Common options\nttl -p udp google.com                # UDP probes\nttl --flows 8 cloudflare.com         # ECMP path discovery\nttl --pmtud 1.1.1.1                  # Path MTU discovery\nttl 8.8.8.8 1.1.1.1 9.9.9.9          # Multiple targets\nttl --resolve-all google.com         # Trace all resolved IPs\n```\n\nSee [Installation](#installation) below for setup instructions.\n\n## Features\n\n- **Fast continuous path monitoring** with detailed hop statistics\n- **Multiple simultaneous targets** - trace to several destinations at once\n- **Paris/Dublin traceroute** - multi-flow probing for ECMP path enumeration\n- **Path MTU discovery** - binary search for maximum unfragmented size\n- **NAT detection** - identify when NAT devices rewrite source ports\n- **Route flap detection** - alert on path changes indicating routing instability\n- **Rich enrichment** - ASN, GeoIP, reverse DNS, IX detection (PeeringDB)\n- **MPLS label detection** from ICMP extensions\n- **ICMP, UDP, TCP probing** with auto-detection\n- **Great TUI** with themes, sparklines, and session export\n- **Update notifications** - in-app banner when new versions are available\n- **Scriptable** - JSON, CSV, and text report output\n\nSee [docs/FEATURES.md](docs/FEATURES.md) for detailed documentation, including optional setup for [GeoIP](docs/FEATURES.md#geoip-location) and [IX detection](docs/FEATURES.md#ix-detection).\n\n## Installation\n\n### From crates.io (Recommended)\n\nRequires [Rust](https://www.rust-lang.org/tools/install):\n\n```bash\n# Install Rust (if not already installed)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource ~/.cargo/env\n\n# Install ttl\ncargo install ttl\n```\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew install lance0/tap/ttl\n```\n\n### Arch Linux (AUR)\n\n```bash\nyay -S ttl-bin\n```\n\n### Gentoo\n\n```bash\nemerge net-analyzer/ttl\n```\n\n### Pre-built Binaries\n\nDownload from [GitHub Releases](https://github.com/lance0/ttl/releases):\n\n| Platform | Target |\n|----------|--------|\n| Linux x86_64 | `ttl-x86_64-unknown-linux-musl.tar.gz` |\n| Linux ARM64 | `ttl-aarch64-unknown-linux-gnu.tar.gz` |\n| macOS Apple Silicon | `ttl-aarch64-apple-darwin.tar.gz` |\n| macOS Intel | `ttl-x86_64-apple-darwin.tar.gz` |\n\n```bash\n# Download, verify, and install (Linux x86_64 example)\ncurl -LO https://github.com/lance0/ttl/releases/latest/download/ttl-x86_64-unknown-linux-musl.tar.gz\ncurl -LO https://github.com/lance0/ttl/releases/latest/download/SHA256SUMS\nsha256sum -c SHA256SUMS --ignore-missing  # macOS: shasum -a 256 -c\ntar xzf ttl-*.tar.gz \u0026\u0026 sudo mv ttl /usr/local/bin/\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/lance0/ttl\ncd ttl \u0026\u0026 cargo build --release\nsudo cp target/release/ttl /usr/local/bin/\n```\n\n### Quick Install Script\n\n\u003e **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](https://github.com/lance0/ttl/blob/master/install.sh) before running.\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/lance0/ttl/master/install.sh | sh\n```\n\n### Permissions (Linux)\n\nRaw sockets require elevated privileges. The easiest approach is to add the capability once:\n\n```bash\n# Add capability (works for any install location)\nsudo setcap cap_net_raw+ep $(which ttl)\n\n# Then run without sudo:\nttl 8.8.8.8\n```\n\n### Shell Completions\n\n```bash\n# Bash\nttl --completions bash \u003e ~/.local/share/bash-completion/completions/ttl\n\n# Zsh (add ~/.zfunc to fpath in .zshrc first)\nttl --completions zsh \u003e ~/.zfunc/_ttl\n\n# Fish\nttl --completions fish \u003e ~/.config/fish/completions/ttl.fish\n\n# PowerShell (add to $PROFILE)\nttl --completions powershell \u003e\u003e $PROFILE\n```\n\n## Usage Examples\n\n### Interactive TUI\n\n```bash\nttl google.com\nttl 8.8.8.8 1.1.1.1      # Multiple targets (Tab to switch)\n```\n\n### Report and Export\n\n```bash\nttl 1.1.1.1 -c 100 --report    # Text report\nttl 1.1.1.1 -c 100 --json      # JSON export\nttl 1.1.1.1 -c 100 --csv       # CSV export\nttl --replay results.json      # Replay saved session\nttl --replay results.json --animate  # Animated replay\n```\n\n### Advanced Options\n\n```bash\nttl -p tcp --port 443 host     # TCP probes to HTTPS\nttl --flows 4 host             # ECMP path enumeration\nttl --interface eth0 host      # Bind to interface\nttl --size 1400 host           # Large packets for MTU testing\nttl --dscp 46 host             # QoS marking (EF)\nttl --wide host                # Wide mode for wider terminals\n```\n\nSee [docs/FEATURES.md](docs/FEATURES.md) for full CLI reference.\n\n## Real-World Use Cases\n\n### Find MTU Blackholes in VPNs\n\nVPN tunnels often have lower MTU than expected. Large packets get silently dropped, causing mysterious connection hangs.\n\n```bash\nsudo ttl --pmtud vpn-gateway.example.com\n```\n\nTTL binary-searches to find the maximum packet size that works. The `[MTU: 1400]` indicator shows exactly where fragmentation occurs.\n\n### Detect Carrier-Grade NAT Breaking Your Flows\n\nRunning multi-flow traceroute but getting inconsistent results? NAT devices may be rewriting your source ports.\n\n```bash\nsudo ttl --flows 4 target.com\n```\n\nTTL 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.\n\n### Identify Internet Exchange Points\n\nSee exactly where your traffic peers with other networks:\n\n```bash\nsudo ttl cloudflare.com\n```\n\nTTL 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](docs/FEATURES.md#ix-detection) for setup details.\n\n### Catch Flapping Routes\n\nUnstable BGP or failover issues cause intermittent problems that are hard to catch:\n\n```bash\nsudo ttl -i 0.5 production-server.com\n```\n\nTTL tracks when the responding IP at a hop changes. The `!` indicator flags route flaps, and hop details show change history.\n\n### Detect Transparent Proxies\n\nSome networks intercept traffic with transparent proxies that manipulate TTL values:\n\n```bash\nsudo ttl -p tcp --port 80 website.com\n```\n\nThe `[TTL!]` indicator appears when TTL manipulation is detected.\n\n### Distinguish Real Loss from ICMP Rate Limiting\n\nThat 30% packet loss at hop 5 might be fake - routers often rate-limit ICMP responses:\n\n```bash\nsudo ttl target.com\n```\n\nThe `[RL?]` indicator and `50%RL` in the loss column tell you it's rate limiting, not actual packet drops.\n\n### Compare Multiple Paths\n\n```bash\nsudo ttl 8.8.8.8 1.1.1.1 9.9.9.9\n```\n\nTrace multiple destinations at once. Press `Tab` to switch between them, or `l` to see a list of all targets.\n\n### Trace All Resolved IPs (Round-Robin DNS)\n\n```bash\nsudo ttl --resolve-all google.com\n```\n\nWhen 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.\n\n## Keybindings\n\n| Key | Action |\n|-----|--------|\n| `q` / `Ctrl+C` | Quit |\n| `p` / `Space` | Pause/Resume |\n| `r` | Reset stats |\n| `t` | Cycle theme |\n| `w` | Cycle display mode |\n| `s` | Settings |\n| `e` | Export JSON |\n| `?` | Help |\n| `u` | Dismiss update banner |\n| `Tab` | Next target |\n| `l` | Target list |\n| `Enter` | Expand hop |\n\n## Themes\n\n11 built-in themes: `default`, `kawaii`, `cyber`, `dracula`, `monochrome`, `matrix`, `nord`, `gruvbox`, `catppuccin`, `tokyo_night`, `solarized`\n\n```bash\nttl 1.1.1.1 --theme dracula    # Start with theme\n# Press 't' to cycle themes (saved to ~/.config/ttl/config.toml)\n```\n\n## Platform Support\n\n| Platform | Status |\n|----------|--------|\n| Linux | Full support |\n| macOS (Tahoe 26+) | Full support |\n| macOS (Sequoia 15) | Build from source* |\n| FreeBSD | Experimental** |\n| Windows (WSL2) | Full support |\n| Windows (native) | Not supported |\n\n*Pre-built binaries are built on `macos-latest` (Tahoe). Older macOS versions may have display issues - use `cargo install ttl` to compile from source.\n\n**FreeBSD support is untested. Requires `sudo`. Interface binding (`-i`) is not supported. Please report issues at https://github.com/lance0/ttl/issues\n\n### Windows via WSL2\n\n```powershell\nwsl --install                    # Install WSL if needed, then restart\nwsl                              # Open Ubuntu\n```\n\nThen in Ubuntu:\n\n```bash\n# Option 1: Install via cargo (recommended)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh\nsource ~/.cargo/env\ncargo install ttl\nsudo ~/.cargo/bin/ttl 8.8.8.8\n\n# Option 2: Pre-built binary via install script\ncurl -fsSL https://raw.githubusercontent.com/lance0/ttl/master/install.sh | sh\nsudo ttl 8.8.8.8\n```\n\n## Known Issues\n\n- **iTerm2 on macOS Sequoia**: Initial display may render incorrectly. Press `r` to reset, or use Terminal.app.\n\n## Known Limitations\n\n### Permissions\n- Linux: Requires `CAP_NET_RAW` capability or root (see [Permissions](#permissions-linux))\n- macOS/FreeBSD: Requires root (`sudo ttl target`) - RAW sockets are needed to receive ICMP Time Exceeded messages from intermediate routers\n\n### Protocol Limitations\n- ICMP probes: Some networks filter ICMP, try `-p udp` or `-p tcp`\n- TCP probes: Only SYN (no connection establishment)\n- UDP probes: High ports may be filtered by firewalls\n\n### Multi-flow Mode\n- NAT devices may rewrite source ports, breaking flow correlation\n- The `[NAT]` indicator warns when this is detected\n\n## Documentation\n\n- [Features](docs/FEATURES.md) - Detailed feature documentation and CLI reference\n- [Scripting](docs/SCRIPTING.md) - CI/CD integration, JSON parsing, Docker usage\n- [Architecture](docs/ARCHITECTURE.md) - Internal design and module structure\n- [Contributing](CONTRIBUTING.md) - Development setup and guidelines\n- [Comparison](docs/COMPARISON.md) - Comparison with similar tools (including pathping)\n- [Changelog](CHANGELOG.md) - Release history\n- [Roadmap](ROADMAP.md) - Planned features\n\n## Troubleshooting\n\n### \"sudo: ttl: command not found\"\n\nsudo uses a restricted PATH. Use the full path or copy to a sudo-accessible location:\n\n```bash\n# Option 1: Use full path\nsudo ~/.cargo/bin/ttl 8.8.8.8\n\n# Option 2: Copy to /usr/local/bin (one-time)\nsudo cp ~/.cargo/bin/ttl /usr/local/bin/\n\n# Option 3: Symlink (updates automatically with cargo install)\nsudo ln -sf ~/.cargo/bin/ttl /usr/local/bin/ttl\n```\n\n### Permission errors\n\nRaw ICMP sockets require `CAP_NET_RAW` or root. See [Permissions](#permissions-linux).\n\n### High packet loss\n\nTry increasing probe interval: `ttl target -i 2.0`\n\nSome routers rate-limit ICMP - look for the `[RL?]` indicator in the TUI.\n\n### All hops showing `* * *`\n\nCheck firewall rules, VPN configuration, or try a different protocol: `ttl -p udp target`\n\n### Theme/config not persisting (macOS)\n\nAs 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:\n\n```bash\nmv ~/Library/Preferences/ttl ~/Library/Application\\ Support/ttl\n```\n\n## License\n\nLicensed under either of:\n\n- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))\n- MIT license ([LICENSE-MIT](LICENSE-MIT))\n\nat your option.\n","funding_links":["https://ko-fi.com/lance0"],"categories":["cli"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flance0%2Fttl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flance0%2Fttl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flance0%2Fttl/lists"}