Port Monitor with Telegram Alerts

This is a simple Python utility that monitors whether specific ports (e.g., Redis on port 6379) are being listened to on one or more hosts. If a port is not open, it sends a warning message to a Telegram bot and can optionally execute recovery commands.

📦 Features

• Monitors any TCP port(s) on one or more hosts
• Sends alerts via Telegram
• Configurable via YAML file
• Includes a test script for Telegram alerts
• Suitable for use in cron jobs or system monitoring scripts
• Automatic recovery: Execute shell commands when port is unavailable, then re-check and report results
• Multiple targets: Monitor multiple hosts and ports with individual recovery commands for each

🛠️ Files

• check_port.py
  – Main script to check port(s) and send warning if closed
• test_send_msg.py
  – Test script to verify Telegram alert sending
• config.yaml
  – Configuration file with port and Telegram settings
• config_samples/config.yaml
  – Single target configuration example
• config_samples/config_multiple.yaml
  – Multiple targets configuration example
• requirements.txt
  – Python dependencies
• check_port.sh
  – Example shell wrapper (optional)

⚙️ Setup

1. Install dependencies

2. Configure Telegram bot

1. Create a bot with @BotFather
2. Get your bot token
3. Get your Telegram chat ID using @userinfobot

3. Edit

config.yaml

You can configure either a single target or multiple targets.

Single target (legacy format)

Multiple targets

Each target can have its own

,

port

,

source

(alias for display in Telegram), and

run_cmd

list. Targets are checked sequentially.

3.2. (Optional) Configure a proxy

If the host running the script has no direct access to the Telegram API, you can route alerts through a SOCKS5 or HTTP proxy (e.g. Squid). Add a

block inside

telegram:

:

• Use
  type: socks5
  for a SOCKS5 proxy (e.g. SSH tunnel, Tor).
• Use
  type: http
  for an HTTP CONNECT proxy (e.g. Squid).
• username
  and
  password
  are optional.

SOCKS5 support requires the

package, which is installed automatically via

requests[socks]

in

requirements.txt

.

3.1. (Optional) Configure recovery commands

You can specify a list of shell commands to execute when the port is unavailable. After executing the commands, the script will re-check the port and report the result.

Each command is executed sequentially. Commands must be valid shell commands as strings.

4. Run the script

You can specify a custom config file path using the

or

--config

argument:

If no config path is provided, the script uses

in the same directory as the script.

5. (Optional) Run the test script

6. (Optional) Set up a cron job

Example: Check every 5 minutes

✅ Output

If the port is open:

If the port is not open, you'll get a Telegram alert like:

⚠️ 2025-05-22T15:00:00 Warning: Port 6379 is NOT listening on 127.0.0.1!

Multiple Targets Output

When monitoring multiple targets, each target is checked independently. You'll receive separate alerts for each unavailable port. The

alias is used in messages to identify the target:

⚠️ 2025-05-22T15:00:00 Warning: Port 6379 is NOT listening on redis-server!

✅ Recovery commands executed successfully, port is now listening!

⚠️ 2025-05-22T15:00:00 Warning: Port 5432 is NOT listening on postgresql!

❌ Recovery commands executed, but port is still NOT listening!

Recovery Commands Output

If

is configured and the port is unavailable:

Success case (port restored after commands):

⚠️ 2025-05-22T15:00:00 Warning: Port 6379 is NOT listening on 127.0.0.1!

✅ Recovery commands executed successfully, port is now listening!

Failure case (port still unavailable):

⚠️ 2025-05-22T15:00:00 Warning: Port 6379 is NOT listening on 127.0.0.1!

❌ Recovery commands executed, but port is still NOT listening!

📄 License

This project is provided as-is under the MIT License.

---

Made with ❤️ for system monitoring.