Hello, first TCP check! 🦄

From download to your first local check in a few minutes. This guide works on Debian, Ubuntu, Raspberry Pi OS, AlmaLinux and Rocky Linux. The test checks whether a TCP connection to 127.0.0.1:22 can be established. It does not log in via SSH or check credentials.

Step 1 — Download and verify the release

Get the latest ipsonic-probe-VERSION.tar.gz and the matching .sha256 file from the Downloads page. Place both files in the same directory and verify them:

sha256sum -c ipsonic-probe-VERSION.tar.gz.sha256

Replace VERSION with the actual downloaded version. Verification must print OK; do not install an archive with a mismatched checksum. The checksum protects against accidental corruption; for authenticity, obtain the checksum through a trusted channel.

Step 2 — Install standard Linux packages

On Debian, Ubuntu, or Raspberry Pi OS:

sudo apt-get update
sudo apt-get install -y python3 python3-requests python3-yaml ca-certificates

On AlmaLinux or Rocky Linux:

sudo dnf install -y python3 python3-requests python3-pyyaml ca-certificates

All dependencies come from the distribution's configured standard repositories or an approved internal mirror. No pip, PyPI, virtualenv or additional package repositories. The test itself does not need elevated privileges.

Step 3 — Unpack the release

tar -xzf ipsonic-probe-VERSION.tar.gz
cd ipsonic-probe-VERSION
python3 ipsonic-probe.py --help

The archive directory uses the release version. You can run ipsonic-probe directly from the extracted directory; there is no separate installation step.

Step 4 — Understand the first YAML

The release includes examples/138-hello-first-tcp-ssh.yaml:

name: Hello first TCP test - local SSH port
url: tcp://127.0.0.1:22
timeouts:
  connect: 3
  response: 5
monitoring:
  service_name: Local SSH TCP port 22
  output: text
  on_failure: critical

127.0.0.1 means this Linux host, not another machine.
Port 22 is the conventional SSH port; the example only checks TCP connectivity.
connect: 3 sets the connection timeout in seconds.
monitoring.output: text provides human-readable output.

Step 5 — Run the check

python3 ipsonic-probe.py examples/138-hello-first-tcp-ssh.yaml
printf 'exit code: %s\n' "$?"

Success: When a service is listening on 127.0.0.1:22 and connections are allowed, the probe reports success and exits with code 0.

Failure: If SSH is not installed, not listening on localhost, uses another port, or a firewall rejects the connection, the probe reports failure and exits with code 1. This is a useful first diagnostic, not necessarily an ipsonic-probe error.

To see whether the host is listening, run:

ss -ltn | grep ':22'

The ss command is usually supplied by the distribution's iproute2 package (Debian family) or iproute package (RHEL family). It is optional for the probe. Do not enable or expose SSH solely to make the example pass. If SSH is intentionally disabled, point the YAML to an existing, approved TCP service instead.

Step 6 — Try monitoring output

python3 ipsonic-probe.py --output nagios examples/138-hello-first-tcp-ssh.yaml

The same YAML can later be used as a Nagios/Icinga-compatible service check. See Best Practices for alerting, timeouts, and production rollout.

Next steps

Try examples/01-tcp-connect.yaml for a different TCP port, then explore HTTP, HTTPS, TLS and DNS checks in the Examples catalog. The Ansible installation guide remains available as an optional way to provision multiple hosts, but is not required for this first test.

Maintainer and disclaimer

Maintained by mati peterson (ipsonic@mailbox.org). Official project URL: https://ipsonic.com/probe/.

Disclaimer: This software and its examples are provided AS IS, without warranty of any kind. Use at your own risk. Review and validate configurations before production deployment.

ipsonic-probe ✦