Add comprehensive README with usage instructions and examples
This commit is contained in:
171
README.md
Normal file
171
README.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user