README.md

TCPING

A cross-platform ping program for TCP ports inspired by the Linux's ping utility. This program will send TCP probes to an IP address or a hostname specified by you and prints the results. It supports both IPv4 and IPv6.

TCPING uses different TCP sequence numbering for successful and unsuccessful probes, so that when you look at the results and spot a failed probe, inferring the total packet drops to that point would be easy.

Here are some of the features of TCPING:

• An alternative to ping in environments that ICMP is blocked.
• Monitor your network connection.
• Determine packet loss.
• Analyze the network's latency.
• Calculate minimum, average and maximum latency of network probes.
• Print connection statistics by pressing the Enter key, without stopping the program.
• Retry 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).
• Enforce using IPv4 or IPv6.
• Display the longest encountered downtime and uptime duration and time.
• Monitor and audit your peers network (SLA).
• Calculate the total uptime or downtime of your network when conducting a maintenance.

This document is also available in Chinese | 中文.

---

Table of Contents

• TCPING
  • Table of Contents
  • Demos
    • Basic usage
    • Retry hostname lookup (-r) flag
    • JSON output (-j --pretty) flag
  • Download
  • Usage
    • Linux - Debian and Ubuntu
    • Linux, BSD and mac OS
    • Windows
    • Docker
  • Flags
  • Tips
  • Check for Updates
  • Contributing
  • Feature Requests and Issues
  • Tested on
  • Help The Project
  • License

---

Demos

Basic usage

---

Retry hostname lookup (-r) flag

---

JSON output (-j --pretty) flag

---

Download

We offer prebuilt binaries for various OSes and architectures (Windows, Linux and macOS). You can find them on the release page.

When the download is complete, head to the usage section.

Alternatively, you can:

• Use the Docker images:

  docker pull pouriyajamshidi/tcping:latest

  Image is also available on GitHub container registry:

  docker pull ghcr.io/pouriyajamshidi/tcping:latest

• Install using go install:

  This requires at least go version 1.23.1

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

• Install using brew:

  brew install pouriyajamshidi/tap/tcping

• x tcping:

  Use it directly without installation in x-cmd.

  x tcping bing.com 80

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

  x env use tcping
  tcping bing.com 80

• Or compile the code yourself by running the make command in the tcping directory:

  make build

  This will produce an executable under target/ folder.

---

Usage

Follow the instructions below for your operating system:

• Linux - Debian and Ubuntu
• Linux, BSD and macOS
• Windows
• Docker images

Also check the available flags here.

Linux - Debian and Ubuntu

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

And install it:

sudo apt install -y /tmp/tcping.deb

If you are using different Linux distros, proceed to this section.

Linux, BSD and mac OS

Extract the file:

tar -xvf tcping_Linux.tar.gz
#
# Or on Mac OS
#
tar -xvf tcping_MacOS.tar.gz
#
# on Mac OS ARM
#
tar -xvf tcping_MacOS_ARM.tar.gz
#
# on BSD
#
tar -xvf tcping_FreeBSD.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/

Run it like:

tcping www.example.com 443
# Or
tcping 10.10.10.1 22

Windows

We recommend Windows Terminal for the best experience and proper colorization.

Copy tcping.exe to your system PATH like C:\Windows\System32 and run it like:

tcping www.example.com 443
# Or provide the -r flag to
# enable name resolution retries after a certain number of failures:
tcping www.example.com 443 -r 10

TCPING might falsely get flagged by Windows Defender or some anti-malware software. This is common among Go programs. Check out the official documentation from Go here.

Docker

The Docker image can be used like:

# Using Docker Hub
docker run -it pouriyajamshidi/tcping:latest example.com 443

# Using GitHub container registry:
docker run -it ghcr.io/pouriyajamshidi/tcping:latest example.com 443

---

Flags

The following flags are available to control the behavior of application:

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
-j	Output in JSON format
--pretty	Prettify the JSON output
--no-color	Do not colorize output (unreleased - included in version 2.7.0)
--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-local_address	Show the local IP address and port used for probes (unreleased - included in version 2.7.0)

Without specifying the -4 and -6 flags, tcping will randomly select an IP address based on DNS lookups.

---

Tips

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

---

Check for Updates

TCPING is constantly being improved, adding numerous new features and fixing bugs. Be sure to look for updated versions.

tcping -u

Contributing

Pull requests are welcome to solve bugs, add new features and also 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 an issue before starting your work.

Tested on

Windows, Linux and macOS.

Help The Project

If tcping proves to be useful for you, consider giving it a ⭐ 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:

GitHub Sponsors:

Total number of sponsors:

License