posix: state directory outside the storage root is silently allowed (config trap) #821

Closed
opened 2026-09-29 17:41:56 +00:00 by Cordy · 2 comments
Owner

Split out of the #820 discussion (2026-09-29).

Design: on the posix driver, instance state is plain files under /data/.cairn/ and is meant to live with the data (deployment.md: "on the posix driver they are plain files under the data root you already persist"). That only holds because both defaults agree: storage.root = /data and every state path defaults to /data/.cairn/….

Trap: an operator mounts NFS at e.g. /mnt/nfs, sets storage.root: /mnt/nfs, and leaves the state paths at their defaults. State now lives on the container's /data, not on the share. If /data is not persisted, every restart wipes all state (settings, license, shares, holds, users, spaces, …), not just the #820 set. Nothing warns.

This predates #820 and is independent of it; s3 is unaffected.

Options (pick in review):

  1. Boot warning when storage.driver == "posix" and filepath.Dir(cfg.SettingsPath) is not inside storage.root (log + admin overview hint). Cheapest, no behaviour change.
  2. Derive the posix state-path defaults from storage.root (<root>/.cairn/…) when not explicitly set. Changes defaults, needs an upgrade note for anyone relying on the split.
  3. Docs only: a sharp-edge row in deployment.md.

Suggest 1 + 3. Acceptance: a test config with root outside /data logs the warning; the default config does not.

Split out of the #820 discussion (2026-09-29). **Design:** on the posix driver, instance state is plain files under `/data/.cairn/` and is meant to live *with the data* (deployment.md: "on the posix driver they are plain files under the data root you already persist"). That only holds because both defaults agree: `storage.root = /data` and every state path defaults to `/data/.cairn/…`. **Trap:** an operator mounts NFS at e.g. `/mnt/nfs`, sets `storage.root: /mnt/nfs`, and leaves the state paths at their defaults. State now lives on the container's `/data`, not on the share. If `/data` is not persisted, every restart wipes *all* state (settings, license, shares, holds, users, spaces, …), not just the #820 set. Nothing warns. This predates #820 and is independent of it; s3 is unaffected. **Options (pick in review):** 1. Boot warning when `storage.driver == "posix"` and `filepath.Dir(cfg.SettingsPath)` is not inside `storage.root` (log + admin overview hint). Cheapest, no behaviour change. 2. Derive the posix state-path defaults from `storage.root` (`<root>/.cairn/…`) when not explicitly set. Changes defaults, needs an upgrade note for anyone relying on the split. 3. Docs only: a sharp-edge row in deployment.md. Suggest 1 + 3. Acceptance: a test config with root outside `/data` logs the warning; the default config does not.
Author
Owner

suggestion seems like a fix that an unassuming operator might run into. 2 and 3 seem like the correct way to do. 2 to ensure it persists, 3 for when someone wants to specifically know about it and wants to specifically split it via deployment config and how to do that.

suggestion seems like a fix that an unassuming operator might run into. 2 and 3 seem like the correct way to do. 2 to ensure it persists, 3 for when someone wants to specifically know about it and wants to specifically split it via deployment config and how to do that.
Cordy closed this issue 2026-10-01 05:53:07 +00:00
Author
Owner

Shipped in v0.6.311 (PR #827) with options 2 + 3 after review: the state directory follows storage.root on posix (<root>/.cairn), storage.stateDir / CAIRN_STATE_DIR for a deliberate split, one-time adopt-or-refuse move from /data/.cairn, startup log line; TUS spool and peering staging stay local (cleanup: #826). Research summary (Vaultwarden, Gitea, Nextcloud, MinIO) in the PR. Live on both dogfoods: both log instance state directory dir=/data/.cairn from=default (both run the s3 driver), no other change. A posix (NFS) dogfood does not exist yet, so the moved-root path is verified by tests and a local binary run only.

Shipped in v0.6.311 (PR #827) with options 2 + 3 after review: the state directory follows `storage.root` on posix (`<root>/.cairn`), `storage.stateDir` / `CAIRN_STATE_DIR` for a deliberate split, one-time adopt-or-refuse move from `/data/.cairn`, startup log line; TUS spool and peering staging stay local (cleanup: #826). Research summary (Vaultwarden, Gitea, Nextcloud, MinIO) in the PR. Live on both dogfoods: both log `instance state directory dir=/data/.cairn from=default` (both run the s3 driver), no other change. A posix (NFS) dogfood does not exist yet, so the moved-root path is verified by tests and a local binary run only.
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#821
No description provided.