Skip to content

docs: explain the remote-access error in user terms - #1000

Open
HuggeK wants to merge 1 commit into
srcfl:masterfrom
HuggeK:docs/remote-access-error
Open

docs: explain the remote-access error in user terms#1000
HuggeK wants to merge 1 commit into
srcfl:masterfrom
HuggeK:docs/remote-access-error

Conversation

@HuggeK

@HuggeK HuggeK commented Aug 29, 2026

Copy link
Copy Markdown
Contributor

Community users hitting remote access to protected API routes is disabled; configure FTW_API_TOKEN or use a local address currently have nothing to read: the string appears in the update dialog and settings with no link, docs/operations.md never quotes it, and the setup guide doesn't mention it. The confusion is predictable — the check is about the URL and source address, not the network, so people standing next to the Pi don't understand why they are "remote".

This adds:

  • a subsection in docs/operations.md under LAN and API access that quotes the message verbatim (so search finds it), states the two locality rules in user terms, and lists the common LAN traps: dot-free hostnames (not local since v2.2.1 / fix(api): stop treating no-dot hosts as local #952 — an address that worked before an update stops working), router names like pi.lan/ftw.fritz.box, Tailscale (100.x, *.ts.net), global-IPv6 resolution, and public reverse-proxy/HA-ingress URLs. It also says explicitly that the built-in UI never sends the token and that ?token=... in the URL does nothing.
  • one troubleshooting bullet in each of the five setup guides (en/sv/de/es/fr), linking to that subsection.
How this was verified against the code
  • Rules taken from isLocalAuthority / isLocalClient in go/internal/api/security.go on current master, including the fix(api): stop treating no-dot hosts as local #952 change that removed dot-free names from the local list (DNS-rebinding guard).
  • "UI never sends the token": no Authorization: Bearer writer and no token query-param reader anywhere under web/ (the tip circulating among users, appending ?token=... to the URL, is a placebo — it "works" only when the address is a private IP).
  • Prompted by a real support thread: a user on their LAN whose myhost:8080 bookmark broke after updating past v2.2.1; the direct private IP worked.

Docs-only change, so no changeset per the auto-exemption.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JXoRP5AK9zCFxzB2N2Th9V

Co-authored-by: HuggeK <48095810+HuggeK@users.noreply.github.com>
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.

2 participants