diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 5d8acc1..534e8ff 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Report a reproducible LineWatch problem +about: Report a reproducible UplinkWitness problem title: "[Bug] " labels: bug --- @@ -17,7 +17,7 @@ Describe the problem and what you expected instead. - `LINEWATCH_ROUTER_MODE`: - Router model: - FRITZ!OS version, if applicable: -- LineWatch version/commit: +- UplinkWitness version/commit: ## Reproduction steps diff --git a/AUTHORS.md b/AUTHORS.md index e08d2da..b7bdc90 100644 --- a/AUTHORS.md +++ b/AUTHORS.md @@ -1,6 +1,8 @@ # Authors -LineWatch was created by **Luca Serioli** ([@LucaXTech](https://github.com/LucaXTech)). +**UplinkWitness** was created by **Luca Serioli** ([@LucaXTech](https://github.com/LucaXTech)). + +The project was originally released as **LineWatch** through v1.1.0 and was renamed to UplinkWitness before broader public launch. ## Original author and maintainer @@ -10,4 +12,4 @@ LineWatch was created by **Luca Serioli** ([@LucaXTech](https://github.com/LucaX Community contributions are welcome and remain attributed through the Git history and GitHub contributor graph. -LineWatch is released under the MIT License; see [LICENSE](LICENSE). +UplinkWitness is released under the MIT License; see [LICENSE](LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6f393e3..9d1f635 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ -# Contributing to LineWatch +# Contributing to UplinkWitness -Thanks for helping improve LineWatch. +Thanks for helping improve UplinkWitness. The project aims to keep a small, dependable generic Internet-monitoring core while adding deeper router diagnostics through optional adapters. @@ -46,9 +46,11 @@ Please include: - router model - router firmware, if relevant - generic or enhanced mode -- LineWatch version/commit +- UplinkWitness version/commit - what worked and what failed +Legacy runtime identifiers such as `linewatch.service` and `LINEWATCH_*` remain valid during the rename transition and should not be changed casually in compatibility or upgrade work. + See [docs/TESTING.md](docs/TESTING.md) for the validation checklist. ## License diff --git a/README.md b/README.md index 6a9a2db..69e9b15 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,40 @@ -# LineWatch +# UplinkWitness -[![CI](https://github.com/LucaXTech/LineWatch/actions/workflows/ci.yml/badge.svg)](https://github.com/LucaXTech/LineWatch/actions/workflows/ci.yml) -[![Release](https://img.shields.io/github/v/release/LucaXTech/LineWatch)](https://github.com/LucaXTech/LineWatch/releases/latest) +[![CI](https://github.com/LucaXTech/UplinkWitness/actions/workflows/ci.yml/badge.svg)](https://github.com/LucaXTech/UplinkWitness/actions/workflows/ci.yml) +[![Release](https://img.shields.io/github/v/release/LucaXTech/UplinkWitness)](https://github.com/LucaXTech/UplinkWitness/releases/latest) ![Python](https://img.shields.io/badge/Python-3.11%2B-blue) ![Linux](https://img.shields.io/badge/Linux-self--hosted-success) ![License](https://img.shields.io/badge/license-MIT-green) > **Know what actually went down.** -**LineWatch is a self-hosted Internet connection black box for Linux.** Most uptime monitors tell you that something stopped answering; LineWatch tries to preserve enough local evidence to tell you **where the failure was**: local link, gateway, upstream Internet, DNS, HTTP, or — with optional router telemetry — the router/WAN session itself. +**UplinkWitness is a self-hosted Internet connection black box for Linux.** Most uptime monitors tell you that something stopped answering; UplinkWitness tries to preserve enough local evidence to tell you **where the failure was**: local link, gateway, upstream Internet, DNS, HTTP, or — with optional router telemetry — the router/WAN session itself. It works with ordinary routers in **generic Linux mode** and becomes more diagnostic with a **FRITZ!Box** through TR-064. A Raspberry Pi is a convenient always-on deployment target, **not a requirement**. -**Current stable release:** [v1.1.0](https://github.com/LucaXTech/LineWatch/releases/tag/v1.1.0) · [Quick install](#quick-install) · [Compatibility](docs/COMPATIBILITY.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) +**Latest release:** [GitHub Releases](https://github.com/LucaXTech/UplinkWitness/releases/latest) · [Quick install](#quick-install) · [Compatibility](docs/COMPATIBILITY.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.md) · [Rename notes](docs/RENAMING.md) + +> **Project rename:** releases through v1.1.0 were published as **LineWatch**. The public project is now **UplinkWitness**. Existing runtime identifiers such as `linewatch.service`, `LINEWATCH_*` environment variables and `data/linewatch.sqlite3` are intentionally retained for upgrade compatibility. See [docs/RENAMING.md](docs/RENAMING.md). ## Screenshots ### Desktop dashboard -![LineWatch desktop dashboard](docs/screenshots/dashboard-desktop.png) +![UplinkWitness desktop dashboard](docs/screenshots/dashboard-desktop.png) ### Mobile dashboard

- LineWatch mobile dashboard + UplinkWitness mobile dashboard

-> The screenshots currently show the FRITZ!Box-enhanced dashboard. In generic mode, FRITZ-specific cards are replaced by gateway and generic connectivity diagnostics. +> The screenshots currently show the FRITZ!Box-enhanced dashboard. In generic mode, FRITZ-specific cards are replaced by gateway and generic connectivity diagnostics. Screenshots from v1.1 may still show the former LineWatch name while the rebrand is being completed. -## Why LineWatch? +## Why UplinkWitness? A normal uptime check can tell you that a target stopped answering. That is useful, but it often does not tell you **which part of a home Internet connection failed**. -LineWatch combines multiple signals and keeps the evidence locally: +UplinkWitness combines multiple signals and keeps the evidence locally: - Linux network-link state when available - default-gateway reachability @@ -77,7 +79,7 @@ This is particularly useful for short or intermittent faults that disappear befo - latency trends - outage duration, total downtime and observed-period availability -LineWatch does **not** assume that every router or Internet path answers ICMP. In automatic gateway-probe mode, a router that drops ping while DNS/HTTP remain healthy is not incorrectly classified as down. +UplinkWitness does **not** assume that every router or Internet path answers ICMP. In automatic gateway-probe mode, a router that drops ping while DNS/HTTP remain healthy is not incorrectly classified as down. ### With FRITZ!Box telemetry @@ -102,7 +104,7 @@ The responsive local dashboard provides: - CSV event export - human-readable ISP diagnostic report -Availability is calculated only over the period LineWatch has actually observed. A new installation does not pretend to have 30 days of monitoring history. +Availability is calculated only over the period UplinkWitness has actually observed. A new installation does not pretend to have 30 days of monitoring history. ## Where it can run @@ -114,7 +116,7 @@ The monitor is designed for an **always-on Linux host**. Good deployment targets - Linux VM - other ARM or x86 Linux systems with the required networking tools -For meaningful line diagnostics, an **Ethernet-connected always-on machine is recommended**. Wi-Fi can work, but then local wireless problems become part of what LineWatch observes. +For meaningful line diagnostics, an **Ethernet-connected always-on machine is recommended**. Wi-Fi can work, but then local wireless problems become part of what UplinkWitness observes. The automatic installer currently targets systems with `apt` and `systemd`, including Debian, Ubuntu and Raspberry Pi OS. Other Linux distributions can use the manual setup path once Python, `iproute2` and `ping` are available. @@ -129,8 +131,8 @@ See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) for the current matrix and [d Recommended: an always-on Debian/Ubuntu/Raspberry Pi OS machine connected by Ethernet. ```bash -git clone https://github.com/LucaXTech/LineWatch.git -cd LineWatch +git clone https://github.com/LucaXTech/UplinkWitness.git +cd UplinkWitness chmod +x install.sh ./install.sh ``` @@ -141,7 +143,7 @@ The installer asks whether you want FRITZ!Box enhanced diagnostics. Choose **No** when asked about FRITZ!Box integration. No router credentials are required. -LineWatch will monitor the Linux default gateway and external connectivity probes. +UplinkWitness will monitor the Linux default gateway and external connectivity probes. ### FRITZ!Box enhanced mode @@ -149,13 +151,13 @@ Choose **Yes** and provide a FRITZ!Box account allowed to access router settings A dedicated account is optional. Remote/Internet access for that account is not required. -After installation, open: +After installation, open the dashboard on port `8080` of the Linux host. For example: ```text -http://linewatch.local:8080 +http://:8080 ``` -If mDNS is unavailable, use the Linux host's LAN IP with port `8080`. +If the machine is already reachable as `linewatch.local`, that hostname continues to work; the project rename does not change your host's network name. ## Manual configuration @@ -198,10 +200,12 @@ FRITZ_HOST= `off` : Never use gateway ICMP to classify an outage. -Leaving `LINEWATCH_INTERFACE` empty lets LineWatch detect the interface associated with the Linux IPv4 default route. +Leaving `LINEWATCH_INTERFACE` empty lets UplinkWitness detect the interface associated with the Linux IPv4 default route. ## Services +Existing service identifiers deliberately retain the original internal name: + ```bash systemctl status linewatch systemctl status linewatch-dashboard @@ -221,9 +225,9 @@ For private remote access, use a VPN or mesh VPN such as Tailscale. ## Data and privacy -Runtime data stays on the machine running LineWatch: +Runtime data stays on the machine running UplinkWitness: -- `data/linewatch.sqlite3` — SQLite database +- `data/linewatch.sqlite3` — SQLite database; legacy-compatible filename - `data/events/` — incident bundles and optional FRITZ!Box logs The repository ignores `.env`, runtime databases and logs. Do not commit real router credentials, event logs, public IP addresses or personal network data. @@ -231,7 +235,7 @@ The repository ignores `.env`, runtime databases and logs. Do not commit real ro ## Architecture ```text - LineWatch Core + UplinkWitness Core │ ┌────────────────┼────────────────┐ │ │ │ @@ -268,7 +272,7 @@ Bug reports, Linux compatibility results, FRITZ!Box model reports, tests and rou Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request. The current development priorities are tracked in [ROADMAP.md](ROADMAP.md). -If you test LineWatch on different hardware, include: +If you test UplinkWitness on different hardware, include: - Linux distribution and version - architecture (`x86_64`, `aarch64`, etc.) @@ -284,7 +288,7 @@ See [AUTHORS.md](AUTHORS.md) for project attribution and contributor information ## License -LineWatch is open-source software released under the **MIT License**. See [LICENSE](LICENSE). +UplinkWitness is open-source software released under the **MIT License**. See [LICENSE](LICENSE). ## Status diff --git a/ROADMAP.md b/ROADMAP.md index 53d1d70..7161fdf 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,12 +1,12 @@ -# LineWatch roadmap +# UplinkWitness roadmap -LineWatch is intentionally developed as a small, dependable Internet-connection black box rather than a general-purpose observability platform. +UplinkWitness is intentionally developed as a small, dependable Internet-connection black box rather than a general-purpose observability platform. The roadmap is ordered by reliability and evidence quality first, feature count second. ## Current baseline — v1.1.x -The current stable baseline provides: +The current stable baseline, originally released under the LineWatch name, provides: - vendor-neutral Linux monitoring - physical/link carrier detection where Linux exposes it @@ -48,6 +48,10 @@ This should be completed before adding several router vendors. Prioritize changes that make an incident easier to explain after the fact, including clearer event context, exports and regression coverage for ambiguous failure cases. +### 4. Complete the brand transition without breaking upgrades + +The public project is now **UplinkWitness**. Existing runtime identifiers such as `linewatch.service`, `LINEWATCH_*` environment variables and the historical SQLite filename remain intentionally stable for compatibility. Any future internal-identifier migration should be explicit, documented and backward-compatible rather than bundled into the public rename. + ## Next integrations After the adapter contract is stable, candidate enhanced integrations include: @@ -62,11 +66,11 @@ A vendor is only listed as supported after a real implementation has been valida The automatic installer currently targets `apt` + `systemd` systems. Future portability work may include cleaner manual-install documentation and packaging/service recipes for additional Linux distributions. -Containerization is not automatically considered a win for LineWatch: network namespaces can hide the host link and default-route state that the monitor is specifically trying to observe. Any container deployment must preserve diagnostic fidelity. +Containerization is not automatically considered a win for UplinkWitness: network namespaces can hide the host link and default-route state that the monitor is specifically trying to observe. Any container deployment must preserve diagnostic fidelity. ## Non-goals -LineWatch is not trying to become: +UplinkWitness is not trying to become: - a hosted SaaS monitoring service - a replacement for Prometheus/Grafana or full infrastructure observability diff --git a/SECURITY.md b/SECURITY.md index 0135ec5..b07b288 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,6 @@ # Security -LineWatch is designed to run on a trusted local network. +UplinkWitness is designed to run on a trusted local network. ## Dashboard exposure diff --git a/configure.sh b/configure.sh index a9cef79..1ce64eb 100755 --- a/configure.sh +++ b/configure.sh @@ -4,9 +4,9 @@ set -euo pipefail APP_DIR="$(cd "$(dirname "$0")" && pwd)" cd "$APP_DIR" -echo "LineWatch configuration" +echo "UplinkWitness configuration" echo -echo "LineWatch can run with any ordinary Linux Internet connection." +echo "UplinkWitness can run with any ordinary Linux Internet connection." echo "FRITZ!Box credentials are only needed for enhanced TR-064 diagnostics" echo "such as router reboot and WAN/PPPoE session reset detection." echo diff --git a/dashboard.py b/dashboard.py index 7c1df64..bd3e6b0 100644 --- a/dashboard.py +++ b/dashboard.py @@ -464,8 +464,8 @@ def export_isp(): generated = datetime.now().astimezone().isoformat(timespec="seconds") if lang == "en": lines = [ - "LINEWATCH - ISP CONNECTION DIAGNOSTIC REPORT", - "=" * 44, + "UPLINKWITNESS - ISP CONNECTION DIAGNOSTIC REPORT", + "=" * 48, f"Period analysed: last {days} days", f"Generated: {generated}", "", @@ -497,12 +497,12 @@ def export_isp(): f"Total recorded downtime: {fmt_duration(downtime)}", "", "EVENT TIMELINE", - "-" * 44, + "-" * 48, ] else: lines = [ - "LINEWATCH - REPORT DIAGNOSTICO CONNESSIONE / ISP", - "=" * 42, + "UPLINKWITNESS - REPORT DIAGNOSTICO CONNESSIONE / ISP", + "=" * 46, f"Periodo analizzato: ultimi {days} giorni", f"Generato: {generated}", "", @@ -534,7 +534,7 @@ def export_isp(): f"Downtime totale registrato: {fmt_duration(downtime)}", "", "CRONOLOGIA EVENTI", - "-" * 42, + "-" * 46, ] if not rows: diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index 145cbdd..61d2b63 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -1,6 +1,6 @@ # Compatibility matrix -This document separates **verified** configurations from planned or community-reported support. LineWatch intentionally avoids claiming broad compatibility without evidence. +This document separates **verified** configurations from planned or community-reported support. UplinkWitness intentionally avoids claiming broad compatibility without evidence. ## Verified by the maintainer @@ -30,7 +30,9 @@ Compatibility reports are welcome for other: - FRITZ!Box models / FRITZ!OS releases - routers that do not answer ICMP on the default gateway -Please use the repository’s **Compatibility report** issue template and include the LineWatch version/commit, Linux distribution, architecture, interface type, router model and the checklist sections that passed or failed. +Please use the repository’s **Compatibility report** issue template and include the UplinkWitness version/commit, Linux distribution, architecture, interface type, router model and the checklist sections that passed or failed. + +Releases through v1.1.0 were published under the former **LineWatch** name. Results from those releases remain valid after the public rename because the runtime monitoring core and compatibility identifiers are unchanged. ## Not yet advertised as supported diff --git a/docs/RENAMING.md b/docs/RENAMING.md new file mode 100644 index 0000000..6991e12 --- /dev/null +++ b/docs/RENAMING.md @@ -0,0 +1,53 @@ +# LineWatch → UplinkWitness rename + +The project was originally published as **LineWatch** and was renamed to **UplinkWitness** before broader public launch. + +## What changed + +The public project identity changed: + +- GitHub repository: `LucaXTech/LineWatch` → `LucaXTech/UplinkWitness` +- README, dashboard, reports and user-facing documentation use **UplinkWitness** +- new clones should use the UplinkWitness repository URL + +GitHub redirects the former repository URL, but existing clones should update their `origin` explicitly: + +```bash +git remote set-url origin https://github.com/LucaXTech/UplinkWitness.git +``` + +## What intentionally did not change + +To preserve upgrades and historical data, the rename does **not** change existing runtime identifiers: + +- `linewatch.service` +- `linewatch-dashboard.service` +- `LINEWATCH_*` environment variables +- `data/linewatch.sqlite3` +- existing event/database schemas +- an installation directory that a current systemd unit already points to + +These names are implementation-level compatibility identifiers, not the public product name. + +## Existing installations + +No database migration is required solely because of the rename. An existing v1.0/v1.1 installation can keep its directory, `.env`, systemd units and SQLite history. + +Do **not** manually rename an existing production directory or systemd unit just to match the new public brand. A path change can break the `WorkingDirectory` or executable paths stored in systemd. + +## New installations + +Use: + +```bash +git clone https://github.com/LucaXTech/UplinkWitness.git +cd UplinkWitness +chmod +x install.sh +./install.sh +``` + +The installer still creates the stable `linewatch` service identifiers for compatibility. + +## Releases + +Releases through **v1.1.0** were published under the LineWatch name. Their tags and history remain part of the same repository. Subsequent releases use the UplinkWitness public identity. diff --git a/docs/TESTING.md b/docs/TESTING.md index 3486d55..a194d7b 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -1,6 +1,6 @@ # Linux validation checklist -Use this checklist before claiming a Linux distribution or device class as tested. +Use this checklist before claiming a Linux distribution or device class as tested with UplinkWitness. ## Fresh install @@ -15,6 +15,8 @@ systemctl status linewatch-dashboard journalctl -u linewatch -n 100 --no-pager ``` +The `linewatch` service names are intentionally retained as stable runtime identifiers during the UplinkWitness rename. + ## Generic mode Configure `LINEWATCH_ROUTER_MODE=generic` and verify: @@ -29,7 +31,7 @@ Configure `LINEWATCH_ROUTER_MODE=generic` and verify: ## Gateway ICMP behavior -If the gateway answers ping, verify LineWatch logs that gateway ICMP is supported. +If the gateway answers ping, verify UplinkWitness logs that gateway ICMP is supported. If the gateway does not answer ping while Internet access works, verify automatic mode disables gateway-based outage classification instead of reporting a false outage. @@ -63,4 +65,4 @@ Reboot the Linux host and verify the monitor/dashboard return automatically and Export both CSV and ISP text reports. Check that generic mode does not invent FRITZ-specific telemetry and enhanced mode includes it when available. -When opening a compatibility issue, include distribution/version, architecture, network interface type, router model, LineWatch commit/version, and which checklist sections passed. +When opening a compatibility issue, include distribution/version, architecture, network interface type, router model, UplinkWitness commit/version, and which checklist sections passed. diff --git a/install.sh b/install.sh index 09f222e..44dd3aa 100755 --- a/install.sh +++ b/install.sh @@ -30,13 +30,15 @@ if [ ! -f "$APP_DIR/.env" ]; then else cp "$APP_DIR/.env.example" "$APP_DIR/.env" chmod 600 "$APP_DIR/.env" - echo "Created .env from .env.example. LineWatch will start in generic mode unless FRITZ credentials are added." + echo "Created .env from .env.example. UplinkWitness will start in generic mode unless FRITZ credentials are added." fi fi +# Service identifiers intentionally retain the original linewatch names so +# existing installations can upgrade without replacing units or data paths. sudo tee /etc/systemd/system/linewatch.service >/dev/null </dev/null < -LineWatch +UplinkWitness