DOCSP-14283 BACKPORT (#369)

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: |