From: Stephan Müller <smueller@suse.com>
Date: Mon, 17 May 2021 09:33:45 +0000 (+0200)
Subject: doc: Improve RGW multisite documentation
X-Git-Tag: v17.1.0~1047^2
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=b9c61ecaee26551ad25b206eeeab97f012bf3068;p=ceph.git

doc: Improve RGW multisite documentation

Signed-off-by: Stephan Müller <smueller@suse.com>
---

diff --git a/doc/man/8/radosgw-admin.rst b/doc/man/8/radosgw-admin.rst
index 4c9f1660548d..de879b219cf3 100644
--- a/doc/man/8/radosgw-admin.rst
+++ b/doc/man/8/radosgw-admin.rst
@@ -380,25 +380,32 @@ which are as follows:
   List metadata info.
 
 :command:`mdlog list`
-  List metadata log.
+  List metadata log which is needed for multi-site deployments.
 
 :command:`mdlog trim`
-  Trim metadata log.
+  Trim metadata log manually instead of relying on RGWs integrated log sync.
+  Before trimming, compare the listings and make sure the last sync was
+  complete, otherwise it can reinitiate a sync.
 
 :command:`mdlog status`
   Read metadata log status.
 
 :command:`bilog list`
-  List bucket index log.
+  List bucket index log which is needed for multi-site deployments.
 
 :command:`bilog trim`
-  Trim bucket index log (use start-marker, end-marker).
+  Trim bucket index log (use start-marker, end-marker) manually instead
+  of relying on RGWs integrated log sync.
+  Before trimming, compare the listings and make sure the last sync was
+  complete, otherwise it can reinitiate a sync.
 
 :command:`datalog list`
-  List data log.
+  List data log which is needed for multi-site deployments.
 
 :command:`datalog trim`
-  Trim data log.
+  Trim data log manually instead of relying on RGWs integrated log sync.
+  Before trimming, compare the listings and make sure the last sync was
+  complete, otherwise it can reinitiate a sync.
 
 :command:`datalog status`
   Read data log status.
diff --git a/doc/radosgw/multisite.rst b/doc/radosgw/multisite.rst
index f9a8ee66732a..b216164d5d36 100644
--- a/doc/radosgw/multisite.rst
+++ b/doc/radosgw/multisite.rst
@@ -503,6 +503,17 @@ example:
           If the master zone is down, bucket operations executed on the
           secondary zone will fail, but object operations should succeed.
 
+Verification of an Object
+-------------------------
+
+By default, the objects are not verified again after the synchronization of an
+object was successful. To enable that, you can set :confval:`rgw_sync_obj_etag_verify`
+to ``true``. After enabling the optional objects that will be synchronized
+going forward, an additional MD5 checksum will verify that it is computed on
+the source and the destination. This is to ensure the integrity of the objects
+fetched from a remote server over HTTP including multisite sync. This option
+can decrease the performance of your RGW as more computation is needed.
+
 
 Maintenance
 ===========
@@ -532,6 +543,25 @@ Information about the replication status of a zone can be queried with::
                           incremental sync: 128/128 shards
                           data is caught up with source
 
+The output can differ depending on the sync status. The shards are described
+as two different types during sync:
+
+- **Behind shards** are shards that need a full data sync and shards needing
+  an incremental data sync because they are not up-to-date.
+
+- **Recovery shards** are shards that encountered an error during sync and marked
+  for retry. The error mostly occurs on minor issues like acquiring a lock on
+  a bucket. This will typically resolve itself.
+
+Check the logs
+--------------
+
+For multi-site only, you can check out the metadata log (``mdlog``),
+the bucket index log (``bilog``) and the data log (``datalog``).
+You can list them and also trim them which is not needed in most cases as
+:confval:`rgw_sync_log_trim_interval` is set to 20 minutes as default. If it isn't manually
+set to 0, you shouldn't have to trim it at any time as it could cause side effects otherwise.
+
 Changing the Metadata Master Zone
 ---------------------------------
 
@@ -714,6 +744,13 @@ Multi-Site Configuration Reference
 The following sections provide additional details and command-line
 usage for realms, periods, zone groups and zones.
 
+For more details on every available configuration option, please check out
+``src/common/options/rgw.yaml.in`` or go to the more comfortable :ref:`mgr-dashboard`
+configuration page (found under `Cluster`) where you can view and set all
+options easily. On the page, set the level to ``advanced`` and search for RGW,
+to see all basic and advanced configuration options with a short description.
+Expand the details of an option to reveal a longer description.
+
 Realms
 ------