From 9142cb79e74bfae403e4aff04e8ce96769ed1084 Mon Sep 17 00:00:00 2001
From: Nick Anderson <nick@cmdln.org>
Date: Thu, 9 Jul 2026 00:36:52 -0500
Subject: [PATCH] CFE-90: document remount, remount_methods and remount_timeout
 mount attributes

Document the new opt-in reconciliation of a live mount's options, and clarify
that mount_options are only enforced against a running mount when remount is
enabled (they otherwise affect just the initial mount and, with edit_fstab,
the fstab entry).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../reference/promise-types/storage.markdown  | 106 ++++++++++++++++++
 1 file changed, 106 insertions(+)

diff --git a/content/reference/promise-types/storage.markdown b/content/reference/promise-types/storage.markdown
index bc018eceb..c01628dbd 100644
--- a/content/reference/promise-types/storage.markdown
+++ b/content/reference/promise-types/storage.markdown
@@ -142,6 +142,12 @@ body mount example
 This list is concatenated in a form appropriate for the filesystem. The
 options must be legal options for the system mount commands.
 
+The options are always applied to the initial mount and, when
+[`edit_fstab`][storage#edit_fstab] is enabled, written to the file system
+table. By default they are **not** enforced on a filesystem that is already
+mounted with different options. To also reconcile the options of a running
+mount, enable [`remount`][storage#remount].
+
 **Type:** `slist`
 
 **Allowed input range:** (arbitrary string)
@@ -172,6 +178,106 @@ body mount example
 }
 ```
 
+#### remount
+
+**Description:** true/false reconcile the options of an already-mounted
+filesystem when they differ from the promise.
+
+By default [`mount_options`][storage#mount_options] only affect the initial
+mount and the file system table entry; a filesystem that is already mounted
+with different options is left unchanged. When `remount` is enabled, the
+promised options are compared against the running (kernel-resolved) mount
+using subset matching — all promised options must be present in the actual
+set, while kernel-added options (for example `vers=`, `rsize=`, `wsize=`,
+`timeo=`, `addr=`) are ignored — and the mount is reconciled if they differ.
+Contradictory options (for example `noatime` vs `relatime`, `ro` vs `rw`)
+count as a difference.
+
+The mechanism used to reconcile is controlled by
+[`remount_methods`][storage#remount_methods]. When
+[`edit_fstab`][storage#edit_fstab] is also enabled, the file system table is
+updated after the live mount is reconciled.
+
+**Type:** [`boolean`][boolean]
+
+**Default value:** false
+
+**Example:**
+
+```cf3
+body mount example
+{
+  remount => "true";
+}
+```
+
+**History:** Introduced in 3.28.0
+
+#### remount_methods
+
+**Description:** Ordered list of mechanisms used to reconcile a mounted
+filesystem with the promise when [`remount`][storage#remount] is enabled.
+
+Each method is attempted in order and the result is verified against the
+running mount; the first mechanism that satisfies the promise wins (the
+kernel reports success from a remount even when it silently ignores
+unsupported options, so the resulting state is re-read rather than trusting
+the command's exit status).
+
+- `remount` — remount in place (`mount -o remount,...`). Applies generic
+  mount flags such as `ro`/`rw` and the `atime` options, but cannot change
+  NFS-negotiated options such as `vers=`, `proto=` or `sec=`.
+- `unmount_mount` — unmount and mount again with the promised options.
+  Applies any option change and can also correct a wrong mount source, but is
+  disruptive and fails if the filesystem is busy.
+
+**Type:** `slist`
+
+**Allowed input range:**
+
+- `remount`
+- `unmount_mount`
+
+**Default value:** `{ "remount", "unmount_mount" }`
+
+**Example:**
+
+```cf3
+body mount example
+{
+  remount => "true";
+
+  # try an in-place remount, fall back to unmount + mount
+  remount_methods => { "remount", "unmount_mount" };
+}
+```
+
+**History:** Introduced in 3.28.0
+
+#### remount_timeout
+
+**Description:** Timeout in seconds bounding the reconciliation of a busy or
+unreachable filesystem when [`remount`][storage#remount] is enabled.
+
+Guards the potentially blocking unmount/mount path against a hung or
+unreachable server.
+
+**Type:** `int`
+
+**Default value:** 60 (the RPC timeout)
+
+**Example:**
+
+```cf3
+body mount example
+{
+  remount => "true";
+  remount_timeout => "30";
+}
+```
+
+**History:** Introduced in 3.28.0
+
 ### volume
 
 **Type:** `body volume`