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>
(cherry picked from commit 83345afa898ebc2daf9a18d725447aa0c738af57)

diff --git a/doc/rados/operations/pools.rst b/doc/rados/operations/pools.rst
index 4bbb458950897c024430f167daf99da6e27784ab..c2a581acfacc6c89570d48964b7be0fd85041a2b 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.