Probe - Multi-Protocol Health Check

Turkish README

Multi-protocol health check library written in Go. Import as a package in your projects, or use the included CLI for simple checks.

Note: The CLI tool in this repository is primarily designed to demonstrate the library's capabilities and perform simple checks. For a comprehensive detailed logging tool based on this library, please check out the NetYazilim/izle project.

Features

• ICMP Ping Probe - Check host availability using ICMP Echo (supports both IP addresses and hostnames; IPv6 support available on Linux).
• TCP Probe - Verify port connectivity and connection information (works with both IPv4 and IPv6 targets).
• HTTP/HTTPS Probe - Verify web service health with status code checks (supports IPv4/IPv6 endpoints transparently).
• TLS/SSL Probe - Supports two modes over IPv4 or IPv6: strict TLS validation (tls) and certificate-only inspection (tls-cert). The certificate-only mode can still read the presented server certificate even when full TLS negotiation is blocked by mTLS/client-certificate requirements.
• No external Go package dependencies - uses only Go standard library.

Platform Support

• Linux - Uses UDP-based ICMP (requires kernel support for unprivileged ping). Supports both IPv4 and IPv6.
• Windows - Uses Win32 ICMP API (no special privileges required). Currently supports IPv4 only for ICMP ping.

Linux ICMP Ping Configuration

On Linux, the kernel must allow unprivileged ICMP ping. Check if it's enabled:

cat /proc/sys/net/ipv4/ping_group_range

Output meanings:

• 1 0 - ICMP ping disabled for unprivileged users
• 0 2147483647 - All users can perform ICMP ping without root

To enable unprivileged ICMP ping:

sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"

To make the change persistent:

echo "net.ipv4.ping_group_range = 0 2147483647" | sudo tee /etc/sysctl.d/99-ping.conf
sudo sysctl -p /etc/sysctl.d/99-ping.conf

Installation

go get "github.com/netyazilim/probe"

Usage

# Display help
./probe

# ICMP Ping (IP Addresses or Hostnames)
./probe ping 8.8.8.8
./probe ping google.com
./probe ping -attempts 5 8.8.8.8
./probe ping -timeout 2s google.com
./probe ping -loop 5s 8.8.8.8                    # Run every 5 seconds

# TCP Probe (Port Connectivity)
./probe tcp example.com:22
./probe tcp google.com:443
./probe tcp -attempts 5 google.com:443
./probe tcp -loop 10s google.com:443             # Run every 10 seconds

# HTTP/HTTPS (URLs)
./probe http https://google.com
./probe http -timeout 3s https://example.com
./probe http -loop 1m https://google.com         # Run every 1 minute

# TLS/SSL Strict Check
./probe tls google.com:443
./probe tls -timeout 10s example.com:443
./probe tls -loop 30m google.com:443             # Run every 30 minutes

# TLS/SSL Certificate-Only Check
./probe tls-cert google.com:443
./probe tls-cert https://google.com
./probe tls-cert -timeout 10s mtls.example.com:443

Flags

-attempts int     Maximum number of attempts (default: 3)
-timeout duration Timeout per attempt (default: 1s for ping/tcp/http, 5s for tls/tls-cert)
-loop duration    Loop interval (0 = run once, e.g., 5s, 1m, 10s)

Commands

ping               ICMP ping probe (supports IP addresses and hostnames)
tcp                TCP port connectivity check (host:port format)
http               HTTP/HTTPS status check (URL format)
tls                Strict TLS/SSL handshake and certificate validation (host:port or URL format)
tls-cert           TLS/SSL certificate inspection without requiring a full handshake (host:port or URL format)

Timeout Configuration

• ICMP Ping: 1 second per attempt
• TCP: 1 second per attempt
• HTTP/HTTPS: 1 second per attempt
• TLS/SSL: 5 seconds per attempt

Each probe supports 3 retry attempts by default.

Docker Usage

# Build Docker image
docker build -t probe .

# Run container
docker run --rm probe ping 8.8.8.8
docker run --rm probe tcp google.com:443
docker run --rm probe http https://google.com
docker run --rm probe tls google.com:443
docker run --rm probe tls-cert mtls.example.com:443

Docker Note

The container runs as an unprivileged user (probeuser).

Output Examples

ICMP Ping

Target: 8.8.8.8
Attempt: 3
Success: true
Duration: 45.32 ms

TCP Probe

Host: google.com
Port: 443
Attempt: 3
Success: true
Duration: 125.45 ms
Local Address: 192.168.1.100:52341
Remote Address: 142.251.32.14:443

HTTP/HTTPS

URL: https://google.com
Attempt: 3
Success: true
Status Code: 200
Duration: 125.45 ms

TLS/SSL (strict)

Host: google.com
Attempt: 3
Success: true
Duration: 235.67 ms
Subject: CN=www.google.com
Issuer: CN=Google Internet Authority G3
Expires At: 2025-12-15 23:59:59
Days Until Expiry: 310
TLS Version: TLS 1.3
Cipher Suite: TLS_AES_128_GCM_SHA256

TLS/SSL (certificate-only)

Host: mtls.example.com
Attempt: 1
Success: true
Duration: 210.12 ms
Subject: CN=mtls.example.com
Issuer: CN=Example Issuing CA
Expires At: 2026-12-15 23:59:59
Days Until Expiry: 213
TLS Version: TLS 1.3
Cipher Suite: TLS_AES_128_GCM_SHA256
Handshake Warning: remote error: tls: certificate required

Dependencies

This package uses only standard Go library packages: No external dependencies required.

Requirements

• Go 1.20 or later
• For ICMP Ping on Linux:
  • Check kernel support: cat /proc/sys/net/ipv4/ping_group_range
  • Unprivileged ICMP must be enabled in kernel
  • To enable: sudo sysctl -w net.ipv4.ping_group_range="0 2147483647"
• Internet connectivity for TCP and TLS probes

Error Handling

All probes include retry logic (3 attempts by default) with 500ms delays between attempts. Detailed error messages are provided for troubleshooting.