DOCSP-14283 ip addresses in split horizons v5.2 (#338)

* DOCSP-14283 Add warning, update tip

* Default bind behavior

* Update parameters

* method reference

* Staging review

* DOCSP-14283 ip addresses in split horizons

* Staging review

* Change tip to important

* Compatibility Notes

* Build errors in core/security-mongodb-configuration.txt

* Review feedback

* Staging updates

Author: Dave

source/core/replica-set-architectures.txt

@@ -185,7 +185,7 @@ interruptions, such as power failures and unexpected reboots.
 Hostnames
 ~~~~~~~~~
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 Replica Set Naming
 ------------------

source/core/security-mongodb-configuration.txt

@@ -13,9 +13,10 @@ IP Binding
 Overview
 --------
 
-.. include:: /includes/fact-default-bind-ip.rst
-   :start-after: begin-intro
-   :end-before: end-intro
+MongoDB binaries, :binary:`mongod` and :binary:`mongos`, bind to
+localhost by default. If the :setting:`net.ipv6` configuration file
+setting or the ``--ipv6`` command line option is set for the binary,
+the binary additionally binds to the localhost IPv6 address.
 
 Considerations
 --------------
@@ -27,9 +28,9 @@ Considerations
    has more than one network interface, bind MongoDB programs to the
    private or internal network interface.
 
-.. include:: /includes/fact-default-bind-ip.rst
-   :start-after: begin-override
-   :end-before: end-override
+If the :setting:`net.ipv6` configuration file setting or the ``--ipv6``
+command line option is set for the binary, the binary additionally
+binds to the localhost IPv6 address.
 
 .. include:: /includes/fact-bind-to-all-ips.rst
 

source/includes/considerations-deploying-replica-set.rst

@@ -9,7 +9,7 @@ See :doc:`/core/replica-set-architectures` for more information.
 Hostnames
 ~~~~~~~~~
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 IP Binding
 ~~~~~~~~~~

source/includes/fact-default-bind-ip.rst

@@ -1,48 +1,37 @@
-.. begin-intro
-
-Starting in MongoDB 3.6, MongoDB binaries, :binary:`~bin.mongod` and
-:binary:`~bin.mongos`, bind to localhost by default. If the
-:setting:`net.ipv6` configuration file setting or the ``--ipv6``
-command line option is set for the binary, the binary additionally binds
-to the localhost IPv6 address.
-
-.. end-intro
-
-Previously, starting from MongoDB 2.6, only the binaries from the
-official MongoDB RPM (Red Hat, CentOS, Fedora Linux, and derivatives)
-and DEB (Debian, Ubuntu, and derivatives) packages bind to localhost by
-default.
+.. include:: /includes/warning-bind-ip-security-considerations.rst
 
-When bound only to the localhost, these MongoDB 3.6 binaries can only
-accept connections from clients (including :binary:`~bin.mongosh` and
-other members of your deployment in replica sets and sharded clusters)
-that are running on the same machine. Remote clients cannot connect to
-the binaries bound only to localhost.
+MongoDB binaries, :binary:`~bin.mongod` and :binary:`~bin.mongos`, bind
+to localhost by default. If the :setting:`net.ipv6` configuration file
+setting or the ``--ipv6`` command line option is set for the binary,
+the binary additionally binds to the localhost IPv6 address.
 
-.. begin-override
+By default :binary:`~bin.mongod` and :binary:`~bin.mongos` that are
+bound to localhost only accept connections from clients that are
+running on the same computer. This binding behavior includes
+:binary:`~bin.mongosh` and other members of your replica set or sharded
+cluster. Remote clients cannot connect to binaries that are bound only
+to localhost.
 
-To override and bind to other ip addresses, you can use the
-:setting:`net.bindIp` configuration file setting or the
-``--bind_ip`` command-line option to specify a list of hostnames or ip
-addresses.
+To override the default binding and bind to other IP addresses, use the
+:setting:`net.bindIp` configuration file setting or the ``--bind_ip``
+command-line option to specify a list of hostnames or IP addresses.
 
-.. include:: /includes/warning-bind-ip-security-considerations.rst
+.. include:: /includes/warning-no-ip-addresses-in-split-horizons.rst
 
 For example, the following :binary:`~bin.mongod` instance binds to both
 the localhost and the hostname ``My-Example-Associated-Hostname``, which is
-associated with the ip address ``198.51.100.1``:
+associated with the IP address ``198.51.100.1``:
 
 .. code-block:: none
 
    mongod --bind_ip localhost,My-Example-Associated-Hostname
 
 In order to connect to this instance, remote clients must specify
-the hostname  or its associated ip address ``198.51.100.1``:
+the hostname  or its associated IP address ``198.51.100.1``:
 
 .. code-block:: none
 
    mongosh --host My-Example-Associated-Hostname
 
    mongosh --host 198.51.100.1
 
-.. end-override

source/includes/fact-split-horizon-binding.rst

@@ -0,0 +1,20 @@
+To configure cluster nodes for `split horizon DNS 
+<https://en.wikipedia.org/wiki/Split-horizon_DNS>`__, use host names
+instead of IP addresses. 
+
+Starting in MongoDB v5.0, :dbcommand:`replSetInitiate` and 
+:dbcommand:`replSetReconfig` reject configurations that use IP
+addresses instead of hostnames.
+
+Use :parameter:`disableSplitHorizonIPCheck` to modify nodes that
+cannot be updated to use host names. The parameter only applies to the
+configuration commands. 
+
+:binary:`mongod` and :binary:`mongos` do not rely on
+:parameter:`disableSplitHorizonIPCheck` for validation at startup.
+Legacy :binary:`mongod` and :binary:`mongos` instances that use IP
+addresses instead of host names will start after an upgrade. 
+
+Instances that are configured with IP addresses log a warning to use
+host names instead of IP addresses. 
+

source/includes/important-hostnames.rst

@@ -0,0 +1,12 @@
+.. important:: 
+
+   To avoid configuration updates due to IP address changes, use DNS
+   hostnames instead of IP addresses. It is particularly important to
+   use a DNS hostname instead of an IP address when configuring replica
+   set members or sharded cluster members.
+
+   Use hostnames instead of IP addresses to configure clusters across a
+   split network horizon. Starting in MongDB 5.0, nodes that are only
+   configured with an IP address will fail startup validation and will
+   not start.
+

source/includes/steps-convert-replica-set-add-new-shard.yaml

@@ -47,7 +47,7 @@ pre: |
 
      .. include:: /includes/fact-rs-initiate-once-only.rst
 
-  .. include:: /includes/tip-hostnames.rst
+  .. include:: /includes/important-hostnames.rst
 action:
   copyable: true
   language: javascript

source/includes/steps-convert-replica-set-shard-deploy-infrastructure.yaml

@@ -27,7 +27,7 @@ action:
 
          .. include:: /includes/fact-rs-initiate-once-only.rst
 
-      .. include:: /includes/tip-hostnames.rst
+      .. include:: /includes/important-hostnames.rst
     language: javascript
     code: |
           rs.initiate( {

source/includes/steps-deploy-replica-set-with-auth.yaml

@@ -79,7 +79,7 @@ action:
        mongod --keyFile <path-to-keyfile> --replSet <replicaSetName> --bind_ip localhost,<hostname(s)|ip address(es)>
     post: |
 
-       .. include:: /includes/tip-hostnames.rst
+       .. include:: /includes/important-hostnames.rst
 
        For more information on command-line options, see the
        :binary:`~bin.mongod` reference page.
@@ -116,7 +116,7 @@ action:
 
          .. include:: /includes/fact-rs-initiate-once-only.rst
 
-      .. include:: /includes/tip-hostnames.rst
+      .. include:: /includes/important-hostnames.rst
 
     language: javascript
     code: |

source/includes/steps-deploy-replica-set.yaml

@@ -107,7 +107,7 @@ pre: |
 
      .. include:: /includes/fact-rs-initiate-once-only.rst
 
-  .. include:: /includes/tip-hostnames.rst
+  .. include:: /includes/important-hostnames.rst
 action:
   language: javascript
   code: |

source/includes/tip-hostnames.rst

@@ -0,0 +1,7 @@
+.. warning::
+
+   Starting in MongDB 5.0, `split horizon DNS 
+   <https://en.wikipedia.org/wiki/Split-horizon_DNS>`__ nodes that are
+   only configured with an IP address fail startup validation and
+   report an error. See :parameter:`disableSplitHorizonIPCheck`.
+

source/includes/warning-no-ip-addresses-in-split-horizons.rst

@@ -44,7 +44,7 @@ replSetInitiate
            ]
       }
 
-   .. include:: /includes/tip-hostnames.rst
+   .. include:: /includes/important-hostnames.rst
 
 IP Binding
 ----------
@@ -70,14 +70,12 @@ the :method:`rs.initiate()` helper:
 
    rs.initiate(config)
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 Notice that omitting the port cause the host to use the default port
 of 27017. Notice also that you can specify other options in the config
 documents such as the ``arbiterOnly`` setting in this example.
 
-.. slave-ok, admin-only
-
 .. seealso::
 
    - :doc:`/reference/replica-configuration`

source/reference/command/replSetInitiate.txt

@@ -131,6 +131,7 @@ Mixed Version Replica Set
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. warning:: 
+
    .. include:: /includes/warning-mixed-version-rs-config.rst
 
 Availability
@@ -206,11 +207,11 @@ modify this timeout using the
 Replace ``<hostname>`` and ``<port>`` with those of the removed 
 member.
 
+.. include:: /includes/warning-no-ip-addresses-in-split-horizons.rst
+
 Member Priority and Votes
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. versionchanged:: 3.2
-
 - .. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
 
 - .. include:: /includes/fact-rs-non-voting-priority-restriction.rst

source/reference/command/replSetReconfig.txt

@@ -889,25 +889,17 @@ Core Options
 
    The TCP port on which the MongoDB instance listens for
    client connections.
-     
-   
-
 
 .. setting:: net.bindIp
 
    *Type*: string
 
    *Default*: localhost
 
-   
-   .. note::
-   
-      Starting in MongoDB 3.6, :binary:`~bin.mongos` or :binary:`~bin.mongod` bind to localhost
-      by default. See :ref:`3.6-bind-to-localhost`.
-   
    The hostnames and/or IP addresses and/or full Unix domain socket
-   paths on which :binary:`~bin.mongos` or :binary:`~bin.mongod` should listen for client connections. You
-   may attach :binary:`~bin.mongos` or :binary:`~bin.mongod` to any interface. To bind to multiple
+   paths on which :binary:`~bin.mongos` or :binary:`~bin.mongod` should
+   listen for client connections. You may attach :binary:`~bin.mongos`
+   or :binary:`~bin.mongod` to any interface. To bind to multiple
    addresses, enter a list of comma-separated values.
 
    .. example::
@@ -924,9 +916,11 @@ Core Options
    .. note::
 
       If specifying an IPv6 address *or* a hostname that resolves to an
-      IPv6 address to :setting:`net.bindIp`, you must start :binary:`~bin.mongos` or :binary:`~bin.mongod` with 
-      :setting:`net.ipv6 : true <net.ipv6>` to enable IPv6 support. Specifying an IPv6 address
-      to :setting:`net.bindIp` does not enable IPv6 support.
+      IPv6 address to :setting:`net.bindIp`, you must start
+      :binary:`~bin.mongos` or :binary:`~bin.mongod` with
+      :setting:`net.ipv6 : true <net.ipv6>` to enable IPv6 support.
+      Specifying an IPv6 address to :setting:`net.bindIp` does not
+      enable IPv6 support.
 
    If specifying a 
    `link-local IPv6 address <https://en.wikipedia.org/wiki/Link-local_address#IPv6>`_
@@ -938,7 +932,7 @@ Core Options
 
       ``localhost,fe80::a00:27ff:fee0:1fcf%enp0s3``
 
-   .. include:: /includes/tip-hostnames.rst
+   .. include:: /includes/important-hostnames.rst
 
    .. include:: /includes/warning-bind-ip-security-considerations.rst
 
@@ -961,8 +955,8 @@ Core Options
 
       - The command-line option ``--bind_ip`` overrides the configuration
         file setting :setting:`net.bindIp`.
-   
 
+   .. include:: /includes/fact-split-horizon-binding.rst
 
 .. setting:: net.bindIpAll
 

source/reference/configuration-options.txt

@@ -87,7 +87,7 @@ IP Binding
 
 .. include:: /includes/fact-default-bind-ip.rst
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 Behavior
 --------

source/reference/method/rs.add.txt

@@ -55,4 +55,4 @@ IP Binding
 
 .. include:: /includes/fact-default-bind-ip.rst
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst

source/reference/method/rs.addArb.txt

@@ -28,28 +28,19 @@ Description
       :widths: 20 20 80
 
       * - Parameter
-   
         - Type
-   
         - Description
 
       * - ``configuration``
-   
         - document
-   
         - Optional. A document that specifies :ref:`configuration
           <replica-set-configuration-document>` for the new replica set. If a
           configuration is not specified, MongoDB uses a default 
           replica set configuration.
-          
-          
-   
-
 
    The :method:`rs.initiate()` method provides a wrapper around the
    :dbcommand:`replSetInitiate` command.
 
-
 IP Binding
 ----------
 
@@ -58,10 +49,10 @@ IP Binding
 Replica Set Configuration
 -------------------------
 
-See :ref:`replica-set-configuration-document` for details of replica
-set configuration document.
+See :ref:`replica-set-configuration-document` for details of the
+replica set configuration document.
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 Example
 -------
@@ -84,7 +75,7 @@ instances and run :method:`rs.initiate()`.
 
    .. include:: /includes/fact-rs-initiate-once-only.rst
 
-.. include:: /includes/tip-hostnames.rst
+.. include:: /includes/important-hostnames.rst
 
 .. code-block:: javascript