diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index 06d99757a8c..a6eeef5225a 100644 --- a/source/includes/options-mongo.yaml +++ b/source/includes/options-mongo.yaml @@ -73,6 +73,23 @@ description: | the CN or SAN of the {{instance}}'s ``--sslPEMKeyFile`` certificate. If the hostname does not match the CN/SAN, {{program}} will fail to connect. + + For `DNS seedlist connections `_, specify the connection protocol as + ``mongodb+srv``, followed by the DNS SRV hostname record and any + options. The ``authSource`` and ``replicaSet`` options, if included in + the connection string, will override any corresponding DNS-configured options + set in the TXT record. Use of the ``mongodb+srv:`` connection string implicitly + enables SSL (normally set with ``ssl=true``) for the client connection. The + SSL option can be turned off by setting ``ssl=false`` in the query string. + + Example: + + .. code-block:: none + + mongodb+srv://server.example.com/?connectionTimeout=3000ms + + .. versionadded:: 3.6 + optional: true replacement: instance: ":program:`mongod` or :program:`mongos`" diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 5f2285a2496..a69b91c8630 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -131,6 +131,92 @@ The components of this string are: mongodb://r1.example.net:27017,r2.example.net:27017/ +.. index:: connections; dns-seedlist +.. _connections-dns-seedlist: + + +DNS Seedlist Connection Format +------------------------------ + +.. versionadded:: 3.6 + +In addition to the standard connection format, MongoDB supports a DNS-constructed +seedlist. Using DNS to construct the available servers list allows more flexibility +of deployment and the ability to change the servers in rotation without reconfiguring +clients. + +In order to leverage the DNS seedlist, use a connection string prefix of ``mongodb+srv:`` +in place of the ``mongodb:`` string above. + +The ``+srv`` indicates to the mongo client that the hostname that follows corresponds to a +DNS SRV record. The client driver will then query the DNS for the record to determine the hosts that +are running the mongod instances. + +For example, to connect to a DNS-listed hostname: + + .. code-block:: none + + mongodb+srv://server.example.com/ + +A typical DNS configuration for the connection string above might look something +like this: + + .. code-block:: none + + Record TTL Class Priority Weight Port Target + _mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27317 mongodb1.example.com. + _mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27017 mongodb2.example.com. + +.. note:: + The hostnames returned in SRV records must share the same parent domain (in this example,``example.com``) + as the given hostname. + +The DNS seedlist connection string can also provide options as a query string, with a trailing "/?" as in +the standard connection string above. However, the ``+srv`` appended to the standard connection string +signals the driver to query the DNS for options as a configured TXT record. + +Only two options are available for configuration via a TXT record -- +``replicaSet`` and ``authSource``, and only one TXT record +is allowed per server. If multiple TXT records appear in the DNS and/or if the TXT record contains +an option other than ``replicaSet`` or ``authSource``, an error will be thrown by the +driver. + +An example of a properly configured TXT record: + + .. code-block:: none + + Record TTL Class Text + server.example.com. 86400 IN TXT "replicaSet=mySet&authSource=authDB" + +In this case, taking into account both +the DNS SRV records and the options retrieved from the TXT records, the parsed string will look like: + + .. code-block:: none + + mongodb://mongodb1.example.com:27317,mongodb2.example.com:27107/?replicaSet=mySet&authSource=authDB + +Options set in a TXT record can be overridden by passing in a query string with the URI. In the example below, +the query string has provided an override for the ``authSource`` option configured in the TXT record of the DNS +entry above. + + .. code-block:: none + + mongodb+srv://server.example.com/?connectTimeoutMS=300000&authSource=aDifferentAuthDB + +The rest of the option string will remain, and we can expect that the resulting URI +would look like this (after parse). + + .. code-block:: none + + mongodb://mongodb1.example.com:27317,mongodb2.example.com:27107/?connectTimeoutMS=300000&replicaSet=mySet&authSource=aDifferentAuthDB + +.. note:: + The ``mongodb+srv`` option will fail if there is no available DNS with records that correspond to the + hostname identified in the connection string. In addition, use of the ``+srv`` connection string modifier + sets the ``ssl`` option to ``true`` automatically for the connection. This can be overridden by explicitly setting + the ``ssl`` option to ``false`` with ``ssl=false`` in the query string. + + .. index:: connections; options .. _connections-connection-options: