From baf0c1ee9f607bb35b669557b324dbeccfc15a05 Mon Sep 17 00:00:00 2001 From: jessikitty Date: Wed, 7 Jan 2026 17:13:16 +1100 Subject: [PATCH] Add comprehensive README with usage instructions and examples --- README.md | 171 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..e81c6b2 --- /dev/null +++ b/README.md @@ -0,0 +1,171 @@ +# Network Connectivity Monitor + +A Python-based network monitoring tool designed to diagnose connectivity issues on your OPNsense/TP-Link network infrastructure. + +## Monitored Devices + +- **10.0.0.254** - OPNsense Firewall +- **10.0.0.253** - TP-Link AX5400 (253) +- **10.0.0.252** - TP-Link Device (252) +- **10.0.0.55** - DNS/Other Service + +## Features + +- ✅ Real-time connectivity monitoring with live status updates +- 📊 Detailed statistics including success rates and failure patterns +- 🔍 Automatic failure incident detection and grouping +- 📈 Final comprehensive report with health assessment +- ⏱️ Configurable monitoring duration and ping intervals +- 🛑 Graceful interrupt handling (Ctrl+C for early stop) + +## Requirements + +- Python 3.6+ +- Unix-like system with `ping` command +- No external Python dependencies required! + +## Usage + +### Quick Start + +```bash +# Make the script executable +chmod +x network_monitor.py + +# Run with default settings (1 hour monitoring) +./network_monitor.py +``` + +Or run directly with Python: + +```bash +python3 network_monitor.py +``` + +### Configuration + +Edit the following constants at the top of the script to customize: + +```python +MONITOR_IPS = { + "10.0.0.254": "OPNsense Firewall", + "10.0.0.253": "TP-Link AX5400 (253)", + "10.0.0.252": "TP-Link Device (252)", + "10.0.0.55": "DNS/Other Service" +} + +PING_INTERVAL = 5 # seconds between ping checks +MONITOR_DURATION = 3600 # 1 hour in seconds +PING_TIMEOUT = 2 # seconds to wait for ping response +PING_COUNT = 1 # number of pings per check +``` + +### Example Output + +**Live Status Screen:** +``` +================================================================================ +Network Connectivity Monitor - 2026-01-07 17:15:30 +================================================================================ + +Monitoring Duration: 45s / 3600s (1.3%) +Next check in: 5s + +-------------------------------------------------------------------------------- +IP Address Device Status Success Rate +-------------------------------------------------------------------------------- +10.0.0.254 OPNsense Firewall 🟢 UP 100.00% (9/9) +10.0.0.253 TP-Link AX5400 (253) 🟢 UP 100.00% (9/9) +10.0.0.252 TP-Link Device (252) 🔴 DOWN 88.89% (8/9) +10.0.0.55 DNS/Other Service 🟢 UP 100.00% (9/9) +-------------------------------------------------------------------------------- + +⚠️ CURRENT ISSUES: + • 10.0.0.252 (TP-Link Device (252)): 1 consecutive failures +``` + +**Final Report:** +``` +================================================================================ +FINAL MONITORING REPORT +================================================================================ +Start Time: 2026-01-07 17:14:45 +End Time: 2026-01-07 18:14:45 +Duration: 3600 seconds +================================================================================ + +DEVICE SUMMARY: +-------------------------------------------------------------------------------- +IP Address Device Success Rate Total Failures +-------------------------------------------------------------------------------- +10.0.0.254 OPNsense Firewall ✅ 100.00% 0 +10.0.0.253 TP-Link AX5400 (253) ✅ 100.00% 0 +10.0.0.252 TP-Link Device (252) ⚠️ 98.61% 10 +10.0.0.55 DNS/Other Service ✅ 100.00% 0 +-------------------------------------------------------------------------------- + +DETAILED STATISTICS: +================================================================================ + +TP-Link Device (252) (10.0.0.252): + Total Checks: 720 + Successful: 710 (98.61%) + Failed: 10 (1.39%) + Max Consecutive Failures: 3 + First Failure: 17:25:10 + Last Failure: 17:42:35 + Failure Incidents: 2 + + Failure Timeline: + Incident 1: 17:25:10 - 17:25:20 (3 failures, 10s) + Incident 2: 17:42:25 - 17:42:35 (7 failures, 10s) + +================================================================================ + +OVERALL ASSESSMENT: +⚠️ ISSUE ISOLATED: Only TP-Link Device (252) (10.0.0.252) had connectivity issues. + This suggests a device-specific problem rather than network-wide issue. +================================================================================ +``` + +## Use Cases + +### Diagnosing DHCP Issues +This tool was originally created to diagnose DHCP renewal loop problems causing high CPU usage on TP-Link routers. Run it before and after applying fixes to verify improvement. + +### Network Stability Testing +Monitor your network infrastructure during configuration changes, firmware updates, or after new device installations to ensure stability. + +### Intermittent Connection Troubleshooting +Identify patterns in connectivity issues that might not be immediately obvious. The incident grouping helps distinguish between temporary blips and recurring problems. + +## Tips + +- **Short Duration Test**: For quick diagnostics, edit `MONITOR_DURATION` to 300 (5 minutes) +- **Faster Checks**: Reduce `PING_INTERVAL` to 1 or 2 seconds for more granular data +- **Save Results**: Redirect output to a file: `./network_monitor.py > results.txt` +- **Background Running**: Use `nohup ./network_monitor.py &` to run in background + +## Troubleshooting + +**Permission Denied:** +```bash +chmod +x network_monitor.py +``` + +**Python Not Found:** +```bash +# Use python instead of python3 +python network_monitor.py +``` + +**No Ping Command:** +This script requires the standard Unix `ping` utility. It should be available by default on Linux, macOS, and WSL. + +## License + +This script is provided as-is for network diagnostics. Feel free to modify and adapt for your specific needs! + +## Related Issues + +This tool helps diagnose the TP-Link AX5400 DHCP renewal loop issue documented in the OPNsense troubleshooting session.