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

---

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

• Windows

• Linux - Also available through brew and .deb package

• macOS - Also available through brew

• macOS M1 - ARM - Also available through brew

• FreeBSD

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

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
--db	Path and file name to store tcping output to sqlite database. e.g. --db /tmp/tcping.db
-t	Time to wait for a response, in seconds. Real number allowed. 0 means infinite timeout
-i	Interval between sending probes
-I	Interface name to use for sending probes
-j	Output in JSON format
--pretty	Prettify the JSON output
-v	Print version
-u	Check for updates
--show-failures-only	Only show probe failures and omit printing probe success messages

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