From 9d41685c77ca16c10a30fbff7d0757145614680b Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:18:55 +0200 Subject: [PATCH 01/16] Rebrand project documentation to UplinkWitness --- README.md | 54 +++++++++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 6a9a2db..0b087b1 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) +**Current stable release:** [v1.1.0](https://github.com/LucaXTech/UplinkWitness/releases/tag/v1.1.0) · [Quick install](#quick-install) · [Compatibility](docs/COMPATIBILITY.md) · [Roadmap](ROADMAP.md) · [Contributing](CONTRIBUTING.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. ## 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 From d2d1d612dd18683de5ab200f702a97f2f012e5ce Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:19:27 +0200 Subject: [PATCH 02/16] Update project attribution for UplinkWitness --- AUTHORS.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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). From 745a15a3b41e19685c15a8522c75fa0584ddfe6f Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:19:35 +0200 Subject: [PATCH 03/16] Update contribution guide for UplinkWitness --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) 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 From b7a7f59258527a2b6d5f92825c23fc1c27d14eba Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:19:42 +0200 Subject: [PATCH 04/16] Update security documentation for UplinkWitness --- SECURITY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 From 85a7f75a7c45c8d08c6557773877c737e5ddb082 Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:19:55 +0200 Subject: [PATCH 05/16] Update roadmap for UplinkWitness --- ROADMAP.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) 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 From 9f11b216a050d902fc11650dbc96cc1fa387d8cb Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:20:03 +0200 Subject: [PATCH 06/16] Update compatibility matrix for UplinkWitness --- docs/COMPATIBILITY.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) 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 From a2b6d304f59e08cc7a1d1b56a2c1f74b9ed123fa Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:20:17 +0200 Subject: [PATCH 07/16] Update testing checklist for UplinkWitness --- docs/TESTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) 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. From b1c70f11465af01e9125834e75f55f8355dc60d7 Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:20:44 +0200 Subject: [PATCH 08/16] Update bug report template for UplinkWitness --- .github/ISSUE_TEMPLATE/bug_report.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 From 9ed2224772f5825c0943141bccc884dcb17137bb Mon Sep 17 00:00:00 2001 From: Luca Serioli Date: Sat, 5 Sep 2026 20:22:12 +0200 Subject: [PATCH 09/16] Rebrand dashboard header to UplinkWitness --- templates/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/templates/index.html b/templates/index.html index 2266bd4..11186c1 100644 --- a/templates/index.html +++ b/templates/index.html @@ -3,7 +3,7 @@ -LineWatch +UplinkWitness