doc/rbd: add mirroring troubleshooting info

Add a note to doc/rbd/rbd-mirroring.rst that directs the reader to set
both "site-a" and "site-b" to have the same pool names in the event that
rbd throws the error message "failed to import peer bootstrap token".

This information was reported to the Ceph upstream by Petr Tlapa in June
of 2025, and credit for its development goes to Petr.

Signed-off-by: Zac Dover <zac.dover@proton.me>

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index a5cce9fb09ea3f3ce3cf3f6763689ea2e36fc036..c2a69e8c1c983c8f6ff6c6a663ff33c89134d817 100644 (file)
--- a/doc/rados/operations/pools.rst
+++ b/doc/rados/operations/pools.rst
@@ -306,6 +306,8 @@ following forms:
     ceph auth del {user}
 
 
+.. _rados_renaming_a_pool:
+
 Renaming a Pool
 ===============
 

diff --git a/doc/rbd/rbd-mirroring.rst b/doc/rbd/rbd-mirroring.rst
index eb94a3716d548434579ca0392a6b7826c0b5494a..2f0ec7c622eef78c41fb5351a71ca03581f9d355 100644 (file)
--- a/doc/rbd/rbd-mirroring.rst
+++ b/doc/rbd/rbd-mirroring.rst
@@ -66,6 +66,9 @@ These pool configuration steps should be performed on both peer clusters. These
 procedures assume that both clusters, named "site-a" and "site-b", are accessible
 from a single host for clarity.
 
+The pool must have the same name on both peer clusters. See :ref:`Renaming a
+Pool<rados_renaming_a_pool>` for instructions on renaming pools.
+
 See the `rbd`_ manpage for additional details of how to connect to different
 Ceph clusters.