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.

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

---

Table of Contents

• TCPING
  • Table of Contents
  • Download and Installation
    • Windows
    • macOS
    • Linux - Debian and Derivatives
    • BSD and Linux - Manual Way
    • Alternative Ways
  • Usage
  • Flags
  • Demos
    • Basic usage
    • Retry hostname lookup (-r) flag
    • JSON output (-j --pretty) flag
  • Contributing
  • Feature Requests and Issues
  • Help The Project
  • License

---

Download and Installation

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

• x tcping:

  Directly without installation in x-cmd.

  x tcping example.com 80

  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.

1. The simplest form is providing the target and the port number:

tcping www.example.com 443

2. 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

3. Enforce using IPv4 or IPv6 only:

  tcping www.example.com 443 -4
  # Or
  tcping www.example.com 443 -6

4. Show timestamp of probes:

tcping www.example.com 443 -D

5. Retry resolving the hostname after 5 failures:

tcping www.example.com 443 -r 5

6. Stop after 5 probes:

tcping www.example.com 443 -c 5

7. 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 flags here 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 <n> number of failed probes. e.g. -r 10 to retry after 10 failed probes
-c	Stop after <n> 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

1. Pick any issue that you feel comfortable with.
2. Fork the repository.
3. Create a branch.
4. Commit your work.
5. Add tests if possible.
6. Run the tests go test or make test and ensure they are successful.
7. 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:

• Buy me a coffee: "Buy Me A Coffee"

• GitHub Sponsors: sponsor

• Total number of sponsors:

License