From 20b44051f2e20cb0d11cd73c441c578ac3e47dd4 Mon Sep 17 00:00:00 2001 From: Felix <301398501+felixfelix-bot@users.noreply.github.com> Date: Sun, 13 Sep 2026 03:08:40 +0530 Subject: [PATCH 1/3] docs(tester): add the alpha RC tester install/upgrade/rollback/report guide docs/rc-tester-guide.md is the document a tester with a supported OpenWrt router follows to install v0.6.0-alpha2 from the feed, upgrade, remove, roll back, and report a result they can act on. The supported matrix is a clearly marked placeholder (the 25.12/apk proposal, to be set by what the acceptance test actually passed); 24.10 and earlier are documented as unsupported, with a pointer at the file-download channel and an explanation of why. Every command in it was executed against a real OpenWrt 25.12.5 userland (apk-tools 3.0.5) installing a rehearsal package from a local copy of the feed layout, and each step that still needs a real router is marked UNTESTED. Two corrections came out of that rehearsal: apk-tools 3.x has no --force-downgrade (the working rollback is apk add 'tollgate-wrt=', which also leaves a pin in /etc/apk/world that blocks later upgrades), and RELEASE-NOTES.md no longer tells testers to use apk add --allow-untrusted. RELEASE-NOTES.md and README.md link the guide; CHANGELOG [Unreleased] entry added. --- CHANGELOG.md | 13 ++ README.md | 1 + RELEASE-NOTES.md | 24 +- docs/rc-tester-guide.md | 488 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 519 insertions(+), 7 deletions(-) create mode 100644 docs/rc-tester-guide.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f2129ff5..0da609cbc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,19 @@ and [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Changed / Internal + +- **Tester guide for the alpha RC.** New [docs/rc-tester-guide.md](docs/rc-tester-guide.md) + documents the supported-matrix placeholder (honest about what is untested), + the feed signing key and the repository line for OpenWrt 25.12, install, + upgrade, remove and rollback — including the `/etc/apk/world` version pin a + rollback leaves behind, and the fact that `--force-downgrade` is not an + apk-tools 3.x option — the failure modes reproduced in practice, how to + report a result, and what to expect from an alpha. Every command was + executed against a real OpenWrt 25.12.5 userland; router-only steps are + marked UNTESTED. `RELEASE-NOTES.md` no longer suggests + `apk add --allow-untrusted`. + ## [v0.6.0-alpha2] - 2026-09-13 ### Added diff --git a/README.md b/README.md index aba4427d1..f5d3671ab 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,7 @@ See [tests/README.md](tests/README.md) for how to wire up the test fleet. Design and protocol docs live under [docs/](docs/): - [docs/operator-guide.md](docs/operator-guide.md) — practical CLI reference for router operators +- [docs/rc-tester-guide.md](docs/rc-tester-guide.md) — install/upgrade/rollback/report guide for the alpha release candidate - [docs/merchant.md](docs/merchant.md) - [docs/upstream_session_manager.md](docs/upstream_session_manager.md) — module internals + end-to-end cross-component flow - [docs/data-session-management.md](docs/data-session-management.md) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index c85e7f360..66e8283d3 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -331,9 +331,13 @@ changes in this release only exist on a real device. - **Package filenames are `tollgate-wrt_v0.6.0-alpha2_.ipk` and `…_.apk`** (the tag name verbatim; UPX variants add a `-upx-…` suffix before the extension). -- **`.apk` (OpenWrt 25.x)**: `apk add --allow-untrusted - tollgate-wrt_v0.6.0-alpha2_.apk`. Inside the package apk-tools sees - the normalised version `0.6.0_alpha2-r0`. +- **`.apk` (OpenWrt 25.x)**: install it from the testing feed — see + [docs/rc-tester-guide.md](docs/rc-tester-guide.md) for the key, the + repository line and the verified install/upgrade/rollback commands. To + install the downloaded file directly instead, `apk add + ./tollgate-wrt_v0.6.0-alpha2_.apk`; inside the package apk-tools sees + the normalised version `0.6.0_alpha2-r1`. Never pass `--allow-untrusted`: + the feed index and key exist so that verification stays on. - **`.ipk` (OpenWrt 24.10 and earlier)**: `opkg install tollgate-wrt_v0.6.0-alpha2_.ipk`; the control-file version is the tag name, `v0.6.0-alpha2`. @@ -367,14 +371,20 @@ changes in this release only exist on a real device. [packaging/](packaging/) recipe into the OpenWrt SDK, producing either format. It takes `PACKAGE_VERSION` from the environment and otherwise reads `VERSION`, so a checkout at this tag builds `v0.6.0-alpha2` by default. +- **OpenWrt 25.12 testers: install from the feed, not from a file.** + [docs/rc-tester-guide.md](docs/rc-tester-guide.md) has the feed key, the + repository line, the install/upgrade/remove/rollback commands and what a + successful install looks like. It also states the supported matrix and + marks every step that has not yet been exercised on router hardware. - **Announcements**: `RELEASE-NOTES.md` (this document) and the `v0.6.0-alpha2` section of [CHANGELOG.md](CHANGELOG.md) are the authoritative description of the release; the per-PR detail lives in the changelog. -- **Reporting problems**: open an issue at - [github.com/OpenTollGate/tollgate-module-basic-go](https://github.com/OpenTollGate/tollgate-module-basic-go) - with the router model, the package version, and `/tmp/tollgate-setup.log` - if setup is involved. Read the known-issues section above first. +- **Reporting problems**: the tester guide's *How to report a result* section + lists the exact commands and the single intake channel for this release. + Send the output it asks for (router release, architecture, package version, + `tollgate version`, log lines), never a key, seed, wallet file or token. + Read the known-issues section above first. ## Contributors diff --git a/docs/rc-tester-guide.md b/docs/rc-tester-guide.md new file mode 100644 index 000000000..dd4deb390 --- /dev/null +++ b/docs/rc-tester-guide.md @@ -0,0 +1,488 @@ +# TollGate `v0.6.0-alpha2` — tester guide + +**Channel:** `alpha` (a release candidate, not a stable release). +**Audience:** you have an OpenWrt router, you can SSH into it, and you are +willing to lose whatever is on that router. + +This guide covers, in order: what this release supports, installing it from +the package feed, upgrading, removing, rolling back, what to do when something +fails, how to report a result we can act on, and what "alpha" means here. + +## How to read the verification markers + +Every command in this document was executed before publication, but not every +command could be executed on router hardware. Two markers are used: + +- **VERIFIED (rehearsal)** — the command was run against a real OpenWrt + 25.12.5 userland (`apk-tools 3.0.5`, `x86_64`) installing a rehearsal + package from a local copy of the feed layout described below. The exact + output quoted is real output from that run. +- **UNTESTED ON A ROUTER** — the command could not be exercised without a real + device (anything that needs `procd`, `ubus`, `logread`, the captive portal, + or the published feed host). It is documented intent, not a verified claim. + §10 lists all of them. + +The published feed host is **not final**: it is written below as +`` and must be filled in when the testing channel is published. +The URL *shape* (full URL to the index **file**, not a directory) is what a +25.12 router requires — that part is verified. + +--- + +## 1. What this release supports (read this first) + +> **PLACEHOLDER — the final supported matrix is set by what the RC acceptance +> test passed on hardware, and is not decided yet.** The table below is the +> current proposal, and is filled in by the maintainer before this guide is +> announced. Architectures that were built but never installed on hardware are +> published as **"built, untested"** — that is not a support claim. + +| OpenWrt release | Architecture | Status | +|---|---|---| +| 25.12.x (apk) | `x86_64` | Install rehearsal passed on a real 25.12.5 userland (container). Router-hardware acceptance test **pending**. | +| 25.12.x (apk) | every other architecture the build matrix produces | **built, untested** — no hardware acceptance test yet | +| 24.10.x and earlier (opkg) | any | **NOT supported** — see below | +| snapshots / master | any | **NOT supported** for testers | + +**Why 24.10 and earlier are not supported.** Their OpenWrt SDK toolchains ship +Go 1.21 / 1.23 and cannot build this module (it requires a current Go +toolchain), so no package for those releases is produced by this build. There +is also no opkg feed: publishing an empty or unsigned opkg index would read to +a router as a broken feed. 24.10's `opkg` has signature checking enabled by +default (`option check_signature` in `/etc/opkg.conf`), so a hand-built +unsigned index does not even load cleanly. + +**If you are on 24.10 or earlier:** the feed is not for you. The release +announcement also lists prebuilt package files (the "file-download channel", +fetched from the announced artifact URLs with their `sha256` values). Those +are **best-effort one-offs**: no feed, no automatic upgrade, no tested rollback +path, no compatibility promise, and nothing we can fix for you if they do not +work. Whether the package would run at all on your release line is untested — +it was built for 25.12. + +--- + +## 2. Before you install + +- A supported router (§1) with working SSH and root access. +- About **30 MB free** in `/overlay` (the two installed binaries are ~28 MB in + total in the rehearsal build). +- **Back up first** — copy `/etc/tollgate/` (wallet and identities) and + `/etc/config/tollgate` somewhere off the router. Removing or rolling back the + package does not delete those paths (verified — see §5), but an alpha is an + alpha; keep a copy. +- Do not install this on a router you or anyone else depends on. + +--- + +## 3. Install from the feed (OpenWrt 25.12) + +Three steps: install the feed's signing key, point `apk` at the testing +channel, install the package. + +### 3.1 Install the feed signing key + +`apk` refuses an index it cannot verify against a trusted key, so the key +comes first. It is a public key; installing it is a file download, not a +secret exchange. + +```sh +wget -O /etc/apk/keys/tollgate-testing.pem https:///keys/tollgate-testing.pem +``` + +**VERIFIED (rehearsal)** — download followed by `ls -l /etc/apk/keys/`: + +``` +-rw-r--r-- 1 root root 178 Jun 29 12:59 openwrt-25.12.pem +-rw-r--r-- 1 root root 178 Sep 12 21:28 tollgate-testing.pem +``` + +The file is a short PEM public key (`-----BEGIN PUBLIC KEY-----` on the first +line). If `wget` reports anything other than success, stop and read §7 — an +index download that cannot be verified is the most likely failure on a real +router. + +### 3.2 Point `apk` at the testing channel + +The repository line is a **full URL to the index file**, not a directory: + +```sh +echo "https:///testing/25.12/x86_64/packages.adb" \ + > /etc/apk/repositories.d/tollgate-testing.list +``` + +- `packages.adb` is the 25.12 index format. `APKINDEX.tar.gz` does not exist on + this release line — if you see someone using it, that is old material. +- The path shape `///packages.adb` follows the + channel layout the feed publishes. **Provisional:** the serving side + (channel host, path layout, cache headers) was still being finalised when + this guide was written; the line above is the intended shape and is the one + the rehearsal used. If the announcement prints a different path, the + announcement wins. +- The testing channel is deliberately separate from any production channel: + same host or not, it has its own path, its own index and its own key. A + production router never sees this release in `apk upgrade`, and unsubscribing + is deleting this one file. + +### 3.3 Refresh the index + +```sh +apk update +``` + +**VERIFIED (rehearsal)** + +``` + [https://downloads.openwrt.org/releases/25.12.5/targets/x86/64/packages/packages.adb] + [https://downloads.openwrt.org/releases/25.12.5/packages/x86_64/base/packages.adb] + ... + [http:///testing/25.12/x86_64/packages.adb] +OK: 11240 distinct packages available +``` + +Exit status 0, your feed line listed, and a package count. (The +`downloads.openwrt.org` lines are the stock OpenWrt feeds the router already +has; the rehearsal was an offline copy of a router's feed list.) If the count +drops or your line is listed as unavailable, see §7. + +### 3.4 Install + +```sh +apk add tollgate-wrt +``` + +**VERIFIED (rehearsal)** + +``` +(1/2) Installing jq (1.8.1-r2) + Executing jq-1.8.1-r2.post-install +(2/2) Installing tollgate-wrt (0.6.0_alpha2-r1) +OK: 39.1 MiB in 138 packages +``` + +`tollgate-wrt` is the package name. It installs two binaries — +`/usr/bin/tollgate-wrt` (the service) and `/usr/bin/tollgate` (the CLI) — plus +`/etc/init.d/tollgate-wrt`. `jq` is a dependency and is pulled in +automatically. + +**Do not pin a version on this line.** `apk add tollgate-wrt=` writes +a pin into `/etc/apk/world` that then blocks normal upgrades (verified — §6). + +### 3.5 What a successful install looks like + +```sh +apk list --installed tollgate-wrt +ls -l /usr/bin/tollgate /usr/bin/tollgate-wrt /etc/init.d/tollgate-wrt +tollgate status +tollgate version +``` + +**VERIFIED (rehearsal)** for the package listing and the files: + +``` +tollgate-wrt-0.6.0_alpha2-r1 x86_64 {tollgate-wrt} (GPL-3.0-only) [installed] +-rwxr-xr-x 1 nobody nogroup 1380 /etc/init.d/tollgate-wrt +-rwxr-xr-x 1 nobody nogroup 10253038 /usr/bin/tollgate +-rwxr-xr-x 1 nobody nogroup 17732119 /usr/bin/tollgate-wrt +``` + +**VERIFIED (rehearsal)** for the CLI, with the service running: + +``` +# tollgate version +TollGate Version +version: v0.6.0_alpha2 +commit: dcf8c5d +build_time: 2026-09-13T00:00:00Z +go_version: go1.26.0 +openwrt_version: OpenWrt 25.12.5 r33051-f5dae5ece4 + +# tollgate status +running: true +version: TollGate v0.6.0_alpha2 +uptime: 17.799201311s +config_ok: true +wallet_ok: true +network_ok: true +``` + +**Version strings, so you know what you are looking at:** + +| where | value | +|---|---| +| release tag / announcement | `v0.6.0-alpha2` | +| package version (`apk list --installed`) | `0.6.0_alpha2-r1` | +| runtime version (`tollgate version`) | `v0.6.0_alpha2` | + +apk normalises the hyphen into an underscore for its own version ordering; the +`-r1` release revision is set when the package is built. The runtime string is +the apk-safe form as well. The exact `-r` number and commit for the published +build are printed in the announcement — compare rather than assume. + +**The CLI talks to the running service over `/var/run/tollgate.sock`.** If the +service is not running, `tollgate status` and `tollgate version` report +`failed to communicate with TollGate service: ... connect: no such file or +directory` (VERIFIED). That is a service problem, not a broken installation — +the version check that never needs the service is +`apk list --installed tollgate-wrt`. Neither binary accepts a `--version` flag +(VERIFIED: `tollgate --version` → `unknown flag: --version`); use the +`version` subcommand. + +**Service status on the router — UNTESTED ON A ROUTER:** + +```sh +/etc/init.d/tollgate-wrt status # needs procd/ubus +logread -e tollgate | tail -50 # needs syslog; the service logs via syslog +``` + +The rehearsal container has no `procd`/`ubus`/`logread`, so neither of these +was executed. On a real router, expect the init script to report `running` and +the log to show the service starting, the wallet initialising and +`CLI server initialized and listening on Unix socket` (that last line was +observed in the rehearsal with the binary started by hand). + +--- + +## 4. Upgrade to a newer build in the channel + +Upgrade this package only: + +```sh +apk update +apk upgrade tollgate-wrt +``` + +**VERIFIED (rehearsal):** `apk upgrade tollgate-wrt` exits 0 (the rehearsal +container was already on the newest build in its channel, so it reported +`OK: 39.1 MiB in 138 packages`; the through-an-upgrade case was exercised with +the plain `apk upgrade` form below). + +**Do not run a bare `apk upgrade` on a router you care about** unless you +accept that it upgrades every other package too. VERIFIED: on a rehearsal +router with a mixed feed list, bare `apk upgrade` rewrote 43 stock packages +and several post-upgrade scripts failed, purely because the container has no +`procd`. `apk upgrade tollgate-wrt` keeps the blast radius at one package. + +**UNTESTED ON A ROUTER:** that the package's post-install logic restarts the +service on the router, that `/etc/config/tollgate` survives an upgrade +byte-for-byte, and that the wallet keeps working afterwards. The config file +is not written by the package (it is created on first run by the +`99-tollgate-setup` script), which is normally how OpenWrt keeps it across +upgrades, but that has not been confirmed on a device. + +--- + +## 5. Remove + +```sh +apk del tollgate-wrt +``` + +**VERIFIED (rehearsal)** + +``` +(1/2) Purging tollgate-wrt (0.6.0_alpha2-r1) +(2/2) Purging jq (1.8.1-r2) + Executing jq-1.8.1-r2.pre-deinstall +OK: 11.4 MiB in 136 packages +``` + +After it: `/usr/bin/tollgate`, `/usr/bin/tollgate-wrt` and +`/etc/init.d/tollgate-wrt` are gone, and the package's `apk list --installed` +entry is empty. + +**Do not do this unless** you can put the package back — keep the repository +line and key installed (§3.1–3.2) so that `apk add tollgate-wrt` works again, +and keep the backup from §2. + +**What removal does and does not delete (VERIFIED):** dependencies that were +installed automatically with it are removed too (`jq` above). Runtime data +under `/etc/tollgate/` is **not** touched: a marker file written into that +directory before `apk del` was still there afterwards, and the directory +itself survived. Files that came from the package (the captive-portal site +directory, `ecash/`) go away with it, and so do the package's `uci-defaults` +scripts — reinstalling restores them. + +If you do not plan to reinstall: do not remove the package to "clean up" +before reporting a problem. Remove only when you are done, and report first. + +--- + +## 6. Roll back to a known-good version + +Rollback is an install of an older version, pinned: + +```sh +apk add 'tollgate-wrt=' +``` + +**VERIFIED (rehearsal)** + +``` +(1/1) Downgrading tollgate-wrt (0.6.0_alpha3-r1 -> 0.6.0_alpha2-r1) +``` + +Exit status 0, and `apk list --installed tollgate-wrt` shows the older +version. Ordering matters and is real: apk knows `0.6.0_alpha3-r1` is newer +than `0.6.0_alpha2-r1`, which is why the same command upgrades, downgrades, or +does nothing, depending on which version you name. + +**`--force-downgrade` does not exist on 25.12.** Older material (and some +tickets) tell you to run `apk add --force-downgrade ...`. That is not an +apk-tools 3.0.5 option — VERIFIED: `ERROR: command line: unrecognized option +'force-downgrade'`. The command above is the rollback on this release line; the +`--force-downgrade` wording belongs to opkg-era routers (opkg on 24.10 does +have that flag, but there is no feed for 24.10 — §1). + +**The trap: rolling back pins you.** `apk add 'tollgate-wrt='` writes +`tollgate-wrt=` into `/etc/apk/world` (VERIFIED: + +``` +# grep tollgate /etc/apk/world (before the pin) +tollgate-wrt +# ... after the rollback ... +tollgate-wrt=0.6.0_alpha2-r1 +``` + +). While that pin is there, `apk upgrade tollgate-wrt` will **not** move you +to a newer build (VERIFIED: it stayed on the pinned version). When you are +ready to follow the channel again: + +```sh +apk add tollgate-wrt # drops the pin; /etc/apk/world goes back to "tollgate-wrt" +apk upgrade tollgate-wrt # VERIFIED: Upgrading tollgate-wrt (0.6.0_alpha2-r1 -> 0.6.0_alpha3-r1) +``` + +**Do not use `apk upgrade --available` as a rollback.** VERIFIED: it is a +whole-system "reset every package to whatever the repositories offer" +operation — in the rehearsal it rewrote 43 unrelated stock packages and +reported 6 script errors. It is not a targeted downgrade. + +--- + +## 7. When something goes wrong + +These are the failures that were reproduced in the rehearsal, with the exact +messages apk prints. + +| What you see | What it means | What to do | +|---|---|---| +| `WARNING: updating and opening : UNTRUSTED signature` and `apk update` exits non-zero; `apk add` then says `unable to select packages ... (no such package)` | The index could not be verified against a trusted key | Do **not** add `--allow-untrusted`. Re-do §3.1, check `ls -l /etc/apk/keys/` for the key file and its permissions, then §3.3. Report it if it still fails | +| `ERROR: wget: exited with error 4`, `WARNING: ... unexpected end of file`, `1 unavailable, 0 stale` | The feed was not fetched — wrong URL, no route, or host down | Check the repository line character by character (§3.2), retry, then report. Nothing was half-installed (VERIFIED) | +| `ERROR: tollgate-wrt-...: failed to extract usr/bin/tollgate: Connection aborted` | The downloaded package is truncated/corrupt | Re-run `apk add tollgate-wrt`. VERIFIED: the package is not installed, `/usr/bin/tollgate` does not exist afterwards. Report the router if it repeats — that could be the mirror, not you | +| `ERROR: unable to select packages: ... error: uninstallable / arch: mipsel_24kc` | The index you are pointed at does not contain your architecture | Report your `apk --print-arch` output. VERIFIED: there is no wrong-arch fallback — apk refuses rather than installing something for another architecture | +| `tollgate status` → `failed to communicate with TollGate service ... no such file or directory` | The service is not running, or the socket is missing | The install is intact. Check `/etc/init.d/tollgate-wrt status`, then `logread -e tollgate \| tail -50`, and include both in a report | +| `apk upgrade tollgate-wrt` does nothing after a rollback | The version pin in `/etc/apk/world` is still active | §6 — drop the pin with `apk add tollgate-wrt` | + +**Never use `--allow-untrusted`.** It disables the verification that makes the +feed trustworthy, and it never becomes necessary on a correct setup: the +rehearsal reproduced both halves — an unsigned index fails +(`WARNING: ... UNTRUSTED signature`, `apk update` exit 1, `apk add` installs +nothing), and the *same* package installs from the same channel without the +flag once the index is signed. With `--allow-untrusted` the unsigned channel +installed happily, which is exactly the hole the rule closes. If you have a +feed problem, fix the key or the URL — do not reach for that flag, and do not +paste it into a report as advice. + +--- + +## 8. What to expect from an alpha + +- **Not production software.** Do not put funds, users, or anything you need + on this router. A router that matters should stay on the stable release. +- **The wallet path is being hardened.** The Cashu wallet's failure paths + (cancelled payments, drained wallets, interrupted funding) are the active + area of work, and this build may still contain defects there. +- **Funds-loss reports are top priority.** Any symptom that could mean money + left the wallet the wrong way — a balance that changes when nothing was + bought, a sale that is credited but not paid, a cancel or drain that behaves + oddly — is a **stop-ship** report (severity S1 in §9). Tell us immediately; + we would rather halt the release than learn about a second case. +- **Known limitations for this build** are listed in `RELEASE-NOTES.md` under + "Verification status" — a version/setup-rerun path that has only ever been + exercised in a checkout, plus the router-only behaviours. Read it before + concluding that something you found is a new bug. +- **Everything can move.** The version string, the channel path, the index + format and the upgrade path are all still being settled; an RC can change + under you between builds, and this guide with it. +- **There is a rollback** (§6), and it is worth knowing before you install + rather than after. + +--- + +## 9. How to report a result + +An actionable report carries facts, not impressions. Run these and paste the +**output**, not a screenshot or a paraphrase: + +```sh +cat /etc/openwrt_release +apk --print-arch +cat /etc/apk/repositories.d/tollgate-testing.list +apk list --installed tollgate-wrt +sha256sum /usr/bin/tollgate /usr/bin/tollgate-wrt +tollgate version +logread -e tollgate | tail -50 +``` + +Plus, in your own words: the router model; the release and architecture you are +on; what you expected; what actually happened; whether the service was running +at the time; and whether you are reporting a clean install, an upgrade, a +removal, or a rollback. + +`tollgate version` needs the service running (§3.5). If it is not running, +say so and send the `apk list --installed` line instead — a report without a +version and an architecture is untriaged and we will ask once, then close it. + +**Where to send it:** the single intake channel named in the release +announcement (`TESTER-INTAKE`). **Provisional:** the intake channel is being +finalised alongside this guide; the announcement will name exactly one place +to report. Do not send reports to several places at once. + +**Severity, so you can see how it will be handled:** + +- **S1** — any wallet/funds symptom, any loss of funds. Stop-ship: the channel + may be pulled before anyone investigates further. +- **S2** — the service is broken, crashes, will not start, or the install + leaves the router in a bad state. +- **S3** — cosmetic, documentation, or anything you are unsure about. + +**Never paste any of the following into a report, a chat, an issue or a +screenshot:** + +- `tollgate config get` output, or the contents of `/etc/tollgate/` + (identities, wallet database) — it contains your keys; +- a wallet file, a seed phrase, a mnemonic, or an `nsec`; +- a Cashu token, or the output of `tollgate wallet drain cashu`; +- router credentials, WireGuard keys, or private network passwords. + +If you think you sent a secret by accident, say so immediately without pasting +it again — that is a recoverable situation, and it is one we would rather hear +about than discover later. + +--- + +## 10. What a real-router test still has to confirm + +Everything below is documented here but was **not** executed on hardware, and +this guide does not present it as verified: + +1. The published feed host and path (``, channel layout and + cache headers) — the serving side was still being built when this was + written. +2. The real, signed index and its key, downloaded over HTTPS from that host. +3. The real `0.6.0_alpha2-r1` package bytes: filename, `sha256`, and that the + provided `sha256` matches the artifact published in the announcement. +4. `/etc/init.d/tollgate-wrt` `enable`/`status`/`start` under `procd`, the + service starting on boot, and the daemon staying up ≥ 5 minutes. +5. `logread` output, and `tollgate logs` (which wraps it). +6. First-run behaviour: `99-tollgate-setup` running from `uci-defaults`, + `/etc/config/tollgate` being created, and WiFi/portal configuration being + preserved across an upgrade. +7. The captive portal and the payment flow end to end — nothing in this guide + exercises them, and no package install can. +8. Rollback executed on a router with a real user configuration in place. +9. Whether 24.10 or earlier can run the package at all (it is untested and + unsupported — §1). +10. The final supported-architecture matrix (§1), and therefore which + architectures may be announced as tested rather than "built, untested". From d25cbb152489820f4ec2b4873fd88ebbc72c2380 Mon Sep 17 00:00:00 2001 From: Felix <301398501+felixfelix-bot@users.noreply.github.com> Date: Sun, 13 Sep 2026 03:13:06 +0530 Subject: [PATCH 2/3] docs(changelog): link the alpha RC tester guide entry to PR #381 --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0da609cbc..44e077505 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -22,6 +22,7 @@ and [Semantic Versioning](https://semver.org/). executed against a real OpenWrt 25.12.5 userland; router-only steps are marked UNTESTED. `RELEASE-NOTES.md` no longer suggests `apk add --allow-untrusted`. + ([#381](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/381)) ## [v0.6.0-alpha2] - 2026-09-13 From 585f00c7fbe5aa09debc99e5f24546981072ef8c Mon Sep 17 00:00:00 2001 From: Felix <301398501+felixfelix-bot@users.noreply.github.com> Date: Sun, 13 Sep 2026 16:44:48 +0530 Subject: [PATCH 3/3] docs(tester): fix the RC guide's package version, config path and install warnings MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Five defects found in review, fixed before a tester reads the guide: - The release revision is -r0, not -r1: packaging/normalize-apk-version.sh emits '-r0' and no build produces -r1. Corrected in the rollback command and every quoted apk output in §3.4/§3.5/§4/§5, and in RELEASE-NOTES.md. - /etc/config/tollgate does not exist. The real path is /etc/tollgate/config.json (+ identities.json, install.json); the backup advice, the upgrade-survival claim, and §10 item 6 are corrected, and the config file is now described as written by the service on first run, not by 99-tollgate-setup (which only commits network/wireless/dhcp/firewall/ uhttpd/nodogsplash UCI). - The offline .apk fallback in RELEASE-NOTES is reworded into a workable path: the downloaded file cannot be verified by apk, so it installs only with --allow-untrusted, and only after checking the sha256 published in the announcement. Installing an unverified file stays forbidden. - §3 now warns that the package's post-install script runs the uci-defaults scripts and restarts network/wifi/firewall/dnsmasq/uhttpd, which can drop an SSH session opened over the LAN being configured. - §9's never-paste list now covers the logread block (read it first, redact after token_preview=/preview:, and say so) and /tmp/tollgate-setup.log, which holds the generated private-WiFi PSK in cleartext. --- RELEASE-NOTES.md | 25 ++++++++++++++++----- docs/rc-tester-guide.md | 49 ++++++++++++++++++++++++++--------------- 2 files changed, 50 insertions(+), 24 deletions(-) diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 66e8283d3..0d0ba288d 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -325,7 +325,7 @@ changes in this release only exist on a real device. ## Upgrade notes -- **Back up the wallet directory and `/etc/config/tollgate` before +- **Back up the wallet directory and `/etc/tollgate/config.json` before upgrading.** The deployment backup that leaked in August is a reminder of what that data is worth. - **Package filenames are `tollgate-wrt_v0.6.0-alpha2_.ipk` and @@ -333,11 +333,24 @@ changes in this release only exist on a real device. suffix before the extension). - **`.apk` (OpenWrt 25.x)**: install it from the testing feed — see [docs/rc-tester-guide.md](docs/rc-tester-guide.md) for the key, the - repository line and the verified install/upgrade/rollback commands. To - install the downloaded file directly instead, `apk add - ./tollgate-wrt_v0.6.0-alpha2_.apk`; inside the package apk-tools sees - the normalised version `0.6.0_alpha2-r1`. Never pass `--allow-untrusted`: - the feed index and key exist so that verification stays on. + repository line and the verified install/upgrade/rollback commands. Inside + the package apk-tools sees the normalised version `0.6.0_alpha2-r0`. + + **An unsigned downloaded file is not a substitute for the feed.** `apk` + will refuse `apk add ./tollgate-wrt_v0.6.0-alpha2_.apk` on its own + (`UNTRUSTED signature`), because the file is not signed with a key the + router trusts. It only installs with `--allow-untrusted`, and only after + you have verified the file against the `sha256` published in the + announcement: + + ```bash + sha256sum tollgate-wrt_v0.6.0-alpha2_.apk # must equal the announced sha256 + apk add --allow-untrusted ./tollgate-wrt_v0.6.0-alpha2_.apk + ``` + + Never `--allow-untrusted` a file whose `sha256` you have not checked — and + never use that flag on the feed path: the index and key exist so that + verification stays on. - **`.ipk` (OpenWrt 24.10 and earlier)**: `opkg install tollgate-wrt_v0.6.0-alpha2_.ipk`; the control-file version is the tag name, `v0.6.0-alpha2`. diff --git a/docs/rc-tester-guide.md b/docs/rc-tester-guide.md index dd4deb390..ae944564b 100644 --- a/docs/rc-tester-guide.md +++ b/docs/rc-tester-guide.md @@ -67,8 +67,8 @@ it was built for 25.12. - A supported router (§1) with working SSH and root access. - About **30 MB free** in `/overlay` (the two installed binaries are ~28 MB in total in the rehearsal build). -- **Back up first** — copy `/etc/tollgate/` (wallet and identities) and - `/etc/config/tollgate` somewhere off the router. Removing or rolling back the +- **Back up first** — copy `/etc/tollgate/` (the wallet, `identities.json`, + `config.json`) somewhere off the router. Removing or rolling back the package does not delete those paths (verified — see §5), but an alpha is an alpha; keep a copy. - Do not install this on a router you or anyone else depends on. @@ -156,10 +156,17 @@ apk add tollgate-wrt ``` (1/2) Installing jq (1.8.1-r2) Executing jq-1.8.1-r2.post-install -(2/2) Installing tollgate-wrt (0.6.0_alpha2-r1) +(2/2) Installing tollgate-wrt (0.6.0_alpha2-r0) OK: 39.1 MiB in 138 packages ``` +**If you are SSH'd in over the LAN this package configures, the install will +drop your session.** The package's post-install script runs the `uci-defaults` +scripts and then restarts `/etc/init.d/network`, reloads +wifi/firewall/dnsmasq/uhttpd and starts the service. Reconnect once the router +is back and continue at the next step — a lost session here is expected, not a +failure. + `tollgate-wrt` is the package name. It installs two binaries — `/usr/bin/tollgate-wrt` (the service) and `/usr/bin/tollgate` (the CLI) — plus `/etc/init.d/tollgate-wrt`. `jq` is a dependency and is pulled in @@ -180,7 +187,7 @@ tollgate version **VERIFIED (rehearsal)** for the package listing and the files: ``` -tollgate-wrt-0.6.0_alpha2-r1 x86_64 {tollgate-wrt} (GPL-3.0-only) [installed] +tollgate-wrt-0.6.0_alpha2-r0 x86_64 {tollgate-wrt} (GPL-3.0-only) [installed] -rwxr-xr-x 1 nobody nogroup 1380 /etc/init.d/tollgate-wrt -rwxr-xr-x 1 nobody nogroup 10253038 /usr/bin/tollgate -rwxr-xr-x 1 nobody nogroup 17732119 /usr/bin/tollgate-wrt @@ -211,11 +218,11 @@ network_ok: true | where | value | |---|---| | release tag / announcement | `v0.6.0-alpha2` | -| package version (`apk list --installed`) | `0.6.0_alpha2-r1` | +| package version (`apk list --installed`) | `0.6.0_alpha2-r0` | | runtime version (`tollgate version`) | `v0.6.0_alpha2` | apk normalises the hyphen into an underscore for its own version ordering; the -`-r1` release revision is set when the package is built. The runtime string is +`-r0` release revision is set when the package is built. The runtime string is the apk-safe form as well. The exact `-r` number and commit for the published build are printed in the announcement — compare rather than assume. @@ -264,10 +271,10 @@ and several post-upgrade scripts failed, purely because the container has no `procd`. `apk upgrade tollgate-wrt` keeps the blast radius at one package. **UNTESTED ON A ROUTER:** that the package's post-install logic restarts the -service on the router, that `/etc/config/tollgate` survives an upgrade +service on the router, that `/etc/tollgate/config.json` survives an upgrade byte-for-byte, and that the wallet keeps working afterwards. The config file -is not written by the package (it is created on first run by the -`99-tollgate-setup` script), which is normally how OpenWrt keeps it across +is not written by the package (it is created on first run by the service, not +by `99-tollgate-setup`), which is normally how OpenWrt keeps it across upgrades, but that has not been confirmed on a device. --- @@ -281,7 +288,7 @@ apk del tollgate-wrt **VERIFIED (rehearsal)** ``` -(1/2) Purging tollgate-wrt (0.6.0_alpha2-r1) +(1/2) Purging tollgate-wrt (0.6.0_alpha2-r0) (2/2) Purging jq (1.8.1-r2) Executing jq-1.8.1-r2.pre-deinstall OK: 11.4 MiB in 136 packages @@ -319,12 +326,12 @@ apk add 'tollgate-wrt=' **VERIFIED (rehearsal)** ``` -(1/1) Downgrading tollgate-wrt (0.6.0_alpha3-r1 -> 0.6.0_alpha2-r1) +(1/1) Downgrading tollgate-wrt (0.6.0_alpha3-r0 -> 0.6.0_alpha2-r0) ``` Exit status 0, and `apk list --installed tollgate-wrt` shows the older -version. Ordering matters and is real: apk knows `0.6.0_alpha3-r1` is newer -than `0.6.0_alpha2-r1`, which is why the same command upgrades, downgrades, or +version. Ordering matters and is real: apk knows `0.6.0_alpha3-r0` is newer +than `0.6.0_alpha2-r0`, which is why the same command upgrades, downgrades, or does nothing, depending on which version you name. **`--force-downgrade` does not exist on 25.12.** Older material (and some @@ -341,7 +348,7 @@ have that flag, but there is no feed for 24.10 — §1). # grep tollgate /etc/apk/world (before the pin) tollgate-wrt # ... after the rollback ... -tollgate-wrt=0.6.0_alpha2-r1 +tollgate-wrt=0.6.0_alpha2-r0 ``` ). While that pin is there, `apk upgrade tollgate-wrt` will **not** move you @@ -350,7 +357,7 @@ ready to follow the channel again: ```sh apk add tollgate-wrt # drops the pin; /etc/apk/world goes back to "tollgate-wrt" -apk upgrade tollgate-wrt # VERIFIED: Upgrading tollgate-wrt (0.6.0_alpha2-r1 -> 0.6.0_alpha3-r1) +apk upgrade tollgate-wrt # VERIFIED: Upgrading tollgate-wrt (0.6.0_alpha2-r0 -> 0.6.0_alpha3-r0) ``` **Do not use `apk upgrade --available` as a rollback.** VERIFIED: it is a @@ -454,6 +461,12 @@ screenshot:** (identities, wallet database) — it contains your keys; - a wallet file, a seed phrase, a mnemonic, or an `nsec`; - a Cashu token, or the output of `tollgate wallet drain cashu`; +- the `logread -e tollgate | tail -50` block before you have read it: the + daemon logs `token_preview=` (the first 50 characters of a Cashu token), so + read the block first, redact everything after `token_preview=` (and after + `preview:`), and say in the report that you redacted it; +- `/tmp/tollgate-setup.log` — it records the generated private-WiFi PSK in + cleartext; - router credentials, WireGuard keys, or private network passwords. If you think you sent a secret by accident, say so immediately without pasting @@ -471,14 +484,14 @@ this guide does not present it as verified: cache headers) — the serving side was still being built when this was written. 2. The real, signed index and its key, downloaded over HTTPS from that host. -3. The real `0.6.0_alpha2-r1` package bytes: filename, `sha256`, and that the +3. The real `0.6.0_alpha2-r0` package bytes: filename, `sha256`, and that the provided `sha256` matches the artifact published in the announcement. 4. `/etc/init.d/tollgate-wrt` `enable`/`status`/`start` under `procd`, the service starting on boot, and the daemon staying up ≥ 5 minutes. 5. `logread` output, and `tollgate logs` (which wraps it). 6. First-run behaviour: `99-tollgate-setup` running from `uci-defaults`, - `/etc/config/tollgate` being created, and WiFi/portal configuration being - preserved across an upgrade. + `/etc/tollgate/config.json` being created on first run, and WiFi/portal + configuration being preserved across an upgrade. 7. The captive portal and the payment flow end to end — nothing in this guide exercises them, and no package install can. 8. Rollback executed on a router with a real user configuration in place.