From 97706f7643fe51401874d88ed16063401269a95c Mon Sep 17 00:00:00 2001 From: skerschb Date: Fri, 17 Nov 2017 13:37:21 -0500 Subject: [PATCH 1/3] DOCS-10980 adding DNS seedlist --- source/includes/options-mongo.yaml | 10 ++++ source/reference/connection-string.txt | 72 ++++++++++++++++++++++++++ 2 files changed, 82 insertions(+) diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index 06d99757a8c..c0ff4e2b345 100644 --- a/source/includes/options-mongo.yaml +++ b/source/includes/options-mongo.yaml @@ -73,6 +73,16 @@ 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 for overriding DNS TXT configured options. For example: + + .. code-block:: none + + mongodb+srv://server.mongodb.com/?connectionTimeout=3000ms + + 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..19635c2101c 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -131,6 +131,78 @@ 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 +------------------------------ + +In addition to the standard connection format, MongoDB supports a DNS-constructed +seedlist. Using the 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.mongodb.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.mongodb.com. 86400 IN SRV 0 5 27317 mongodb1.mongodb.com. + _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27017 mongodb2.mongodb.com. + +The DNS seedlist connection string can also provide options with a trailing "/?" as in +the standard connection string above. However, the ``+srv`` string in the connection URI will +signal to the driver to query the DNS for options as configured TXT records. For example: + + .. code-block:: none + + Record TTL Class Text + server.mongodb.com. 86400 IN TXT "ssl=true&connectTimeoutMS=250000" + server.mongodb.com. 86400 IN TXT "readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1" + +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.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true& + connectTimeoutMS=250000&readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1 + +The TXT records can be overridden by passing in a query string with the uri. In the example below, +the only option that would be overridden in the text record would be the ``connectTimeoutMS``. + + .. code-block:: none + + mongodb+srv://server.mongodb.com/?connectTimeoutMS=300000 + +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.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true&connectTimeoutMS=300000&read + Preference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1 + +.. note:: + The ``mongodb+srv`` option will fail if there is no available DNS with records which correspond to the + hostname identified in the connect string. + + .. index:: connections; options .. _connections-connection-options: From 011bdf6fd24334ab591f0d75aaaaf058df2eed93 Mon Sep 17 00:00:00 2001 From: skerschb Date: Fri, 17 Nov 2017 15:23:08 -0500 Subject: [PATCH 2/3] DOCS-10980 document dns seedlist --- source/includes/options-mongo.yaml | 5 +++-- source/reference/connection-string.txt | 2 ++ 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index c0ff4e2b345..4d2c3009fb8 100644 --- a/source/includes/options-mongo.yaml +++ b/source/includes/options-mongo.yaml @@ -81,8 +81,9 @@ description: | .. code-block:: none mongodb+srv://server.mongodb.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 19635c2101c..5552b2307ae 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -138,6 +138,8 @@ The components of this string are: DNS Seedlist Connection Format ------------------------------ +.. versionadded:: 3.6 + In addition to the standard connection format, MongoDB supports a DNS-constructed seedlist. Using the DNS to construct the available servers list allows more flexibility of deployment and the ability to change the servers in rotation without reconfiguring From da90423c95f311cbc590cc4c1e76378261fa6b70 Mon Sep 17 00:00:00 2001 From: skerschb Date: Tue, 21 Nov 2017 11:46:22 -0500 Subject: [PATCH 3/3] DOCS-10980 incorporated changes to mongodb.com references updates per changes to the spec --- source/includes/options-mongo.yaml | 14 +++++-- source/reference/connection-string.txt | 54 ++++++++++++++++---------- 2 files changed, 43 insertions(+), 25 deletions(-) diff --git a/source/includes/options-mongo.yaml b/source/includes/options-mongo.yaml index 4d2c3009fb8..a6eeef5225a 100644 --- a/source/includes/options-mongo.yaml +++ b/source/includes/options-mongo.yaml @@ -74,13 +74,19 @@ description: | 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 for overriding DNS TXT configured options. For example: + 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.mongodb.com/?connectionTimeout=3000ms + mongodb+srv://server.example.com/?connectionTimeout=3000ms .. versionadded:: 3.6 diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 5552b2307ae..a69b91c8630 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -141,7 +141,7 @@ DNS Seedlist Connection Format .. versionadded:: 3.6 In addition to the standard connection format, MongoDB supports a DNS-constructed -seedlist. Using the DNS to construct the available servers list allows more flexibility +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. @@ -152,11 +152,11 @@ The ``+srv`` indicates to the mongo client that the hostname that follows corres 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: +For example, to connect to a DNS-listed hostname: .. code-block:: none - mongodb+srv://server.mongodb.com/ + mongodb+srv://server.example.com/ A typical DNS configuration for the connection string above might look something like this: @@ -164,45 +164,57 @@ like this: .. code-block:: none Record TTL Class Priority Weight Port Target - _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27317 mongodb1.mongodb.com. - _mongodb._tcp.server.mongodb.com. 86400 IN SRV 0 5 27017 mongodb2.mongodb.com. + _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. -The DNS seedlist connection string can also provide options with a trailing "/?" as in -the standard connection string above. However, the ``+srv`` string in the connection URI will -signal to the driver to query the DNS for options as configured TXT records. For example: +.. 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.mongodb.com. 86400 IN TXT "ssl=true&connectTimeoutMS=250000" - server.mongodb.com. 86400 IN TXT "readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1" - + 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.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true& - connectTimeoutMS=250000&readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1 + mongodb://mongodb1.example.com:27317,mongodb2.example.com:27107/?replicaSet=mySet&authSource=authDB -The TXT records can be overridden by passing in a query string with the uri. In the example below, -the only option that would be overridden in the text record would be the ``connectTimeoutMS``. +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.mongodb.com/?connectTimeoutMS=300000 + 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 +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.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true&connectTimeoutMS=300000&read - Preference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1 + 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 which correspond to the - hostname identified in the connect string. + 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