diff --git a/config/redirects b/config/redirects index 18ccb714a..a3893739e 100644 --- a/config/redirects +++ b/config/redirects @@ -9,3 +9,4 @@ raw: ${prefix}/master -> ${base}/upcoming/ [*-v4.6]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/fundamentals/crud/read-operations/retrieve/ [*-master]: ${prefix}/${version}/fundamentals/csfle/ -> ${base}/${version}/fundamentals/encrypt-fields/ [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/ +[*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/ diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt index a041f4f56..6f398ba7d 100644 --- a/source/fundamentals/connection.txt +++ b/source/fundamentals/connection.txt @@ -11,6 +11,7 @@ Connection Guide /fundamentals/connection/mongoclientsettings /fundamentals/connection/network-compression /fundamentals/connection/tls + /fundamentals/connection/socks /fundamentals/connection/jndi Connect to MongoDB Atlas from AWS Lambda @@ -32,7 +33,8 @@ sections: - :ref:`Specify Connection Behavior with the MongoClient Class ` - :ref:`Enable Network Compression ` - :ref:`Enable TLS/SSL on a Connection ` -- :ref:`Connect to MongoDB Using a JNDI Datasource ` +- :ref:`Connect to MongoDB by Using a SOCKS5 Proxy ` +- :ref:`Connect to MongoDB by Using a JNDI Datasource ` - :atlas:`Connect to MongoDB Atlas from AWS Lambda ` For information about authenticating with a MongoDB instance, diff --git a/source/fundamentals/connection/connection-options.txt b/source/fundamentals/connection/connection-options.txt index e487c9ba3..e8758a661 100644 --- a/source/fundamentals/connection/connection-options.txt +++ b/source/fundamentals/connection/connection-options.txt @@ -72,21 +72,21 @@ parameters of the connection URI to specify the behavior of the client. * - **ssl** - boolean - - Specifies that all communication with MongoDB instances should + - Specifies that all communication with MongoDB instances must use TLS/SSL. Superseded by the **tls** option. | **Default**: ``false`` * - **tls** - boolean - - Specifies that all communication with MongoDB instances should + - Specifies that all communication with MongoDB instances must use TLS. Supersedes the **ssl** option. | **Default**: ``false`` * - **tlsInsecure** - boolean - - Specifies that the driver should allow invalid hostnames for TLS + - Specifies that the driver must allow invalid hostnames for TLS connections. Has the same effect as setting **tlsAllowInvalidHostnames** to ``true``. To configure TLS security constraints in other ways, use a @@ -96,7 +96,7 @@ parameters of the connection URI to specify the behavior of the client. * - **tlsAllowInvalidHostnames** - boolean - - Specifies that the driver should allow invalid hostnames in the + - Specifies that the driver must allow invalid hostnames in the certificate for TLS connections. Supersedes **sslInvalidHostNameAllowed**. @@ -186,14 +186,14 @@ parameters of the connection URI to specify the behavior of the client. is greater. For more information, see the server documentation for the :manual:`maxStalenessSeconds option `. Not providing a parameter or explicitly specifying ``-1`` indicates - that there should be no staleness check for secondaries. + that there must be no staleness check for secondaries. | **Default**: ``-1`` * - **authMechanism** - string - Specifies the :doc:`authentication mechanism - ` that the driver should use if a credential + ` that the driver uses if a credential was supplied. | **Default**: By default, the client picks the most secure @@ -204,9 +204,8 @@ parameters of the connection URI to specify the behavior of the client. * - **authSource** - string - - Specifies the database that the supplied credentials should be - validated against. - + - Specifies the database in which the supplied credentials are validated. + | **Default**: ``admin`` * - **authMechanismProperties** @@ -239,7 +238,7 @@ parameters of the connection URI to specify the behavior of the client. * - **zlibCompressionLevel** - integer - Specifies the degree of compression that `Zlib `__ - should use to decrease the size of requests to the connected MongoDB + uses to decrease the size of requests to the connected MongoDB instance. The level can range from ``-1`` to ``9``, with lower values compressing faster (but resulting in larger requests) and larger values compressing slower (but resulting in smaller requests). @@ -249,7 +248,7 @@ parameters of the connection URI to specify the behavior of the client. * - **retryWrites** - boolean - Specifies that the driver must retry supported write operations - if they fail due to a network error. + if they are unable to complete due to a network error. | **Default**: ``true`` @@ -257,7 +256,7 @@ parameters of the connection URI to specify the behavior of the client. * - **retryReads** - boolean - Specifies that the driver must retry supported read operations - if they fail due to a network error. + if they are unable to complete due to a network error. | **Default**: ``true`` @@ -280,23 +279,23 @@ parameters of the connection URI to specify the behavior of the client. - integer - Specifies the maximum number of connections a pool may be establishing concurrently. - + | **Default**: ``2`` * - **srvServiceName** - string - Specifies the service name of the `SRV resource records `__ - the driver retrieves to construct your + the driver retrieves to construct your :manual:`seed list `. - You must use the + You must use the :manual:`DNS Seed List Connection Format ` in your :ref:`connection URI ` - to use this option. - + to use this option. + | **Default**: ``mongodb`` For a complete list of options, see the `ConnectionString <{+api+}/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html>`__ -API reference page. +API documentation. diff --git a/source/fundamentals/connection/jndi.txt b/source/fundamentals/connection/jndi.txt index 43d53f142..8f1d9d5af 100644 --- a/source/fundamentals/connection/jndi.txt +++ b/source/fundamentals/connection/jndi.txt @@ -1,8 +1,8 @@ .. _jndi: -========================================== -Connect to MongoDB Using a JNDI Datasource -========================================== +============================================= +Connect to MongoDB by Using a JNDI Datasource +============================================= .. contents:: On this page :local: @@ -15,7 +15,7 @@ Overview -------- In this guide, you can learn how to connect the MongoDB Java driver -to your MongoDB instance using a Java Naming and Directory Interface +to your MongoDB instance by using a Java Naming and Directory Interface (JNDI) Datasource. MongoClientFactory includes a `JNDI @@ -61,7 +61,7 @@ JNDI Datasource. Replace the placeholder connection value in the ``property`` tag with a value that points to your MongoDB installation. - This makes a MongoClient instance accessible via the JNDI name + This makes a MongoClient instance discoverable through the JNDI name ``MyMongoClient`` in the ``java:global`` context. .. tab:: Tomcat @@ -106,7 +106,7 @@ JNDI Datasource. - This makes a ``MongoClient`` instance accessible via the JNDI name + This makes a ``MongoClient`` instance discoverable through the JNDI name ``mongodb/MyMongoClient`` in the ``java:comp/env`` context. .. seealso:: diff --git a/source/fundamentals/connection/socks.txt b/source/fundamentals/connection/socks.txt new file mode 100644 index 000000000..c5d0d900c --- /dev/null +++ b/source/fundamentals/connection/socks.txt @@ -0,0 +1,136 @@ +.. _java-connect-socks: + +========================================== +Connect to MongoDB by Using a SOCKS5 Proxy +========================================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to connect to MongoDB by using a SOCKS5 proxy. +SOCKS5 is a standardized protocol for communicating with network services +through a proxy server. + +.. tip:: + + To learn more about the SOCKS5 protocol, see the Wikipedia entry on + :wikipedia:`SOCKS `. + +.. _socks-proxy-settings: + +SOCKS5 Proxy Settings +--------------------- + +The proxy settings specify the SOCKS5 proxy server address and your +authentication credentials. You can specify your settings in an instance of +``MongoClientSettings`` or in your connection string. + +.. important:: + + The driver ignores the proxy settings if you specify a custom + ``StreamFactoryFactory``, which by default creates instances of + ``SocketStreamFactory``. + +The following table describes the SOCKS5 client options: + +.. list-table:: + :header-rows: 1 + :widths: 15 20 65 + + * - Name + - Accepted Values + - Description + + * - **proxyHost** + - String + - Specifies the SOCKS5 proxy IPv4 address, IPv6 address, or hostname. + You must provide this value to connect to a SOCKS5 proxy. + + * - **proxyPort** + - non-negative Integer + - Specifies the TCP port number of the SOCKS5 proxy server. This option + defaults to ``1080`` when you set ``proxyHost``. + + * - **proxyUsername** + - String + - Specifies the username for authentication to the SOCKS5 proxy server. + The driver ignores ``null`` and empty string values for this setting. + The driver requires that you pass values for both ``proxyUsername`` + and ``proxyPassword`` or that you omit both values. + + * - **proxyPassword** + - String + - Specifies the password for authentication to the SOCKS5 proxy server. + The driver ignores ``null`` and empty string values for this setting. + The driver requires that you pass values for both ``proxyUsername`` + and ``proxyPassword`` or that you omit both values. + + +Examples +-------- + +The following examples show how to instantiate a ``MongoClient`` that connects +to MongoDB by using a SOCKS5 proxy. The proxy settings can be specified in a +``MongoClientSettings`` instance or a connection string. These examples use +the placeholder values described in the :ref:`socks-proxy-settings` section. +Replace the placeholders with your proxy settings. + +Specify Proxy Settings in the MongoClientSettings +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code example shows how to specify your SOCKS5 proxy settings by +using the ``MongoClientSettings`` builder: + +.. code-block:: java + :emphasize-lines: 5-12 + + MongoClient mongoClient = MongoClients.create( + MongoClientSettings.builder() + .applyConnectionString( + new ConnectionString("mongodb+srv://myDatabaseUser:myPassword@example.org/")) + .applyToSocketSettings(builder -> + builder.applyToProxySettings(proxyBuilder -> + proxyBuilder + .host("") + .port() + .username("") + .password("") + ) + ).build()); + +Specify Proxy Settings in the Connection String +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following code example shows how to specify your SOCKS5 proxy settings in +your connection string: + +.. code-block:: java + :emphasize-lines: 2-5 + + String connectionString = "mongodb+srv://myDatabaseUser:myPassword@example.org/" + + "?proxyHost=" + + "&proxyPort=" + + "&proxyUsername=" + + "&proxyPassword="; + + MongoClient mongoClient = MongoClients.create(connectionString); + +API Documentation +~~~~~~~~~~~~~~~~~ + +To learn more about the methods and types discussed in this guide, see the +following API documentation: + +- `MongoClientSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.Builder.html>`__ +- `SocketSettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/SocketSettings.Builder.html>`__ +- `MongoClients.create() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html#create(com.mongodb.MongoClientSettings)>`__ + +.. TODO + - provide the link for the proxysettings builder once the API docs are generated: + - `ProxySettings.Builder <{+api+}/apidocs/mongodb-driver-core/com/mongodb/connection/ProxySettings.Builder.html>`__