From dea179748c4d836774fc5b30c9d11cf4b8ed13ee Mon Sep 17 00:00:00 2001
From: Tahlia Richardson <3069029+tahliar@users.noreply.github.com>
Date: Fri, 21 Jun 2024 10:47:38 +1000
Subject: [PATCH] Improve persistent device name warning (#393)

bsc#1226367
jsc#DOCTEAM-1466
---
 xml/ha_cluster_md.xml |  6 +-----
 xml/phrases-decl.ent  | 11 +++++++++++
 2 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/xml/ha_cluster_md.xml b/xml/ha_cluster_md.xml
index 8fc9e67f..cb60e323 100644
--- a/xml/ha_cluster_md.xml
+++ b/xml/ha_cluster_md.xml
@@ -77,11 +77,7 @@
    </listitem>
   </itemizedlist>
 
-  <para>
-   For better stability, use persistent device names
-   such as <literal>/dev/disk/by-id/<replaceable>DEVICE_ID</replaceable></literal>
-   instead of <literal>/dev/sd<replaceable>X</replaceable></literal> names.
-  </para>
+  &warning-persistent-shared-storage-name;
 
   <procedure>
    <step>
diff --git a/xml/phrases-decl.ent b/xml/phrases-decl.ent
index 7d8e09e7..c70d25da 100644
--- a/xml/phrases-decl.ent
+++ b/xml/phrases-decl.ent
@@ -652,3 +652,14 @@
      <systemitem class="resource">softdog</systemitem> can be used as kernel
      watchdog module.</para>
    </important>'>
+
+<!ENTITY warning-persistent-shared-storage-name '<warning xmlns="http://docbook.org/ns/docbook">
+  <title>Always use persistent device names</title>
+  <para>
+    Always use cluster-wide persistent device names, such as
+    <literal>/dev/disk/by-id/<replaceable>DEVICE_ID</replaceable></literal>.
+    Unstable device names like <literal>/dev/sd<replaceable>X</replaceable></literal> or
+    <literal>/dev/dm-<replaceable>X</replaceable></literal> might become mismatched on different
+    nodes, causing major problems across the cluster.
+  </para>
+</warning>'>