Skip to content

v1.1: generic Linux monitoring with optional FRITZ!Box diagnostics - #1

Draft
LucaXTech wants to merge 17 commits into
mainfrom
feature/generic-linux-v1.1-clean
Draft

v1.1: generic Linux monitoring with optional FRITZ!Box diagnostics#1
LucaXTech wants to merge 17 commits into
mainfrom
feature/generic-linux-v1.1-clean

Conversation

@LucaXTech

@LucaXTech LucaXTech commented Sep 5, 2026

Copy link
Copy Markdown
Owner

Summary

This PR evolves LineWatch from a Raspberry-Pi/FRITZ!Box-specific monitor into a generic Linux Internet connection black box while preserving FRITZ!Box as the first enhanced router integration.

Generic Linux mode

  • runs without router credentials
  • auto-detects the IPv4 default gateway and interface
  • monitors link state, gateway reachability, Internet ICMP, DNS, HTTP, public IP, outages and downtime
  • avoids false outages when a gateway or upstream target intentionally drops ICMP
  • keeps ISP report and CSV export useful without router-specific telemetry

FRITZ!Box enhanced mode

When TR-064 credentials are configured, LineWatch keeps the existing deep diagnostics:

  • router model / FRITZ!OS
  • router uptime and reboot detection
  • WAN uptime / state
  • WAN or PPPoE session-reset detection
  • router event logs around incidents when available

User experience

  • installer now offers generic or FRITZ-enhanced setup
  • Raspberry Pi is a recommended always-on target rather than a hard requirement
  • dashboard adapts automatically to the available telemetry
  • README is repositioned around the connection-black-box use case

Open-source project hygiene

  • MIT License, copyright Luca Serioli
  • explicit creator/maintainer attribution
  • contribution and security guidance
  • compatibility, bug and feature-request templates
  • Linux validation checklist
  • expanded CI with unit tests and shell syntax checks

Validation

CI

  • GitHub Actions passes on Python 3.11 and 3.13
  • classifier and route-detection unit tests pass
  • shell scripts pass syntax checks

WSL2 smoke test — passed

Validated on Windows WSL2 with Ubuntu 26.04 LTS x86_64 and Python 3.14.4:

  • 14/14 unit tests passed
  • generic setup and route/interface autodetection passed
  • gateway-ICMP fallback behaved correctly: the WSL virtual gateway did not answer ICMP while Internet/DNS/HTTP remained healthy, and no false outage was raised
  • dashboard, API, SQLite history and public-IP observation worked
  • full install.sh path worked
  • linewatch.service and linewatch-dashboard.service ran successfully under systemd/Waitress
  • services returned automatically after wsl --shutdown and a fresh WSL start
  • FRITZ!Box enhanced mode was re-checked over the real LAN using an explicitly configured router address; TR-064 returned model, FRITZ!OS, router uptime, WAN status/uptime, PPPoE metadata and reconnect timing with no regression observed

No private credentials or IP addresses are recorded here.

Physical validation still required

Do not merge yet. WSL2 validates the Linux userspace/install/service paths but its NIC and default gateway are virtualized. Before this PR is marked ready, complete the relevant parts of docs/TESTING.md on a physical Linux host, ideally Ethernet-connected, so link-carrier and real gateway/router fault behavior are exercised directly.

The PR intentionally avoids claiming untested OpenWrt, UniFi, MikroTik or other router support; those remain possible future adapters.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant