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 2c9cc1b66bf82db454d59958bb00d3d2e9dbdb34..26a6e9412bd374418515fd78abccbc377d03cc76 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.