diff --git a/.beans/ATFS-c2ny--repair-story-for-a-corrupted-atfsdata-volume.md b/.beans/ATFS-c2ny--repair-story-for-a-corrupted-atfsdata-volume.md index d50f571..5e0540e 100644 --- a/.beans/ATFS-c2ny--repair-story-for-a-corrupted-atfsdata-volume.md +++ b/.beans/ATFS-c2ny--repair-story-for-a-corrupted-atfsdata-volume.md @@ -96,6 +96,12 @@ force-format API. Left unstarted here rather than half-built. - [x] ~~gosd: force-format API for an explicitly named label~~ — not needed: gosd-psj0 made the unmountable case return ErrRefusedFormat, which `destructive` already answers +- [x] README: retract the flag's safety promise. The wipeEnvVar doc comment + was corrected when gosd-psj0 landed, but the README carried the same now- + false claim in operator-facing words — that leaving the flag set is + "harmless" because the drive is atfs's own from then on, which is exactly + the case that now also gets rebuilt. It says remove it after a successful + wipe, and why, until the flag question below is settled - [ ] Decide the flag question below: one flag with an honest name, or two - [ ] gosd (small): a distinct sentinel for the unmountable refusal, so atfs can tell it from foreign content without matching error text diff --git a/README.md b/README.md index 7429b45..55c2e40 100644 --- a/README.md +++ b/README.md @@ -296,9 +296,9 @@ AutoNAT *measures* which rung you're on (the `reachability changed` log lines); atfs also builds as flashable SD-card images via [gosd](https://github.com/jphastings/gosd), for the boards listed in `.tangled/workflows/image.yml` today (`rock-4se`, `nanopi-zero2`, `pi-zero-2w`) — adding another board is just adding its gosd board id there. -Flash the image, then edit `gosd.toml` on the card's small `atfs-boot` partition (it mounts like any other FAT32 volume) — it ships pre-populated with atfs's own `[env]` section (see `packaging/env.toml`), commented explanations included, so setting `ATFS_OWNER_DID` is normally the only edit a new card needs. Blobs and this node's identity live on a separate `GOSD-DATA` partition, mounted at the fixed `/data`; if that partition is missing or fails to mount, gosd falls back to an empty read-only volume instead, so a broken data partition fails loudly rather than silently losing writes. To expose the instance publicly, uncomment one of the commented-out `[ingress.*]` sections in `gosd.toml` — see "Serving" above. +Flash the image, then edit `gosd.toml` on the card's small `atfs-boot` partition (it mounts like any other FAT32 volume) — it ships pre-populated with atfs's own `[env]` section (see `packaging/env.toml`), commented explanations included, so setting `ATFS_OWNER_DID` is normally the only edit a new card needs. Blobs and this node's identity live on a separate `atfs-data` partition, mounted at the fixed `/data`; if that partition is missing or fails to mount, gosd falls back to an empty read-only volume instead, so a broken data partition fails loudly rather than silently losing writes. To expose the instance publicly, uncomment one of the commented-out `[ingress.*]` sections in `gosd.toml` — see "Serving" above. -Boards with onboard eMMC (NanoPi Zero2, Radxa Zero 3E) use it for storage automatically instead: atfsd formats and mounts a blank eMMC on first boot, then just mounts it on every boot after that. If the eMMC already holds something else, atfsd halts with instructions on the serial console rather than wiping it. Set `ATFS_DATA_DIR` to opt out and use the SD `/data` partition instead. To authorize wiping a non-blank eMMC, set `ATFS_FORMAT_DRIVES_IF_NOT_ATFS = "true"` in `gosd.toml`'s `[env]` — there's no shell to run `mkfs` by hand, so this is how an operator authorizes a wipe without needing a serial adapter to inspect the eMMC first. The name says exactly what it does: it only ever formats a drive atfs doesn't already recognize as its own, so a value left in `gosd.toml` after a successful wipe is harmless — the freshly wiped eMMC is atfs's own from then on, and never gets reformatted again. +Boards with onboard eMMC (NanoPi Zero2, Radxa Zero 3E) use it for storage automatically instead: atfsd formats and mounts a blank eMMC on first boot, then just mounts it on every boot after that. If the eMMC already holds something else, atfsd halts with instructions on the serial console rather than wiping it. Set `ATFS_DATA_DIR` to opt out and use the SD `/data` partition instead. To authorize wiping a non-blank eMMC, set `ATFS_FORMAT_DRIVES_IF_NOT_ATFS = "true"` in `gosd.toml`'s `[env]` — there's no shell to run `mkfs` by hand, so this is how an operator authorizes a wipe without needing a serial adapter to inspect the eMMC first. Remove it once the wipe has succeeded: it no longer covers only drives atfs doesn't recognize. gosd also refuses — rather than silently reformatting, which is the improvement — an eMMC that carries atfs's own label but has become unmountable, and atfs cannot tell the two refusals apart, so a value left in `gosd.toml` would authorize rebuilding atfs's own volume too, blobs and identity key included, with no further warning. There's no shell and no SSH on a gosd image: `atfsd` — the same binary as the container, built with gosd's `gosd` build tag — is the only binary `gosd-init` runs, restarted forever with backoff if it ever exits, and the serial console is the entire interface. That's where boot shows which release the card is running, this instance's peer ID, the `at://` URI for its config record, and whether uploads are enabled.