Ping using TCP instead of ICMP. Outputs in colored, plain, JSON, CSV, and sqlite3 formats.
README
TCPING
A cross-platform ping program using TCP instead of ICMP, inspired by Linux's ping utility.
> [!TIP]
> This document is also available in Chinese | 中文.
Here are some of the features of TCPING:
An alternative to ping in environments that ICMP is blocked.
Outputs information in colored, plain, JSON, CSV and sqlite3 formats.
Monitor and audit your or your peers network latency, packet loss, and connection quality.
Let's you specify the source interface, timeout, and interval between probes.
Supports both IPv4 or IPv6 and lets you enforce using either.
Prints total connection statistics by pressing the Enter key, without stopping the program.
Reports the longest encountered downtime and uptime duration and time.
Retries hostname resolution after a predetermined number of probe failures by using the -r flag . Suitable to test your DNS load balancing or Global Server Load Balancer (GSLB).
uses different TCP sequence numbering for successful and unsuccessful probes to infer the total failed or successful probes at a glance.
We offer prebuilt binaries for various operating systems (Windows, Linux, macOS, Docker) and architectures (amd64, arm64), which can be found on the release page.
Once you are done with the download and 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
> [!TIP]
> We recommend using Windows Terminal for the best experience and proper colorization.
If you wish to manually install tcping, 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.
macOS
Install using brew:
brew install pouriyajamshidi/tap/tcping
You can also manually download and install tcping following the steps described in this section.
Linux - Debian and Derivatives
On Debian and its flavors such as Ubuntu, download the .deb package:
wget https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-amd64.deb -O /tmp/tcping.deb
# Or for ARM64 machines
wget https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-arm64.deb -O /tmp/tcping.deb
And install it:
sudo apt install -y /tmp/tcping.deb
If you are using different Linux distros, proceed to this section.
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-static.tar.gz
# Or for Linux ARM64 machines and using cURL
curl -LO https://github.com/pouriyajamshidi/tcping/releases/latest/download/tcping-linux-arm64-static.tar.gz
Extract the file:
tar -xvf tcping-freebsd-amd64-static.tar.gz
Make the file executable:
chmod +x tcping
Copy the executable to your system PATH like /usr/local/bin/:
sudo cp tcping /usr/local/bin/
> [!TIP]
> In case you have brew installed, you can install tcping using brew install pouriyajamshidi/tap/tcping
Alternative Ways
These are some additional ways in which tcping can be installed:
Docker images:
docker pull pouriyajamshidi/tcping:latest
# Or
docker pull ghcr.io/pouriyajamshidi/tcping:latest
Using go install:
> This requires at least go version 1.23.1
go install github.com/pouriyajamshidi/tcping/v2@latest
Or install tcping locally using x-cmd, without needing root privileges or affecting your global setup.
x env use tcping
tcping example.com 80
Finally, you can compile the code yourself by running the make command:
make build
This will place the executables in the output folder.
Usage
tcping can run in various ways.
The simplest form is providing the target and the port number:
tcping www.example.com 443
Specify the interval between probes (2 seconds), the timeout (5 seconds) and source interface:
tcping www.example.com 443 -i 2 -t 5 -I eth2
Enforce using IPv4 or IPv6 only:
tcping www.example.com 443 -4
# Or
tcping www.example.com 443 -6
Show timestamp of probes:
tcping www.example.com 443 -D
Retry resolving the hostname after 5 failures:
tcping www.example.com 443 -r 5
Stop after 5 probes:
tcping www.example.com 443 -c 5
Change the default output from colored to:
# Save the output in CSV format:
tcping www.example.com 443 --csv example.com.csv
# Save the output in sqlite3 format:
tcping www.example.com 443 --db example.com.db
# Show the output in JSON format:
tcping www.example.com 443 --json
# Show the output in JSON format - pretty:
tcping www.example.com 443 --json --pretty
# Show the output in plain (no ANSI colors):
tcping www.example.com 443 --no-color
> [!NOTE]
> Check the available flagshere for a more advanced usage.
The Docker image can be used with the same set of flags, like:
# If downloaded from Docker Hub
docker run -it pouriyajamshidi/tcping:latest example.com 443
# If downloaded from GitHub container registry:
docker run -it ghcr.io/pouriyajamshidi/tcping:latest example.com 443
> [!TIP]
> Press the Enter key while the program is running to examine the summary of all probes without terminating the program, as shown in the demos section.
Flags
The following flags are available to control the behavior of tcping:
Flag
Description
-h
Show help
-4
Only use IPv4 addresses
-6
Only use IPv6 addresses
-r
Retry resolving target's hostname after `` number of failed probes. e.g. -r 10 to retry after 10 failed probes
-c
Stop after `` probes, regardless of the result. By default, no limit will be applied
-t
Time to wait for a response, in seconds. Real number allowed. 0 means infinite timeout
-D
Display date and time in probe output. Similar to Linux's ping utility but human-readable
-i
Interval between sending probes
-I
Interface name to use for sending probes
--no-color
Do not colorize output
--csv
Path and file name to store tcping output in CSV format
-j
Output in JSON format
--pretty
Prettify the JSON output
--db
Path and file name to store tcping output to sqlite database. e.g. --db /tmp/tcping.db
-v
Print version
-u
Check for updates
--show-failures-only
Only show probe failures and omit printing probe success messages
--show-source-address
Show the source IP address and port used for probes
> [!TIP]
> Without specifying the -4 and -6 flags, tcping will randomly select an IP address based on DNS lookups.
Demos
Basic usage
Retry hostname lookup (-r) flag
JSON output (-j --pretty) flag
Contributing
Pull requests are welcome to solve bugs, add new features and to help with the open issues that can be found here
Pick any issue that you feel comfortable with.
Fork the repository.
Create a branch.
Commit your work.
Add tests if possible.
Run the tests go test or make test and ensure they are successful.
Create a pull request
Current number of open issues: .
Please make sure that your pull request only covers one specific issue/feature and doesn't handle two or more tickets. This makes it simpler for us to examine your pull request and helps keeping a clean git history.
Feature Requests and Issues
Should you need a new feature or find a bug, please feel free to open a pull request or submit an issue.
For larger features/contributions, please make sure to first communicate it on a discussion before starting your work.
Help The Project
If tcping proves to be useful for you, consider sharing it with your network to extend its reach and help other people to also benefit from it.
Furthermore, you can support the project using the links below:
.
