diff --git a/docs/contribute.txt b/docs/contribute.txt index d25dda4e8d..a541b15fad 100644 --- a/docs/contribute.txt +++ b/docs/contribute.txt @@ -58,7 +58,7 @@ Contribute Code The MongoDB Ruby driver source is located `at GitHub `_. -The list of known issues in the driver is available +The list of known issues in the driver is available `in JIRA `_. We recommend creating a JIRA ticket before starting work on a bug fix or @@ -73,7 +73,7 @@ the changes to the stable branches, if needed. A MongoDB deployment is required to run the tests. Setup procedures and recommendations for various deployments, as well as how to configure the driver's test suite for the deployments, are covered in the `spec -readme `. +readme `__. The driver is tested on `Evergreen `_, MongoDB's in-house continuous integration platform. After a pull request diff --git a/docs/tutorials/client-side-encryption.txt b/docs/tutorials/client-side-encryption.txt index b7ec2ca2db..a5f7c1df24 100644 --- a/docs/tutorials/client-side-encryption.txt +++ b/docs/tutorials/client-side-encryption.txt @@ -74,12 +74,12 @@ enterprise-only feature. If you only intend to use explicit encryption, you may skip this step. Mongocryptd comes pre-packaged with enterprise builds of the MongoDB server -(versions 4.2 and newer). For installation instructions, see -`the MongoDB manual `_. +(versions 4.2 and newer). For installation instructions, see the +`MongoDB manual `_. In order to configure mongocryptd (for example, which port it listens on or the path used to spawn the daemon), it is necessary to pass different options to the -``Mongo::Client`` performing automatic encryption. See the `:extra_options`_ +``Mongo::Client`` performing automatic encryption. See the :ref:`:extra_options ` section of this tutorial for more information. Automatic Encryption @@ -202,11 +202,12 @@ The example above demonstrates using automatic encryption with a local master ke For more information about using the AWS Key Management Service to create a master key and create data keys, see the following sections of this tutorial: -- `Creating A Master Key`_ -- `Creating A Data Key`_ +- :ref:`Creating A Master Key ` +- :ref:`Creating A Data Key ` Explicit Encryption =================== + Explicit encryption is a feature that allows users to encrypt and decrypt individual pieces of data such as strings, integers, or symbols. Explicit encryption is a community feature and does not require an enterprise build @@ -296,8 +297,8 @@ The example above demonstrates using explicit encryption with a local master key For more information about using the AWS Key Management Service to create a master key and create data keys, see the following sections of this tutorial: -- `Creating A Master Key`_, -- `Creating A Data Key`_, +- :ref:`Creating A Master Key ` +- :ref:`Creating A Data Key ` Creating a Master Key ===================== @@ -307,8 +308,11 @@ user data. The master key can be generated in one of two ways: by creating a local key, or by creating a key in the Amazon Web Services Key Management Service (AWS KMS). +.. _local-master-key: + Local Master Key ~~~~~~~~~~~~~~~~ + A local master key is a 96-byte binary string. It should be persisted on your machine as an environment variable or in a text file. @@ -329,14 +333,25 @@ AWS Master Key It is recommended that you use Amazon's Key Management Service to create and store your master key. To do so, follow steps 1 and 2 of the :drivers:`"Convert to a Remote Master Key" section` +.. _remote-master-key: + +Remote Master Key +~~~~~~~~~~~~~~~~~ +It is recommended that you use a remote Key Management Service to create and +store your master key. To do so, follow steps of the +`"Set up a Remote Master Key" `_ in the MongoDB Client-Side Encryption documentation. For more information about creating a master key, see the :drivers:`Create a Master Key ` +`Create a Master Key `_ section of the MongoDB manual. +.. _creating-a-data-key: + Creating a Data Key =================== + Once you have created a master key, create a data key by calling the ``#create_data_key`` method on an instance of the ``Mongo::ClientEncryption`` class. This method generates a new data key and inserts it into the key vault @@ -376,8 +391,8 @@ key with the following code snippet: data_key_id = client_encryption.create_data_key('local') # => -See the `Local Master Key`_ section for more information about generating a new -local master key. +See the :ref:`Local Master Key ` section for more information +about generating a new local master key. Create a Data Key Using an AWS Master Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -423,11 +438,12 @@ generating a new master key on AWS and finding the information you need to create data keys. For more information about creating a data key, see the -:drivers:`Create a Data Encryption Key ` +`Create a Data Encryption Key `_ section of the MongoDB manual. Auto-Encryption Options ======================= + Automatic encryption can be configured on a ``Mongo::Client`` using the ``auto_encryption_options`` option ``Hash``. This section provides an overview of the fields inside ``auto_encryption_options`` and explains how to choose their @@ -435,6 +451,7 @@ values. ``:key_vault_client`` ~~~~~~~~~~~~~~~~~~~~~ + The key vault client is a ``Mongo::Client`` instance that will be used to connect to the MongoDB collection containing your encryption data keys. For example, if your key vault was hosted on a MongoDB instance at ``localhost:30000``: @@ -456,6 +473,7 @@ to insert and fetch data keys. ``:key_vault_namespace`` ~~~~~~~~~~~~~~~~~~~~~~~~ + The key vault namespace is a ``String`` in the format ``"database_name.collection_name"``, where ``database_name`` and ``collection_name`` are the name of the database and collection in which you would like to store your data keys. For example, if your data @@ -474,6 +492,7 @@ There is no default key vault namespace, and this option must be provided. ``:schema_map`` ~~~~~~~~~~~~~~~ + A schema map is a Hash with information about which fields to automatically encrypt and decrypt. @@ -549,11 +568,12 @@ When you intend to use your schema map, convert it to a Ruby ``Hash`` using the .. seealso:: - :drivers:`Specify Encrypted Fields Using JSON Schema`, + `Specify Encrypted Fields Using JSON Schema `_, :manual:`Automatic Encryption Rules` ``:bypass_auto_encryption`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The ``:bypass_auto_encryption`` option is a ``Boolean`` that specifies whether the ``Mongo::Client`` should skip encryption when writing to the database. If ``:bypass_auto_encryption`` is ``true``, the client will still perform automatic @@ -568,8 +588,11 @@ decryption of any previously-encrypted data. } ) +.. _cse-extra-options: + ``:extra_options`` ~~~~~~~~~~~~~~~~~~ + ``:extra_options`` is a ``Hash`` of options related to spawning mongocryptd. Every option in this ``Hash`` has a default value, so it is only necessary to provide the options whose defaults you want to override. diff --git a/docs/tutorials/common-errors.txt b/docs/tutorials/common-errors.txt new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/tutorials/ruby-driver-create-client.txt b/docs/tutorials/ruby-driver-create-client.txt index 5dbb0d514a..7f51fd528b 100644 --- a/docs/tutorials/ruby-driver-create-client.txt +++ b/docs/tutorials/ruby-driver-create-client.txt @@ -29,7 +29,7 @@ to connect to; if no database name is specified, the client will use the .. code-block:: ruby Mongo::Client.new([ '127.0.0.1:27017' ], database: 'mydb') - + # Or using the URI syntax: Mongo::Client.new("mongodb://127.0.0.1:27017/mydb") @@ -82,7 +82,7 @@ The database can be specified during ``Client`` construction: # Using Ruby client options: client = Mongo::Client.new(['localhost'], database: 'mydb') - + # Using a MongoDB URI: client = Mongo::Client.new('mongodb://localhost/mydb') @@ -92,9 +92,9 @@ new ``Client`` instance configured with the specified database: .. code-block:: ruby client = Mongo::Client.new(['localhost'], database: 'mydb') - + admin_client = client.use('admin') - + # Issue an administrative command admin_client.database.command(replSetGetConfig: 1).documents.first @@ -125,7 +125,7 @@ To force all operations to be performed on the designated server, specify the .. code-block:: ruby Mongo::Client.new([ '1.2.3.4:27017' ], database: 'mydb', direct_connection: true) - + # Or using the URI syntax: Mongo::Client.new("mongodb://1.2.3.4:27017/mydb?directConnection=true") @@ -153,7 +153,7 @@ connect to the replica set. Mongo::Client.new([ '127.0.0.1:27017', '127.0.0.1:27018' ], :database => 'mydb', replica_set: 'myapp') - + # Or using the URI syntax: Mongo::Client.new("mongodb://127.0.0.1:27017,127.0.0.1:27018/mydb?replicaSet=myapp") @@ -186,7 +186,7 @@ spread the operation load accordingly. .. code-block:: ruby Mongo::Client.new([ '1.2.3.4:27017', '1.2.3.5:27017' ], :database => 'mydb') - + Mongo::Client.new("mongodb://1.2.3.4:27017,1.2.3.5:27017/mydb") @@ -270,7 +270,7 @@ Ruby Options * - ``:auth_mech_properties`` - Provides additional authentication mechanism properties. - + The keys in properties are interpreted case-insensitively. When the client is created, keys are lowercased. @@ -319,8 +319,8 @@ Ruby Options - none * - ``:compressors`` - - A list of potential compressors to use, in order of preference. The driver chooses the first - compressor that is also supported by the server. Currently the driver only supports 'zlib'. + - A list of potential compressors to use, in order of preference. + Please see below for details on how the driver implements compression. - ``Array`` - none @@ -436,11 +436,11 @@ Ruby Options max_staleness: 5, } } - + If tag sets are provided, they must be an array of hashes. A server satisfies the read preference if its tags match any one hash in the provided tag sets. - + Each tag set must be a hash, and will be converted internally to a ``BSON::Document`` instance prior to being used for server selection. Hash keys can be strings or symbols. The keys are case sensitive. @@ -480,12 +480,12 @@ Ruby Options subscriber not receiving some of the SDAM events. The ``:sdam_proc`` option permits adding event subscribers on the client being constructed before any SDAM events are published. - + Pass a ``Proc`` which will be called with the ``Client`` as the argument after the client's event subscription mechanism has been initialized but before any of the servers are added to the client. Use this ``Proc`` to set up SDAM event subscribers on the client. - + Note: the client is not fully constructed when the ``Proc`` provided in ``:sdam_proc is invoked, in particular the cluster is nil at this time. ``:sdam_proc`` procedure should limit itself to calling @@ -696,6 +696,7 @@ URI options are explained in detail in the :manual:`Connection URI reference `. .. note:: + Options that are set in **milliseconds** in the URI are represented as a ``float`` in Ruby and the units are **seconds**. @@ -1090,6 +1091,53 @@ file and both must be stored in the same file. Example usage: URI option values must be properly URI escaped. This applies, for example, to slashes in the paths. + +.. _modifying-tls-context: + +Modifying ``SSLContext`` +------------------------ +It may be desirable to further configure TLS options in the driver, for example +by enabling or disabling certain ciphers. Currently, the Ruby driver does not +provide a way to do this when initializing a ``Mongo::Client``. + +However, the Ruby driver provides a way to set global "TLS context hooks" -- +these are user-provided ``Proc``s that will be invoked before any TLS socket +connection and can be used to modify the underlying ``OpenSSL::SSL::SSLContext`` +object used by the socket. + +To set the TLS context hooks, add ``Proc``s to the ``Mongo.tls_context_hooks`` +array. This should be done before creating any Mongo::Client instances. +For example, in a Rails application this code could be placed in an initializer. + +.. code-block:: ruby + + Mongo.tls_context_hooks.push( + Proc.new { |context| + context.ciphers = ["AES256-SHA"] + } + ) + + # Only the AES256-SHA cipher will be enabled from this point forward + +Every ``Proc`` in ``Mongo.tls_context_hooks`` will be passed an +``OpenSSL::SSL::SSLContext`` object as its sole argument. These ``Proc``s will +be executed sequentially during the creation of every ``Mongo::Socket::SSL`` object. + +It is possible to assign the entire array of hooks calling ``Mongo.tls_context_hooks=``, +but doing so will remove any previously assigned hooks. It is recommended to use +the ``Array#push`` or ``Array#unshift`` methods to add new hooks. + +It is also possible to remove hooks from ``Mongo.tls_context_hooks`` by storing +a reference to the Procs somewhere else in the application, and then using +``Array#delete_if`` to remove the desired hooks. + +.. warning:: + + TLS context hooks are global and will affect every instance of ``Mongo::Client``. + Any library that allows applications to enable these hooks should expose methods to + modify the hooks (which can be called by the application) rather than + automatically enabling the hooks when the library is loaded. + Further information on configuring MongoDB server for TLS is available in the :manual:`MongoDB manual `. @@ -1162,10 +1210,13 @@ The ``:ssl_ca_cert_string`` option supports specifying only one CA certificate. CA certificate options. Doing so would elevate the intermediate certificates to the status of root certificates, rather than verifying intermediate certificates against the root certificates. - + If intermediate certificates need to be used, specify them as part of the client or server TLS certificate files. + +.. _ocsp-verification: + OCSP Verification ----------------- @@ -1300,7 +1351,7 @@ Usage with Forking Servers ========================== .. note:: - + Applications using Mongoid should follow `Mongoid's forking guidance `_. The guidance and sample code below is provided for applications using the @@ -1316,7 +1367,7 @@ This is because: 2. File descriptors like network sockets are shared between parent and child processes. -The driver attempts to detect client use from forked processes and +The driver attempts to detect client use from forked processes and reestablish network connections when such use is detected, alleviating the issue of file descriptor sharing. diff --git a/docs/tutorials/ruby-driver-crud-operations.txt b/docs/tutorials/ruby-driver-crud-operations.txt index 4e6fc1e0ba..9080efc669 100644 --- a/docs/tutorials/ruby-driver-crud-operations.txt +++ b/docs/tutorials/ruby-driver-crud-operations.txt @@ -900,7 +900,7 @@ underscore one that Ruby driver uses. A Note about the BSON Symbol type ================================= -Because the BSON specification deprecated the BSON symbol type, the `bson` gem +Because the BSON specification deprecated the BSON symbol type, the ``bson`` gem will serialize Ruby symbols into BSON strings when used on its own. However, in order to maintain backwards compatibility with older datasets, the Ruby driver overrides this behavior to serialize Ruby symbols as BSON symbols. This is diff --git a/docs/tutorials/ruby-driver-gridfs.txt b/docs/tutorials/ruby-driver-gridfs.txt index 66087bd9ae..d0781bfa18 100644 --- a/docs/tutorials/ruby-driver-gridfs.txt +++ b/docs/tutorials/ruby-driver-gridfs.txt @@ -252,7 +252,7 @@ by default into the ``fs.chunks`` collection and file metadata is inserted into client.database.fs.insert_one(file) -To insert into collections with a name prefix other than `fs`, access the +To insert into collections with a name prefix other than ``fs``, access the filesystem with a ``:fs_name`` option. .. code-block:: ruby diff --git a/docs/tutorials/ruby-driver-monitoring.txt b/docs/tutorials/ruby-driver-monitoring.txt index e822dc1ce3..d2c54067c5 100644 --- a/docs/tutorials/ruby-driver-monitoring.txt +++ b/docs/tutorials/ruby-driver-monitoring.txt @@ -134,35 +134,35 @@ can look like the following: format("SDAM | %s".freeze, message) end end - + class TopologyOpeningLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Topology type '#{event.topology.display_name}' initializing." end end - + class ServerOpeningLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server #{event.address} initializing." end end - + class ServerDescriptionChangedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server description for #{event.address} changed from " + "'#{event.previous_description.server_type}' to '#{event.new_description.server_type}'." end end - + class TopologyChangedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) if event.previous_topology != event.new_topology "Topology type '#{event.previous_topology.display_name}' changed to " + @@ -173,18 +173,18 @@ can look like the following: end end end - + class ServerClosedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Server #{event.address} connection closed." end end - + class TopologyClosedLogSubscriber < SDAMLogSubscriber private - + def format_event(event) "Topology type '#{event.topology.display_name}' closed." end @@ -225,7 +225,7 @@ since the events may be published during the client's construction: topology_changed_subscriber = TopologyChangedLogSubscriber.new server_closed_subscriber = ServerClosedLogSubscriber.new topology_closed_subscriber = TopologyClosedLogSubscriber.new - + sdam_proc = Proc.new do |client| client.subscribe(Mongo::Monitoring::TOPOLOGY_OPENING, topology_opening_subscriber) @@ -282,9 +282,9 @@ Server Heartbeats The application can be notified of each server heartbeat by subscribing to SERVER_HEARTBEAT topic. A server heartbeat listener must implement -three methods: `started`, `succeeded` and `failed`. Each heartbeat invokes -the `started` method on the listener, and then either `succeeded` or `failed` -method depending on the outcome of the heartbeat. +three methods: ``started``, ``succeeded`` and ``failed``. Each heartbeat +invokes the ``started`` method on the listener, and then either ``succeeded`` +or ``failed`` method depending on the outcome of the heartbeat. All heartbeat events contain the address of the server that the heartbeat was sent to. Succeeded and failed events contain the round trip time for @@ -311,9 +311,9 @@ The following is an example logging heartbeat event subscriber: def failed(event) log_debug("#{event.address} | FAILED | #{event.error.class}: #{event.error.message} | #{event.duration}s") end - + private - + def logger Mongo::Logger.logger end