CFE-90: document remount, remount_methods and remount_timeout mount attributes

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,117 @@ 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 and
+the mount is reconciled if they differ.
+
+Only the options the promise names are enforced; kernel-added options (for
+example `vers=`, `rsize=`, `wsize=`, `timeo=`, `addr=`) and any other option
+the promise does not mention are ignored. The option list is resolved with the
+same "last wins" rule `mount -o` applies, so a later option overrides an
+earlier conflicting one — for example `{ "defaults", "ro" }` is a read-only
+mount and `{ "ro", "rw" }` is read-write. The `defaults` pseudo-option is
+expanded to its checkable parts (`rw`, `suid`, `dev`, `exec`, `async`) and is
+satisfied unless a conflicting negative such as `ro`, `nosuid` or `sync` is
+present.
+
+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.29.0
+
+#### remount_methods
+
+**Description:** Ordered list of mechanisms used to reconcile a mounted
+filesystem with the promise when [`remount`][storage#remount] is enabled. By
+default only the non-disruptive in-place `remount` is tried; add
+`unmount_mount` to allow the disruptive fallback.
+
+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" }`
+
+**Example:**
+
+```cf3
+body mount example
+{
+  remount => "true";
+
+  # opt in to the disruptive fallback: try an in-place remount, then
+  # unmount + mount (needed for options a remount cannot change, or a
+  # wrong mount source)
+  remount_methods => { "remount", "unmount_mount" };
+}
+```
+
+**History:** Introduced in 3.29.0
+
+#### remount_timeout
+
+**Description:** Timeout in seconds applied to each mechanism in
+[`remount_methods`][storage#remount_methods] 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.29.0
+
 ### volume
 
 **Type:** `body volume`