From 4f6d62b566196c14fc278499ef3175142756a27e Mon Sep 17 00:00:00 2001 From: Claude Fable 5 Date: Sat, 29 Aug 2026 18:18:52 +0200 Subject: [PATCH] docs: explain the remote-access error in user terms Co-authored-by: HuggeK <48095810+HuggeK@users.noreply.github.com> --- docs/operations.md | 38 ++++++++++++++++++++++++++++++++++++++ docs/setup-guide/de.md | 1 + docs/setup-guide/en.md | 1 + docs/setup-guide/es.md | 1 + docs/setup-guide/fr.md | 1 + docs/setup-guide/sv.md | 1 + 6 files changed, 43 insertions(+) diff --git a/docs/operations.md b/docs/operations.md index 193fd1dbf..842aa22d9 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -174,6 +174,44 @@ The FTW app and Home Assistant MQTT are unchanged. Recovery: `curl` to `127.0.0.1`, or set `api.lan_auth: false` in `config.yaml` and restart Core. +### "remote access to protected API routes is disabled" + +The full message is `remote access to protected API routes is disabled; +configure FTW_API_TOKEN or use a local address`. The dashboard still loads — +the message appears when a protected request (saving settings, starting an +update, a scan) is refused. It means the request failed the locality rules +above, and "local" is judged on the request, not on which network the +browser sits on: + +1. **The address in the browser's address bar** must be a private or + loopback IP, `localhost`, or a `.local`/`.localhost`/`.home.arpa` name. +2. **The address the connection arrives from** must be loopback, private, or + link-local. + +Being on the same LAN as the box satisfies neither by itself. The common +ways to trip the boundary from the couch next to the Pi: + +- **A plain hostname without a dot** — `http://myhost:8080`. Since v2.2.1 + a no-dot name is deliberately not local (a DNS-rebinding guard), so an + address that worked before an update stops working. Use the `.local` + name or the IP instead. +- **A router-issued name with a dot in it** — `pi.lan`, `ftw.fritz.box`, + `box.home`. Only the suffixes listed above count as local names. +- **Tailscale** — both `100.x.y.z` addresses (CGNAT space) and `*.ts.net` + names count as remote. +- **IPv6** — when the name resolves to a global IPv6 address, the browser + connects from a global address and fails the second rule, even with a + `.local` name in the address bar. +- **A reverse proxy or Home Assistant ingress reached through a public + URL** — the request arrives carrying the public hostname. + +The reliable fix for a browser is to open the UI through the box's private +IPv4 address, for example `http://192.168.1.123:8080`. Setting +`FTW_API_TOKEN` does not change what the built-in UI sends — the token is +only for API clients that attach the `Authorization: Bearer` header, as +described above — and a `?token=...` query parameter in the URL does +nothing. + ## Logs and health ```bash diff --git a/docs/setup-guide/de.md b/docs/setup-guide/de.md index 13e732124..083db33aa 100644 --- a/docs/setup-guide/de.md +++ b/docs/setup-guide/de.md @@ -145,4 +145,5 @@ Wenn diese Adresse nicht funktioniert — probiere die IP-Adresse, die du aufges - **Das Lämpchen leuchtet gar nicht** → prüfe, ob das Netzteil richtig eingesteckt ist. - **Keine IP-Adresse zu finden** → starte den Router neu, warte 5 Minuten, schau nochmal. - **SSH sagt "Connection refused"** → warte noch etwas. Der erste Start dauert. +- **Die Seite lädt, aber beim Ändern von Einstellungen oder beim Update erscheint "remote access to protected API routes is disabled"** → FTW nimmt Änderungen nur von Adressen an, die es als lokal erkennt. Öffne die Oberfläche über die IP-Adresse des Pi, z. B. `http://192.168.1.123:8080`. Warum das passiert — auch zu Hause — steht in [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (auf Englisch). - **Das alles hilft nicht** → schau auf unserem Discord vorbei und frage freundlich nach Hilfe: **https://discord.gg/25xcBzQaux** diff --git a/docs/setup-guide/en.md b/docs/setup-guide/en.md index 4b33af760..32d0ca270 100644 --- a/docs/setup-guide/en.md +++ b/docs/setup-guide/en.md @@ -145,4 +145,5 @@ If that address doesn't work — try the IP address you wrote down, e.g. `http:/ - **The light isn't on at all** → check that the power adapter is plugged in. - **Can't find the IP address** → restart the router, wait 5 minutes, look again. - **SSH says "Connection refused"** → wait a little longer. The first boot takes time. +- **The page opens, but changing settings or updating shows "remote access to protected API routes is disabled"** → FTW only accepts changes from addresses it recognizes as local. Open the UI through the Pi's IP address, e.g. `http://192.168.1.123:8080`. Why this happens — even at home — is explained in [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled). - **None of this helps** → drop by our Discord and kindly ask for help: **https://discord.gg/25xcBzQaux** diff --git a/docs/setup-guide/es.md b/docs/setup-guide/es.md index 00ef326c3..d3a869691 100644 --- a/docs/setup-guide/es.md +++ b/docs/setup-guide/es.md @@ -145,4 +145,5 @@ Si esa dirección no funciona — prueba con la dirección IP que apuntaste, p. - **La luz no se enciende nada** → revisa que el adaptador de corriente esté bien conectado. - **No encuentras la dirección IP** → reinicia el router, espera 5 minutos, vuelve a mirar. - **SSH dice "Connection refused"** → espera un poco más. El primer arranque tarda. +- **La página abre, pero al cambiar ajustes o actualizar aparece "remote access to protected API routes is disabled"** → FTW solo acepta cambios desde direcciones que reconoce como locales. Abre la interfaz con la dirección IP de la Pi, p. ej. `http://192.168.1.123:8080`. El porqué — incluso en casa — se explica en [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (en inglés). - **Nada de esto funciona** → pásate por nuestro Discord y pide ayuda amablemente: **https://discord.gg/25xcBzQaux** diff --git a/docs/setup-guide/fr.md b/docs/setup-guide/fr.md index fec4c941e..f59eee7b0 100644 --- a/docs/setup-guide/fr.md +++ b/docs/setup-guide/fr.md @@ -145,4 +145,5 @@ Si cette adresse ne fonctionne pas — essayez l'adresse IP que vous avez notée - **La lumière ne s'allume pas du tout** → vérifiez que l'adaptateur secteur est bien branché. - **Pas d'adresse IP trouvée** → redémarrez la box, attendez 5 minutes, regardez à nouveau. - **SSH dit "Connection refused"** → attendez encore un peu. Le premier démarrage prend du temps. +- **La page s'ouvre, mais modifier un réglage ou lancer une mise à jour affiche "remote access to protected API routes is disabled"** → FTW n'accepte les modifications que depuis des adresses qu'il reconnaît comme locales. Ouvrez l'interface via l'adresse IP du Pi, p. ex. `http://192.168.1.123:8080`. Le pourquoi — même à la maison — est expliqué dans [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (en anglais). - **Rien de tout cela ne marche** → passez sur notre Discord et demandez gentiment de l'aide : **https://discord.gg/25xcBzQaux** diff --git a/docs/setup-guide/sv.md b/docs/setup-guide/sv.md index f0a1dc78b..93c376010 100644 --- a/docs/setup-guide/sv.md +++ b/docs/setup-guide/sv.md @@ -145,4 +145,5 @@ Fungerar inte den adressen — prova IP-adressen du skrev ner, t.ex. `http://192 - **Lampan lyser inte alls** → kolla att strömadaptern sitter i. - **Hittar ingen IP-adress** → starta om routern, vänta 5 minuter, titta igen. - **SSH säger "Connection refused"** → vänta lite till. Första uppstarten tar tid. +- **Sidan öppnas, men vid ändringar eller uppdatering står det "remote access to protected API routes is disabled"** → FTW tar bara emot ändringar från adresser den ser som lokala. Öppna gränssnittet via Pi:ns IP-adress, t.ex. `http://192.168.1.123:8080`. Varför det händer — även hemma — förklaras i [operations.md](../operations.md#remote-access-to-protected-api-routes-is-disabled) (på engelska). - **Det hjälper inte** → kika in på vår Discord och fråga snällt om hjälp: **https://discord.gg/25xcBzQaux**