tcping

README

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 result. It works with 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, understanding the total packet drops to that point would be illustrative enough.

• Monitor your network connection.
• Determine packet loss.
• Analyze the network's latency.
• Show min/avg/max probes latency.
• Print connection statistics by pressing the Enter key and without stopping the program.
• Use the -r flag to retry hostname resolution after a predetermined number of ping failures. If you want to test your DNS load balancing or Global Server Load Balancer (GSLB), you should utilize this option.
• Enforce using IPv4 or IPv6 address resolution
• Display the longest encountered downtime and uptime duration and time.
• Monitor and audit your peers network.
• Calculate the total uptime/downtime when conducting a maintenance.
• An alternative to ping in environments that ICMP is blocked.

---

Table of Contents

• TCPING
  • Table of Contents
  • Demos
    • Vanilla usage
    • Retry resolve (-r) flag
    • Pretty json output (-j --pretty)
  • Download
  • Usage
    • On Linux and macOS
    • On Windows
    • Using Docker
  • Flags
  • Tips
  • Notes
  • Contributing
  • Tested on
  • Sponsor The Project
  • Contact me
  • License

---

Demos

Vanilla usage

---

Retry resolve (-r) flag

---

Pretty json output (-j --pretty)

---

Download

• Windows

• Linux - Also available through brew

• macOS - Also available through brew

• macOS M1 - ARM - Also available through brew

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:

  go install github.com/pouriyajamshidi/tcping@latest
  

• Install using brew:

  brew install pouriyajamshidi/tap/tcping
  

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

  make build
  

  This will give you a compressed file with executables for all the supported operating systems inside the executables folder.

---

Usage

If you have decided to download the executables using the aforementioned links, go to the folder containing the file and extract it. Then, depending on your operating system, follow the instructions below:

• Linux and macOS
• Windows
• Docker images

On Linux and macOS

De-compress the downloaded 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

Make the file executable:

chmod +x tcping

For easier use, copy the executable to your system PATH like /usr/local/bin/:

sudo cp tcping /usr/local/bin/

Then run it like, tcping <hostname/IP address> <port>. For instance:

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

Specifying the -r option will cause a name resolution retry after a certain number of failures. For instance:

tcping www.example.com 443 -r 10
# OR
tcping -r 10 www.example.com 443

The -r 10 in the command above will result in a retry of name resolution after 10 probe failures.

On Windows

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

For easier use, 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

If you prefer not to add the executable to your PATH, go to the folder that contains the tcping.exe open up the terminal and run the following command:

.\tcping.exe 10.10.10.1 22

Please note, if you copy the program to your system PATH, you don't need to specify .\ and the .exe extension to run the program anymore.

Using 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
-r	Retry resolving a hostname after <n> number of failures
-4	Only use IPv4 addresses
-6	Only use IPv6 addresses
-j	Output in JSON format
--pretty	Prettify the JSON output
-u	Check for updates
-v	Print version

---

Tips

• Press the Enter key while the program is running to examine the summary of all probes without shutting it down, as shown in the demos section.

---

Notes

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 me with the open issues that can be found here

Current number of open issues: .

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.
7. Create a pull request

Please make sure that your pull request only works on one specific issue and doesn't handle two or more tickets. This makes it simpler for us to examine your pull request and helps keep the git history clean.

Tested on

Windows, Linux and macOS.

Sponsor The Project

Contact me

License