[PATCH docs v8 5/5] fix #7339: lvm: document discard option

[Lukas Sichert <l.sichert@proxmox.com>]

Document the new `on-volume-remove` property for LVM storage and its
initial `discard` action.

Also update the `saferemove` description to match the range-based
zero-out worker and avoid referring to the old command-specific
implementation details.

Signed-off-by: Lukas Sichert <l.sichert@proxmox.com>
Link: bugzilla.proxmox.com/show_bug.cgi?id=7339
---
 pve-storage-lvm.adoc | 34 +++++++++++++++++++++++++++-------
 1 file changed, 27 insertions(+), 7 deletions(-)

diff --git a/pve-storage-lvm.adoc b/pve-storage-lvm.adoc
index ba78663..3ddb26c 100644
--- a/pve-storage-lvm.adoc
+++ b/pve-storage-lvm.adoc
@@ -44,18 +44,39 @@ accessed by other LVs created later (which happen to be assigned the same
 physical extents). This is a costly operation, but may be required as a security
 measure in certain environments.
 +
-Storage devices that support the "write zeroes" operation will use `blkdiscard`
-to zero blocks. Otherwise, a fallback to `cstream` is performed.
+Storage devices that support the "write zeroes" operation use it to zero blocks.
+Otherwise, zeroes are written manually. The volume is processed range by range,
+according to `saferemove-stepsize`.
+
+`on-volume-remove`::
+
+Configure additional actions to run before an LV is removed.
++
+Set `discard=1` to issue discard (TRIM) requests for the LV's blocks before the
+LV is removed, so thin-provisioned backing storage, such as a SAN LUN, can
+reclaim space the LV occupied. This is called "Discard Removed Volumes"
+in the web UI. Discard is rejected if any backing device in the
+LV's volume group is detected as not supporting it.
++
+If wiping or discarding fails, the renamed `del-*` LV is kept and renamed to
+`failed-<N>-del-*`, so one can inspect it, retry cleanup manually, or remove
+it explicitly.
++
+If `saferemove` and `discard` are both enabled, the LV is processed range by
+range: one range is zeroed out and then discarded before continuing with the
+next range. This avoids allocating the whole LV with zeroes on thin-provisioned
+backing storage before the space can be reclaimed again.
 
 `saferemove-stepsize`::
 
-Wipe step size in MiB (`blkdiscard -p` parameter value), capped to the maximum
-step size supported by the underlying storage. Up to 32 MiB (maximum) by
-default.
+Wipe step size in MiB, capped to the maximum step size supported by the
+underlying storage. Up to 32 MiB (maximum) by default.
 
 `saferemove_throughput`::
 
-Wipe throughput (`cstream -t` parameter value), up to 10 MiB/s by default.
+Limits wipe throughput. If the backing storage supports the "write zeroes"
+operation, throughput is unlimited by default. Otherwise, manually written
+zeroes are limited to 10 MiB/s by default.
 
 `snapshot-as-volume-chain`::
 
@@ -150,4 +171,3 @@ See Also
 
 endif::wiki[]
 
-
-- 
2.47.3