Merge remote-tracking branch 'refs/remotes/upstream/master' into DOCSP-22726-c2c-install-v2

Author: mungitoperrito

source/faq.txt

@@ -10,3 +10,82 @@ Frequently Asked Questions
 This page provides answers to some frequently asked questions we have
 encountered. If you have additional questions please contact MongoDB
 Support.
+
+Does ``mongosync`` have to use the same operating system as MongoDB Enterprise Server? 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When ``mongosync`` runs on its own hardware, it does not have to use
+the same operation system (OS) as the source or destination clusters it
+is connecting.
+
+Should I increase the size of the oplog in the source cluster?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you anticipate synchronizing a large data set, or if you plan to
+pause synchronization for an extended period of time, increase the size
+of the replica set :term:`oplog` in the source cluster.
+
+The ``oplog`` in the source cluster must be large enough to track
+events that happen during the time it takes to complete the initial
+sync to the destination cluster.
+
+The proper ``oplog`` size depends on system hardware, network speed,
+and other factors including system workload. However, assuming network
+transfer speeds of 30-50GB per hour, a rough formula to estimate the
+required ``oplog`` size is:
+
+.. code-block:: shell
+
+   minimumRetentionHours = dataSizeInGB / 30
+
+To learn more about how to increase the size of the ``oplog``, see:
+:ref:`tutorial-change-oplog-size`. 
+
+Which connection string options does ``mongosync`` allow?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``mongosync`` requires :ref:`readConcern: "majority" <read-concern>`
+and :ref:`writeConcern: "majority" <write-concern>`. ``mongosync`` 
+overwrites any other ``readConcern`` or ``writeConcern`` and uses
+``"majority"`` instead.
+
+``monogosync`` accepts all other :ref:`connection string options
+<mongodb-uri>`.
+
+
+Which security and authentication options are supported?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``mongosync`` uses a standard MongoDB :ref:`connection string
+<mongodb-uri>` to connect to the source and destination clusters. 
+
+:ref:`LDAP <security-auth-ldap>` and :ref:`X509
+<authentication-mechanism-x509>` are supported. For available
+authentication options, see :ref:`authentication`.
+
+
+Can I configure ``mongosync`` for high availability?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There is no automatic failover built into ``mongosync``. However you
+can write a script or use your operating system's process managers,
+``systemd`` for example, to restart the ``mongosync`` process. 
+
+The ``mongosync`` binary is stateless. The metadata for restarting is
+stored on the destination cluster.
+
+A ``mongosync`` operation can be resumed if ``mongosync`` becomes
+unavailable during synchronization. When ``mongosync`` becomes
+available again, restart the ``mongosync`` process with the same
+parameters. ``mongosync`` resumes the operation from where it stopped
+when ``mongosync`` became unavailable.
+
+Can the source or destination be a replica set with arbiters? 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Yes, the replica set can have arbiters. The source replica set must
+have more than 2 non-arbiter nodes and you must sync from a non-arbiter
+node. Use the source cluster's connection string to specify a
+:ref:`read preference <mongodb-uri>` for a non-arbiter, data-bearing
+node. 
+

source/reference/mongosync.txt

@@ -1,9 +1,166 @@
 .. _c2c-mongosync:
 
+.. default-domain:: mongodb
+
+.. program:: mongosync
+
 =============
 ``mongosync``
 =============
 
-.. default-domain:: mongodb
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Description
+-----------
+
+The ``mongosync`` binary is the primary process used in Cluster-to-Cluster Sync.
+It migrates data from one cluster to another and can keep the clusters
+in continuous sync.
+
+This document provides a complete overview of all command-line options.
+
+Options
+-------
+
+Global Options
+~~~~~~~~~~~~~~
+
+.. option:: --cluster0 <URI>
+
+   Sets the :ref:`connection URI <mongodb-uri>` for the first cluster.
+   The first cluster can serve as either the source cluster or the destination 
+   cluster in the sync process.
+
+   .. note::
+ 
+      The cluster must use MongoDB 6.0 or later.
+
+
+   For more information on connecting ``mongosync``, see
+   :ref:`Connections <c2c-conn-top-level>`.
+
+
+.. option:: --cluster1 <URI>
+
+   Sets the :ref:`connection URI <mongodb-uri>` for the second cluster.
+   The second cluster can serve as either the source cluster or the destination 
+   cluster in the sync process.
+
+   .. note::
+
+      The cluster must use MongoDB 6.0 or later.
+
+
+   For more information on connecting ``mongosync``, see
+   :ref:`Connections <c2c-conn-top-level>`.
+
+
+.. option:: --verbosity <level>
+
+   *Default*: ``INFO``
+
+   Sets the verbosity level to use in log messages.  Cluster-to-Cluster Sync logs
+   all messages at the specified level as well as any messages at less severe levels.
+
+   The ``--verbosity`` option supports the following values:
+
+   - ``TRACE``
+   - ``DEBUG``
+   - ``INFO``
+   - ``WARN``
+   - ``ERROR``
+   - ``FATAL``
+   - ``PANIC``
+
+
+.. option:: --logPath <DIR>
+
+   Sets the path to the log directory. Cluster-to-Cluster Sync writes logs to
+   files in this directory.
+
+
+.. option:: --port
+
+   *Default*: ``27182``
+
+   Sets the port used by the HTTP server for the Cluster-to-Cluster Sync REST API.
+
+
+.. option:: --id <ID>
+
+   Sets an identifier for the ``mongosync`` instance.
+
+   Use this option when running multiple instances of ``mongosync`` on a sharded
+   cluster, to synchronize the shards individually.  The ``--id`` option must
+   correspond to the shard ID of the shard it
+   syncs.  To find the shard ID, use the :dbcommand:`listShards` command.
+
+.. option:: --config <filename>
+
+   Sets the path to the configuration file.
+
+   For more information, see :ref:`c2c-mongosync-config`.
+
+
+.. option:: --version, -v
+
+   Prints ``mongosync`` version information to stdout.
+
+
+.. option:: --help, h
+
+   Prints usage information to stdout.
+
+
+Behavior
+--------
+
+.. _c2c-mongosync-config:
+
+Configuration File
+~~~~~~~~~~~~~~~~~~
+
+Options for ``mongosync`` can be set in a YAML configuration file, specified
+using the :option:`--config` option.  For example:
+
+.. code-block:: yaml
+
+   # Cluster Configuration
+   cluster0: "mongodb://192.0.2.10:27017,192.0.2.11:27017,192.0.2.12:27017"
+   cluster1: "mongodb://192.0.2.20:27017,192.0.2.21:27017,192.0.2.22:27017"
+
+
+Examples
+--------
+
+#. Deploy a source and a destination cluster.
+
+#. Initialize Cluster-to-Cluster Sync:
+
+   .. code-block:: bash
+
+      mongosync \
+           --cluster0 'mongodb://192.0.2.10:27017,192.0.2.11:27017,192.0.2.12:27017' \
+           --cluster1 'mongodb://192.0.2.20:27017,192.0.2.21:27017,192.0.2.22:27017'
+
+   Use the appropriate connection strings for the :option:`--cluster0` and
+   :option:`--cluster1` options so that they can connect to your replica sets.
+
+#. To start the synchronization process, use a REST client such as cURL to send
+   the ``start`` command to ``mongosync``:
+
+   .. code-block:: bash
+
+      curl localhost:27182/api/v1/start -X POST \
+            --data '{ "source": "cluster0", "destination": "cluster1" }'
+
+   Example Output:
+
+   .. code-block:: json
+      :copyable: false
 
-Migrate data between clusters using ``mongosync``.
+      { "success": true }