diff --git a/CHANGELOG.md b/CHANGELOG.md index ae01e04d9..11f436b18 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -72,6 +72,18 @@ and [Semantic Versioning](https://semver.org/). GPL-3.0 `LICENSE`. ([#383](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/383)) ### 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`. + ([#381](https://github.com/OpenTollGate/tollgate-module-basic-go/pull/381)) + - **Packaging artifact-contents test.** New `tests/packaging/assert-artifact-contents.sh` asserts a built `.ipk`/`.apk` ships the runtime files under `packaging/files/`, and is wired into both diff --git a/RELEASE-NOTES.md b/RELEASE-NOTES.md index 061ac4431..5f5851921 100644 --- a/RELEASE-NOTES.md +++ b/RELEASE-NOTES.md @@ -328,7 +328,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 @@ -336,11 +336,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`. @@ -388,8 +401,9 @@ changes in this release only exist on a real device. (a comment on the pinned *Tester reports — TollGate v0.6.0-alpha2 (alpha channel)* issue in the [project tracker](https://github.com/OpenTollGate/tollgate-module-basic-go/issues)), - carries the report template, and states the triage and severity rules. Send - the facts it asks for (router model, `cat /etc/openwrt_release`, + carries the report template, and states the triage and severity rules; the + tester guide's *How to report a result* section lists the exact commands to + run. Send the facts they ask for (router model, `cat /etc/openwrt_release`, `apk --print-arch`, the feed line, `apk list --installed tollgate-wrt`, `tollgate version`, `sha256sum` of the installed binaries, `logread -e tollgate | tail -50`, expected vs actual) and never a key, seed, diff --git a/docs/rc-tester-guide.md b/docs/rc-tester-guide.md index 06939548b..a452e8452 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 @@ -206,17 +213,33 @@ wallet_ok: true network_ok: true ``` +**Note — the version string the published build prints.** The repository-root +`VERSION` file (`v0.6.0-alpha2`) is injected into both binaries verbatim: CI +passes the tag down as `PACKAGE_VERSION` and every packaging path in this tree +(`scripts/build-sdk-package.sh`, `packaging/local-build-ipk.sh`) forwards it to +`-X .../src/cli.Version` unchanged. A build from the current tree therefore +prints `version: v0.6.0-alpha2` (hyphen) and `version: TollGate v0.6.0-alpha2`. +The rehearsal block above was produced by an earlier packaging path and shows +the underscore form; the number is the same either way, and a difference of only +`-` versus `_`, or a trailing `-r`, is not a finding (see +[tester-intake.md](tester-intake.md)). The same block records +`go_version: go1.26.0`; builds from the current tree are pinned to the toolchain +in [packaging/build-inputs.json](packaging/build-inputs.json) (`go1.25.8`), so +expect that value on a published artifact. + **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 +| package version (`apk list --installed`) | `0.6.0_alpha2-r0` | +| runtime version (`tollgate version`) | `v0.6.0-alpha2` | + +apk carries no hyphen in a version, so its control value spells the tag as +`0.6.0_alpha2`; the `-r0` release revision is what +[packaging/normalize-apk-version.sh](packaging/normalize-apk-version.sh) +appends (the recipe sets no `PKG_RELEASE` of its own). The runtime string is +the tag **verbatim** — hyphen kept, no `-r0`. 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 @@ -264,10 +287,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 +304,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 +342,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 +364,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 +373,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 @@ -460,6 +483,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 @@ -477,14 +506,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.