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 7ee51c1eff623c8bd2b6f4ed355da46234099d1a..91f77e2535785fc7263b00919d11187d9fa4f851 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 74a2a364e8d0d961e9da4b17aeb55c2b08a78680..4d6924db843928c7a4d7e711b79266a153dc246e 100644 (file)
--- a/doc/rbd/rbd-mirroring.rst
+++ b/doc/rbd/rbd-mirroring.rst
@@ -63,6 +63,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.