Trippy

Trippy combines the functionality of traceroute and ping and is designed to assist with the analysis of networking issues.

trippy

Navigation

Trippy

Features

Trace using multiple protocols:
- ICMP, UDP & TCP
- IPv4 & IPv6
Customizable tracing options:
- packet size & payload pattern
- start and maximum time-to-live (TTL)
- minimum and maximum round duration
- round end grace period & maximum number of unknown hops
- source & destination port (TCP & UDP)
- source address and source interface
- TOS (aka DSCP + ECN)
Support for classic, paris and dublin Equal Cost Multi-path Routing strategies (tracking issue)
Tui interface:
- Trace multiple targets simultaneously from a single instance of Trippy
- Per hop stats (sent, received, loss%, last, avg, best, worst, stddev & status)
- Per hop round-trip-time (RTT) history and frequency distributing charts
- Interactive chart of RTT for all hops in a trace with zooming capability
- Interactive GeoIp world map
- Customizable color theme & key bindings
- Configuration via both command line arguments and a configuration file
- Show multiple hosts per hop with ability to cap display to N hosts and show frequency %
- Show hop details and navigate hosts within each hop
- Freeze/unfreeze the Tui, reset the stats, flush the cache, preserve screen on exit
- Responsive UI with adjustable refresh rate
DNS:
- Use system, external (Google 8.8.8.8 or Cloudflare 1.1.1.1) or custom resolver
- Lazy reverse DNS queries
- Lookup autonomous system number (ASN) and name
GeoIp:
- Lookup and display GeoIp information from local mmdb files
Generate tracing reports:
- json, csv & tabular (pretty-printed and markdown)
- configurable reporting cycles
Runs on multiple platform (macOS, Linux, NetBSD, FreeBSD, Windows)
Capabilities aware application (Linux only)

Distributions

Cargo

shell cargo install trippy

Snap (Linux)

shell snap install trippy

Homebrew (MacOS)

shell brew install trippy

Scoop (Windows)

shell scoop install https://trippy.cli.rs/scoop/trippy.json

NetBSD

shell pkgin install trippy

FreeBSD

shell pkg install trippy

Pacman (Arch Linux)

shell pacman -S trippy

Nix

shell nix-env -iA trippy

Docker

shell docker run -it fujiapple/trippy

Platforms

Trippy has been (lightly...) tested on the following platforms:

IPv4

| Platform | ICMP | UDP | TCP | Notes | |----------|------|-----|-----|---------------------------------------------------------------| | Linux | ✅ | ✅ | ✅ | | | macOS | ✅ | ✅ | ✅ | | | NetBSD | ✅ | ✅ | ✅ | | | OpenBSD | ⏳ | ⏳ | ⏳ | See #213 | | FreeBSD | ✅ | ✅ | ✅ | See #214 | | Windows | ✅ | ✅ | ✅ | See #98 |

IPv6

Privileges

Trippy uses a raw socket which require elevated privileges. Enabling the required privilege can be achieved in several ways, including:

1: Run as root user via sudo:

shell sudo trip www.example.com

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

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

3: [Linux only] Set the CAP_NET_RAW capability:

shell sudo setcap CAP_NET_RAW+p $(which trip)

Trippy is a capability aware application and will add CAP_NET_RAW to the effective set if it is present in the allowed set. Note that trippy will drop all capabilities after creating the raw socket.

Usage Examples

Basic usage with default parameters:

shell trip www.example.com

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

shell trip www.example.com -p udp

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

shell trip www.example.com google.com crates.io

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

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

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

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

Use custom destination port 443 for tcp tracing:

shell trip www.example.com -p tcp -P 443

Use custom source port 5000 for udp tracing:

shell trip www.example.com -p udp -S 5000

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

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

Trace with a custom source address:

shell trip www.example.com -p tcp -A 127.0.0.1

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

shell trip www.example.com -p tcp -I en0

Trace using IPv6:

shell trip www.example.com -6

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

shell trip www.example.com -m json -C 5

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

shell trip www.example.com -r google

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

shell trip www.example.com -r google -z true

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

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

Customize the color theme:

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

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

shell trip --print-tui-theme-items

Customize the key bindings:

shell trip www.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:

shell trip --print-tui-binding-commands

Specify the location of the trippy config file:

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

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

shell trip --generate bash

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

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

Command Reference

```shell Usage: trip [OPTIONS] [TARGETS]...

Arguments: [TARGETS]... A space delimited list of hostnames and IPs to trace

Options: -c, --config-file Config file

-m, --mode Output mode [default: tui]

      Possible values:
      - tui:      Display interactive TUI
      - stream:   Display a continuous stream of tracing data
      - pretty:   Generate an pretty text table report for N cycles
      - markdown: Generate a markdown text table report for N cycles
      - csv:      Generate a SCV report for N cycles
      - json:     Generate a JSON report for N cycles
      - silent:   Do not generate any tracing output for N cycles

-p, --protocol Tracing protocol [default: icmp]

      Possible values:
      - icmp: Internet Control Message Protocol
      - udp:  User Datagram Protocol
      - tcp:  Transmission Control Protocol

  --udp
      Trace using the UDP protocol

  --tcp
      Trace using the TCP protocol

-4, --ipv4 use IPv4 only

-6, --ipv6 Use IPv6 only

-P, --target-port The target port (TCP & UDP only) [default: 80]

-S, --source-port The source port (TCP & UDP only) [default: auto]

-A, --source-address The source IP address [default: auto]

-I, --interface The network interface [default: auto]

-i, --min-round-duration The minimum duration of every round [default: 1s]

-T, --max-round-duration The maximum duration of every round [default: 1s]

-g, --grace-duration The period of time to wait for additional ICMP responses after the target has responded [default: 100ms]

  --initial-sequence <INITIAL_SEQUENCE>
      The initial sequence number [default: 33000]

-R, --multipath-strategy The Equal-cost Multi-Path routing strategy (IPv4/UDP only) [default: classic]

      Possible values:
      - classic:
        The src or dest port is used to store the sequence number
      - paris:
        The UDP `checksum` field is used to store the sequence number
      - dublin:
        The IP `identifier` field is used to store the sequence number

-U, --max-inflight The maximum number of in-flight ICMP echo requests [default: 24]

-f, --first-ttl The TTL to start from [default: 1]

-t, --max-ttl The maximum number of TTL hops [default: 64]

  --packet-size <PACKET_SIZE>
      The size of IP packet to send (IP header + ICMP header + payload)
      [default: 84]

  --payload-pattern <PAYLOAD_PATTERN>
      The repeating pattern in the payload of the ICMP packet [default: 0]

-Q, --tos The TOS (i.e. DSCP+ECN) IP header value (TCP and UDP only) [default: 0]

  --read-timeout <READ_TIMEOUT>
      The socket read timeout [default: 10ms]

-r, --dns-resolve-method How to perform DNS queries [default: system]

      Possible values:
      - system:     Resolve using the OS resolver
      - resolv:     Resolve using the `/etc/resolv.conf` DNS configuration
      - google:     Resolve using the Google `8.8.8.8` DNS service
      - cloudflare: Resolve using the Cloudflare `1.1.1.1` DNS service

  --dns-timeout <DNS_TIMEOUT>
      The maximum time to wait to perform DNS queries [default: 5s]

-z, --dns-lookup-as-info Lookup autonomous system (AS) information during DNS queries [default: false]

      [possible values: true, false]

-a, --tui-address-mode How to render addresses [default: host]

      Possible values:
      - ip:   Show IP address only
      - host: Show reverse-lookup DNS hostname only
      - both: Show both IP address and reverse-lookup DNS hostname

  --tui-as-mode <TUI_AS_MODE>
      How to render AS information [default: asn]

      Possible values:
      - asn:          Show the ASN
      - prefix:       Display the AS prefix
      - country-code: Display the country code
      - registry:     Display the registry name
      - allocated:    Display the allocated date
      - name:         Display the AS name

  --tui-geoip-mode <TUI_GEOIP_MODE>
      How to render GeoIp information [default: short]

      Possible values:
      - off:      Do not display GeoIp data
      - short:    Show short format
      - long:     Show long format
      - location: Show latitude and Longitude format

-M, --tui-max-addrs The maximum number of addresses to show per hop [default: auto]

-s, --tui-max-samples The maximum number of samples to record per hop [default: 256]

  --tui-preserve-screen <TUI_PRESERVE_SCREEN>
      Preserve the screen on exit [default: false]

      [possible values: true, false]

  --tui-refresh-rate <TUI_REFRESH_RATE>
      The Tui refresh rate [default: 100ms]

  --tui-theme-colors <TUI_THEME_COLORS>
      The TUI theme colors [item=color,item=color,..]

  --print-tui-theme-items
      Print all TUI theme items and exit

  --tui-key-bindings <TUI_KEY_BINDINGS>
      The TUI key bindings [command=key,command=key,..]

  --print-tui-binding-commands
      Print all TUI commands that can be bound and exit

-C, --report-cycles The number of report cycles to run [default: 10]

-G, --geoip-mmdb-file The MaxMind City GeoLite2 mmdb file

  --generate <GENERATE>
      Generate shell completion

      [possible values: bash, elvish, fish, powershell, zsh]

  --log-format <LOG_FORMAT>
      The debug log format [default: pretty]

      Possible values:
      - compact: Display log data in a compact format
      - pretty:  Display log data in a pretty format
      - json:    Display log data in a json format
      - chrome:  Display log data in Chrome trace format

  --log-filter <LOG_FILTER>
      The debug log filter [default: trippy=debug]

  --log-span-events <LOG_SPAN_EVENTS>
      The debug log format [default: off]

      Possible values:
      - off:    Do not display event spans
      - active: Display enter and exit event spans
      - full:   Display all event spans

-v, --verbose Enable verbose debug logging

-h, --help Print help (see a summary with '-h')

-V, --version Print version ```

Theme Reference

The following table lists the default Tui color theme. These can be overridden with the --tui-theme-colors command line option.

| Item |-------------------------------------- | bg-color | border-color | text-color | tab-text-color | hops-table-header-bg-color | hops-table-header-text-color | hops-table-row-active-text-color | hops-table-row-inactive-text-color | hops-chart-selected-color | hops-chart-unselected-color | hops-chart-axis-color | frequency-chart-bar-color | frequency-chart-text-color | samples-chart-color | help-dialog-bg-color | help-dialog-text-color | settings-dialog-bg-color | settings-tab-text-color | settings-table-header-text-color | settings-table-header-bg-color | settings-table-row-text-color | map-world-color | map-radius-color | map-selected-color | map-info-panel-border-color | map-info-panel-bg-color | map-info-panel-text-color | Description | Default | |------------------------------------------------------|------------| | The default background color | Black | | The default color of borders | Gray | | The default color of text | Gray | | The color of the text in traces tabs | Green | | The background color of the hops table header | White | | The color of text in the hops table header | Black | | The color of text of active rows in the hops table | Gray | | The color of text of inactive rows in the hops table | DarkGray | | The color of the selected series in the hops chart | Green | | The color of the unselected series in the hops chart | Gray | | The color of the axis in the hops chart | DarkGray | | The color of bars in the frequency chart | Green | | The color of text in the bars of the frequency chart | Gray | | The color of the samples chart | Yellow | | The background color of the help dialog | Blue | | The color of the text in the help dialog | Gray | | The background color of the settings dialog | blue | | The color of the text in settings dialog tabs | green | | The color of text in the settings table header | black | | The background color of the settings table header | white | | The color of text of rows in the settings table | gray | | The color of the map world diagram | white | | The color of the map accuracy radius circle | yellow | | The color of the map selected item box | green | | The color of border of the map info panel | gray | | The background color of the map info panel | black | | The color of text in the map info panel | gray |

The supported colors are:

Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White

Color names are case-insensitive and may contain dashes. Raw hex values, such as ffffff for white, may also be used.

Key Bindings Reference

The following table lists the default Tui command key bindings. These can be overridden with the --tui-key-bindings command line option.

| Command | Description | Default | |------------------------|-------------------------------------------------|----------| | toggle-help | Toggle help | h | | toggle-settings | Toggle settings | s | | next-hop | Select next hop | down | | previous-hop | Select previous hop | up | | next-trace | Select next trace | right | | previous-trace | Select previous trace | left | | next-hop-address | Select next hop address | . | | previous-hop-address | Select previous hop address | , | | address-mode-ip | Show IP address only | i | | address-mode-host | Show hostname only | n | | address-mode-both | Show both IP address and hostname | b | | toggle-freeze | Toggle freezing the display | f | | toggle-chart | Toggle the chart | c | | toggle-map | Toggle the GeoIp map | m | | expand-hosts | Expand the hosts shown per hop | ] | | expand-hosts-max | Expand the hosts shown per hop to the maximum | } | | contract-hosts | Contract the hosts shown per hop | [ | | contract-hosts-min | Contract the hosts shown per hop to the minimum | { | | chart-zoom-in | Zoom in the chart | = | | chart-zoom-out | Zoom out the chart | - | | clear-trace-data | Clear all trace data | ctrl+r | | clear-dns-cache | Flush the DNS cache | ctrl+k | | clear-selection | Clear the current selection | esc | | toggle-as-info | Toggle AS info display | z | | toggle-hop-details | Toggle hop details | d | | quit | Quit the application | q |

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

Configuration Reference

Trippy can be configured with via command line arguments or an optional configuration file. If a given configuration item is specified in both the configuration file and via a command line argument then the latter will take precedence.

The configuration file location may be provided to trippy via the -c (--config-file) argument. If not provided, Trippy will attempt to locate a trippy.toml or .trippy.toml configuration file in one of the following locations:

The current directory
The user home directory
the XDG config directory (Unix only): $XDG_CONFIG_HOME or ~/.config
the Windows data directory (Windows only): %APPDATA%

An annotated template configuration file is available.

Acknowledgements

Trippy is made possible by 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.

License

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.