fix(#1763): address argus review on PR #2430

- regenerate docs/tools/hivectl-cli.md for the new `subvol snapshot send` verb
- close the TOCTOU on the no-overwrite guard: File::options().create_new(true)
  (O_CREAT|O_EXCL) instead of exists()-then-create, so the guarantee is
  atomic against a concurrent request racing the same dest filename
- warn (not silently swallow) if cleaning up a partial export after a
  failed btrfs send itself fails, so a stuck garbage file masquerading
  as a completed export is visible in the log
This commit is contained in:
atlas 2026-07-14 19:16:49 +02:00 committed by mara
commit 60a253a2f6
2 changed files with 45 additions and 8 deletions

View file

@ -41,6 +41,7 @@ This document contains the help content for the `hivectl` command-line program.
* [`hivectl subvol snapshot`↴](#hivectl-subvol-snapshot)
* [`hivectl subvol snapshot create`↴](#hivectl-subvol-snapshot-create)
* [`hivectl subvol snapshot delete`↴](#hivectl-subvol-snapshot-delete)
* [`hivectl subvol snapshot send`↴](#hivectl-subvol-snapshot-send)
* [`hivectl open`↴](#hivectl-open)
* [`hivectl completions`↴](#hivectl-completions)
@ -581,6 +582,7 @@ Read-only snapshots of an agent's state subvolume — the first step of the (in-
* `create` — Create a read-only snapshot. Agent must already be a subvolume (`subvol upgrade` first). Prints the snapshot's host path
* `delete` — Delete a snapshot created by `subvol snapshot create`
* `send` — Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
@ -613,6 +615,24 @@ Delete a snapshot created by `subvol snapshot create`
## `hivectl subvol snapshot send`
Export a snapshot to a local file via `btrfs send` (the local-file half of inter-hive migration transport; the cross-hive `ssh ... btrfs receive` leg isn't wired up yet). Also useful standalone as a point-in-time backup: a full send with no `--parent` produces a self-contained archive of the snapshot
**Usage:** `hivectl subvol snapshot send [OPTIONS] --dest <DEST> <NAME> <LABEL>`
###### **Arguments:**
* `<NAME>` — Agent name the snapshot belongs to
* `<LABEL>` — Snapshot label passed to `subvol snapshot create --label`
###### **Options:**
* `--parent <PARENT>` — Optional parent snapshot label for an incremental send (`btrfs send -p`) — must be an existing, older snapshot of the same agent. Omit for a full send
* `--dest <DEST>` — Destination filename (not a path) under the migrate-staging dir. Refused if it already exists
## `hivectl open`
Print (and best-effort open in a browser) a hive web surface URL.