tcping

TCPING

[!CAUTION] This is a work in progress branch, not the main one.

A cross-platform ping program using TCP, UDP or HTTP(S) instead of ICMP, inspired by Linux's ping utility.

[!TIP] This document is also available in 中文.

• An alternative to ping where ICMP is blocked, probing over TCP, HTTP(S) or UDP.
• Reports the packet loss and the minimum, average, maximum and mean deviation of the latency, the same way ping does, plus the longest uptime and downtime and when they happened.
• Prints the statistics at any time by pressing the Enter key, without stopping the program.
• Outputs in colored, plain, JSON, CSV or sqlite3 format, or sends every probe as metrics over OTLP (Grafana Alloy, the OpenTelemetry Collector and others) or to InfluxDB.
• Shows the status code, the TLS version and cipher, the certificate expiry and the connect, TLS handshake and first-byte timings of every HTTP(S) probe.
• Resolves the target's hostname again after a number of failures (-r) or before every probe (--resolve-every-probe), and reports how long each lookup took. Suitable to test your DNS load balancing or Global Server Load Balancer (GSLB).
• Lets you pick the source interface, the timeout, the interval and the DNS server, and enforce IPv4 or IPv6.
• Numbers successful and unsuccessful probes separately, so the totals are visible at a glance.

Check out the demos to get a look and feel of tcping.

Table of Contents

• Demos
• Download and Installation
• Usage
• Flags
• Contributing
• Help The Project
• License

Demos

Click to expand

Basic usage

Timestamped probes over IPv4 (-D -4) flags

Plain output, statistics only when Enter is pressed (--no-color --no-stats) flags

Retry hostname lookup (-r) flag

JSON output (-j --pretty) flag

Streaming the JSON output to a collector (--json-url --json-server) flags

Hostname resolution timing (--resolve-every-probe) flag

Source interface (-I) flag

HTTP(S) probes

HTTP(S) probe details (-v) flag

Skipping certificate verification (--insecure) flag

UDP probes against a UDP server (--udp-server) flag

Only the failed probes (--failures-only) flag

Download and Installation

The binaries are static, meaning they carry everything they need inside one file and do not depend on any library being present on your machine. They live on the release page, for amd64 and arm64.

Once you are done with the installation, head to the usage section.

Windows

The best way to install tcping on Windows is through Windows Package Manager by utilizing WinGet, which is available on practically all Windows 10 and 11 machines by default since September of 2020:

winget install pj.tcping

To install it by hand instead, extract the downloaded zip file and copy tcping.exe to your system PATH like C:\Windows\System32.

[!CAUTION] TCPING might falsely get flagged by Windows Defender or some anti-malware software. This is common among Go programs. Check out the official statement from the Go team here.

[!WARNING] The --sqlite (sqlite3) output format is not available on Windows binaries anymore. All the other flags work as expected.

macOS

brew install pouriyajamshidi/tap/tcping

Linux - One-line install

Paste the following in your terminal to grab the latest binary for your architecture and install it:

cd /tmp &&
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/') &&
curl -LO "https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-linux-$ARCH.tar.gz" &&
tar -xf "tcping-linux-$ARCH.tar.gz" &&
sudo install tcping /usr/local/bin/ &&
sudo install -Dm 644 completions/tcping.bash /usr/share/bash-completion/completions/tcping &&
sudo install -Dm 644 completions/_tcping /usr/share/zsh/site-functions/_tcping &&
sudo install -Dm 644 completions/tcping.fish /usr/share/fish/vendor_completions.d/tcping.fish &&
tcping --version

The last three lines install the shell completions. Drop the ones for the shells you do not use, and start a new shell to pick them up.

If you don't have curl, swap its line for wget:

wget "https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-linux-$ARCH.tar.gz" &&

Linux - Package repositories

Adding the repository once means apt, dnf or apk handles installs and upgrades from then on, like any other package.

Debian, Ubuntu and their flavors:

sudo install -d /etc/apt/keyrings &&
  sudo curl -fsSL https://pouriyajamshidi.github.io/packages/keys/pouriyajamshidi.gpg -o /etc/apt/keyrings/pouriyajamshidi.gpg &&
  echo "deb [signed-by=/etc/apt/keyrings/pouriyajamshidi.gpg] https://pouriyajamshidi.github.io/packages/deb ./" | sudo tee /etc/apt/sources.list.d/pouriyajamshidi.list &&
  sudo apt update &&
  sudo apt install tcping

Fedora, RHEL, CentOS and their flavors:

sudo curl -fsSL https://pouriyajamshidi.github.io/packages/rpm/pouriyajamshidi.repo -o /etc/yum.repos.d/pouriyajamshidi.repo &&
  sudo dnf install tcping

Alpine:

sudo curl -fsSL https://pouriyajamshidi.github.io/packages/keys/pouriyajamshidi.rsa.pub -o /etc/apk/keys/pouriyajamshidi.rsa.pub &&
  echo "https://pouriyajamshidi.github.io/packages/apk" | sudo tee -a /etc/apk/repositories &&
  sudo apk update &&
  sudo apk add tcping

Arch, Manjaro, EndeavourOS and their flavors have it on the AUR, so use your favorite helper:

yay -S tcping-bin

Linux - Package files

Without adding a repository, download the package for your distro from the release page and install it:

Swap amd64 for arm64 on ARM machines. All four install the binary and the shell completions for you. Machines without dnf can use yum instead, and Alpine needs --allow-untrusted because our packages are not signed with an Alpine key.

BSD and Linux - Manual Way

Download the file for your respective OS and architecture:

wget https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-freebsd-amd64.tar.gz
# Or for Linux ARM64 machines and using cURL
curl -LO https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-linux-arm64.tar.gz

Extract it and copy the executable to your system PATH like /usr/local/bin/:

tar -xvf tcping-freebsd-amd64.tar.gz &&
  chmod +x tcping &&
  sudo cp tcping /usr/local/bin/

The archive also carries a completions folder. See Shell Completions to install them.

Nix

tcping ships a flake, so on any machine that has Nix you can run it without installing anything:

nix run github:pouriyajamshidi/tcping -- example.com 80

Or install it for good:

nix profile install github:pouriyajamshidi/tcping

Both give you the binary and the shell completions. The flake also has a devShells.default with everything needed to work on tcping, which you get with nix develop.

Other ways

• Docker images:

  bash复制

  docker pull pouriyajamshidi/tcping:latest
  # Or
  docker pull ghcr.io/pouriyajamshidi/tcping:latest

• Using go install:

  This requires at least go version 1.26.8

  bash复制

  go install github.com/pouriyajamshidi/tcping/v3@latest

• x tcping:

  Directly without installation in x-cmd.

  bash复制

  x tcping example.com 80

  Or install tcping locally using x-cmd, without needing root privileges or affecting your global setup.

  bash复制

  x env use tcping
  tcping example.com 80

• Finally, you can compile the code yourself by running the make command:

  bash复制

  make build

  This will place the executables in the output folder.

Shell Completions

Completion scripts for bash, zsh, fish and PowerShell live in the completions folder. They complete the flags, the interface names for -I and the file names for --csv and --sqlite.

The Linux packages and the one-line install put them in place for you. The release archives ship them next to the binary, so they can also be installed from there with the commands below.

• bash:

  bash复制

  sudo install -Dm 644 completions/tcping.bash /usr/share/bash-completion/completions/tcping

• zsh:

  bash复制

  sudo install -Dm 644 completions/_tcping /usr/share/zsh/site-functions/_tcping

• fish:

  bash复制

  install -Dm 644 completions/tcping.fish ~/.config/fish/completions/tcping.fish

• PowerShell, by dot-sourcing the script from your profile:

  powershell复制

  Add-Content $PROFILE ". C:\path\to\tcping.ps1"

Start a new shell afterwards to pick them up.

Usage

Give tcping a target and a port, and it starts probing:

tcping www.example.com 443
tcping www.example.com:443          # host:port works too
tcping 192.168.1.1:80
tcping '[2001:db8::1]:443'          # quoted, so the shell leaves it alone
tcping https://www.example.com      # probed over HTTP(S)
tcping udp://127.0.0.1 53           # probed over UDP

Some of the things you can ask of a run:

tcping www.example.com 443 -c 5            # stop after 5 probes
tcping www.example.com 443 -i 2 -t 5       # 2 seconds between probes, 5 seconds timeout
tcping www.example.com 443 -I eth2         # send the probes from a given interface
tcping www.example.com 443 -4              # or -6, to enforce an address family
tcping www.example.com 443 -D              # show a timestamp for each probe
tcping www.example.com 443 -r 5            # resolve the hostname again after 5 failures

And the output formats it can produce, instead of th