mping

README

mping

mping is a terminal-based multi-target ping tool written in Go. It pings multiple hosts simultaneously and displays real-time statistics — packet loss, RTT, TTL, and more — in a clean TUI (Text User Interface).

日本語

Features

• Multi-target ping — monitor multiple hosts concurrently in a single view.
• Real-time statistics — packet loss, RTT, TTL, and error messages updated live.
• TUI dashboard — high-visibility table on a black background. Column widths are distributed automatically based on terminal width; switches to a compact 2-row-per-target layout when the window is narrow.
• Color-coded alerts — loss ratio, RTT, and Jitter are color-coded for instant status recognition. Alerts are recorded in the Log pane when thresholds are exceeded.
• Flexible configuration — specify interface, source IP, packet size, send count, and more.
• YAML host list — manage target hosts in a file.
• Traceroute pane — show the route to each target in a Host/Route table when -T is given. Multiple targets are traced concurrently and displayed together.
• Port Monitor pane — monitor TCP/UDP port reachability in real time with -p. Displays the estimated service name, cumulative Open/Closed counts, and time since last status change.
• PMTU discovery — probe maximum payload size using DF-bit ICMP packets.
• Auto source IP detection — automatically detects and displays the local IP used for each destination.
• RTT graph — fixed range of 0–100 ms (Y-axis) × 30 seconds (X-axis) per target.
• CSV log output — save results with statistics to a file.

Supported platforms

OS	Architecture	Notes
Linux	amd64, arm64	Recommended: grant CAP_NET_RAW via setcap
macOS	amd64, arm64 (Apple Silicon)	Uses setuid

Privileges required — mping uses raw ICMP sockets to obtain accurate TTL values. On Linux the preferred approach is granting CAP_NET_RAW with setcap; install.sh handles this automatically. On macOS a setuid bit is set instead.

Terminal Compatibility — Standard terminals on Linux and macOS may not render colors correctly. If you experience issues with color display, consider using a modern terminal emulator (e.g., iTerm2, Alacritty, or kitty).

Installation

Option 1 — Pre-built binary (recommended)

Download the archive for your platform from the Releases page and run the bundled install.sh.

Linux (amd64)

# Download and extract (replace vX.Y.Z with the latest version)
curl -LO https://github.com/nagayon-935/mping/releases/download/vX.Y.Z/mping-vX.Y.Z-linux-amd64.tar.gz
tar -xzf mping-vX.Y.Z-linux-amd64.tar.gz

# Install (grants CAP_NET_RAW via setcap; falls back to setuid if setcap is unavailable)
sudo ./install.sh

Linux (arm64 — e.g. Raspberry Pi, AWS Graviton)

curl -LO https://github.com/nagayon-935/mping/releases/download/vX.Y.Z/mping-vX.Y.Z-linux-arm64.tar.gz
tar -xzf mping-vX.Y.Z-linux-arm64.tar.gz
sudo ./install.sh

macOS (Intel)

curl -LO https://github.com/nagayon-935/mping/releases/download/vX.Y.Z/mping-vX.Y.Z-darwin-amd64.tar.gz
tar -xzf mping-vX.Y.Z-darwin-amd64.tar.gz
sudo ./install.sh

macOS (Apple Silicon)

curl -LO https://github.com/nagayon-935/mping/releases/download/vX.Y.Z/mping-vX.Y.Z-darwin-arm64.tar.gz
tar -xzf mping-vX.Y.Z-darwin-arm64.tar.gz
sudo ./install.sh

install.sh copies the binary to INSTALL_DIR (default: /usr/local/bin) and sets the appropriate privilege:

• Linux — setcap cap_net_raw+ep (falls back to setuid if setcap is not available)
• macOS — chown root + chmod u+s (setuid)

To install to a different directory:

sudo INSTALL_DIR=/usr/local/bin ./install.sh

After installation, run mping without sudo:

mping google.com 1.1.1.1

---

Option 2 — Build from source

Requirements: Go 1.24 or later

git clone https://github.com/nagayon-935/mping.git
cd mping

Using make

# Build only
make build

# Build + install (sets setuid on macOS; use install.sh on Linux for setcap)
make install

Note for Linux users: make install sets a setuid bit, which works but is less secure than setcap. For production use, run go build -o mping ./cmd/main and then sudo ./install.sh to get CAP_NET_RAW via setcap.

Using go build directly

go build -o mping ./cmd/main
sudo ./install.sh

Usage

# Basic (no sudo needed after install.sh)
mping google.com 1.1.1.1 8.8.8.8

# Specify network interface
mping -I eth0 google.com

# Set packet size (100 bytes) and count (10 packets)
mping -s 100 -c 10 google.com

# Save results to a CSV file
mping -o results.csv google.com

# Load hosts from a YAML file
mping -f hosts.yaml

# Force IPv4 only
mping -4 google.com

# Force IPv6 only
mping -6 google.com

# Show Traceroute pane
mping -T google.com

# PMTU discovery (probes from payload size 9872 downward)
mping -m google.com

# TCP port reachability check (443/tcp)
mping -p 443/tcp google.com

# Multiple ports (comma-separated)
mping -p 443/tcp,53/udp google.com 8.8.8.8

# Traceroute + Port Monitor simultaneously
mping -T -p 443/tcp google.com

If you run mping without installing (i.e. without setcap/setuid), prepend sudo:

sudo ./mping google.com

hosts.yaml example

List hosts under the hosts: key. Options specified here are overridden by explicit CLI flags.

hosts:
  - google.com
  - 1.1.1.1
interval: 500
timeout: 2000
traceroute: true
port:
  - 443/tcp
  - 53/udp

Options

Flag	Short	Description	Default
--interval	-i	Ping send interval (ms)	1000
--timeout	-t	Ping timeout (ms)	1000
--file	-f	Path to YAML host list file	""
--traceroute	-T	Show Traceroute pane	false
--discovery-mtu	-m	Discover max payload size with DF bit	false
--interface	-I	Network interface name (e.g. eth0, en0)	""
--source	-S	Source IPv4 address	"" (auto-detect)
--size	-s	Payload size in bytes	56
--count	-c	Number of packets per target (0 = unlimited)	0
--ipv4	-4	Use IPv4 only	false
--ipv6	-6	Use IPv6 only	false
--output	-o	CSV log output file path	""
--port	-p	Ports to check (e.g. 443/tcp, 53/udp, 443). Comma-separated for multiple.	""

Key bindings

Key	Action
q	Quit the application
s	Pause ping
S	Resume ping (only valid after s)
R	Reset all statistics and logs
Tab	Cycle focus: Ping Monitor → Traceroute Monitor → Port Monitor → RTT Graphs → Log
↑ / ↓ / PgUp / PgDn	Scroll focused pane (Table / Traceroute / RTT Graphs)

TUI columns

• Src IP — Local IP address used for sending.
• Dst IP — Resolved destination IP. Shown as domain (IP) when a hostname is given.
• Success — Number of packets received successfully.
• Loss — Number of lost packets.
• Loss Ratio — Packet loss percentage.
  • Green: 0%–20%  |  Orange: 20%–80%  |  Vivid red: >80%
• RTT / Avg / Jitter — Latest / average / jitter round-trip time.
  • RTT: Green (≤50 ms) / Orange (≤200 ms) / Red (>200 ms)
  • Jitter: Green (≤10 ms) / Orange (≤50 ms) / Red (>50 ms)
• Size — Payload size of sent packets.
• MTU — MTU of the outbound interface.
• TTL — Time To Live of the last received packet.
• Error — Abbreviated latest error message (red). Full details appear in the Log pane.
• Last Loss — Time elapsed since the last packet loss.

Traceroute Monitor pane

• Shown only when -T / --traceroute is given.
• Probes up to 30 hops and displays results in a Host / Route two-column table.
• Multiple targets are traced concurrently and separated by divider rows.
• One traceroute is run at startup, then automatically refreshed every 10 minutes.

Port Monitor pane

• Shown only when -p / --port is given.
• Performs TCP/UDP reachability checks in real time at the ping interval.
• Multiple ports can be specified comma-separated (e.g. -p 443/tcp,53/udp).
• Omitting the protocol defaults to TCP (e.g. -p 443 → 443/tcp).
• Columns:
  • Target — Hostname
  • Port — Port number and protocol (e.g. 443/tcp)
  • Service — Estimated service name (Unknown if not recognized)
  • Status — Green Open / Red Closed / Yellow Filtered or Open|Filtered
  • Open/Closed — Cumulative Open count / Closed+Filtered count
  • Last Change — Time elapsed since the last status change

PMTU discovery

• Enabled with --discovery-mtu / -m.
• Probes maximum payload size using DF-bit ICMP, starting from 9872 bytes.
• The discovered size is reflected in the Size column.

License

MIT