DOCSP-41323 made behavior page (#365)

Author: sonderdonk-mdb

snooty.toml

@@ -21,7 +21,8 @@ toc_landing_pages = ["/quickstart",
                      "/release-notes/release-notes",
                      "/faq",
                      "/reference/collection-level-filtering",
-                     "/reference/verification"
+                     "/reference/verification",
+                     "/reference/mongosync"
                     ]
 
 [constants]

source/about-mongosync.txt

@@ -12,9 +12,9 @@ About ``mongosync``
    :depth: 2
    :class: singlecol
 
-The ``mongosync`` binary is the primary process used in {+c2c-product-name+}. 
-``mongosync`` migrates data from a source cluster to a destination cluster and 
-keeps the clusters in continuous sync until you 
+The :ref:`mongosync <c2c-mongosync>` binary is the primary process used in 
+{+c2c-product-name+}. ``mongosync`` migrates data from a source cluster to a 
+destination cluster and keeps the clusters in continuous sync until you 
 :ref:`finalize <c2c-about-finalizing>` the sync. 
 
 You can use ``mongosync`` to create 
@@ -162,5 +162,6 @@ Learn More
 
 To learn more about ``mongosync``, see:
 
-- :ref:`mongosync <c2c-mongosync>`
-- :ref:`mongosync States <c2c-states>`
+- :ref:`c2c-mongosync`
+- :ref:`mongosync Behavior <c2c-mongosync-behavior>`
+- :ref:`c2c-limitations`

source/includes/fact-connection-strings-atlas.rst

@@ -1,5 +1,5 @@
-:ref:`mongosync <c2c-mongosync>` uses a :ref:`MongoDB URI
-connection string <mongodb-uri>` to connect clusters:
+``mongosync`` uses a :ref:`MongoDB URI
+connection string <mongodb-uri>` to connect Atlas clusters:
 
 - The SRV connection scheme has the form:
 

source/includes/fact-connection-strings-onprem.rst

@@ -0,0 +1,27 @@
+``mongosync`` uses a :ref:`MongoDB URI
+connection string <mongodb-uri>` to connect self-managed clusters:
+
+- The SRV connection scheme has the form:
+
+  .. code-block:: none
+
+     mongodb+srv://[username:password@][host.domain.TLD][/defaultauthdb][?options]
+
+- The standard URI connection scheme has the form:
+
+  .. code-block:: none
+  
+     mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
+
+Specify the hostnames of the :program:`mongod` instances the same way
+that they are listed in your replica set configuration.
+
+For :ref:`sharded clusters <sharding-sharded-cluster>`, specify the
+hostnames of the :program:`mongos` instances instead of the
+:program:`mongod` instances.
+
+.. note::
+
+   ``mongosync`` does not require the :urioption:`replicaSet` option.
+
+.. include:: /includes/read-preference-connection-string.rst

source/includes/fact-connection-strings.rst

@@ -1,4 +1,4 @@
-:ref:`mongosync <c2c-mongosync>` uses a :ref:`MongoDB URI
+``mongosync`` uses a :ref:`MongoDB URI
 connection string <mongodb-uri>` to connect clusters:
 
 - The SRV connection scheme has the form:

source/index.txt

@@ -20,13 +20,13 @@ and data residency compliance.
 In addition to continuous data synchronization, ``mongosync`` can also
 facilitate a one time data migration between clusters. 
 
-For an overview of ``mongosync``, see :ref:`about-mongosync`.
+For an overview of the ``mongosync`` process, see :ref:`about-mongosync`.
 
 To get started with ``mongosync``, refer to the :ref:`Quick Start Guide
 <c2c-quickstart>`. For more detailed information, refer to the
 :ref:`c2c-install` or :ref:`c2c-connecting` page that best fits your
 situation. See also the :ref:`c2c-limitations` page for important
-restrictions.
+restrictions and the :ref:`c2c-mongosync-behavior` page for behavior information.
 
 .. include:: /includes/limitations-warning
 

source/quickstart.txt

@@ -21,8 +21,7 @@ Overview
 
 {+c2c-full-product-name+} connects MongoDB clusters and provides a way
 to synchronize data between them. The tool that makes the connection is
-:ref:`c2c-mongosync`. This page provides a short introduction to help
-you get started with {+c2c-product-name+}. For more details, please see
+:ref:`mongosync <c2c-mongosync>`. For more details, please see
 the rest of the {+c2c-product-name+} documentation.
 
 ``mongosync`` syncs data between two clusters. 
@@ -117,7 +116,7 @@ Setup
 
    .. step:: Download and install ``mongosync``
 
-      :ref:`c2c-mongosync` is the tool that connects the source and
+      ``mongosync`` is the tool that connects the source and
       destination clusters. You can host ``mongosync`` on its own
       hardware, ``mongosync`` does not have to run on the hardware that
       hosts your MongodDB clusters.
@@ -169,7 +168,7 @@ Connect the Clusters
 
    .. step:: Initialize mongosync
 
-      :program:`mongosync` must create an initial connection to the source and
+      ``mongosync`` must create an initial connection to the source and
       destination clusters before it can start to sync data. To create the initial
       connection, issue the following command with your connection
       strings on a single line (the command is
@@ -284,7 +283,7 @@ Synchronization Notes
 
 - The default port for the HTTP API is ``27182``.  Use the ``--port``
   option with ``mongosync`` to :ref:`configure another port
-  <c2c-mongosync>`
+  <c2c-config>`.
 
 - ``mongosync`` can swap the source and destination clusters to enable
   :ref:`reverse synchronization <c2c-api-reverse>`.  

source/reference.txt

@@ -3,11 +3,11 @@ Reference
 =========
 
 :ref:`c2c-mongosync`
-   The options and behavior in {+c2c-product-name+}.
+   Overview of ``mongosync`` binary.
 
 :ref:`c2c-config`
-   Configure :program:`mongosync` instances at startup using a
-   configuration file.
+   Configure ``mongosync`` instances at startup 
+   using a configuration file.
 
 :ref:`c2c-api`
    API endpoints to interact with ``mongosync``. 
@@ -50,7 +50,7 @@ Reference
 
 .. toctree::
    :titlesonly:
-
+   
    /reference/mongosync
    /reference/configuration
    /reference/api

source/reference/configuration.txt

@@ -12,16 +12,16 @@ Configuration
    :depth: 2
    :class: singlecol
 
-You can configure :program:`mongosync` instances at startup using a
-configuration file.  The configuration file contains settings that are
+You can configure :ref:`mongosync <c2c-mongosync>` instances at startup 
+using a configuration file.  The configuration file contains settings that are
 the equivalent of ``mongosync`` command line options.
 
 Configuration File
 ==================
 
-Most :program:`mongosync` command line options can be written to a YAML
-file. The configuration file specifies values for each setting using
-YAML format. 
+You can write most ``mongosync`` 
+:ref:`command line options <c2c-cli-options>` to a YAML file. The 
+configuration file specifies values for each setting using YAML format. 
 
 For example:
 

source/reference/disaster-recovery.txt

@@ -21,9 +21,9 @@ version of the source cluster. If the source cluster fails or becomes otherwise
 unavailable, the destination cluster can replace it as the primary cluster if 
 your application can tolerate potentially stale data.
 
-:program:`mongosync` temporarily alters some collection characteristics
-during synchronization. The original values are restored during the
-:ref:`commit process <c2c-api-commit>`. If synchronization ends prematurely,
+:ref:`mongosync <c2c-mongosync>` temporarily alters some collection 
+characteristics during synchronization. The original values are restored during 
+the :ref:`commit process <c2c-api-commit>`. If synchronization ends prematurely,
 you must manually reset these collection characteristics on the destination
 cluster before you can use it as the primary cluster.
 
@@ -77,8 +77,8 @@ the following changes that mimic the sync finalization process of the
 Unique Indexes
 --------------
 
-:program:`mongosync` replicates writes in parallel, which can cause
-transient uniqueness violations on the destination cluster. To avoid
+``mongosync`` replicates writes in parallel, which 
+can cause transient uniqueness violations on the destination cluster. To avoid
 these errors, unique indexes are replicated as non-unique. If
 synchronization ends early, manually resolve any uniqueness violations
 and convert any non-unique indexes that should be unique into unique indexes.

source/reference/logging.txt

@@ -6,9 +6,9 @@ Logging
 
 .. default-domain:: mongodb
 
-:program:`mongosync` maintains a running log of events, including entries
-such as the copying collections and indexes, change stream events, and API 
-calls. 
+:ref:`mongosync <c2c-mongosync>` maintains a running log of events, 
+including entries such as the copying collections and indexes, change stream 
+events, and API calls. 
 
 .. contents:: On this page
    :local:
@@ -20,7 +20,8 @@ calls.
 Destination
 -----------
 
-:program:`mongosync` can write log messages to stdout or to file.
+``mongosync`` can write log messages to stdout or 
+to file.
 
 Standard Output
 ^^^^^^^^^^^^^^^
@@ -72,18 +73,19 @@ logs that ``mongosync`` has rotated.
 Verbosity
 ---------
 
-:program:`mongosync` supports user-defined verbosity to increase or decrease
-the level of log messages ``mongosync`` outputs.
+``mongosync`` supports user-defined verbosity to 
+increase or decrease the level of log messages ``mongosync`` outputs.
 
 The verbosity level can be set using the :option:`--verbosity` option from the
 command-line or the :setting:`verbosity` setting in the configuration file.
 
 Format
 ------
 
-:program:`mongosync` outputs log messages in structured JSON format.
-Each log message is a document that holds the key-value pairs for that entry.
-The keys label the log message elements, the values are the reported events.
+``mongosync`` outputs log messages in structured 
+JSON format. Each log message is a document that holds the key-value pairs for 
+that entry. The keys label the log message elements, the values are the 
+reported events.
 
 For example: