From f38ec19210c32494a82d531aadc5f2718916a0e1 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Dec 2023 12:22:01 -0500 Subject: [PATCH 01/11] DOCSP-34709: Connection Troubleshooting Shared Content --- source/connection-troubleshooting.txt | 248 ++++++++++---------------- 1 file changed, 95 insertions(+), 153 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index a1e70717..abd20eff 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -10,198 +10,140 @@ Connection Troubleshooting :depth: 2 :class: singlecol -This page offers potential solutions to issues you might encounter when -using the {+driver-long+} to connect to a MongoDB deployment. +.. sharedinclude:: dbx/connection-troubleshooting.rst -.. note:: + .. replacement:: non-connection-issue-callout - This page only addresses connection issues. If you encounter any other issues - with MongoDB or the driver, visit the following resources: + .. note:: - - :ref:`rust-operation-errors` for recommendations on how to handle - different error types that the driver raises during operations - - :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the driver, and - finding more resources - - `MongoDB Community Forums `__ for - questions, discussions, or general technical support - - .. - TODO: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} - -Server Connection Error -~~~~~~~~~~~~~~~~~~~~~~~ - -When you attempt to connect to a server, the {+driver-short+} might generate an -error message. This message might look similar to the following message indicating -that the driver cannot connect to a server on the specified hostname or port: - -.. code-block:: none - :copyable: false - - Error: Error { kind: ServerSelection { message: "Server selection timeout: - No available servers. Topology: { Type: Unknown, Servers: [ { Address: - 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused - (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: - None } - -The following sections describe methods that might help resolve the issue. - -.. _rust-troubleshooting-connection-string-port: - -Check Connection String ------------------------ - -Verify that the hostname and port number in the connection string are both -accurate. In the sample error message, the hostname is ``127.0.0.1`` and the -port is ``27017``. The default port value for a MongoDB instance is -``27017``, but you can configure MongoDB to communicate on another port. + This page only addresses connection issues. If you encounter any other issues + with MongoDB or the driver, visit the following resources: -.. _rust-troubleshooting-connection-firewall: - -Configure Firewall ------------------- - -Assuming that your MongoDB deployment uses the default port, verify that port -``27017`` is open in your firewall. If your deployment uses a different port, -verify the correct port is open in your firewall. - -.. warning:: - - Do not open a port in your firewall unless you are sure that it is the port - used by your MongoDB instance. - -.. _rust-troubleshooting-connection-number-connections: + - :ref:`rust-operation-errors` for recommendations on how to handle + different error types that the driver raises during operations + - :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the driver, and + finding more resources + - `MongoDB Community Forums `__ for + questions, discussions, or general technical support + + .. + TODO: + - The :ref:`Frequently Asked Questions (FAQ) ` for the + {+driver-short+} + + + .. replacement:: server-selection-timeout-error + + .. code-block:: none + :copyable: false + + Error: Error { kind: ServerSelection { message: "Server selection timeout: + No available servers. Topology: { Type: Unknown, Servers: [ { Address: + 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused + (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: + None } + + .. replacement:: check-connection-string-anchor -Check the Number of Connections -------------------------------- + .. _rust-troubleshooting-connection-string-port: -Each ``Client`` instance supports a maximum number of concurrent open -connections in its connection pool. The configuration parameter ``maxPoolSize`` -defines this value and is set to ``100`` by default. If there are already a -number of open connections equal to ``maxPoolSize``, the server waits until -a connection becomes available. If this wait time exceeds the ``maxIdleTimeMS`` -value, the driver responds with an error. + .. replacement:: multiple-hosts-connection-guide-link -.. - TODO To learn more about how connection pools work in the driver, see - the :ref:`FAQ page `. + To learn more about specifying multiple hosts in a replica set, see the + :ref:`Connect to a Replica Set ` section of the + Connection Guide. -Authentication Error -~~~~~~~~~~~~~~~~~~~~ + .. replacement:: configure-firewall-anchor -The {+driver-short+} may be unable connect to a MongoDB instance if -the authorization is not configured correctly. In these cases, the driver -raises an error message similar to the following message: + .. _rust-troubleshooting-connection-firewall: -.. code-block:: none - :copyable: false + .. replacement:: check-the-number-of-connections-anchor - Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : - authentication failed" }, labels: {}, wire_version: None, source: Some(Error - { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: - "bad auth : authentication failed", topology_version: None }), - labels: {}, wire_version: None, source: None }) } + .. _rust-troubleshooting-connection-number-connections: -The following sections describe methods that may help resolve the issue. + .. replacement:: mongo-client-class -.. _rust-troubleshooting-connection-string-auth: + ``Client`` -Check Connection String ------------------------ + .. replacement:: max-pool-size-param -An invalid connection string is the most common cause of authentication -issues when attempting to connect to MongoDB. + ``maxPoolSize`` -.. tip:: + .. replacement:: max-pool-size-default - For more information about connection strings, - see the :ref:`rust-quick-start-connection-string` guide. + ``100`` -If your connection string contains a username and password, ensure that they -are in the correct format. + .. replacement:: max-idle-time-param -.. note:: + ``maxIdleTimeMS`` - If your username or password includes any of the following characters, you - must `percent encode `__ it: + .. + TODO To learn more about how connection pools work in the driver, see + the :ref:`FAQ page `. + - .. code-block:: none - :copyable: false + .. replacement:: authentication-error-anchor - : / ? # [ ] @ - - After percent encoding your username and password, you can use them as - credentials in your connection string. + .. _rust-troubleshooting-auth-error: -When connecting to a replica set, include all the replica set hosts in -your connection string. Separate each of the hosts in the connection -string with a comma. This enables the driver to establish a connection if -one of the hosts is unreachable. For an example of a connection string -that specifies multiple replica set hosts, see :ref:`Connect to a Replica Set -` in the Connection Guide. + .. replacement:: authentication-error-anchor -.. _rust-troubleshooting-connection-auth-mechanism: + .. _scram-failure-error: + + .. code-block:: none + :copyable: false + + Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : + authentication failed" }, labels: {}, wire_version: None, source: Some(Error + { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: + "bad auth : authentication failed", topology_version: None }), + labels: {}, wire_version: None, source: None }) } -Verify the Authentication Mechanism ------------------------------------ + .. replacement:: check-credentials-formatting-anchor -Ensure that your credentials and authentication mechanism are correct. You can -specify your authentication credentials in the options of your connection string -or in a ``Credential`` struct. + .. _rust-troubleshooting-connection-string-auth: -To learn more about authentication, see the -:ref:`rust-authentication` guide. + .. replacement:: learn-more-connection-string-admonition + + .. tip:: + + For more information about connection strings, + see the :ref:`rust-quick-start-connection-string` guide. -.. _rust-troubleshooting-connection-admin: + .. replacement:: verify-authentication-mechanism-anchor -Verify User Is in Authentication Database ------------------------------------------ + .. _rust-troubleshooting-connection-auth-mechanism: -To successfully authenticate a connection by using a username and password, -the username must be defined in the authentication database. The default -authentication database is the ``admin`` database. To use a different database -for authentication, specify the ``authSource`` option in the connection string. -The following example instructs the driver to use ``users`` as the authentication -database: -.. code-block:: rust - :copyable: true + .. replacement:: credentials-provider-alternative-method-description - let uri = "mongodb://:@:/?authSource=users"; - let client = Client::with_uri_str(uri).await?; + TODO -DNS Resolution Error -~~~~~~~~~~~~~~~~~~~~ + .. replacement:: authentication-guide-reference -The {+driver-short+} may be unable to resolve your DNS connection. When this -happens, you might receive an error message similar to the following message: + To learn more about authentication, see the :ref:`rust-authentication` guide. -.. code-block:: none - :copyable: false + .. replacement:: verify-authentication-database-anchor - Error: Error { kind: DnsResolve { message: "sample message. type: - SRV class: IN" }, labels: {}, wire_version: None, source: None } + .. _rust-troubleshooting-connection-admin: -If you receive this error, try the following methods to resolve the issue. + .. replacement:: authsource-param-code-block -Check Database Deployment Availability --------------------------------------- + .. code-block:: rust + :copyable: true + + let uri = "mongodb://:@:/?authSource=users"; + let client = Client::with_uri_str(uri).await?; -If you are using an Atlas connection string and your driver cannot find the DNS host -of the Atlas database deployment, the database deployment might be paused or deleted. -Check that the database deployment exists. If the cluster is paused, you can resume -the cluster on the Atlas UI or the Atlas command line interface. + .. replacement:: dns-resolution-anchor -To learn how to resume a cluster, see :atlas:`Resume One Cluster -` in the Atlas documentation. + .. _rust-troubleshooting-connection-dns-resolution: -Check Connection String ------------------------ + .. replacement:: dns-error-message -Verify that the connection string in your app is accurate. For more information -about verifying your connection string, see -:ref:`Connection Error ` -and :ref:`Authentication Error `. + .. code-block:: none + :copyable: false + + Error: Error { kind: DnsResolve { message: "sample message. type: + SRV class: IN" }, labels: {}, wire_version: None, source: None } From 333e430d4f13b83087eca0d569e90115724d31aa Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Dec 2023 13:16:17 -0500 Subject: [PATCH 02/11] update replacements --- source/connection-troubleshooting.txt | 52 +++++++++++++-------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index abd20eff..4bd851e4 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -22,12 +22,12 @@ Connection Troubleshooting - :ref:`rust-operation-errors` for recommendations on how to handle different error types that the driver raises during operations - :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the driver, and + information about reporting bugs, contributing to the driver, and finding more resources - `MongoDB Community Forums `__ for questions, discussions, or general technical support - - .. + + .. TODO: - The :ref:`Frequently Asked Questions (FAQ) ` for the {+driver-short+} @@ -37,13 +37,13 @@ Connection Troubleshooting .. code-block:: none :copyable: false - - Error: Error { kind: ServerSelection { message: "Server selection timeout: - No available servers. Topology: { Type: Unknown, Servers: [ { Address: - 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused - (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: + + Error: Error { kind: ServerSelection { message: "Server selection timeout: + No available servers. Topology: { Type: Unknown, Servers: [ { Address: + 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused + (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: None } - + .. replacement:: check-connection-string-anchor .. _rust-troubleshooting-connection-string-port: @@ -78,36 +78,34 @@ Connection Troubleshooting ``maxIdleTimeMS`` - .. + .. TODO To learn more about how connection pools work in the driver, see the :ref:`FAQ page `. - + .. replacement:: authentication-error-anchor .. _rust-troubleshooting-auth-error: - .. replacement:: authentication-error-anchor + .. replacement:: scram-failure-error - .. _scram-failure-error: - - .. code-block:: none - :copyable: false - - Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : - authentication failed" }, labels: {}, wire_version: None, source: Some(Error - { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: - "bad auth : authentication failed", topology_version: None }), - labels: {}, wire_version: None, source: None }) } + .. code-block:: none + :copyable: false + + Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : + authentication failed" }, labels: {}, wire_version: None, source: Some(Error + { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: + "bad auth : authentication failed", topology_version: None }), + labels: {}, wire_version: None, source: None }) } .. replacement:: check-credentials-formatting-anchor .. _rust-troubleshooting-connection-string-auth: .. replacement:: learn-more-connection-string-admonition - + .. tip:: - + For more information about connection strings, see the :ref:`rust-quick-start-connection-string` guide. @@ -132,7 +130,7 @@ Connection Troubleshooting .. code-block:: rust :copyable: true - + let uri = "mongodb://:@:/?authSource=users"; let client = Client::with_uri_str(uri).await?; @@ -144,6 +142,6 @@ Connection Troubleshooting .. code-block:: none :copyable: false - - Error: Error { kind: DnsResolve { message: "sample message. type: + + Error: Error { kind: DnsResolve { message: "sample message. type: SRV class: IN" }, labels: {}, wire_version: None, source: None } From d1d893a9f7612ad1c1de201aa817ae9755ce38cb Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Dec 2023 13:52:52 -0500 Subject: [PATCH 03/11] fix spacing and missing replacement --- source/connection-troubleshooting.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 4bd851e4..aef2c473 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -33,16 +33,16 @@ Connection Troubleshooting {+driver-short+} - .. replacement:: server-selection-timeout-error + .. replacement:: server-selection-timeout-error - .. code-block:: none - :copyable: false + .. code-block:: none + :copyable: false - Error: Error { kind: ServerSelection { message: "Server selection timeout: - No available servers. Topology: { Type: Unknown, Servers: [ { Address: - 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused - (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: - None } + Error: Error { kind: ServerSelection { message: "Server selection timeout: + No available servers. Topology: { Type: Unknown, Servers: [ { Address: + 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused + (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: + None } .. replacement:: check-connection-string-anchor @@ -78,10 +78,10 @@ Connection Troubleshooting ``maxIdleTimeMS`` - .. - TODO To learn more about how connection pools work in the driver, see - the :ref:`FAQ page `. - + .. replacement:: connection-pools-learn-more + .. + TODO To learn more about how connection pools work in the driver, see + the :ref:`FAQ page `. .. replacement:: authentication-error-anchor From d23ac9d9c92b699eb2e828c77b4b73b0a77889b6 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Dec 2023 13:59:06 -0500 Subject: [PATCH 04/11] update indentation of comment blocks --- source/connection-troubleshooting.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index aef2c473..305fd626 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -27,11 +27,10 @@ Connection Troubleshooting - `MongoDB Community Forums `__ for questions, discussions, or general technical support - .. - TODO: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} - + .. + TODO: + - The :ref:`Frequently Asked Questions (FAQ) ` for the + {+driver-short+} .. replacement:: server-selection-timeout-error @@ -79,6 +78,7 @@ Connection Troubleshooting ``maxIdleTimeMS`` .. replacement:: connection-pools-learn-more + .. TODO To learn more about how connection pools work in the driver, see the :ref:`FAQ page `. From ad6b6a4023be26915c8ae8f8bdcb8c12aa44c139 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Wed, 6 Dec 2023 14:31:25 -0500 Subject: [PATCH 05/11] test indentation --- source/connection-troubleshooting.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 305fd626..80b85aed 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -10,6 +10,8 @@ Connection Troubleshooting :depth: 2 :class: singlecol +ABC + .. sharedinclude:: dbx/connection-troubleshooting.rst .. replacement:: non-connection-issue-callout @@ -78,7 +80,7 @@ Connection Troubleshooting ``maxIdleTimeMS`` .. replacement:: connection-pools-learn-more - + .. TODO To learn more about how connection pools work in the driver, see the :ref:`FAQ page `. @@ -113,7 +115,6 @@ Connection Troubleshooting .. _rust-troubleshooting-connection-auth-mechanism: - .. replacement:: credentials-provider-alternative-method-description TODO From 2fa748655f4db0078188018b4a9f2b7e3febbd59 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Tue, 12 Dec 2023 11:11:03 -0500 Subject: [PATCH 06/11] WIP --- source/connection-troubleshooting.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 80b85aed..43934fb5 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -10,8 +10,6 @@ Connection Troubleshooting :depth: 2 :class: singlecol -ABC - .. sharedinclude:: dbx/connection-troubleshooting.rst .. replacement:: non-connection-issue-callout From b340c494947ec55c7f41124dd70698367926ec9e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Jan 2024 13:26:02 -0500 Subject: [PATCH 07/11] updates --- source/connection-troubleshooting.txt | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 43934fb5..f63f2024 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -26,11 +26,9 @@ Connection Troubleshooting finding more resources - `MongoDB Community Forums `__ for questions, discussions, or general technical support - - .. - TODO: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} + - The :ref:`Frequently Asked Questions (FAQ) ` section for + common questions and corresponding answers about the + {+driver-short+}. .. replacement:: server-selection-timeout-error @@ -79,9 +77,9 @@ Connection Troubleshooting .. replacement:: connection-pools-learn-more - .. - TODO To learn more about how connection pools work in the driver, see - the :ref:`FAQ page `. + To learn more about how connection pools work in the driver, see + the related :ref:`question and answer ` on + the FAQ page. .. replacement:: authentication-error-anchor @@ -115,7 +113,8 @@ Connection Troubleshooting .. replacement:: credentials-provider-alternative-method-description - TODO + Alternatively, you can specify your authentication credentials in a + ``Credential`` struct. .. replacement:: authentication-guide-reference From 1111711dd84925d79ecc5cd706bb919215d52324 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Jan 2024 14:17:57 -0500 Subject: [PATCH 08/11] update link text --- source/connection-troubleshooting.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index f63f2024..ab8b0aac 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -78,8 +78,8 @@ Connection Troubleshooting .. replacement:: connection-pools-learn-more To learn more about how connection pools work in the driver, see - the related :ref:`question and answer ` on - the FAQ page. + :ref:`How Does Connection Pooling Work in the Rust Driver? ` + on the FAQ page. .. replacement:: authentication-error-anchor From 86033cdf0fb3aa33ec6080c905cc9bea4c58a834 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Jan 2024 14:24:13 -0500 Subject: [PATCH 09/11] add facet --- source/connection-troubleshooting.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index ab8b0aac..ef039533 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -10,6 +10,10 @@ Connection Troubleshooting :depth: 2 :class: singlecol +.. facet:: + :name: genre + :values: reference + .. sharedinclude:: dbx/connection-troubleshooting.rst .. replacement:: non-connection-issue-callout From ce3869e067f955465a5d81df5b4b7ee20fc9ef57 Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Jan 2024 14:26:19 -0500 Subject: [PATCH 10/11] add meta keywords --- source/connection-troubleshooting.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index ef039533..26dc17b2 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -14,6 +14,9 @@ Connection Troubleshooting :name: genre :values: reference +.. meta:: + :keyworrds: code example, disconnected, deployment + .. sharedinclude:: dbx/connection-troubleshooting.rst .. replacement:: non-connection-issue-callout From d2490c1df10ca029b079b3c28c9c461016556e0e Mon Sep 17 00:00:00 2001 From: Chris Cho Date: Thu, 18 Jan 2024 15:27:21 -0500 Subject: [PATCH 11/11] remove extraneous period --- source/connection-troubleshooting.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 26dc17b2..7a2d2a3e 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -35,7 +35,7 @@ Connection Troubleshooting questions, discussions, or general technical support - The :ref:`Frequently Asked Questions (FAQ) ` section for common questions and corresponding answers about the - {+driver-short+}. + {+driver-short+} .. replacement:: server-selection-timeout-error