diff --git a/changelogs/generatechangelogs.py b/changelogs/generatechangelogs.py index 19bdd1db6cc..5288abed4f8 100644 --- a/changelogs/generatechangelogs.py +++ b/changelogs/generatechangelogs.py @@ -63,7 +63,7 @@ def get_jira_issues(fixVersion): return issues -def get_issue_structure(config, issues): +def get_issue_structure(config, issues, version): """ Group the JIRA issues by component. Structure headings and subheadings. @@ -227,7 +227,7 @@ def main(): config = get_config() # Generate issue headings based on component config - issue_headings = get_issue_structure(config, issues) + issue_headings = get_issue_structure(config, issues, fixVersion) # Convert the issue headings into rst changelog_rst = generate_changelog_rst(config, issue_headings, fixVersion) diff --git a/config/changelog_conf.yaml b/config/changelog_conf.yaml index 1ca1e251940..3af2baba4f8 100644 --- a/config/changelog_conf.yaml +++ b/config/changelog_conf.yaml @@ -12,7 +12,9 @@ groups: "Query": - Querying - Query Execution + - Query Language - Indexing + - Index Maintenance - Geo - Text Search "Write Operations": @@ -44,6 +46,7 @@ groups: - HTTP Console "Build and Packaging": - Build + - Build/compile - Packaging - Mobile "Internals": @@ -63,6 +66,7 @@ groups: - Cache and eviction - Backup - Checkpoints + - Documentation "Tools": - Tools - All Tools diff --git a/config/redirects b/config/redirects index 0794caeb3df..c9f079850bf 100644 --- a/config/redirects +++ b/config/redirects @@ -1879,6 +1879,14 @@ raw: /manual/core/wildcard -> ${base}/manual/core/index-wildcard/ [v5.0-*]: /${version}/reference/read-concern-majority/#disable-read-concern-majority -> ${base}/${version}/reference/read-concern-majority/#primary-secondary-arbiter-replica-sets + +# +# Redirects for 5.1 and greater (if pages are removed in 5.0 that used to exist in earlier versions) +# + +[v5.0-*]: /${version}/core/core/authentication-mechanisms -> ${base}/${version}/core/authentication + + # # Upgrade / Downgrade redirects # diff --git a/snooty.toml b/snooty.toml index 54803e778f2..8062db85771 100644 --- a/snooty.toml +++ b/snooty.toml @@ -67,6 +67,7 @@ toc_landing_pages = [ "/core/security-hardening", "/core/security-internal-authentication", "/core/security-ldap", + "/core/security-scram", "/core/security-transport-encryption", "/core/security-users", "/core/security-x.509", diff --git a/source/administration/change-streams-production-recommendations.txt b/source/administration/change-streams-production-recommendations.txt index 161533444e7..c470c360320 100644 --- a/source/administration/change-streams-production-recommendations.txt +++ b/source/administration/change-streams-production-recommendations.txt @@ -83,3 +83,11 @@ From the moment an unsharded collection is sharded until the time the change stream catches up to the first chunk migration, the ``documentKey`` in the change stream notification document only includes the ``_id`` of the document, not the full shard key. + +Indexes +------- + +Change streams cannot use indexes. MongoDB does not support creating +indexes on the :term:`oplog` collection. Therefore, avoid opening a high +number of :ref:`specifically-targeted ` +change streams as these can impact server performance. diff --git a/source/administration/security-checklist.txt b/source/administration/security-checklist.txt index 63665f4e737..b77c8518137 100644 --- a/source/administration/security-checklist.txt +++ b/source/administration/security-checklist.txt @@ -6,9 +6,9 @@ Security Checklist .. |arrow| unicode:: U+27A4 -*Last updated: 2020-03-25* +*Last updated: 2021-09-29* -This documents provides a list of security measures that you should +This document provides a list of security measures that you should implement to protect your MongoDB installation. The list is not meant to be exhaustive. @@ -20,46 +20,54 @@ Pre-production Checklist/Considerations |arrow| Enable Access Control and Enforce Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Enable access control and specify the authentication mechanism. - You can use MongoDB's SCRAM or x.509 authentication mechanism or - integrate with your existing Kerberos/LDAP infrastructure. Authentication - requires that all clients and servers provide valid credentials - before they can connect to the system. +- Enable access control and specify an authentication mechanism. - | + MongoDB Community supports a number of :ref:`authentication mechanisms + ` that clients can use to verify + their identity: - See also: + - :ref:`authentication-scram` (*Default*) + - :ref:`x.509 Certificate Authentication `. - - :doc:`/core/authentication` - - :doc:`/tutorial/enable-authentication` + In addition to the preceding mechanisms, MongoDB Atlas and MongoDB + Enterprise support the following mechanisms: + + - :ref:`LDAP proxy authentication `, and + - :ref:`Kerberos authentication `. + + These mechanisms allow MongoDB to integrate into your + existing authentication system. + +.. seealso:: + + - :doc:`/core/authentication` + - :doc:`/tutorial/enable-authentication` .. _security-checklist-role-based-access-control: |arrow| Configure Role-Based Access Control ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Create a user administrator **first**, then create additional - users. Create a unique MongoDB user for each person/application - that accesses the system. - +- Create a :ref:`user administrator ` **first**, then + create additional users. Create a unique MongoDB user for each + person/application that accesses the system. + - Follow the principle of least privilege. Create roles that define the exact access rights required by a set of users. Then create users and assign them only the roles they need to perform their operations. A user can be a person or a client application. .. note:: - + A user can have privileges across different databases. If a user requires privileges on multiple databases, create a single user with roles that grant applicable database privileges instead of creating the user multiple times in different databases. - | - - See also: +.. seealso:: - - :doc:`/core/authorization` - - :doc:`/tutorial/manage-users-and-roles` + - :doc:`/core/authorization` + - :doc:`/tutorial/manage-users-and-roles` |arrow| Encrypt Communication (TLS/SSL) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -72,33 +80,29 @@ Pre-production Checklist/Considerations .. include:: /includes/fact-tls-libraries.rst - .. note:: - - .. include:: /includes/fact-tls-1.0.rst +.. seealso:: - | - - See also: :doc:`/tutorial/configure-ssl`. - -.. |binary| replace:: MongoDB + :doc:`/tutorial/configure-ssl`. |arrow| Encrypt and Protect Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Starting with MongoDB Enterprise 3.2, you can encrypt data in - the storage layer with the WiredTiger storage engine's native - :doc:`/core/security-encryption-at-rest`. +- You can encrypt data in the storage layer with the WiredTiger storage + engine's native :doc:`/core/security-encryption-at-rest`. - If you are not using WiredTiger's encryption at rest, MongoDB data should be encrypted on each host using file-system, device, - or physical encryption (e.g. dm-crypt). Protect MongoDB data - using file-system permissions. MongoDB data includes data files, - configuration files, auditing logs, and key files. - -- Collect logs to a central log store. These logs contain DB - authentication attempts including source IP address. - - + or physical encryption (for example dm-crypt). You should also protect + MongoDB data using file-system permissions. MongoDB data includes data + files, configuration files, auditing logs, and key files. + +- You can use :doc:`/core/security-client-side-encryption` to encrypt + fields in documents application-side prior to transmitting data over + the wire to the server. + +- Collect logs to a central log store. These logs contain database + authentication attempts including source IP addresses. + |arrow| Limit Network Exposure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -111,25 +115,19 @@ Pre-production Checklist/Considerations - Allow only trusted clients to access the network interfaces and ports on which MongoDB instances are available. - .. note:: - - .. include:: /includes/fact-default-bind-ip-change.rst +.. seealso:: - | + - :doc:`/core/security-hardening` - See also: + - the :setting:`net.bindIp` configuration setting - - :doc:`/core/security-hardening` + - the :setting:`security.clusterIpSourceAllowlist` configuration + setting - - the :setting:`net.bindIp` configuration setting - - - the :setting:`security.clusterIpSourceAllowlist` configuration - setting - - - the :ref:`authenticationRestrictions - ` field to the - :method:`db.createUser()` command to specify a per-user IP - allow list. + - the :ref:`authenticationRestrictions + ` field to the + :method:`db.createUser()` command to specify a per-user IP + allow list. |arrow| Audit System Activity @@ -137,21 +135,19 @@ Pre-production Checklist/Considerations - Track access and changes to database configurations and data. `MongoDB Enterprise - `_ + `_ includes a system auditing facility that can record - system events (e.g. user operations, connection events) on a + system events (including user operations and connection events) on a MongoDB instance. These audit records permit forensic analysis - and allow administrators to verify proper controls. You can set - up filters to record specific events, such as authentication + and allow administrators to exercise proper controls. You can set + up filters to record only specific events, such as authentication events. - | - - See also: +.. seealso:: - - :doc:`/core/auditing` + - :doc:`/core/auditing` - - :doc:`/tutorial/configure-auditing` + - :doc:`/tutorial/configure-auditing` |arrow| Run MongoDB with a Dedicated User ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -160,9 +156,9 @@ Pre-production Checklist/Considerations account. Ensure that the account has permissions to access data but no unnecessary permissions. - | +.. seealso:: - See also: :doc:`/installation` + :doc:`/installation` .. _security-checklist-javascript: @@ -173,17 +169,16 @@ Pre-production Checklist/Considerations server-side operations: :dbcommand:`mapReduce`, :query:`$where`, :group:`$accumulator`, and :expression:`$function`. If you do not use these operations, disable server-side scripting by using - the :option:`--noscripting ` option on the - command line. + the :option:`--noscripting ` option. - Keep input validation enabled. MongoDB enables input validation by default through the :setting:`net.wireObjectCheck` setting. This ensures that all documents stored by the :binary:`~bin.mongod` instance are valid :term:`BSON`. - | +.. seealso:: - See also: :doc:`/core/security-hardening` + :doc:`/core/security-hardening` |arrow| Request a Security Technical Implementation Guide (where applicable) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -191,9 +186,7 @@ Pre-production Checklist/Considerations - The Security Technical Implementation Guide (STIG) contains security guidelines for deployments within the United States Department of Defense. MongoDB Inc. provides its STIG, upon - request, for situations where it is required. Please `request a - copy `_ for - more information. + `request `_. |arrow| Consider Security Standards Compliance ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -201,7 +194,7 @@ Pre-production Checklist/Considerations - For applications requiring HIPAA or PCI-DSS compliance, please refer to the `MongoDB Security Reference Architecture `_ - to learn more about how you can use the key security + to learn more about how you can use MongoDB's key security capabilities to build compliant application infrastructure. @@ -213,15 +206,14 @@ Periodic/Ongoing Production Checks - Consult the `MongoDB end of life dates `_ and upgrade your - MongoDB installation. In general, try to stay on the latest + MongoDB installation as needed. In general, try to stay on the latest version. - Ensure that your information security management system policies and procedures extend to your MongoDB installation, including performing the following: - - Periodically apply patches to your machine and review - guidelines. + - Periodically apply patches to your machine. - Review policy/procedure changes, especially changes to your network rules to prevent inadvertent MongoDB exposure to the diff --git a/source/aggregation.txt b/source/aggregation.txt index 2088b42a5f5..ab352d80cbc 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -10,39 +10,41 @@ Aggregation :depth: 1 :class: singlecol -Aggregation operations process data records and return computed -results. Aggregation operations group values from multiple documents -together, and can perform a variety of operations on the grouped data -to return a single result. MongoDB provides three ways to perform -aggregation: the :ref:`aggregation pipeline -`, the :ref:`map-reduce function -`, and :ref:`single purpose aggregation methods -`. +Aggregation operations process multiple documents and return computed +results. You can use aggregation operations to: + +- Group values from multiple documents together. + +- Perform operations on the grouped data to return a single result. + +- Analyze data changes over time. + +To perform aggregation operations, you can use: + +- :ref:`Aggregation pipelines ` + +- :ref:`Single purpose aggregation methods + ` + +- :ref:`Map-reduce functions ` .. _aggregation-framework: -Aggregation Pipeline --------------------- +Aggregation Pipelines +--------------------- -MongoDB's :doc:`aggregation framework -` is modeled on the concept of data -processing pipelines. Documents enter a multi-stage pipeline that -transforms the documents into an aggregated result. For example: +.. include:: /includes/aggregation-pipeline-introduction.rst -.. code-block:: javascript +Aggregation Pipeline Example +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - db.orders.aggregate([ - { $match: { status: "A" } }, - { $group: { _id: "$cust_id", total: { $sum: "$amount" } } } - ]) +.. include:: /includes/aggregation-pipeline-example.rst -**First Stage**: The :pipeline:`$match` stage filters the documents by -the ``status`` field and passes to the next stage those documents that -have ``status`` equal to ``"A"``. +For a runnable example, see :ref:`Complete Aggregation Pipeline +Example `. -**Second Stage**: The :pipeline:`$group` stage groups the documents by -the ``cust_id`` field to calculate the sum of the amount for each -unique ``cust_id``. +Aggregation Pipeline Stages and Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The most basic pipeline stages provide *filters* that operate like queries and *document transformations* that modify the form diff --git a/source/changeStreams.txt b/source/changeStreams.txt index f55a0a657db..33fe9ab02b8 100644 --- a/source/changeStreams.txt +++ b/source/changeStreams.txt @@ -49,8 +49,10 @@ Change streams are available for :doc:`replica sets ` and .. include:: /includes/extracts/changestream-rc-majority-4.2.rst -Watch Collection/Database/Deployment ------------------------------------- +.. _changeStreams-watch-deployment: + +Watch a Collection, Database, or Deployment +------------------------------------------- You can open change streams against: diff --git a/source/core/aggregation-pipeline.txt b/source/core/aggregation-pipeline.txt index 8e75bf415f7..e9a3baafa52 100644 --- a/source/core/aggregation-pipeline.txt +++ b/source/core/aggregation-pipeline.txt @@ -1,4 +1,4 @@ -.. _aggregation-top-level-server: +.. _aggregation-pipeline: ==================== Aggregation Pipeline @@ -12,65 +12,88 @@ Aggregation Pipeline :depth: 1 :class: singlecol -The aggregation pipeline is a framework for data aggregation modeled -on the concept of data processing pipelines. Documents enter a -multi-stage pipeline that transforms the documents into aggregated -results. For example: +.. include:: /includes/aggregation-pipeline-introduction.rst + +.. _aggregation-pipeline-example: + +Complete Aggregation Pipeline Example +------------------------------------- + +Create the following collection that contains orders for products: .. code-block:: javascript - db.orders.aggregate([ - { $match: { status: "A" } }, - { $group: { _id: "$cust_id", total: { $sum: "$amount" } } } - ]) + db.orders.insertMany( [ + { _id: 0, productName: "Steel beam", status: "new", quantity: 10 }, + { _id: 1, productName: "Steel beam", status: "urgent", quantity: 20 }, + { _id: 2, productName: "Steel beam", status: "urgent", quantity: 30 }, + { _id: 3, productName: "Iron rod", status: "new", quantity: 15 }, + { _id: 4, productName: "Iron rod", status: "urgent", quantity: 50 }, + { _id: 5, productName: "Iron rod", status: "urgent", quantity: 10 } + ] ) -**First Stage**: The :pipeline:`$match` stage filters the documents by -the ``status`` field and passes to the next stage those documents that -have ``status`` equal to ``"A"``. +.. include:: /includes/aggregation-pipeline-example.rst -**Second Stage**: The :pipeline:`$group` stage groups the documents by -the ``cust_id`` field to calculate the sum of the amount for each -unique ``cust_id``. +Example output: -.. _aggregation-pipeline: +.. code-block:: javascript + :copyable: false -Pipeline --------- + [ + { _id: 'Steel beam', sumQuantity: 50 }, + { _id: 'Iron rod', sumQuantity: 60 } + ] -The MongoDB aggregation pipeline consists of :ref:`stages -`. Each stage transforms the -documents as they pass through the pipeline. Pipeline stages do not need -to produce one output document for every input document. For example, -some stages may generate new documents or filter out documents. +.. seealso:: -Pipeline stages can appear multiple times in the pipeline with the -exception of :pipeline:`$out`, :pipeline:`$merge`, and -:pipeline:`$geoNear` stages. For a list -of all available stages, see -:ref:`aggregation-pipeline-operator-reference`. + - :doc:`/tutorial/aggregation-with-user-preference-data` + - :doc:`/tutorial/aggregation-zip-code-data-set` + - :doc:`/tutorial/update-documents-with-aggregation-pipeline` -MongoDB provides the :method:`db.collection.aggregate()` shell method -and the :dbcommand:`aggregate` command to run the aggregation pipeline. +.. _aggregation-pipeline-stages: -For example usage of the aggregation pipeline, consider -:doc:`/tutorial/aggregation-with-user-preference-data` and -:doc:`/tutorial/aggregation-zip-code-data-set`. +Aggregation Pipeline Stages +--------------------------- -Starting in MongoDB 4.2, you can use the aggregation pipeline for -updates in: +An aggregation pipeline consists of one or more :ref:`stages +` that process documents: + +- Each stage transforms the documents as they pass through the pipeline. -.. include:: /includes/table-update-with-aggregation-availability.rst +- A stage does not have to output one document for every input + document. For example, some stages may produce new documents or + filter out documents. -.. seealso:: +- The same stage can appear multiple times in the pipeline with these + stage exceptions: :pipeline:`$out`, :pipeline:`$merge`, and + :pipeline:`$geoNear`. + +- For all available stages, see + :ref:`aggregation-pipeline-operator-reference`. + +Run an Aggregation Pipeline +--------------------------- + +To run an aggregation pipeline, use: - :doc:`/tutorial/update-documents-with-aggregation-pipeline` +- :method:`db.collection.aggregate()` or -.. _aggregation-pipeline-expressions: +- :dbcommand:`aggregate` + +Update Documents Using an Aggregation Pipeline +---------------------------------------------- + +Starting in MongoDB 4.2, you can use the aggregation pipeline to update +documents using these methods: + +.. include:: /includes/table-update-with-aggregation-availability.rst + .. _aggregation-pipeline-expressions: + Pipeline Expressions -------------------- -Some pipeline stages take a pipeline expression as the operand. +Some pipeline stages accept a pipeline expression as the operand. Pipeline expressions specify the transformation to apply to the input documents. Expressions have a :doc:`document ` structure and can contain other :ref:`expression diff --git a/source/core/authentication-mechanisms-enterprise.txt b/source/core/authentication-mechanisms-enterprise.txt deleted file mode 100644 index d4f02d35bc5..00000000000 --- a/source/core/authentication-mechanisms-enterprise.txt +++ /dev/null @@ -1,89 +0,0 @@ -==================================== -Enterprise Authentication Mechanisms -==================================== - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -In addition to the authentication mechanisms offered in MongoDB -Community, MongoDB Enterprise provides integration with the following -external authentication mechanisms. - -.. _security-auth-kerberos: - -Kerberos Authentication ------------------------ - -`MongoDB Enterprise `_ -supports authentication using a Kerberos service. Kerberos is an industry -standard authentication protocol for large client/server systems. - -To use MongoDB with Kerberos, you must have a properly configured -Kerberos deployment, configured :ref:`Kerberos service principals -` for MongoDB, and added :ref:`Kerberos -user principal ` to MongoDB. - -For more information on Kerberos and MongoDB, see: - -- :doc:`/core/kerberos`, - -- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` and - -- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`. - -.. _security-auth-ldap: - -LDAP Proxy Authentication -------------------------- - - -`MongoDB Enterprise -`_ supports -proxy authentication through a Lightweight Directory Access Protocol -(LDAP) service. - -.. versionchanged:: 3.4 - - MongoDB 3.4 supports using operating system libraries instead of the - `saslauthd `_ - daemon, allowing MongoDB 3.4 servers running on Linux and Microsoft Windows - to connect to LDAP servers. Linux MongoDB deployments continue to support - ``saslauthd``. - -Previous versions of MongoDB support authentication against an LDAP server -using simple and SASL binding via ``saslauthd``. This restricted LDAP -authentication support to only Linux MongoDB deployments. - -See :doc:`/core/security-ldap` for more information. - -LDAP Authorization -~~~~~~~~~~~~~~~~~~ - -.. versionadded:: 3.4 - -MongoDB Enterprise supports querying an LDAP server for the LDAP groups the -authenticated user is a member of. MongoDB maps the Distinguished Names (DN) -of each returned group to :ref:`roles ` on the ``admin`` database. -MongoDB authorizes the user based on the mapped roles and their associated -privileges. See :ref:`LDAP Authorization ` for more -information. - -.. seealso:: - - - :doc:`/core/security-ldap` - - :doc:`/tutorial/configure-ldap-sasl-openldap` - - :doc:`/tutorial/configure-ldap-sasl-activedirectory` - -.. toctree:: - :titlesonly: - :hidden: - - /core/kerberos - /core/security-ldap - /core/security-ldap-external - diff --git a/source/core/authentication-mechanisms.txt b/source/core/authentication-mechanisms.txt deleted file mode 100644 index 2a58a277451..00000000000 --- a/source/core/authentication-mechanisms.txt +++ /dev/null @@ -1,57 +0,0 @@ -.. _security-authentication-mechanisms: - -========================= -Authentication Mechanisms -========================= - -.. default-domain:: mongodb - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. note:: - - Starting in version 4.0, MongoDB removes support for the deprecated - MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. - -MongoDB supports the following authentication mechanisms: - -- :doc:`/core/security-scram` (*Default*) - -- :doc:`x.509 Certificate Authentication `. - -In addition, MongoDB Enterprise provides integration with a number of -external authentication mechanisms, including Kerberos and LDAP. See -:doc:`/core/authentication-mechanisms-enterprise` for the additional -authentication mechanisms supported by MongoDB Enterprise. - -.. _authentication-mechanism-default: - -Default Authentication Mechanism --------------------------------- - -As of MongoDB 3.0, :ref:`Salted Challenge Response Authentication -Mechanism (SCRAM) ` is the default -authentication mechanism for MongoDB. - - -Specify Authentication Mechanism --------------------------------- - -To specify the authentication mechanism to use, set the -:parameter:`authenticationMechanisms` parameter for :binary:`~bin.mongod` and -:binary:`~bin.mongos`. - -Clients specify the authentication mechanism in the :method:`db.auth()` method. -For :binary:`~bin.mongosh` and the MongoDB tools, you can also specify the -authentication mechanism from the command line. - -.. toctree:: - :titlesonly: - :hidden: - - /core/security-scram - /core/security-x.509 diff --git a/source/core/authentication.txt b/source/core/authentication.txt index e5c53de6428..d4230bc36ab 100644 --- a/source/core/authentication.txt +++ b/source/core/authentication.txt @@ -12,46 +12,119 @@ Authentication :depth: 1 :class: singlecol -Authentication is the process of verifying the identity of a client. When -access control, i.e. :doc:`authorization `, is enabled, -MongoDB requires all clients to authenticate themselves in order to determine -their access. +Authentication is the process of verifying the identity of a client. +When access control (:doc:`authorization `) is +enabled, MongoDB requires all clients to authenticate themselves in +order to determine their access. -Although authentication and :doc:`authorization ` are -closely connected, authentication is distinct from authorization. -Authentication verifies the identity of a user; authorization determines the -verified user's access to resources and operations. +Although authentication and :doc:`authorization ` +are closely connected, authentication is distinct from authorization: -Authentication Methods ----------------------- +- **Authentication** verifies the identity of a :ref:`user `. +- **Authorization** determines the verified user's access to resources + and operations. -.. include:: /includes/fact-authenticate.rst +Getting Started +--------------- + +To get started using access control, follow these tutorials: + +- :ref:`enable-access-control` +- :ref:`create-users` +- :ref:`authentication-auth-as-user` .. _available-authentication-mechanisms: +.. _security-authentication-mechanisms: Authentication Mechanisms ------------------------- -MongoDB supports a number of :ref:`authentication mechanisms -` that clients can use to verify -their identity. These mechanisms allow MongoDB to integrate into your -existing authentication system. +.. _authentication-mechanism-default: + +SCRAM Authentication +~~~~~~~~~~~~~~~~~~~~ + +:doc:`Salted Challenge Response Authentication Mechanism (SCRAM) +` is the default authentication mechanism for +MongoDB. + +For more information on SCRAM and MongoDB, see: + +- :doc:`SCRAM Authentication ` +- :ref:`scram-client-authentication` + +.. _authentication-mechanism-x509: + +x.509 Certificate Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MongoDB supports :doc:`x.509 certificate authentication +` for client authentication and internal +authentication of the members of replica sets and sharded clusters. +x.509 certificate authentication requires a secure :doc:`TLS/SSL +connection `. + +To use MongoDB with x.509, you must use valid certificates generated and +signed by a certificate authority. The client x.509 certificates +must meet the :ref:`client certificate requirements +`. + +For more information on x.509 and MongoDB, see: + +- :doc:`x.509 Certificate Authentication ` +- :ref:`x509-client-authentication` -MongoDB supports multiple authentication mechanisms: +.. _security-auth-kerberos: -- :ref:`authentication-scram` (*Default*) +Kerberos Authentication +~~~~~~~~~~~~~~~~~~~~~~~ -- :ref:`x.509 Certificate Authentication `. +`MongoDB Enterprise +`_ +and `MongoDB Atlas +`__ support +:doc:`Kerberos Authentication `. Kerberos is an industry +standard authentication protocol for large client/server systems that +provides authentication using short-lived tokens that are called +tickets. -In addition to supporting the aforementioned mechanisms, MongoDB Enterprise -also supports the following mechanisms: +To use MongoDB with Kerberos, you must have a properly configured +Kerberos deployment, configured :ref:`Kerberos service principals +` for MongoDB, and a :ref:`Kerberos user +principal ` added to MongoDB. -- :ref:`LDAP proxy authentication `, and +For more information on Kerberos and MongoDB, see: -- :ref:`Kerberos authentication `. +- :doc:`Kerberos Authentication ` +- :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` +- :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication` -Internal Authentication ------------------------ +.. _security-auth-ldap: + +LDAP Proxy Authentication +~~~~~~~~~~~~~~~~~~~~~~~~~ + +`MongoDB Enterprise +`_ +and `MongoDB Atlas +`__ support +:doc:`LDAP Proxy Authentication ` proxy +authentication through a Lightweight Directory Access Protocol (LDAP) +service. + +For more information on Kerberos and MongoDB, see: + +- :doc:`LDAP Proxy Authentication ` +- :doc:`/tutorial/configure-ldap-sasl-activedirectory` +- :doc:`/tutorial/configure-ldap-sasl-openldap` +- :doc:`/tutorial/authenticate-nativeldap-activedirectory` + +These mechanisms allow MongoDB to integrate into your +existing authentication system. + + +Internal / Membership Authentication +------------------------------------ In addition to verifying the identity of a client, MongoDB can require members of replica sets and sharded clusters to :ref:`authenticate @@ -59,19 +132,14 @@ their membership ` to their respective replica set or sharded cluster. See :ref:`inter-process-auth` for more information. -Authentication on Sharded Clusters ----------------------------------- - -In sharded clusters, clients generally authenticate directly to the -:binary:`~bin.mongos` instances. However, some maintenance operations may require -authenticating directly to a specific shard. For more information on -authentication and sharded clusters, see :ref:`sharding-security`. - .. toctree:: :titlesonly: :hidden: - /core/security-users - /core/authentication-mechanisms - /core/authentication-mechanisms-enterprise + /core/security-scram + /core/security-x.509 + /core/kerberos + /core/security-ldap /core/security-internal-authentication + /core/localhost-exception + /core/security-users diff --git a/source/core/authorization.txt b/source/core/authorization.txt index 45ad2fbe4e4..9e3d13d2f4a 100644 --- a/source/core/authorization.txt +++ b/source/core/authorization.txt @@ -103,6 +103,16 @@ If these built-in-roles cannot provide the desired set of privileges, MongoDB provides methods to create and modify :doc:`user-defined roles `. +LDAP Authorization +------------------ + +MongoDB Enterprise supports querying an LDAP server for the LDAP groups the +authenticated user is a member of. MongoDB maps the Distinguished Names (DN) +of each returned group to :ref:`roles ` on the ``admin`` database. +MongoDB authorizes the user based on the mapped roles and their associated +privileges. See :ref:`LDAP Authorization ` for more +information. + .. toctree:: :titlesonly: :hidden: @@ -112,3 +122,4 @@ MongoDB provides methods to create and modify :doc:`user-defined roles /tutorial/manage-users-and-roles /tutorial/change-own-password-and-custom-data /core/collection-level-access-control + /core/security-ldap-external diff --git a/source/core/capped-collections.txt b/source/core/capped-collections.txt index 97af39f65a1..79e88ec5ae8 100644 --- a/source/core/capped-collections.txt +++ b/source/core/capped-collections.txt @@ -48,6 +48,8 @@ result, queries do not need an index to return documents in insertion order. Without this indexing overhead, capped collections can support higher insertion throughput. +.. _capped_collections_remove_documents: + Automatic Removal of Oldest Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/core/document.txt b/source/core/document.txt index b0761476f9c..605220c32d4 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -199,6 +199,37 @@ Document Size Limit Document Field Order ~~~~~~~~~~~~~~~~~~~~ +Unlike JavaScript objects, the fields in a BSON document are ordered. + +Field Order in Queries +`````````````````````` + +For queries, the field order behavior is as follows: + +- When comparing documents, field ordering is significant. For + example, when comparing documents with fields ``a`` and ``b`` in a + query: + + - ``{a: 1, b: 1}`` is equal to ``{a: 1, b: 1}`` + + - ``{a: 1, b: 1}`` is not equal to ``{b: 1, a: 1}`` + +- For efficient query execution, the query engine may reorder fields + during query processing. Among other cases, reordering fields may + occur when processing these projection operators: + :pipeline:`$project`, :pipeline:`$addFields`, :pipeline:`$set`, and + :pipeline:`$unset`. + + - Field reordering may occur in intermediate results as well as the + final results returned by a query. + + - Because some operations may reorder fields, you should not rely on + specific field ordering in the results returned by a query that + uses the projection operators listed earlier. + +Field Order in Write Operations +``````````````````````````````` + .. include:: /includes/fact-update-field-order.rst :start-after: order-of-document-fields diff --git a/source/core/hashed-sharding.txt b/source/core/hashed-sharding.txt index adb2004a32a..f5a399e9267 100644 --- a/source/core/hashed-sharding.txt +++ b/source/core/hashed-sharding.txt @@ -10,7 +10,7 @@ Hashed Sharding Hashed sharding uses either a :ref:`single field hashed index ` or a :ref:`compound hashed index ` (*New in 4.4*) as the shard key to -partition data across your cluster. +partition data across your sharded cluster. Sharding on a Single Field Hashed Index Hashed sharding provides a more even data distribution across the diff --git a/source/core/index-partial.txt b/source/core/index-partial.txt index 5805f64981a..eb3c8346160 100644 --- a/source/core/index-partial.txt +++ b/source/core/index-partial.txt @@ -162,17 +162,11 @@ by the filter expression Restrictions ------------ -In MongoDB, you cannot create multiple versions of an index that -differ only in the options. As such, you cannot create multiple -partial indexes that differ only by the filter expression. +.. include:: /includes/fact-5.0-multiple-partial-index.rst You cannot specify both the ``partialFilterExpression`` option and the ``sparse`` option. -MongoDB 3.0 or earlier do not support partial indexes. To use partial -indexes, you must use MongoDB version 3.2 or higher. For sharded -clusters or replica sets, all nodes must be version 3.2 or higher. - ``_id`` indexes cannot be partial indexes. Shard key indexes cannot be partial indexes. diff --git a/source/core/index-ttl.txt b/source/core/index-ttl.txt index b636a818af6..c21b185f467 100644 --- a/source/core/index-ttl.txt +++ b/source/core/index-ttl.txt @@ -57,8 +57,9 @@ If the field is an array, and there are multiple date values in the index, MongoDB uses *lowest* (i.e. earliest) date value in the array to calculate the expiration threshold. -If the indexed field in a document is not a :term:`date ` -or an array that holds a date value(s), the document will not expire. +If the indexed field in a document is not a +:ref:`date ` or an array that holds one or +more date values, the document will not expire. If a document does not contain the indexed field, the document will not expire. diff --git a/source/core/localhost-exception.txt b/source/core/localhost-exception.txt new file mode 100644 index 00000000000..a34955dee50 --- /dev/null +++ b/source/core/localhost-exception.txt @@ -0,0 +1,67 @@ +.. _localhost-exception: + +=================== +Localhost Exception +=================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. important:: + + On a :binary:`~bin.mongod` instance, the localhost exception only + applies when there are **no users or roles** created in the MongoDB + instance. + +The localhost exception allows you to enable access control and then +create the first user or role in the system. After you enable access +control, connect to the localhost interface and create the first user in +the ``admin`` database. + +If you create a user first, the user must have privileges to create +other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. + +.. warning:: + + Connections using the localhost exception have access to create + *only* the **first user or role**. + + Once you create any user or role, the localhost exception is + disabled. If you need to create a user and a role, you must create + the user first using one of the builtin :authrole:`userAdmin` or + :authrole:`userAdminAnyDatabase` roles. If you create a role first, + you won't be able to create a user. + +The ability to create a role first with the :method:`db.createRole()` +method is specifically for users authorizing with LDAP. See :ref:`LDAP +Authorization ` for more information. + +Localhost Exception for Sharded Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. important:: + + - On a :binary:`~bin.mongos`, the localhost exception only applies + when there are no :ref:`sharded cluster users ` + or roles created. + - In a sharded cluster, the localhost exception applies to each shard + individually as well as to the cluster as a whole. + +Once you create a sharded cluster and add a :ref:`user administrator +` through the :binary:`~bin.mongos` instance, you +**must** still prevent unauthorized access to the individual shards. To +prevent unauthorized access to individual shards, follow one of the +following steps for each shard in your cluster: + +- :ref:`Create a user administrator ` on the shard's + primary. +- Disable the localhost exception at startup. To disable the localhost + exception, set the :parameter:`enableLocalhostAuthBypass` parameter to + ``0``. diff --git a/source/core/replica-set-delayed-member.txt b/source/core/replica-set-delayed-member.txt index bdd5a61c384..df8406cba12 100644 --- a/source/core/replica-set-delayed-member.txt +++ b/source/core/replica-set-delayed-member.txt @@ -39,11 +39,16 @@ Delayed members: members. Set the priority to 0 to prevent a delayed member from becoming primary. -- **Should be** :ref:`hidden ` +- **Must be** :ref:`hidden ` members. Always prevent applications from seeing and querying delayed members. -- *Do* vote in :term:`elections ` for primary, if :rsconf:`members[n].votes` is set to 1. +- *Do* vote in :term:`elections ` for primary, if + :rsconf:`members[n].votes` is set to 1. Ensuring that delayed members + are non-voting by setting :rsconf:`members[n].votes` to 0 can help + improve performance. + +.. include:: /includes/important-delayed-replica-set-members.rst Behavior ~~~~~~~~ diff --git a/source/core/replica-set-hidden-member.txt b/source/core/replica-set-hidden-member.txt index e26261655ab..3fd2d10e999 100644 --- a/source/core/replica-set-hidden-member.txt +++ b/source/core/replica-set-hidden-member.txt @@ -39,8 +39,10 @@ Clients will not distribute reads with the appropriate :doc:`read preference ` to hidden members. As a result, these members receive no traffic other than basic replication. Use hidden members for dedicated tasks such as reporting and -backups. :doc:`Delayed members ` -should be hidden. +backups. + +.. include:: /includes/important-delayed-replica-set-members.rst + In a sharded cluster, :binary:`~bin.mongos` do not interact with hidden members. diff --git a/source/core/replica-set-rollbacks.txt b/source/core/replica-set-rollbacks.txt index 87eacaf6a0a..c7dd6f32596 100644 --- a/source/core/replica-set-rollbacks.txt +++ b/source/core/replica-set-rollbacks.txt @@ -171,25 +171,26 @@ administrators can decide the next course of action to take. Avoid Replica Set Rollbacks --------------------------- -For replica sets, the :doc:`write concern {w: 1} -` only provides acknowledgement of write -operations on the primary. With the default write concern, data may be -rolled back if the primary steps down before the write operations have -replicated to any of the secondaries. This includes data written in -:doc:`multi-document transactions ` that commit -using :writeconcern:`"w: 1" <\>` write concern. - -.. include:: /includes/5.0-default-wc.rst +For replica sets, the :doc:`write concern ` +:writeconcern:`{ w: 1 } <\>` only provides acknowledgement of write +operations on the primary. Data may be rolled back if the primary steps +down before the write operations have replicated to any of the +secondaries. This includes data written in :doc:`multi-document +transactions ` that commit using +:writeconcern:`{ w: 1 } <\>` write concern. Journaling and Write Concern ``majority`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To prevent rollbacks of data that have been acknowledged to the client, -run all voting members with journaling enabled and use :ref:`w: -majority write concern ` to guarantee that the write operations +run all voting members with journaling enabled and use :ref:`{ w: +"majority" } write concern ` to guarantee that the write operations propagate to a majority of the replica set nodes before returning with acknowledgement to the issuing client. +Starting in MongoDB 5.0, ``{ w: "majority" }`` is the default write concern +for *most* MongoDB deployments. See :ref:`wc-default-behavior`. + .. include:: /includes/extracts/no-journaling-rollback.rst Visibility of Data That Can Be Rolled Back diff --git a/source/core/schema-validation.txt b/source/core/schema-validation.txt index dc64954c9c8..bc12c844528 100644 --- a/source/core/schema-validation.txt +++ b/source/core/schema-validation.txt @@ -17,6 +17,8 @@ Schema Validation MongoDB provides the capability to perform schema validation during updates and insertions. +.. _schema-validation-document: + Specify Validation Rules ------------------------ diff --git a/source/core/security-internal-authentication.txt b/source/core/security-internal-authentication.txt index 2066e0c73d7..bb1b0634f27 100644 --- a/source/core/security-internal-authentication.txt +++ b/source/core/security-internal-authentication.txt @@ -67,7 +67,7 @@ For example, .. tabs:: tabs: - + - id: single-key name: Single key content: | @@ -175,10 +175,10 @@ see :doc:`/tutorial/upgrade-keyfile-to-x509`. /tutorial/deploy-replica-set-with-keyfile-access-control /tutorial/enforce-keyfile-access-control-in-existing-replica-set /tutorial/enforce-keyfile-access-control-in-existing-replica-set-without-downtime - /tutorial/rotate-key-replica-set /tutorial/deploy-sharded-cluster-with-keyfile-access-control /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster /tutorial/enforce-keyfile-access-control-in-existing-sharded-cluster-no-downtime + /tutorial/rotate-key-replica-set /tutorial/rotate-key-sharded-cluster /tutorial/configure-x509-member-authentication /tutorial/upgrade-keyfile-to-x509 diff --git a/source/core/security-scram.txt b/source/core/security-scram.txt index aea924f3d1b..dbab88bcbff 100644 --- a/source/core/security-scram.txt +++ b/source/core/security-scram.txt @@ -1,7 +1,5 @@ .. _authentication-scram: - - ===== SCRAM ===== @@ -14,33 +12,22 @@ SCRAM :depth: 1 :class: singlecol -.. note:: +Salted Challenge Response Authentication Mechanism (SCRAM) is the +default authentication mechanism for MongoDB. - Starting in version 4.0, MongoDB removes support for the deprecated - MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. +When a user :ref:`authenticates ` +themselves, MongoDB uses SCRAM to verify the supplied user credentials +against the user's :data:`name `, +:data:`password ` and +:data:`authentication database `. - If your deployment has user credentials stored in ``MONGODB-CR`` - schema, you must upgrade to SCRAM **before** you upgrade to version - 4.0. For information on upgrading to ``SCRAM``, see - :doc:`/release-notes/3.0-scram`. - -Salted Challenge Response Authentication Mechanism (SCRAM) is the -default authentication mechanism for MongoDB. SCRAM is based on the -IETF `RFC 5802 `_ standard that -defines best practices for implementation of challenge-response -mechanisms for authenticating users with passwords. - -Using SCRAM, MongoDB verifies the supplied user credentials against the -user's :data:`name `, :data:`password -` and :data:`authentication database -`. The authentication database is the database -where the user was created, and together with the user's name, serves -to identify the user. +SCRAM is based on the IETF `RFC 5802 +`_ standard that defines best +practices for the implementation of challenge-response mechanisms for +authenticating users with passwords. .. _authentication-scram-sha-1: - .. _authentication-scram-sha-256: - .. _scram-features: Features @@ -48,12 +35,9 @@ Features MongoDB's implementation of SCRAM provides: -- A tunable work factor (i.e. the iteration count), - -- Per-user random salts, and - -- Authentication of the server to the client as well as the client to the - server. +- A tunable work factor (the iteration count) +- Per-user random salts +- Bi-directional authentication between server and client .. _scram-mechanisms: @@ -69,35 +53,34 @@ MongoDB supports the following SCRAM mechanisms: * - SCRAM Mechanism - Description - * - ``SCRAM-SHA-1`` + * - ``SCRAM-SHA-1`` - Uses the SHA-1 hashing function. To modify the iteration count for ``SCRAM-SHA-1``, see :parameter:`scramIterationCount`. - * - ``SCRAM-SHA-256`` + * - ``SCRAM-SHA-256`` - - Uses the SHA-256 hashing function and requires - featureCompatibilityVersion (``fcv``) set to ``4.0``. + - Uses the SHA-256 hashing function. To modify the iteration count for ``SCRAM-SHA-256``, see :parameter:`scramSHA256IterationCount`. - .. versionadded:: 4.0 -When creating or updating a SCRAM user, you can indicate the specific -SCRAM mechanism as well as indicate whether the server or the client -digests the password. When using ``SCRAM-SHA-256``, MongoDB requires -server-side password hashing, i.e. the server digests the password. For -details, see :method:`db.createUser()` and :method:`db.updateUser()`. +When you create or update a SCRAM user, you can indicate: + +- the SCRAM mechanism to use +- whether the server or the client digests the password + +When you use ``SCRAM-SHA-256``, MongoDB requires server-side password +hashing, which means that the server digests the password. For more +information, see :method:`db.createUser()` and +:method:`db.updateUser()`. Driver Support -------------- -To use SCRAM, you must upgrade your driver if your current driver -version does not support ``SCRAM``. - The minimum driver versions that support ``SCRAM`` are: .. |driver-compatibility-heading| replace:: Version @@ -107,12 +90,16 @@ The minimum driver versions that support ``SCRAM`` are: Additional Information ---------------------- -- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM - Explained (Part 1) +- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 1) `_ -- `Blog Post: Improved Password-Based Authentication in MongoDB 3.0: SCRAM - Explained (Part 2) +- `Blog Post: Improved Password-Based Authentication: SCRAM Explained (Part 2) `_ + +.. toctree:: + :titlesonly: + :hidden: + + /tutorial/configure-scram-client-authentication diff --git a/source/core/security-users.txt b/source/core/security-users.txt index b1ca89cf9cb..4ac929a0021 100644 --- a/source/core/security-users.txt +++ b/source/core/security-users.txt @@ -10,90 +10,88 @@ Users .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -To authenticate a client in MongoDB, you must add a corresponding user to -MongoDB. +To authenticate a client in MongoDB, you must add a corresponding user +to MongoDB. +User Management +--------------- -User Management Interface -------------------------- +You can add a user with the :method:`db.createUser()` method using +:binary:`~bin.mongosh`. The first user you create must have privileges +to create other users. The :authrole:`userAdmin` or +:authrole:`userAdminAnyDatabase` role both confer the privilege to +create other users. -To add a user, MongoDB provides the :method:`db.createUser()` method. -When adding a user, you can assign :doc:`roles ` to -the user in order to grant privileges. - -.. note:: +.. seealso:: - The first user created in the database should be a user administrator - who has the privileges to manage other users. See - :doc:`/tutorial/enable-authentication`. + :doc:`/tutorial/create-users` -You can also update existing users, such as to change password and grant -or revoke roles. For a full list of user management methods, see +You can grant a user privileges by assinging :doc:`roles +` to the user when you create the user. You can +also grant or revoke roles, as well as update passwords, by updating +existing users. For a full list of user management methods, see :ref:`user-management-methods`. +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` + A user is uniquely identified by the user's name and associated -authentication database. Starting in MongoDB 4.0.9, a users managed by -MongoDB are assigned a unique ``userId``. [#userid]_ +:ref:`authentication database `. MongoDB +associates a user with a unique ``userId`` upon creation in MongoDB. + +LDAP Managed Users +~~~~~~~~~~~~~~~~~~ + +:ref:`LDAP managed users ` created on an LDAP +server do not have an associated document in the :doc:`system.users +` collection, and therefore don't +have a :data:`~admin.system.users.userId` field associated with them. -.. seealso:: - :doc:`/tutorial/create-users` - .. _authentication-database: .. _user-authentication-database: Authentication Database ----------------------- -When adding a user, you create the user in a specific database. This -database is the authentication database for the user. - -A user can have privileges across different databases; that is, a user's -privileges are not limited to their authentication database. By assigning -to the user roles in other databases, a user created in one database can -have permissions to act on other databases. For more information on -roles, see :doc:`/core/authorization`. - -The user's name and authentication database serve as a unique identifier -for that user. [#userid]_ That is, if two users have the same name but are created -in different databases, they are two separate users. If you intend to -have a single user with permissions on multiple databases, create a -single user with roles in the applicable databases instead of creating -the user multiple times in different databases. +When you add a user, you create the user in a specific database. The +database you create the user in is the authentication database for the +user. -.. [#userid] +However, a user's privileges are not limited to their authentication +database. Therefore, a user can have privileges across different +databases. For more information on roles, see +:doc:`/core/authorization`. - Starting in version 4.0.9, MongoDB associates a user with a unique - ``userId`` upon creation in MongoDB. - - :ref:`LDAP managed users ` created on the LDAP server - do not have an associated document in the :doc:`system.users - ` collection, and hence, do not - have a :data:`~admin.system.users.userId` field associated with them. +A user's name and authentication database serve as a unique identifier +for that user. MongoDB associates a user with a unique ``userId`` upon +creation in MongoDB. However, :ref:`LDAP managed users ` +created on an LDAP server do not have an associated document in the +:doc:`system.users ` collection, and +therefore don't have a :data:`~admin.system.users.userId` field +associated with them. -.. _authentication-auth-as-user: - -Authenticate a User -------------------- - -.. include:: /includes/fact-authenticate.rst +If two users have the same name but are created in different databases, +they are two separate users. If you want to have a single user with +permissions on multiple databases, create a single user with a role for +each applicable database. Centralized User Data --------------------- For users created in MongoDB, MongoDB stores all user information, including :data:`name `, :data:`password -`, and the :data:`user's authentication +`, and the user's :data:`authentication database `, in the :doc:`system.users ` collection in the ``admin`` database. -Do not access this collection directly but instead use the :ref:`user -management commands `. - +Do not modify this collection directly. To manage users, use the +designated :ref:`user management commands `. .. _sharding-localhost: .. _sharding-security: @@ -101,9 +99,11 @@ management commands `. Sharded Cluster Users --------------------- -To create users for a sharded cluster, connect to the -:binary:`~bin.mongos` instance and add the users. Clients then -authenticate these users through the :binary:`~bin.mongos` instances. +To create users for a sharded cluster, connect to a +:binary:`~bin.mongos` instance and add the users. To authenticate as a +user created on a :binary:`~bin.mongos` instance, you must authenticate +through a :binary:`~bin.mongos` instance. + In sharded clusters, MongoDB stores user configuration data in the ``admin`` database of the :term:`config servers `. @@ -112,62 +112,34 @@ In sharded clusters, MongoDB stores user configuration data in the Shard Local Users ~~~~~~~~~~~~~~~~~ -However, some maintenance operations, such as :dbcommand:`cleanupOrphaned`, -:dbcommand:`compact`, :method:`rs.reconfig()`, require direct connections to -specific shards in a sharded cluster. To perform these operations, you must -connect directly to the shard and authenticate as a *shard local* -administrative user. - -To create a *shard local* administrative user, connect directly to the shard -and create the user. MongoDB stores *shard local* users in the ``admin`` -database of the shard itself. - -These *shard local* users are completely independent from the users added to -the sharded cluster via :binary:`~bin.mongos`. *Shard local* users are local to the -shard and are inaccessible by :binary:`~bin.mongos`. - -Direct connections to a shard should only be for shard-specific maintenance and -configuration. In general, clients should connect to the sharded cluster -through the :binary:`~bin.mongos`. - -.. _localhost-exception: - -Localhost Exception -------------------- - -The localhost exception allows you to enable access control and then -create the first user in the system. With the localhost exception, after -you enable access control, connect to the localhost interface and create -the first user in the ``admin`` database. The first user must have -privileges to create other users, such as a user with the -:authrole:`userAdmin` or :authrole:`userAdminAnyDatabase` role. -Connections using the localhost exception *only* have access to create -the first user on the ``admin`` database. - -.. versionchanged:: 3.4 - - MongoDB 3.4 extended the localhost exception to permit execution of the - :method:`db.createRole()` method. This method allows users authorizing via - LDAP to create a role inside of MongoDB that maps to a role defined - in LDAP. See :ref:`LDAP Authorization ` for more - information. +Some maintenance operations, such as :dbcommand:`cleanupOrphaned`, +:dbcommand:`compact`, or :method:`rs.reconfig()`, require direct +connections to specific shards in a sharded cluster. To perform these +operations, you must connect directly to the shard and authenticate as a +*shard local* administrative user. -The localhost exception applies only when there are no users created in the -MongoDB instance. +To create a *shard local* administrative user, connect directly to the +primary of the shard and create the user. For instructions on how to +create a shard local user administrator see the +:doc:`/tutorial/deploy-sharded-cluster-with-keyfile-access-control` +tutorial. -In the case of a sharded cluster, the localhost exception applies to each shard -individually as well as to the cluster as a whole. Once you create a sharded -cluster and add a user administrator through the :binary:`~bin.mongos` instance, -you must still prevent unauthorized access to the individual shards. Follow one -of the following steps for each shard in your cluster: +MongoDB stores *shard local* users in the ``admin`` database of the +shard itself. These *shard local* users are independent from +the users added to the sharded cluster through a :binary:`~bin.mongos`. +*Shard local* users are local to the shard and are inaccessible by +:binary:`~bin.mongos`. -- Create an administrative user, or +Direct connections to a shard should only be used for shard-specific +maintenance and configuration or for targeted analytics workloads. In +general, clients should connect to the sharded cluster through the +:binary:`~bin.mongos`. -- Disable the localhost exception at startup. To disable the localhost - exception, set the :parameter:`enableLocalhostAuthBypass` parameter to ``0``. .. toctree:: :titlesonly: :hidden: /tutorial/create-users + /tutorial/authenticate-a-user + /tutorial/list-users diff --git a/source/core/security-x.509.txt b/source/core/security-x.509.txt index 7c6b127b030..fb55f75a576 100644 --- a/source/core/security-x.509.txt +++ b/source/core/security-x.509.txt @@ -12,17 +12,12 @@ x.509 :depth: 1 :class: singlecol -MongoDB supports x.509 certificate authentication for client authentication and -internal authentication of the members of replica sets and sharded clusters. +MongoDB supports x.509 certificate authentication for client +authentication and internal authentication of the members of replica +sets and sharded clusters. -x.509 certificate authentication requires a secure :doc:`TLS/SSL connection -`. - -.. note:: - - .. include:: /includes/fact-tls-1.0.rst - -.. |binary| replace:: MongoDB +x.509 certificate authentication requires a secure :doc:`TLS/SSL +connection `. Certificate Authority --------------------- @@ -37,6 +32,8 @@ Client x.509 Certificates To authenticate to servers, clients can use x.509 certificates instead of usernames and passwords. +.. _client-x509-certificates-requirements: + Client Certificate Requirements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -49,63 +46,21 @@ MongoDB User and ``$external`` Database To authenticate with a client certificate, you must first add the value of the ``subject`` from the client certificate as a MongoDB user. Each -unique x.509 client certificate corresponds to a single MongoDB user; -i.e. you cannot use a single client certificate to authenticate more -than one MongoDB user. +unique x.509 client certificate corresponds to a single MongoDB user. +You cannot use a single client certificate to authenticate more than one +MongoDB user. -Add the user in the ``$external`` database; i.e. the -:ref:`authentication-database` is the ``$external`` database +Add the user in the ``$external`` database. The ``$external`` database +is the :ref:`authentication-database` for the user. .. include:: /includes/extracts/sessions-external-username-limit.rst -Authenticate -~~~~~~~~~~~~ - -To connect and authenticate using x.509 client certificate: - -- For MongoDB 4.2 or greater, include the following options for the client: - - - :option:`--tls ` (or the deprecated ``--ssl`` option) - - - :option:`--tlsCertificateKeyFile ` - (or the deprecated ``--sslPEMKeyFile`` option) - - - :option:`--tlsCertificateKeyFilePassword ` - (or the deprecated ``--sslPEMKeyPassword`` option) if the - certificate key file is encrypted - - - :option:`--authenticationDatabase '$external' - ` - - - :option:`--authenticationMechanism MONGODB-X509 - ` - -- For MongoDB 4.0 and earlier, include the following options for the client: - - - ``--ssl`` - - - ``--sslPEMKeyFile`` - - - ``--sslPEMKeyPassword`` option if - the ``--sslPEMKeyFile`` is encrypted. - - - :option:`--authenticationDatabase '$external' - ` - - - :option:`--authenticationMechanism MONGODB-X509 ` - -You can also make the TLS/SSL connection first, and then use -:method:`db.auth()` in the ``$external`` database to authenticate. - -For examples of both cases, see the :ref:`authenticate-with-x509-cert` -section in :doc:`/tutorial/configure-x509-client-authentication` - Member x.509 Certificates --------------------------- +------------------------- -For internal authentication, members of sharded clusters and replica sets -can use x.509 certificates instead of keyfiles, which use the -:doc:`/core/security-scram` authentication mechanism. +For internal authentication between members of sharded clusters and +replica sets you can use x.509 certificates instead of keyfiles, which +use the :doc:`/core/security-scram` authentication mechanism. .. _x509-member-certificate-requirements: @@ -119,12 +74,6 @@ MongoDB Configuration for Membership Authentication .. include:: /includes/extracts/x509-member-auth-configuration.rst -Next Steps -~~~~~~~~~~ - -For an example of x.509 internal authentication, see -:doc:`/tutorial/configure-x509-member-authentication`. - .. toctree:: :titlesonly: :hidden: diff --git a/source/core/sharded-cluster-query-router.txt b/source/core/sharded-cluster-query-router.txt index 17425db9d9b..d56ae60caa4 100644 --- a/source/core/sharded-cluster-query-router.txt +++ b/source/core/sharded-cluster-query-router.txt @@ -379,3 +379,13 @@ Connection Pools .. |newversion| replace:: 4.2 .. |oldversion| replace:: 4.0 + +Using Aggregation Pipelines with Clusters +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For more information on how sharding works with :ref:`aggregations +`, read the sharding chapter in the `Practical +MongoDB Aggregations +`__ +e-book. + diff --git a/source/core/sharded-cluster-requirements.txt b/source/core/sharded-cluster-requirements.txt index 140b4c88c9b..c25688b7e58 100644 --- a/source/core/sharded-cluster-requirements.txt +++ b/source/core/sharded-cluster-requirements.txt @@ -39,6 +39,16 @@ Single Document Modification Operations in Sharded Collections .. include:: /includes/fact-single-modification-in-sharded-collections.rst +To use :method:`~db.collection.findOneAndUpdate()` with a sharded +collection, your query filter must include an equality condition on the +:term:`shard key` to compare the key and value in either of these +formats: + +.. code-block:: javascript + + { key: value } + { key: { $eq: value } } + .. _sharding-requirements-unique-indexes: Unique Indexes in Sharded Collections diff --git a/source/core/sharding-balancer-administration.txt b/source/core/sharding-balancer-administration.txt index 9fa3fe6dde5..b88c1d31e96 100644 --- a/source/core/sharding-balancer-administration.txt +++ b/source/core/sharding-balancer-administration.txt @@ -329,6 +329,12 @@ with :parameter:`rangeDeleterBatchSize` and :parameter:`rangeDeleterBatchDelayMS` above the current default of ``20`` milliseconds. +.. note:: + + If there are ongoing read operations or open cursors on the + collection targeted for deletes, range deletion processes may + not proceed. + .. _sharding-shard-size: Shard Size diff --git a/source/core/timeseries-collections.txt b/source/core/timeseries-collections.txt index 1d3c3285c9d..3f50a673e01 100644 --- a/source/core/timeseries-collections.txt +++ b/source/core/timeseries-collections.txt @@ -109,8 +109,7 @@ When creating a time series collection, specify the following options: metadata should rarely, if ever, change. The name of the specified field may not be ``_id`` or the same as - the ``timeseries.timeField``. The field can be of any type except - array. + the ``timeseries.timeField``. The field can be of any type. * - ``timeseries.granularity`` @@ -166,51 +165,51 @@ multiple documents at once, issue the following command: .. code-block:: javescript db.weather.insertMany([{ - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T00:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T04:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T08:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T12:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T16:00:00.000Z"), "temp": 16 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T20:00:00.000Z"), "temp": 15 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T00:00:00.000Z"), "temp": 13 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T04:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T08:00:00.000Z"), "temp": 11 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T12:00:00.000Z"), "temp": 12 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T16:00:00.000Z"), "temp": 17 }, { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-19T20:00:00.000Z"), "temp": 12 }]) @@ -227,7 +226,7 @@ following command: .. code-block:: javescript db.weather.findOne({ - "timestamp": {"$date": "2021-05-11T04:00:00.000Z"} + "timestamp": ISODate("2021-05-18T00:00:00.000Z") }) Run Aggregations on a Time Series Collection diff --git a/source/core/timeseries/timeseries-automatic-removal.txt b/source/core/timeseries/timeseries-automatic-removal.txt index 289cd6b6257..f21b7b710cd 100644 --- a/source/core/timeseries/timeseries-automatic-removal.txt +++ b/source/core/timeseries/timeseries-automatic-removal.txt @@ -42,7 +42,7 @@ specified number of seconds. Consider the following document in the .. code-block:: { - "metadata": [{"sensorId": 5578}, {"type": "temperature"}], + "metadata": {"sensorId": 5578, "type": "temperature"}, "timestamp": ISODate("2021-05-18T10:00:00.000Z"), "temp": 12 } diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index bbede4711b1..9334e5f65f8 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -44,35 +44,51 @@ the columns in a relational database table. How do I create a database and a collection? -------------------------------------------- +.. note:: + + You can enter the commands referenced in this FAQ by using + the :binary:`MongoDB Shell <~bin.mongosh>`. The MongoDB Shell is an + interactive JavaScript interface to MongoDB. You can use the MongoDB + Shell to query and update data as well as perform administrative + operations. + If a database does not exist, MongoDB creates the database when you first store data for that database. If a collection does not exist, MongoDB creates the collection when you -first store data for that collection. [#explicit-creation]_ +first store data for that collection. As such, you can switch to a non-existent database (``use ``) and perform the following operation: .. code-block:: javascript - use myNewDB + use myNewDB; + + db.myNewCollection1.insertOne( { x: 1 } ); + db.myNewCollection2.createIndex( { a: 1 } ); - db.myNewCollection1.insertOne( { x: 1 } ) - db.myNewCollection2.createIndex( { a: 1 } ) +- The :method:`db.collection.insertOne()` method creates + the collection ``myNewCollection1`` if it does not already exist. -The ``insert`` operation creates both the database ``myNewDB`` and the -collection ``myNewCollection1`` if they do not already exist. +- The :method:`db.collection.createIndex()` method creates the index and + the collection ``myNewCollection2`` if it does not already exist. -The ``createIndex`` operation, which occurs after the ``myNewDB`` has -been created, creates the index and the collection ``myNewCollection2`` -if the collection does not exist. If ``myNewDb`` did not exist, the -``createIndex`` operation would have also created the ``myNewDB``. +- If the ``myNewDb`` database did not exist, either the + :method:`db.collection.createIndex()` method or + :method:`db.collection.insertOne()` method would have created + the ``myNewDb`` database automatically. + +You can also create a collection explicitly using +:method:`db.createCollection` method if you want to specify specific +:ref:`options`, such as maximum size +or document validation rules: + +.. code-block:: javascript -.. [#explicit-creation] + use myNewDB; - You can also create a collection explicitly using - :method:`db.createCollection` if you want to specify specific - options, such as maximum size or document validation rules. + db.createCollection("myNewCollection1"); .. _faq-schema-free: diff --git a/source/images/hero.png b/source/images/hero.png new file mode 100644 index 00000000000..c272c9d05ee Binary files /dev/null and b/source/images/hero.png differ diff --git a/source/images/icons/compass.svg b/source/images/icons/compass.svg new file mode 100644 index 00000000000..ddd1c267e06 --- /dev/null +++ b/source/images/icons/compass.svg @@ -0,0 +1,23 @@ + + + + + + + + + + + + + + + + + + + + + + + diff --git a/source/images/icons/drivers.svg b/source/images/icons/drivers.svg new file mode 100644 index 00000000000..5c9e8a1de02 --- /dev/null +++ b/source/images/icons/drivers.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/source/images/icons/opsmanager.svg b/source/images/icons/opsmanager.svg new file mode 100644 index 00000000000..537c2129203 --- /dev/null +++ b/source/images/icons/opsmanager.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/source/images/scaling.png b/source/images/scaling.png new file mode 100644 index 00000000000..872685eae00 Binary files /dev/null and b/source/images/scaling.png differ diff --git a/source/images/security.png b/source/images/security.png new file mode 100644 index 00000000000..cae4f808cbf Binary files /dev/null and b/source/images/security.png differ diff --git a/source/includes/5.0-changes-getLastErrorDefaults-removed.rst b/source/includes/5.0-changes-getLastErrorDefaults-removed.rst new file mode 100644 index 00000000000..3c12e925c21 --- /dev/null +++ b/source/includes/5.0-changes-getLastErrorDefaults-removed.rst @@ -0,0 +1,5 @@ +Starting in MongoDB 5.0, you cannot specify a default write concern with +:rsconf:`settings.getLastErrorDefaults` other than the default of +``{ w: 1, wtimeout: 0 }`` . Instead, use the +:dbcommand:`setDefaultRWConcern` command to set the default read or +write concern configuration for a replica set or sharded cluster. diff --git a/source/includes/5.0-changes/fact-odd-number-releases.rst b/source/includes/5.0-changes/fact-odd-number-releases.rst new file mode 100644 index 00000000000..b36b0c6a28d --- /dev/null +++ b/source/includes/5.0-changes/fact-odd-number-releases.rst @@ -0,0 +1,6 @@ +Prior to MongoDB 5.0, odd-numbered MongoDB release versions, such as +``4.3``, were development releases. Beginning with MongoDB 5.1, +MongoDB has quarterly rapid releases. For more information on the +differences between rapid and long-term support releases, see +:ref:`release-version-numbers`. + diff --git a/source/includes/5.0-default-wc.rst b/source/includes/5.0-default-wc.rst index dc763006b62..65a5befaa29 100644 --- a/source/includes/5.0-default-wc.rst +++ b/source/includes/5.0-default-wc.rst @@ -1,13 +1,16 @@ -Starting in MongoDB 5.0, the implicit default write concern is +Starting in MongoDB 5.0, the implicit default +:ref:`write concern ` is :writeconcern:`w: majority <"majority">`. However, special -considerations are made for deployments containing :ref:`arbiters -`: +considerations are made for deployments containing +:ref:`arbiters `: -- If the number of data-bearing voting members is not strictly more - than the voting majority, the default write concern is ``w: 1``. +- The voting majority of a replica set is 1 plus half the number of + voting members, rounded down. If the number of data-bearing voting + members is not greater than the voting majority, the default write + concern is ``{ w: 1 }``. -- In all other scenarios, the default write concern is ``w: - "majority"``. +- In all other scenarios, the default write concern is ``{ w: + "majority" }``. Specifically, MongoDB uses the following formula to determine the default write concern: @@ -15,7 +18,55 @@ default write concern: .. code-block:: none :copyable: false - if [(#arbiters > 0) AND (#arbiters >= ½(#voting nodes) - 1)] + if [ (#arbiters > 0) AND (#non-arbiters <= majority(#voting-nodes)) ] defaultWriteConcern = { w: 1 } else - defaultWriteConcern = { w: majority } + defaultWriteConcern = { w: "majority" } + +For example, consider the following deployments and their respective +default write concerns: + +.. list-table:: + :header-rows: 1 + + * - Non-Arbiters + - Arbiters + - Voting Nodes + - Majority of Voting Nodes + - Implicit Default Write Concern + + * - 2 + - 1 + - 3 + - 2 + - ``{ w: 1 }`` + + * - 4 + - 1 + - 5 + - 3 + - ``{ w: "majority" }`` + +- In the first example: + + - There are 2 non-arbiters and 1 arbiter for a total of 3 voting + nodes. + + - The majority of voting nodes (1 plus half of 3, rounded + down) is 2. + + - The number of non-arbiters (2) is equal to + the majority of voting nodes (2), resulting in an implicit write + concern of ``{ w: 1 }``. + +- In the second example: + + - There are 4 non-arbiters and 1 arbiter for a total of 5 + voting nodes. + + - The majority of voting nodes (1 plus half of 5, rounded + down) is 3. + + - The number of non-arbiters (4) is greater than the majority + of voting nodes (3), resulting in an implicit write concern of + ``{ w: "majority" }``. diff --git a/source/includes/5.0-fact-currentop.rst b/source/includes/5.0-fact-currentop.rst new file mode 100644 index 00000000000..90cb4a7faa4 --- /dev/null +++ b/source/includes/5.0-fact-currentop.rst @@ -0,0 +1,9 @@ +Starting in MongoDB 5.0, the :pipeline:`$currentOp` aggregation +stage is used when running the helper method :method:`db.currentOp()` +with :binary:`~bin.mongosh`. + +Given this, in the 5.0 version of the shell and with mongosh, +:method:`db.currentOp()` result sets are not subject to the +:ref:`16MB BSON document return size` +document return size limit for documents of the previous legacy +:binary:`~bin.mongo` versions. \ No newline at end of file diff --git a/source/includes/access-create-user.rst b/source/includes/access-create-user.rst index b99dc1352bb..7e22b00aa66 100644 --- a/source/includes/access-create-user.rst +++ b/source/includes/access-create-user.rst @@ -6,7 +6,6 @@ :ref:`action ` on the role's database. The :authrole:`userAdmin` and -:authrole:`userAdminAnyDatabase` built-in roles -provide :authaction:`createUser` and -:authaction:`grantRole` actions on their respective :doc:`resources -`. +:authrole:`userAdminAnyDatabase` built-in roles provide +:authaction:`createUser` and :authaction:`grantRole` actions on their +respective :doc:`resources `. diff --git a/source/includes/aggregation-pipeline-example.rst b/source/includes/aggregation-pipeline-example.rst new file mode 100644 index 00000000000..d27da46338d --- /dev/null +++ b/source/includes/aggregation-pipeline-example.rst @@ -0,0 +1,24 @@ +The following aggregation pipeline example contains two :ref:`stages +` and returns the total +quantity of urgent orders for each product: + +.. code-block:: javascript + + db.orders.aggregate( [ + { $match: { status: "urgent" } }, + { $group: { _id: "$productName", sumQuantity: { $sum: "$quantity" } } } + ] ) + +The :pipeline:`$match` stage: + +- Filters the documents to those with a ``status`` of ``urgent``. + +- Outputs the filtered documents to the :pipeline:`$group` stage. + +The :pipeline:`$group` stage: + +- Groups the input documents by ``productName``. + +- Uses :group:`$sum` to calculate the total ``quantity`` for each + ``productName``, which is stored in the ``sumQuantity`` field returned + by the aggregation pipeline. \ No newline at end of file diff --git a/source/includes/aggregation-pipeline-introduction.rst b/source/includes/aggregation-pipeline-introduction.rst new file mode 100644 index 00000000000..341e0c73e87 --- /dev/null +++ b/source/includes/aggregation-pipeline-introduction.rst @@ -0,0 +1,12 @@ +An aggregation pipeline consists of one or more :ref:`stages +` that process documents: + +- Each stage performs an operation on the input documents. + For example, a stage can filter documents, group documents, and + calculate values. + +- The documents that are output from one stage are input to the next + stage. + +- An aggregation pipeline can return results for groups of documents. + For example, return the total, average, maximum, and minimum values. \ No newline at end of file diff --git a/source/includes/and-or-behavior.rst b/source/includes/and-or-behavior.rst new file mode 100644 index 00000000000..e4bcb5bd226 --- /dev/null +++ b/source/includes/and-or-behavior.rst @@ -0,0 +1,23 @@ +To allow the query engine to optimize queries, |and-or| handles +errors as follows: + +- If any expression supplied to |and-or| would cause an error when + evaluated alone, the |and-or| containing the expression may cause an + error but an error is not guaranteed. + +- An expression supplied after the first expression supplied to |and-or| + may cause an error even if the first expression evaluates to + |true-false|. + +For example, the following query *always* produces an error if ``$x`` is +``0``: + +.. code-block:: javascript + + db.example.find( { + $expr: { $eq: [ { $divide: [ 1, "$x" ] }, 3 ] } + } ) + +The following query, which contains multiple expressions supplied to +|and-or|, *may* produce an error if there is any document where ``$x`` +is ``0``: diff --git a/source/includes/changelogs/releases/4.0.27.rst b/source/includes/changelogs/releases/4.0.27.rst new file mode 100644 index 00000000000..0f2913f4c59 --- /dev/null +++ b/source/includes/changelogs/releases/4.0.27.rst @@ -0,0 +1,51 @@ +.. _4.0.27-changelog: + +4.0.27 Changelog +---------------- + +Sharding +~~~~~~~~ + +:issue:`SERVER-40170` Increase the default timeout for unit-tests which schedule work through NetworkTestEnv::launchAsync + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege + +Query +~~~~~ + +:issue:`SERVER-58127` Fix benchRun() memory leak for parsing benchRun() args under exception + +Storage +~~~~~~~ + +:issue:`SERVER-40712` Clarify the behaviour of db.dropDatabase and the dropDatabase command + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`SERVER-54729` MongoDB Enterprise Debian/Ubuntu packages should depend on libsasl2-modules and libsasl2-modules-gssapi-mit + +Internals +~~~~~~~~~ + +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-53728` Platform Support: Remove SLES12 zSeries +- :issue:`SERVER-55649` Sharding messages being logged for non-sharded clusters +- :issue:`SERVER-56516` Fix undefined behaviour in parsing code for $slice projectional operator +- :issue:`SERVER-57642` Invariant Failure on src/mongo/db/query/plan_yield_policy.cpp 75 | Aborting +- :issue:`SERVER-57798` Direct user to MongoDB Compass download page when failing to install MongoDB Compass due to a connection issue using ./install_compass +- :issue:`SERVER-57983` Integer overflow for $range in Classic Engine +- :issue:`SERVER-58283` Add a new versioning file to set MONGO_VERSION and MONGO_GIT_HASH +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-59055` Pin oauthlib == 3.1.0 in 4.0 branch +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`SERVER-59504` Fix formatting in network_test_env.h on v4.0 + diff --git a/source/includes/changelogs/releases/4.2.16.rst b/source/includes/changelogs/releases/4.2.16.rst new file mode 100644 index 00000000000..a0bf85ba432 --- /dev/null +++ b/source/includes/changelogs/releases/4.2.16.rst @@ -0,0 +1,83 @@ +.. _4.2.16-changelog: + +4.2.16 Changelog +---------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57727` Race conditions in x509_invalid.js + +Sharding +~~~~~~~~ + +- :issue:`SERVER-55648` Mongos doesn't return top-level batch-write error in case of shutdown +- :issue:`SERVER-58909` Missing versions for "admin" and "config" databases migrating to version 4.2 + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege +- :issue:`SERVER-37904` Allow a node to override the cluster chaining (enabled/disabled) setting +- :issue:`SERVER-39621` Disabled chaining should enforce sync source change when the primary steps down even if the oplog fetcher isn't killed on sync source +- :issue:`SERVER-41875` Should ban "emptyCapped" commands on jstestfuzz_concurrent_replication_continuous__stepdown suite for WiredTiger Storage. +- :issue:`SERVER-50486` invokeWithSessionCheckedOut being called on prepared transactions on secondaries +- :issue:`SERVER-55465` Fix Invariant upon failed request for a vote from the current primary in the election dry-run of catchup takeover +- :issue:`SERVER-58258` Wait for initial sync to clear state before asserting 'replSetGetStatus' reply has no 'initialSync' field + +Query +~~~~~ + +- :issue:`SERVER-55319` [4.2] Invariant failure isVersionInitialized() src/mongo/db/server_options.h 217 after index build completes +- :issue:`SERVER-58127` Fix benchRun() memory leak for parsing benchRun() args under exception + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`SERVER-54729` MongoDB Enterprise Debian/Ubuntu packages should depend on libsasl2-modules and libsasl2-modules-gssapi-mit + +Internals +~~~~~~~~~ + +- :issue:`SERVER-49237` Add a way for OperationContexts to opt-in to always getting interrupted at stepdown +- :issue:`SERVER-50547` Explore aggregation pipeline length limit +- :issue:`SERVER-52728` Upgrade path from MongoDB 2.4 to 4.2 causes config servers to go down +- :issue:`SERVER-53431` Server should respond running operations with appropriate topologyVersion on stepdown +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-55649` Sharding messages being logged for non-sharded clusters +- :issue:`SERVER-56489` New pass-through test with random hello server-side delays +- :issue:`SERVER-56516` Fix undefined behaviour in parsing code for $slice projectional operator +- :issue:`SERVER-56839` Index seeks concurrent with recently-committed prepared transactions can return wrong results +- :issue:`SERVER-57033` The AuthorizationManager Cache in 4.2 should use roles as cache key +- :issue:`SERVER-57064` Log create index and dropIndex(es) on mongos +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57642` Invariant Failure on src/mongo/db/query/plan_yield_policy.cpp 75 | Aborting +- :issue:`SERVER-57650` Make MigrationChunkClonerSource interruptible when waiting response to recipient commands +- :issue:`SERVER-57798` Direct user to MongoDB Compass download page when failing to install MongoDB Compass due to a connection issue using ./install_compass +- :issue:`SERVER-57983` Integer overflow for $range in Classic Engine +- :issue:`SERVER-58169` Log timestamps info on hitting invariants around stable timestamp calculation +- :issue:`SERVER-58187` Improve Connection Reaper and MongoLDAP performance +- :issue:`SERVER-58191` [Migrate Protocol] Allow delete_during_migrate.js to tolerate chunk migration failures due to timeout in catchup phase in slow variants. +- :issue:`SERVER-58283` Add a new versioning file to set MONGO_VERSION and MONGO_GIT_HASH +- :issue:`SERVER-58313` Fix package test failure caused by SERVER-55460 backport to v4.2 and v4.0 +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58623` Shorten the mongos RSM refresh interval in delayed Hello tests +- :issue:`SERVER-58826` [4.2] Disallow compact_keeps_indexes.js and explain_shell_helpers .js to run concurrently on parallel suite +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59388` Revert BACKPORT-10185 +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`WT-6568` Fix split generation use +- :issue:`WT-6926` Update WiredTiger source code to include 2021 copyright notices +- :issue:`WT-7065` Add check for WT_DHANDLE_DEAD to assertion +- :issue:`WT-7135` Additional checks to detect when writing corrupted metadata +- :issue:`WT-7437` Upgrade documentation to doxygen 1.8.17 +- :issue:`WT-7675` Query last ckpt timestamp changes without taking checkpoint +- :issue:`WT-7721` Update test-format to reopen an existing database with different config +- :issue:`WT-7776` Add a hard limit on the number of modify updates before we instantiate a complete update +- :issue:`WT-7871` Remove comment that is no longer true + diff --git a/source/includes/changelogs/releases/4.2.17.rst b/source/includes/changelogs/releases/4.2.17.rst new file mode 100644 index 00000000000..4a33e23818e --- /dev/null +++ b/source/includes/changelogs/releases/4.2.17.rst @@ -0,0 +1,19 @@ +.. _4.2.17-changelog: + +4.2.17 Changelog +---------------- + +Storage +~~~~~~~ + +:issue:`SERVER-49521` fix tests in core/txn to use write concern "majority" for createIndexes commands run before starting transactions + +Internals +~~~~~~~~~ + +- :issue:`SERVER-48090` Support python 3.6 for evergreen.py and shrub.py +- :issue:`SERVER-50549` Transform connection-related error codes in proxied commands +- :issue:`SERVER-53726` Platform Support: Remove RHEL6 zSeries +- :issue:`SERVER-59456` Start the LDAPReaper threadpool +- :issue:`SERVER-59876` Large delays in returning from libcrypto.so while establishing egress connections + diff --git a/source/includes/changelogs/releases/4.4.10.rst b/source/includes/changelogs/releases/4.4.10.rst new file mode 100644 index 00000000000..7529649d489 --- /dev/null +++ b/source/includes/changelogs/releases/4.4.10.rst @@ -0,0 +1,172 @@ +.. _4.4.10-changelog: + +4.4.10 Changelog +---------------- + +Security +~~~~~~~~ + +:issue:`SERVER-50050` Build with --ssl=off fails + +Sharding +~~~~~~~~ + +- :issue:`SERVER-53332` Change ShardRegistry::_connStringLookup to store connection strings as std::strings +- :issue:`SERVER-54064` Sessions on arbiters accumulate and cannot be cleared out +- :issue:`SERVER-55975` The core/find_and_modify.js test is not suitable to run in the stepdown suites +- :issue:`SERVER-59160` Disable balancer in test_stacked_migration_cleanup.js +- :issue:`SERVER-59769` Balancer conflicts with chunk migration tests +- :issue:`SERVER-59916` T{1, 2}Starts{First, Second}AndWins In WriteConflictHelpers Does Not Synchronize Committing Of Failed Transaction +- :issue:`SERVER-60142` Shard can migrate on top of orphans after filtering metadata was cleared +- :issue:`SERVER-60419` Make CleanUpForMigrateIn deterministic + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-50241` PeriodicShardedIndexConsistencyChecker should skip dropped collections +- :issue:`SERVER-55376` Reconfig can roll back committed writes in PSA sets +- :issue:`SERVER-58988` Avoid sync source selection cycle during primary catchup. +- :issue:`SERVER-60153` More INFO level logs during election + +Query +~~~~~ + +- :issue:`SERVER-51806` bulk key insertion phase of index build holds IX lock without yielding +- :issue:`SERVER-54791` Excessive file descriptor usage during index build with external sort +- :issue:`SERVER-57321` $mod match expression incorrectly handles NaN, Infinity and large values + +Aggregation +~~~~~~~~~~~ + +:issue:`SERVER-49214` Add $toHashedIndexKey expression + +Operations +~~~~~~~~~~ + +:issue:`SERVER-53242` Always log collmod command + +Internals +~~~~~~~~~ + +- :issue:`SERVER-34597` shardedcluster.py does not wait correctly on shards initialization +- :issue:`SERVER-46147` Update repair to fix multikey errors without performing an index rebuild +- :issue:`SERVER-49340` Add repair mode to validate for startup --repair +- :issue:`SERVER-52850` Remove assertion from initial_sync_nodes_maintain_and_gossip_commit_point.js +- :issue:`SERVER-53448` Make ftdc_mirrored_reads.js resilient to slow machines +- :issue:`SERVER-54825` Use 'toArray()' in addition to array access after 'find()' in rslib.js +- :issue:`SERVER-55904` Consolidate getFirstOplogEntry and getLeastRecentOp helpers +- :issue:`SERVER-56326` Add a round() method to the Decimal128 class +- :issue:`SERVER-56416` mongod --version returns with extraneous log line on M1 laptops +- :issue:`SERVER-56919` Add validation for memberIndex to reconfigToPSASet() shell helper +- :issue:`SERVER-57284` Wait for config commitment in reconfig_for_psa_set_shell.js +- :issue:`SERVER-57605` Expose Decimal128 equality comparison helper to shell +- :issue:`SERVER-57938` Skip polygon validation for stored GeoJSON when query has $geoIntersect and a 2dsphere index +- :issue:`SERVER-58047` $toHashedIndexKey expression doesn't add any dependencies +- :issue:`SERVER-58104` config.system.sessions collection can end up with invalid chunks if it is dropped and re-sharded with a shard key other than _id +- :issue:`SERVER-58122` Replace searching logs for invariant failure with failpoint usage in resync_majority_member.js +- :issue:`SERVER-58139` Avoid leaking state from NetworkInterfaceTest::CancelLocally +- :issue:`SERVER-58148` mirrored_reads.js assertion does not consider mirrored read failure +- :issue:`SERVER-58183` _applyPrepareTransaction does not ensure prepareConflictBehavior is kIgnoreConflictAcceptWrites on retry attempts +- :issue:`SERVER-58203` improve $unionWith stage +- :issue:`SERVER-58583` Query analysis for mongocryptd does not handle expressive projections in find +- :issue:`SERVER-58777` Inserts and updates disagree on whether an empty subdocument is a level of nesting +- :issue:`SERVER-58780` [v4.4] Ensure that _shouldSetStableTimestamp gets restored to true if replSetInitiate fails +- :issue:`SERVER-59010` Fix SSL off build, OCSPManager shouldn't be used when ssl = off +- :issue:`SERVER-59074` Do not acquire storage tickets just to set/wait on oplog visibility +- :issue:`SERVER-59120` Create unit tests for commitChunksMerge +- :issue:`SERVER-59143` hard fail if "--ninja" tool option is used with ninja module in place +- :issue:`SERVER-59190` IndexAccessMethod can be destructed during index build bulk load yield +- :issue:`SERVER-59294` Check action type for oidReset +- :issue:`SERVER-59299` Improve $match stage +- :issue:`SERVER-59425` Ninja fails to install archive targets locally +- :issue:`SERVER-59456` Start the LDAPReaper threadpool +- :issue:`SERVER-59476` validate_commit_message does not allow wiredtiger imports to be reverted +- :issue:`SERVER-59651` replsettest runCommandWithRetry should handle slow configs +- :issue:`SERVER-59725` Remove push task from extra RHEL 6.2 variants +- :issue:`SERVER-59804` Using a separate branch for YCSB in system_perf.yml +- :issue:`SERVER-59866` Stop FCV from waiting for majority when currentCommittedSnapshot is dropped +- :issue:`SERVER-59867` Split horizon mappings in ReplSetConfig/MemberConfig should be serialized deterministically +- :issue:`SERVER-59876` Large delays in returning from libcrypto.so while establishing egress connections +- :issue:`SERVER-60025` queue document crashes the server due to producing invalid runtime object +- :issue:`SERVER-60062` Fix duplicate uuid and server description deep copy found in topology description clone +- :issue:`SERVER-60085` Cap number of fallback test suites at number of tests in suite +- :issue:`SERVER-60290` Update Windows external auth test distro +- :issue:`SERVER-60299` Backport PCRE bugfix for Bugzilla #2613 +- :issue:`SERVER-60406` $searchMeta fails on unsharded collection in sharded cluster when there are no search results +- :issue:`WT-5270` Create wtperf script for evergreen +- :issue:`WT-6193` Re-enable VLCS testing in format-test +- :issue:`WT-6669` Enable VLCS coverage and checkpoint tests in evergreen +- :issue:`WT-6900` Write "schema" subpage for Architecture Guide +- :issue:`WT-6903` Write "dhandle/btree" subpage for Architecture Guide +- :issue:`WT-6907` Write "snapshots" subpage for Architecture Guide +- :issue:`WT-6909` Eviction architecture guide +- :issue:`WT-6913` file system and os interface architecture guide +- :issue:`WT-7169` Commit ts should not be lesser than the last durable ts in test_timestamp22.py +- :issue:`WT-7294` Re-enable VLCS evergreen endianness tests +- :issue:`WT-7392` Added evicted flag to dhandle for use by session sweep +- :issue:`WT-7601` Fix typo in operation tracking documentation +- :issue:`WT-7695` Dump entire tree when key out-of-order found in __cursor_key_order_check_row +- :issue:`WT-7745` Add macro to identify uris for btree objects +- :issue:`WT-7757` Skip obsolete leaf pages without having to read them +- :issue:`WT-7844` Add tiered_abort stress test for tiered storage. +- :issue:`WT-7902` Retry the alter command after a system wide checkpoint +- :issue:`WT-7914` Update the documentation only when required +- :issue:`WT-7942` Release timestamp lock in test/format when all_durable timestamp is not found +- :issue:`WT-7949` Change local store cache and bucket directories to be relative to WT_HOME +- :issue:`WT-7957` Tiered storage should look in local system for objects +- :issue:`WT-7959` Skipped_pages is less than expected_pages_skipped in test_cursor17 +- :issue:`WT-7980` Create interface to "log:" cursor which switches log files before returning them +- :issue:`WT-7987` Create Unit Test to check compact does not rewrite overflow items +- :issue:`WT-7989` Compact quits when running at the same time as a system checkpoint +- :issue:`WT-7992` Provide API to return the last key in a table regardless of visibility +- :issue:`WT-7993` If gathering handles and not in aggressive eviction mode, have eviction sleep to let checkpoint grab a contentious spinlock. +- :issue:`WT-8001` Fix Inconsistent API behaviour when setting global oldest and stable timestamps +- :issue:`WT-8007` Update script to correctly generate new test for the CPP test suite framework +- :issue:`WT-8011` Add format support for randomly choosing RS or VLCS +- :issue:`WT-8017` Re-enable VLCS format stress testing in evergreen. +- :issue:`WT-8019` VLCS snapshot-isolation search mismatch +- :issue:`WT-8022` Verify WT_CURSOR.modify return values in format test program +- :issue:`WT-8023` Use global transaction information to assess if a session has active transaction +- :issue:`WT-8024` Add link text to cross-references in Arch Guide +- :issue:`WT-8034` Use the PR branch when docs are compiled in PR testing +- :issue:`WT-8035` Handle prefix enabled lexicographical comparisons for string key formats +- :issue:`WT-8036` Added connection panic flag in two assert statements in wt_evict_thread_run and _wt_evict_thread_stop. +- :issue:`WT-8039` Add a new flag for API check instead of clearing prepared flag which may incorrectly force a roll back +- :issue:`WT-8041` Rollback to stable unpacks values repeatedly +- :issue:`WT-8042` Create an evergreen job to run test/checkpoint variation +- :issue:`WT-8043` Tidy the "ripcip" argument into the visibility code +- :issue:`WT-8044` Prefix enabled search near only returns matching keys +- :issue:`WT-8048` Remove split_8 timing stress configuration +- :issue:`WT-8055` Fix issue when compact quits when running at the same time as a checkpoint +- :issue:`WT-8057` Add a test to verify that changing compact is not resulting in data loss +- :issue:`WT-8059` Add a check in salvage when no overflow items are found +- :issue:`WT-8068` Improve __rollback_row_modify control flow +- :issue:`WT-8069` Coverity analysis defect 120706: Redundant test +- :issue:`WT-8070` Remove discrepancy between prefix_key and prefix_search +- :issue:`WT-8075` Coverity analysis defect 120712: 'Constant' variable guards dead code +- :issue:`WT-8077` Mark the page dirty once the prepared updates are resolved +- :issue:`WT-8078` Implement tiered storage local retention caching +- :issue:`WT-8079` Add breakpoint to verify error macros, clean up API processing +- :issue:`WT-8081` Fix tiered hook functions to provide default for config string +- :issue:`WT-8086` Create cpp test for prefix search near entries +- :issue:`WT-8092` Prefix early exit when keys are present in the insert list +- :issue:`WT-8094` Fix use after free in csv extractor +- :issue:`WT-8101` Enable diagnostic mode for the CPP tests in evergreen +- :issue:`WT-8103` Skip a dhandle if it isn't a btree +- :issue:`WT-8104` Fix memory leaks noted by ASAN +- :issue:`WT-8108` Use temporary files and rename in local store +- :issue:`WT-8112` Skip null check, per coverity +- :issue:`WT-8113` Remove dead code, per coverity +- :issue:`WT-8115` Define macros only when necessary in cpp files +- :issue:`WT-8119` Add targeted compact testing to the existing testing framework +- :issue:`WT-8121` Create a long running stress test which inserts a large amount of data over a long period +- :issue:`WT-8125` Update hs_cleanup cppsuite test to use the new thread_context logic +- :issue:`WT-8126` Mark btree as dirty only if not newly created when instantiating a deleted row-store leaf page +- :issue:`WT-8146` Stop the tracking component when a CPP test ends +- :issue:`WT-8148` Fix comment typo in util_verify.c +- :issue:`WT-8161` Reduce verbosity of CMake Evergreen smoke +- :issue:`WT-8162` Refactor uses of SMOKE arg in 'define_c_test' helper +- :issue:`WT-8164` Disable rollback_to_stable10 python test on Windows +- :issue:`WT-8171` Implement a C style test in the CPP testing framework +- :issue:`WT-8193` Wrong corner case in VLCS rollback-to-stable + diff --git a/source/includes/changelogs/releases/4.4.9.rst b/source/includes/changelogs/releases/4.4.9.rst new file mode 100644 index 00000000000..c9cda32b12e --- /dev/null +++ b/source/includes/changelogs/releases/4.4.9.rst @@ -0,0 +1,149 @@ +.. _4.4.9-changelog: + +4.4.9 Changelog +--------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57716` Partial certificate chain in PEM causes validation failure in OCSP + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-34938` Secondary slowdown or hang due to content pinned in cache by single oplog batch +- :issue:`SERVER-36263` Bypassing operation validation in applyOps should require special privilege +- :issue:`SERVER-44316` Log message in InitialSyncer for setting begin applying timestamp is incorrect +- :issue:`SERVER-59212` Make sure node stepped down before waiting for catchup takeover in catchup_takeover_with_higher_config.js +- :issue:`SERVER-59478` Move serverStatus command before taking RSTL in catchup_takeover_with_higher_config.js + +Query +~~~~~ + +:issue:`SERVER-57178` add regression test for multikey compound index + +Storage +~~~~~~~ + +:issue:`SERVER-56877` insert operations may fail to set index to multikey after aborted multikey catalog update + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`WT-7830` Migrate the python setup scripts to use cmake + +Internals +~~~~~~~~~ + +- :issue:`SERVER-49435` uassert in NetworkInterfaceTL::setTimer can cause server to crash if connection future not immediately ready +- :issue:`SERVER-53069` Disable death tests on address and memory sanitizer variants +- :issue:`SERVER-53479` Wait for mirrored operations in mirror_reads.js +- :issue:`SERVER-53849` Move away from getLog in timestamped_reads_wait_for_prepare_oplog_visibility.js +- :issue:`SERVER-55589` replSetMaintenance command does not take the RSTL +- :issue:`SERVER-56580` Promote build-tools=next to stable +- :issue:`SERVER-57262` Allow nodes to vote for candidates with higher config +- :issue:`SERVER-57268` add multikey query to validate_multikey_restart.js +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57630` Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04 when running against OpenSSL 1.1.1 +- :issue:`SERVER-57752` Test terminating mongod during a clean shutdown checkpoint +- :issue:`SERVER-57893` Make rsm_horizon_change.js resilient to network failures +- :issue:`SERVER-58051` Mongod.exe does not release file handles on rotated logs on windows 10 +- :issue:`SERVER-58169` Log timestamps info on hitting invariants around stable timestamp calculation +- :issue:`SERVER-58184` Checkpoint thread causes assertions when raced with recovering prepared transactions on startup +- :issue:`SERVER-58280` initial sync hangs on hiding dropped index when index builds are active +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58581` Add SEARCH_META variable that populates from mongot +- :issue:`SERVER-58582` Create $documents stage and implement collectionless unionWith +- :issue:`SERVER-58588` Implement $searchMeta stage +- :issue:`SERVER-58594` ReplicationCoordinatorImpl::handleHeartbeatResponse_forTest doesn't use _mutex when reading _rsConfig +- :issue:`SERVER-58676` Ban pipelines that set SEARCH_META variable in sharded collections +- :issue:`SERVER-58813` Robustify jstests/multiversion/hashed_index_bad_keys_cleanup.js +- :issue:`SERVER-58886` Allow 'vars' result to be returned from a sharded search query but fail on SEARCH_META access +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59188` Coverity analysis defect 120391: Uninitialized scalar field +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59262` Remove burn_in_tests tasks from storeFindAndModifyImagesInSideCollection build variants +- :issue:`SERVER-59414` Retry curator setup in powercycle on older branches +- :issue:`SERVER-59469` Add missing space in burn_in_tags list of variants +- :issue:`SERVER-59573` Add setParameter which can be used to restore inactive cursor timeout in sessions +- :issue:`WT-6755` Documentation: populate developer glossary +- :issue:`WT-6902` Metadata subpage for Architecture Guide +- :issue:`WT-6910` Write "history store" subpage for Architecture Guide +- :issue:`WT-6911` Write "block manager" subpage for Architecture Guide +- :issue:`WT-6914` Write "database files" subpage for Architecture Guide +- :issue:`WT-6915` Write "log files" subpage for Architecture Guide +- :issue:`WT-7006` Write Connection subpage for Architecture Guide +- :issue:`WT-7007` Backup architecture guide page +- :issue:`WT-7198` Fix test_backup15 failure with backup mismatch +- :issue:`WT-7352` Fix test_hs01 conflict between concurrent operations in cursor modify +- :issue:`WT-7363` Add support for dumping history store output in hex format +- :issue:`WT-7521` Remove excess ckplist invalidations +- :issue:`WT-7592` Remove log_flush("sync=background") support +- :issue:`WT-7599` Update the CONFIG file based on the release that is about to run for compatibility tests +- :issue:`WT-7663` Change local store extension to allow only readonly FS operations +- :issue:`WT-7673` Investigate and fix manydbs test failure on Windows +- :issue:`WT-7703` Fix timeout in test_checkpoint_snapshot04 +- :issue:`WT-7718` Rename 'build_cmake' +- :issue:`WT-7732` Add a timeout configuration for flush_tier +- :issue:`WT-7758` Force evict a page when the update chain is too long +- :issue:`WT-7787` Don't read pages for checkpoint cleanup when the cache is in aggressive mode +- :issue:`WT-7789` Change tiered python tests to fail without extension library +- :issue:`WT-7817` Make tiered storage address cookies backward compatible +- :issue:`WT-7838` Ability for ordered timestamp assertion to do more than a log message +- :issue:`WT-7842` Remove explicit ulimit -n call in many-collection-test +- :issue:`WT-7860` Improve code coverage reporting +- :issue:`WT-7864` Add support to run.py for running lists/ranges of scenarios in a test +- :issue:`WT-7865` Disable timeout assert while waiting for eviction to quiesce prior to RTS and test +- :issue:`WT-7866` Update cache_hs_insert limits in cppsuite-hs-cleanup-stress +- :issue:`WT-7870` Fix measurement of cyclomatic code complexity +- :issue:`WT-7871` Remove comment that is no longer true +- :issue:`WT-7874` Remove two other stale comments +- :issue:`WT-7876` Update rollback to stable test to use correct boolean values and update statistic checking logic +- :issue:`WT-7880` Fix history store record issue when the update following the prepared update is in history store +- :issue:`WT-7882` Fix discrepancy for wiredtiger.in on mongodb-4.4 branch +- :issue:`WT-7883` Remove incorrect wt_free statement +- :issue:`WT-7889` Find/replace existing uses of WT with WiredTiger in reference guide +- :issue:`WT-7890` Fix CMake syntax error in config_lib +- :issue:`WT-7891` Remove doc typos +- :issue:`WT-7893` Remove ignored message from wiredtiger_open in test_encrypt08 +- :issue:`WT-7895` Fix arch-data-file.dox documentation build failure +- :issue:`WT-7897` Enable verbose logging for test_backup15 to aid debugging +- :issue:`WT-7900` Fix insertion of new records in test format for column-store +- :issue:`WT-7901` test suite cleanup +- :issue:`WT-7905` Fix incorrect builtin behaviour for builds in CMake +- :issue:`WT-7907` Add dependencies to swig module definition in CMake build +- :issue:`WT-7908` Make variable-length column store work again with the static tests +- :issue:`WT-7909` Create a new method to check for running user transactions before starting rollback-to-stable operation +- :issue:`WT-7918` Support setting a prepare timestamp at current read timestamp +- :issue:`WT-7928` VLCS checkpoint and additional test suite improvements +- :issue:`WT-7931` Evicting modifies using the evict cursor in test_multiple_older_readers_with_multiple_mixed_mode() to ensure that eviction happens. +- :issue:`WT-7934` Upload perf results from many-collection test to Altas +- :issue:`WT-7935` Add arm64 implementation of rdtsc equivalent instruction +- :issue:`WT-7936` Update the format.sh script to run recovery tests +- :issue:`WT-7937` Fix s_docs to use sh, not bash syntax +- :issue:`WT-7938` Fix rollback-to-stable memory leak on error +- :issue:`WT-7940` Update mongod path for many-coll test +- :issue:`WT-7941` Add an Evergreen task to test abort/recovery using test/format +- :issue:`WT-7943` Do not assert timestamps when rolling back a prepared transactions +- :issue:`WT-7945` Move rollback handling to the operation layer in the cppsuite. +- :issue:`WT-7947` Allow CMake to take in a specific Python version +- :issue:`WT-7952` Minor docs build fixes +- :issue:`WT-7953` Teach s_string to not look inside getopt option lists. +- :issue:`WT-7955` Copy format.sh and CONFIG.stress to the test/format build directory with CMake +- :issue:`WT-7956` RTS to skip deleted or stable RLE cells +- :issue:`WT-7961` Sometimes lag oldest timestamp in timestamp_abort. +- :issue:`WT-7964` Fix rollback to stable incorrectly not rolling back updates at snap_max +- :issue:`WT-7965` Update connection base write generation number at the end of recovery checkpoint +- :issue:`WT-7968` In timestamp_abort skip setting timestamps when all_durable moves backwards +- :issue:`WT-7970` Set the stable timestamp before starting the checkpointer and clock threads +- :issue:`WT-7974` More column-store fixes and tests +- :issue:`WT-7984` Fix a bug that could cause a checkpoint to omit a page of data +- :issue:`WT-7994` Add docs compile task to PR testing +- :issue:`WT-7995` Fix the global visibility that it cannot go beyond checkpoint visibility +- :issue:`WT-7996` More column-store C testing +- :issue:`WT-7998` Minor fixes on Cache subpage of Architecture Guide +- :issue:`WT-7999` Fix the assert to handle an update in the middle with max stop timestamp +- :issue:`WT-8005` Fix a prepare commit bug that could leave the history store entry unresolved +- :issue:`WT-8006` sync/checkpoint cleanup code isn't appropriate for VLCS + diff --git a/source/includes/changelogs/releases/5.0.3.rst b/source/includes/changelogs/releases/5.0.3.rst new file mode 100644 index 00000000000..e4cb1da9ccc --- /dev/null +++ b/source/includes/changelogs/releases/5.0.3.rst @@ -0,0 +1,233 @@ +.. _5.0.3-changelog: + +5.0.3 Changelog +--------------- + +Security +~~~~~~~~ + +:issue:`SERVER-57716` Partial certificate chain in PEM causes validation failure in OCSP + +Sharding +~~~~~~~~ + +- :issue:`SERVER-27383` Require --replSet with --configsvr +- :issue:`SERVER-50937` Make resharding coordinator support recovery +- :issue:`SERVER-55824` Make ssl_get_more.js start shards as replicaset +- :issue:`SERVER-57487` Update chunks during setFCV 4.4 «--» 5.0 must not block balancing for long periods +- :issue:`SERVER-57953` _flushReshardingStateChange attempts to refresh shard version while another refresh already pending, leading to invariant failure +- :issue:`SERVER-58081` _flushReshardingStateChange from coordinator races with donor shard acquiring critical section, stalling the resharding operation +- :issue:`SERVER-58315` Change jstests to not use standalone nodes as shards nor config server +- :issue:`SERVER-58342` Allow specifying of reshardCollection zones to be empty +- :issue:`SERVER-58603` ensureTempReshardingCollectionExistsWithIndexes may hit an invariant if collection was previously dropped +- :issue:`SERVER-58702` Fix comment in ReshardingDataReplication and update its member declaration order +- :issue:`SERVER-58720` DropDatabaseCoordinator must not re-execute destructive logic after removing CSRS metadata +- :issue:`SERVER-58781` ReshardingCoordinatorObserver should not fulfill promises if the "donors" or "recipients" fields are empty +- :issue:`SERVER-58868` Enable/Remove a commented moveChunk + AllowMigrations test +- :issue:`SERVER-58917` Wait until donors/recipients are aware that coordinator has persisted decision before expecting successful collMod, createIndexes, and dropIndexes in resharding_prohibited_commands.js +- :issue:`SERVER-58926` ReshardingDonor should not try to set the stop time of the critical section if it the critical section was already released +- :issue:`SERVER-59114` ReshardingOplogFetcher stops fetching new oplog entries if remote donor shard responds with Interruption exception +- :issue:`SERVER-59292` completion future can be set more than once because of WithAutomaticRetry + +Replication +~~~~~~~~~~~ + +- :issue:`SERVER-58133` Use split replication tasks because they are timing out because of "majority" implicit default write concern +- :issue:`SERVER-58987` Fix read_only_test.js to avoid start point beyond end point during replication recovery. +- :issue:`SERVER-59083` catchup_takeover_with_higher_config.js needs to be excluded from multiversion suite for last-continuous +- :issue:`SERVER-59131` Wrap rawMongoProgramOutput search in an assert.soon in implicit_default_write_concern_upgrade_shards.js +- :issue:`SERVER-59212` Make sure node stepped down before waiting for catchup takeover in catchup_takeover_with_higher_config.js +- :issue:`SERVER-59478` Move serverStatus command before taking RSTL in catchup_takeover_with_higher_config.js + +Query +~~~~~ + +- :issue:`SERVER-54791` Excessive file descriptor usage during index build with external sort +- :issue:`SERVER-57448` fix ExpressionParams::parseTwoDParams() to handle int values in key patterns that are out of bounds +- :issue:`SERVER-57667` Improve processing speed for resharding's collection cloning pipeline + +Storage +~~~~~~~ + +:issue:`SERVER-58744` applyOps on capped collections can violate the multi-timestamp constraint + +Build and Packaging +~~~~~~~~~~~~~~~~~~~ + +:issue:`WT-7830` Migrate the python setup scripts to use cmake + +Internals +~~~~~~~~~ + +- :issue:`SERVER-52007` Create feature flag for Integration work to support new $search parameters +- :issue:`SERVER-53001` Complete TODO listed in SERVER-47323 +- :issue:`SERVER-53437` Architecture Guide updates for Change the Default Write Concern to Majority +- :issue:`SERVER-54735` Executor shutdown can cause AsyncTry-until to set its result with ErrorCodes::BrokenPromise +- :issue:`SERVER-55589` replSetMaintenance command does not take the RSTL +- :issue:`SERVER-55664` Support clustered _id indexes in ephemeralForTest +- :issue:`SERVER-55760` Cancelation tests for AsyncTry are racy +- :issue:`SERVER-55966` AsyncTry no longer handles exceptions from until() lambda, leading to process crash +- :issue:`SERVER-56235` Evaluate index types that are dependent on a collection not being clustered, rather that it not being time-series +- :issue:`SERVER-56492` Normalize time-series metadata with array type +- :issue:`SERVER-56580` Promote build-tools=next to stable +- :issue:`SERVER-56763` Validate collection epoch when not holding a DB lock for $merge +- :issue:`SERVER-56800` Fail addShard if CWWC disagrees with existing CWWC on cluster +- :issue:`SERVER-56844` Fassert shard server on startup if DWCF=w:1 and no CWWC set +- :issue:`SERVER-56845` Fail addShard if DWCF=w:1 and no CWWC is set +- :issue:`SERVER-56846` Fail reconfig for shard server if it would change DWCF and CWWC is not set +- :issue:`SERVER-57086` Do not set inherited maxTimeMSOpOnly deadline on hello command in v4.4 +- :issue:`SERVER-57140` Fix up perl relics from migrated shell scripts +- :issue:`SERVER-57262` Allow nodes to vote for candidates with higher config +- :issue:`SERVER-57279` Update the FCV constant in the logkeeper snapshot workload +- :issue:`SERVER-57360` Log additional debug info for the "invariant (_requests.empty());" in ~LockerImpl +- :issue:`SERVER-57387` create_view_does_not_take_database_X.js should check its insert +- :issue:`SERVER-57435` Exclude views_coll_stats.js from causally_consistent test suites +- :issue:`SERVER-57465` remove_newly_added_field_after_finishing_initial_sync.js does not wait until the new configuration has been replicated +- :issue:`SERVER-57520` Make set_audit_config.js test start shard as replicaset +- :issue:`SERVER-57575` Investigate create_view_does_not_take_database_X.js failures on Windows +- :issue:`SERVER-57585` oplog_visibility.js prints null 'next' timestamp for missing oplog entry +- :issue:`SERVER-57599` DocumentSourceBucketAuto returning eof when disposed +- :issue:`SERVER-57615` Reset CWWC to w:majority for tests that don't create/stop the replica set +- :issue:`SERVER-57616` Wait for secondary to load signing keys in disable_cluster_time_gossiping_in_unreadable_state.js +- :issue:`SERVER-57617` Have the OplogFetcher in Tenant Migrations do an aggregation query instead of a find +- :issue:`SERVER-57630` Enable SSL_OP_NO_RENEGOTIATION on Ubuntu 18.04 when running against OpenSSL 1.1.1 +- :issue:`SERVER-57651` Prevent integer overflow in Query Planner parsing of hint parameter +- :issue:`SERVER-57657` disable_cluster_time_gossiping_in_unreadable_state.js shouldn't modify a response's $clusterTime +- :issue:`SERVER-57700` Measure latency/throughput of resharding::data_copy::fillBatchForInsert in ReshardingCollectionCloner::doOneBatch +- :issue:`SERVER-57737` The index builds code path can throw WCEs and invalidate an active cursor by calling abandonSnapshot without calling save/restore cursor. +- :issue:`SERVER-57740` ShardingTest use X509 also with preferTLS mode +- :issue:`SERVER-58051` Mongod.exe does not release file handles on rotated logs on windows 10 +- :issue:`SERVER-58060` Add new aggregation stage to downconvert RRFaM images to oplog entries +- :issue:`SERVER-58068` Multi updates interrupted by a tenant migration should wait for the migration to complete +- :issue:`SERVER-58119` single_node_set_new_hostname.js needs to call replSetReconfig with an assert.soonNoExcept +- :issue:`SERVER-58152` Create Feature flag for Remove Faulty Mongos From Cluster Topology +- :issue:`SERVER-58160` Increase egress timeout in cluster_x509_roate.js +- :issue:`SERVER-58184` Checkpoint thread causes assertions when raced with recovering prepared transactions on startup +- :issue:`SERVER-58264` Only run cron jobs in Evergreen on the master branch +- :issue:`SERVER-58293` mongocryptd does not include server API fields in explain command response +- :issue:`SERVER-58353` Fix disabled Replication tests failing in multiversion suites due to changing latest release to 5.1 +- :issue:`SERVER-58392` Unpin durable history on rollback to refetch +- :issue:`SERVER-58399` Duplicate errInfo field in write errors when operation fails document validation +- :issue:`SERVER-58402` Increase timeout of shutdown command in shutdown_primary.js +- :issue:`SERVER-58420` Gracefully handle the demotion of data-types in umask +- :issue:`SERVER-58432` Include dochub link in log line 5578800 when warning about deprecation/removal of old op codes +- :issue:`SERVER-58438` Tenant migration retryable write prefetching pipeline could be very slow under load +- :issue:`SERVER-58464` Invariant failure during time-series insert with concurrent shutdown +- :issue:`SERVER-58565` Adjust timeout for replica_sets_jscore_passthrough +- :issue:`SERVER-58581` Add SEARCH_META variable that populates from mongot +- :issue:`SERVER-58582` Create $documents stage and implement collectionless unionWith +- :issue:`SERVER-58588` Implement $searchMeta stage +- :issue:`SERVER-58594` ReplicationCoordinatorImpl::handleHeartbeatResponse_forTest doesn't use _mutex when reading _rsConfig +- :issue:`SERVER-58620` New recipient primary can complete migration before donor renames collection in tenant_migration_resume_collection_cloner_after_rename.js +- :issue:`SERVER-58626` Mark capped_max1 as tenant_migration_incompatible. +- :issue:`SERVER-58637` Temporarily disable null_query_semantics.js from multiversion passthroughs +- :issue:`SERVER-58669` createIndexes, dropIndexes, and collMod may still fail with ReshardCollectionInProgress after resharding operation completes +- :issue:`SERVER-58676` Ban pipelines that set SEARCH_META variable in sharded collections +- :issue:`SERVER-58682` check_todos.py should be no-oping in the waterfall +- :issue:`SERVER-58698` [Linux Repeated Execution builder] disable concurrency_replication_multi_stmt_txn +- :issue:`SERVER-58740` Reserve multiple oplog slots when writing retryable findAndModify with storeFindAndModifyImagesInSideCollection=true +- :issue:`SERVER-58806` Use replica_sets_jscore_passthrough_gen task on Enterprise MacOS +- :issue:`SERVER-58812` tenant_migration_timeseries_retryable_write_oplog_cloning.js should get donorDoc before being garbage collected +- :issue:`SERVER-58815` Have internal findAndModifyImageLookup set the synthetic oplog entry to timestamp of findAndModify - 1 +- :issue:`SERVER-58823` The refineShardKey command should mark its operation context as interruptible at step down/step up +- :issue:`SERVER-58855` Improve/Fix the Race Condition in out_max_time_ms.js +- :issue:`SERVER-58857` Change stream accidentally filters out rename event from reshardCollection [5.0 Only] +- :issue:`SERVER-58886` Allow 'vars' result to be returned from a sharded search query but fail on SEARCH_META access +- :issue:`SERVER-58898` Prevent writing to "local" db from waiting for writeConcern +- :issue:`SERVER-58904` Escaped or single-quoted DESTDIR causes malformed .ninja and resmoke.ini +- :issue:`SERVER-58919` sharding_jscore_passthrough_wire_ops_gen needs to be marked as a generated task. +- :issue:`SERVER-58948` idl_tool: support generated idls +- :issue:`SERVER-58973` Fix failure deprecated_wire_ops_mongos.js with v5.0 windows debug build +- :issue:`SERVER-58984` awaitable_hello_fcv_change.js doesn't account for window between awaitable hello requests due to reconfig +- :issue:`SERVER-59000` Enforce dependencies for generated tasks +- :issue:`SERVER-59025` Increase storage log verbosity in oplog_slow_sampling_logging.js +- :issue:`SERVER-59040` add operations_longer_than_stepdown_interval tag to background_unique_indexes.js +- :issue:`SERVER-59044` Handle empty time series collection for $sample in the TrialStage +- :issue:`SERVER-59056` [5.0] Fix primary check in timeseries_retryable_write_downgrade.js +- :issue:`SERVER-59071` Using $sample can trigger invariant when connecting directly to shards +- :issue:`SERVER-59091` Avoid fetching namespace from durable catalog for every key inserted in index build +- :issue:`SERVER-59093` Temporarily disable the failing jstest suite for ephemeralForTest on evergreen +- :issue:`SERVER-59101` remove unnecessary LIBDEPS edge from pipeline library +- :issue:`SERVER-59117` xcode next builders hit dyld 512 library limit +- :issue:`SERVER-59121` ssh connection failure during check_disk command in powercycle should cause ssh failure exit +- :issue:`SERVER-59135` Make mongocryptd targets in MSIs depend on libsasl2 +- :issue:`SERVER-59158` Support running checkFCV() shell helper with mongos connection +- :issue:`SERVER-59188` Coverity analysis defect 120391: Uninitialized scalar field +- :issue:`SERVER-59197` Delete fam image entries when the corresponding session documents are deleted +- :issue:`SERVER-59203` Don't rely on mocks to test generating tasks for build variants +- :issue:`SERVER-59204` unowned filter BSONObj stored in PlanCache entry debugInfo +- :issue:`SERVER-59217` convert spaces to tabs for package files +- :issue:`SERVER-59236` Add function to legacy shell to recursively copy directories +- :issue:`SERVER-59242` update to snmp 5.9.1 +- :issue:`SERVER-59291` Consider adding 'enableSearchMeta' query knob +- :issue:`SERVER-59324` Remove feature flag performance variant from sys-perf on 5.0. +- :issue:`SERVER-59353` Have shell strip featureFlagRetryableFindAndModify when launching mongod version <= 4.4 +- :issue:`SERVER-59362` Setup Fault Manager State Machine +- :issue:`SERVER-59404` Avoid powercycle_smoke_skip_compile reaching task timeout +- :issue:`SERVER-59431` [v5.0] disable parallel task in EFT builder +- :issue:`SERVER-59516` Create opCtx outside of lock in oplog fetcher +- :issue:`SERVER-59573` Add setParameter which can be used to restore inactive cursor timeout in sessions +- :issue:`SERVER-59640` [5.0] Add coverage for geoSearch command in views_all_commands.js test +- :issue:`WT-6755` Documentation: populate developer glossary +- :issue:`WT-6910` Write "history store" subpage for Architecture Guide +- :issue:`WT-6911` Write "block manager" subpage for Architecture Guide +- :issue:`WT-6915` Write "log files" subpage for Architecture Guide +- :issue:`WT-7006` Write Connection subpage for Architecture Guide +- :issue:`WT-7007` Backup architecture guide page +- :issue:`WT-7198` Fix test_backup15 failure with backup mismatch +- :issue:`WT-7352` Fix test_hs01 conflict between concurrent operations in cursor modify +- :issue:`WT-7363` Add support for dumping history store output in hex format +- :issue:`WT-7521` Remove excess ckplist invalidations +- :issue:`WT-7592` Remove log_flush("sync=background") support +- :issue:`WT-7599` Update the CONFIG file based on the release that is about to run for compatibility tests +- :issue:`WT-7663` Change local store extension to allow only readonly FS operations +- :issue:`WT-7673` Investigate and fix manydbs test failure on Windows +- :issue:`WT-7718` Rename 'build_cmake' +- :issue:`WT-7838` Ability for ordered timestamp assertion to do more than a log message +- :issue:`WT-7842` Remove explicit ulimit -n call in many-collection-test +- :issue:`WT-7860` Improve code coverage reporting +- :issue:`WT-7866` Update cache_hs_insert limits in cppsuite-hs-cleanup-stress +- :issue:`WT-7876` Update rollback to stable test to use correct boolean values and update statistic checking logic +- :issue:`WT-7880` Fix history store record issue when the update following the prepared update is in history store +- :issue:`WT-7891` Remove doc typos +- :issue:`WT-7893` Remove ignored message from wiredtiger_open in test_encrypt08 +- :issue:`WT-7895` Fix arch-data-file.dox documentation build failure +- :issue:`WT-7897` Enable verbose logging for test_backup15 to aid debugging +- :issue:`WT-7900` Fix insertion of new records in test format for column-store +- :issue:`WT-7901` test suite cleanup +- :issue:`WT-7905` Fix incorrect builtin behaviour for builds in CMake +- :issue:`WT-7907` Add dependencies to swig module definition in CMake build +- :issue:`WT-7908` Make variable-length column store work again with the static tests +- :issue:`WT-7909` Create a new method to check for running user transactions before starting rollback-to-stable operation +- :issue:`WT-7918` Support setting a prepare timestamp at current read timestamp +- :issue:`WT-7928` VLCS checkpoint and additional test suite improvements +- :issue:`WT-7931` Evicting modifies using the evict cursor in test_multiple_older_readers_with_multiple_mixed_mode() to ensure that eviction happens. +- :issue:`WT-7934` Upload perf results from many-collection test to Altas +- :issue:`WT-7935` Add arm64 implementation of rdtsc equivalent instruction +- :issue:`WT-7936` Update the format.sh script to run recovery tests +- :issue:`WT-7937` Fix s_docs to use sh, not bash syntax +- :issue:`WT-7938` Fix rollback-to-stable memory leak on error +- :issue:`WT-7940` Update mongod path for many-coll test +- :issue:`WT-7941` Add an Evergreen task to test abort/recovery using test/format +- :issue:`WT-7943` Do not assert timestamps when rolling back a prepared transactions +- :issue:`WT-7945` Move rollback handling to the operation layer in the cppsuite. +- :issue:`WT-7947` Allow CMake to take in a specific Python version +- :issue:`WT-7952` Minor docs build fixes +- :issue:`WT-7953` Teach s_string to not look inside getopt option lists. +- :issue:`WT-7955` Copy format.sh and CONFIG.stress to the test/format build directory with CMake +- :issue:`WT-7956` RTS to skip deleted or stable RLE cells +- :issue:`WT-7961` Sometimes lag oldest timestamp in timestamp_abort. +- :issue:`WT-7964` Fix rollback to stable incorrectly not rolling back updates at snap_max +- :issue:`WT-7965` Update connection base write generation number at the end of recovery checkpoint +- :issue:`WT-7968` In timestamp_abort skip setting timestamps when all_durable moves backwards +- :issue:`WT-7970` Set the stable timestamp before starting the checkpointer and clock threads +- :issue:`WT-7974` More column-store fixes and tests +- :issue:`WT-7984` Fix a bug that could cause a checkpoint to omit a page of data +- :issue:`WT-7994` Add docs compile task to PR testing +- :issue:`WT-7995` Fix the global visibility that it cannot go beyond checkpoint visibility +- :issue:`WT-7996` More column-store C testing +- :issue:`WT-7998` Minor fixes on Cache subpage of Architecture Guide +- :issue:`WT-7999` Fix the assert to handle an update in the middle with max stop timestamp +- :issue:`WT-8005` Fix a prepare commit bug that could leave the history store entry unresolved +- :issue:`WT-8006` sync/checkpoint cleanup code isn't appropriate for VLCS + diff --git a/source/includes/currentOp-output-example.rst b/source/includes/currentOp-output-example.rst index b8ca98380fd..09bc864d258 100644 --- a/source/includes/currentOp-output-example.rst +++ b/source/includes/currentOp-output-example.rst @@ -342,6 +342,8 @@ "op" : , "ns" : , "command" : , + "configTime" : , // Starting in 5.0 + "topologyTime" : , // Starting in 5.0 "planSummary": , "prepareReadConflicts" : , "writeConflicts" : , diff --git a/source/includes/downgrade-path.rst b/source/includes/downgrade-path.rst index 890a144aa05..a23a81e1b10 100644 --- a/source/includes/downgrade-path.rst +++ b/source/includes/downgrade-path.rst @@ -1 +1,3 @@ +.. include:: /includes/upgrade-downgrade-replica-set.rst + Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of |downgradeversion|. diff --git a/source/includes/extracts-5.0-changes.yaml b/source/includes/extracts-5.0-changes.yaml index 7eb11a0ff65..7852eaedbdf 100644 --- a/source/includes/extracts-5.0-changes.yaml +++ b/source/includes/extracts-5.0-changes.yaml @@ -29,4 +29,15 @@ content: | Dropping the :term:`admin database` or the :term:`config database` can leave your cluster in an unusable state. +--- + +ref: mongosh-password-prompt +content: | + + The :method:`passwordPrompt()` method prompts you to enter the + password. You can also specify your password directly as a string. We + recommend to use the :method:`passwordPrompt()` method to avoid the + password being visible on your screen and potentially leaking the + password to your shell history. + ... diff --git a/source/includes/extracts-create-users-base.yaml b/source/includes/extracts-create-users-base.yaml index 55df6eea5f0..d7df57c8f5b 100644 --- a/source/includes/extracts-create-users-base.yaml +++ b/source/includes/extracts-create-users-base.yaml @@ -1,10 +1,10 @@ ref: _create-user-intro content: | - Users that will authenticate to MongoDB using an external authentication - mechanism, such as {{mechanism}}, must be created in the ``$external`` database, - which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` to consult an - external source for authentication. - + Users that authenticate to MongoDB using an external authentication + mechanism, such as {{mechanism}}, must be created in the ``$external`` + database, which allows :binary:`~bin.mongos` or :binary:`~bin.mongod` + to consult an external source for authentication. + .. include:: /includes/extracts/sessions-external-username-limit.rst ... \ No newline at end of file diff --git a/source/includes/extracts-create-users.yaml b/source/includes/extracts-create-users.yaml index a519296f8a2..08e9c11156f 100644 --- a/source/includes/extracts-create-users.yaml +++ b/source/includes/extracts-create-users.yaml @@ -2,7 +2,7 @@ ref: create-user-intro-kerberos inherit: ref: _create-user-intro file: extracts-create-users-base.yaml -replacement: +replacement: mechanism: "Kerberos" --- ref: create-user-intro-ldap @@ -18,4 +18,4 @@ inherit: file: extracts-create-users-base.yaml replacement: mechanism: "x.509 Client Certificate Authentication" -... +... diff --git a/source/includes/extracts-server-status-projection-base.yaml b/source/includes/extracts-server-status-projection-base.yaml index c0388a1ac2c..0df4b243298 100644 --- a/source/includes/extracts-server-status-projection-base.yaml +++ b/source/includes/extracts-server-status-projection-base.yaml @@ -11,192 +11,4 @@ content: | field and set it to ``1`` in the command. To exclude fields that are included by default, specify the top-level field and set to ``0`` in the command. ---- -ref: _serverStatus-output-changes -content: | - - - Starting in MongoDB 5.0, {{operationName}}: - - - Added new metrics to track use of Aggregation Pipeline methods: - - - :serverstatus:`metrics.commands.update.pipeline` - - - :serverstatus:`metrics.commands.findAndModify.pipeline` - - - Added new metrics to track use of arrayFilter methods: - - - :serverstatus:`metrics.commands.update.arrayFilters` - - - :serverstatus:`metrics.commands.findAndModify.arrayFilters` - - - Added new metric to track number of times ``newlyAdded`` fields - were automatically removed: - - - :serverstatus:`metrics.repl.reconfig.numAutoReconfigsForRemovalOfNewlyAddedFields` - - - Replaced :serverstatus:`opReadConcernCounters` with - :serverstatus:`readConcernCounters` to track use of read concern - levels specified by query operations - - - Added new metric to track number of incoming connections: - - - :serverstatus:`connections.threaded` - - - Added new metric to track resharding operations: - - - :serverstatus:`shardingStatistics.resharding` - - - Added new metric to track service executors: - - - :serverstatus:`network.serviceExecutors` - - - Added new metrics to track cursors: - - - :serverstatus:`metrics.cursor.moreThanOneBatch` - - - :serverstatus:`metrics.cursor.totalOpened` - - - Added new metric to track hello commands: - - - :serverstatus:`connections.exhaustHello` - - - Starting in MongoDB 4.4, {{operationName}}: - - - Added new metrics to track write concern failures caused - by a custom global default write concern: - - - :serverstatus:`metrics.getLastError.default` - - - :serverstatus:`metrics.getLastError.default.unsatisfiable` - - - :serverstatus:`metrics.getLastError.default.wtimeouts` - - - Added new metrics to track authentication mechanism usage: - - - :serverstatus:`security.authentication.mechanisms` - - Each field in :serverstatus:`security.authentication.mechanisms` - represents an authentication mechanism supported by your - :binary:`~bin.mongod` / :binary:`~bin.mongos` instance, and - includes information on the number of times that mechanism - has been used. - - These metrics are also available starting in MongoDB - 4.2.6 and 4.0.19. - - - Added new topology metrics in :serverstatus:`connections`: - - - :serverstatus:`connections.exhaustIsMaster` - - - :serverstatus:`connections.awaitingTopologyChanges` - - - Added new metrics to track slow DNS and SSL handshake operations - in :serverstatus:`network`: - - - :serverstatus:`network.numSlowDNSOperations` - - - :serverstatus:`network.numSlowSSLOperations` - - - Added new sync source metrics in :serverstatus:`metrics.repl`: - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed` - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.num` - - - :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.totalMillis` - - - :serverstatus:`metrics.repl.network.replSetUpdatePosition.num` - - - :serverstatus:`metrics.repl.syncSource.numSelections` - - - :serverstatus:`metrics.repl.syncSource.numTimesChoseSame` - - - :serverstatus:`metrics.repl.syncSource.numTimesChoseDifferent` - - - :serverstatus:`metrics.repl.syncSource.numTimesCouldNotFind` - - - Added new metrics to track aggregation pipeline stage use in - :serverstatus:`metrics.aggStageCounters`. - - - Added new metrics to track queries that perform a collection scan: - - - :serverstatus:`metrics.queryExecutor.collectionScans` - - :serverstatus:`metrics.queryExecutor.collectionScans.nonTailable` - - :serverstatus:`metrics.queryExecutor.collectionScans.total` - - - Added new :serverstatus:`range deletion metrics - ` in - :serverstatus:`shardingStatistics`. - - - Starting in MongoDB 4.2.2, {{operationName}}: - - - Added new transaction metrics in :serverstatus:`transactions` for - :binary:`~bin.mongos`: - - - :serverstatus:`transactions.currentOpen` - - - :serverstatus:`transactions.currentActive` - - - :serverstatus:`transactions.currentInactive` - - - Starting in MongoDB 4.2.1 (and 4.0.13), {{operationName}} includes: - - - :ref:`electionMetrics ` - - - Starting in MongoDB 4.2, {{operationName}}: - - - Returns :serverstatus:`opcounters` and - :serverstatus:`opcountersRepl` metrics as 64-bit integers (i.e. - NumberLong) instead of 32-bit integers (i.e. NumberInt). - - - Includes ``trafficRecording`` metrics in its output. - - - Added new document count (``countDocs``) metrics in - :serverstatus:`shardingStatistics`. - - - Added new unacknowledged writes counts to - :serverstatus:`metrics.repl.network`. - - - Added new user operations counts to - :serverstatus:`metrics.repl.stepDown`. - - - Added new transaction metrics in :serverstatus:`transactions` for - :binary:`~bin.mongod`. - - - Includes :serverstatus:`transactions` metrics for - :binary:`~bin.mongos`. - - - Added - :serverstatus:`~logicalSessionRecordCache.sessionCatalogSize` - metric to :serverstatus:`logicalSessionRecordCache`. - - - Added - :serverstatus:`~shardingStatistics.countDonorMoveChunkLockTimeout` - metric to :serverstatus:`shardingStatistics`. - - - Added ``ReplicationStateTransition`` lock information to - :serverstatus:`locks`. - - - Reports ``ParallelBatchWriterMode`` lock information separately from - ``Global`` lock information. See :serverstatus:`locks`. - - - Starting in MongoDB 4.0.6, {{operationName}} includes: - - - :serverstatus:`opReadConcernCounters` - - - :serverstatus:`opWriteConcernCounters` (Requires - :parameter:`reportOpWriteConcernCountersInServerStatus` parameter - set to ``true``). - - - :serverstatus:`metrics.repl.apply.batchSize` - - - Starting in MongoDB 4.0, {{operationName}} includes - :serverstatus:`shardingStatistics` in its output. - - - Starting in MongoDB 3.6, {{operationName}} no longer outputs the - ``rangeDeleter`` section. - - - Starting in MongoDB 3.0, {{operationName}} no longer outputs the - ``workingSet``, ``indexCounters``, and ``recordStats`` sections. - ... diff --git a/source/includes/extracts-server-status-projection.yaml b/source/includes/extracts-server-status-projection.yaml index b201db4d4e4..f12a1e59904 100644 --- a/source/includes/extracts-server-status-projection.yaml +++ b/source/includes/extracts-server-status-projection.yaml @@ -12,20 +12,6 @@ inherit: replacement: operationName: ":method:`db.serverStatus()`" --- -ref: serverStatus-command-output-change -inherit: - ref: _serverStatus-output-changes - file: extracts-server-status-projection-base.yaml -replacement: - operationName: ":dbcommand:`serverStatus`" ---- -ref: serverStatus-method-output-change -inherit: - ref: _serverStatus-output-changes - file: extracts-server-status-projection-base.yaml -replacement: - operationName: ":method:`db.serverStatus()`" ---- ref: serverStatus-opWriteConcernCounters content: | diff --git a/source/includes/extracts-sessions.yaml b/source/includes/extracts-sessions.yaml index c5b7ec20130..e98bd15a55e 100644 --- a/source/includes/extracts-sessions.yaml +++ b/source/includes/extracts-sessions.yaml @@ -101,11 +101,10 @@ content: | ref: sessions-external-username-limit content: | - .. versionchanged:: 3.6.3 + To use :ref:`sessions` with ``$external`` authentication users + (Kerberos, LDAP, or x.509 users), the usernames cannot be greater + than 10k bytes. - To use sessions with ``$external`` authentication users (i.e. - Kerberos, LDAP, x.509 users), the usernames cannot be greater - than 10k bytes. --- ref: sessions-cursor-timeout content: | diff --git a/source/includes/extracts-ssl-facts.yaml b/source/includes/extracts-ssl-facts.yaml index 22bc149360e..3304090e1a1 100644 --- a/source/includes/extracts-ssl-facts.yaml +++ b/source/includes/extracts-ssl-facts.yaml @@ -1,13 +1,11 @@ ref: ssl-facts-x509-invalid-certificate content: | - Starting in MongoDB 4.0, if you specify - ``--sslAllowInvalidCertificates`` or - ``net.ssl.allowInvalidCertificates: true`` (or in MongoDB 4.2, the - alias ``--tlsAllowInvalidateCertificates`` or - ``net.tls.allowInvalidCertificates: true``) when using x.509 + Starting in MongoDB 4.2, if you specify + ``--tlsAllowInvalidateCertificates`` or + ``net.tls.allowInvalidCertificates: true`` when using x.509 authentication, an invalid certificate is only sufficient to - establish a TLS/SSL connection but is *insufficient* for + establish a TLS connection but it is *insufficient* for authentication. --- @@ -28,10 +26,8 @@ ref: ssl-facts-x509-ca-file content: | To use x.509 authentication, ``--tlsCAFile`` or ``net.tls.CAFile`` - must be specified unless using ``--tlsCertificateSelector`` or - ``--net.tls.certificateSelector``. Or if using the ``ssl`` aliases, - ``--sslCAFile`` or ``net.ssl.CAFile`` must be specified unless using - ``--sslCertificateSelector`` or ``net.ssl.certificateSelector``. + must be specified unless you are using ``--tlsCertificateSelector`` + or ``--net.tls.certificateSelector``. --- ref: ssl-facts-see-more diff --git a/source/includes/extracts-x509-certificate.yaml b/source/includes/extracts-x509-certificate.yaml index 81736beabd9..f34f1411057 100644 --- a/source/includes/extracts-x509-certificate.yaml +++ b/source/includes/extracts-x509-certificate.yaml @@ -1,7 +1,7 @@ ref: x509-certificate-client content: | - The client certificate must have the following - properties: + + Client certificates must have the following properties: - A single Certificate Authority (CA) must issue the certificates for both the client and the server. @@ -16,65 +16,63 @@ content: | - Each unique MongoDB user must have a unique certificate. - A client x.509 certificate's subject, which contains the - Distinguished Name (``DN``), must **differ** from that of a - :ref:`x509-member-certificate`. - + Distinguished Name (``DN``), must **differ** from the subjects of + :ref:`member x.509 certificates `. + At least one of the Organization (``O``), Organizational Unit (``OU``), or Domain Component (``DC``) attributes in the client certificate must differ from those in the :setting:`net.tls.clusterFile` and - :setting:`net.tls.certificateKeyFile` server certificates. - + :setting:`net.tls.certificateKeyFile` server certificates. If a + client x.509 certificate's subject has the same ``O``, ``OU``, and + ``DC`` combination as the :ref:`x509-member-certificate` (or + :parameter:`tlsX509ClusterAuthDNOverride` if set), the client + connection is rejected. Only :ref:`cluster member x509 certificates + ` should use same ``O``, ``OU``, and + ``DC`` combinations as this grants full permissions. + If the MongoDB deployment has - :parameter:`tlsX509ClusterAuthDNOverride` set (available starting - in MongoDB 4.2), the client x.509 certificate's subject must also + :parameter:`tlsX509ClusterAuthDNOverride` set (*available starting + in MongoDB 4.2*), the client x.509 certificate's subject must also differ from that value. - .. warning:: - - If a client x.509 certificate's subject has the same ``O``, - ``OU``, and ``DC`` combination as the - :ref:`x509-member-certificate` (or - :parameter:`tlsX509ClusterAuthDNOverride` if set), the client - connection is rejected. Only - :ref:`cluster member x509 certificates ` - should use same ``O``, ``OU``, and ``DC`` combinations as this - grants full permissions. + - The x.509 certificate must *not* be expired. - - The x.509 certificate must *not* be expired. - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-certificate-member content: | - The member certificate (:setting:`net.tls.clusterFile`, if - specified, and :setting:`net.tls.certificateKeyFile`), used to - verify membership to the sharded cluster or a replica set, must have - the following properties: + Member certificates which you use to verify membership to a sharded + cluster or a replica set (:setting:`net.tls.clusterFile`, if + specified, and :setting:`net.tls.certificateKeyFile`), must have the + following properties: - A single Certificate Authority (CA) must issue all the x.509 certificates for the members of a sharded cluster or a replica set. - The Distinguished Name (``DN``), found in the member certificate's - ``subject``, must specify a non-empty value for *at least one* of the - following attributes: Organization (``O``), the Organizational Unit - (``OU``) or the Domain Component (``DC``). - + ``subject``, must specify a non-empty value for *at least one* of + the following attributes: + + - the Organization (``O``) + - the Organizational Unit (``OU``) + - the Domain Component (``DC``) + - The Organization attributes (``O``\'s), the Organizational Unit attributes (``OU``\'s), and the Domain Components (``DC``\'s) must match those from both the :setting:`net.tls.clusterFile` and :setting:`net.tls.certificateKeyFile` certificates for the other cluster members (or the :parameter:`tlsX509ClusterAuthDNOverride` value, if set). - + To match, the certificate must match all specifications of these - attributes, or even the non-specification of these attributes. The + attributes, even the non-specification of these attributes. The order of the attributes does not matter. In the following example, the two ``DN``\'s contain matching - specifications for ``O``, ``OU`` as well as the non-specification of - the ``DC`` attribute. + specifications for ``O``, ``OU`` as well as the non-specification + of the ``DC`` attribute. .. code-block:: none @@ -97,8 +95,8 @@ content: | names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names. - For example, the certificates for a cluster could have the following - subjects: + For example, the certificates for a cluster could have the + following subjects: .. code-block:: bash @@ -106,68 +104,49 @@ content: | subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US subject= CN=,OU=Dept1,O=MongoDB,ST=NY,C=US - - *If* the certificate includes the Extended Key Usage (``extendedKeyUsage``) - setting, the value must include ``clientAuth`` ("TLS Web Client - Authentication"). + - *If* the certificate includes the Extended Key Usage + (``extendedKeyUsage``) setting, the value must include + ``clientAuth`` ("TLS Web Client Authentication"). .. code-block:: none extendedKeyUsage = clientAuth - - You can also use a certificate that does not include the Extended - Key Usage (EKU). - - The x.509 certificate must *not* be expired. - + - The x.509 certificate must *not* be expired. + .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst --- ref: x509-member-auth-configuration content: | - In addition to any TLS/SSL configurations as appropriate for your - deployment, include the following to specify x.509 for internal - authentication for each member of your replica set (i.e. the - :binary:`~bin.mongod` instances) or sharded cluster (i.e. the - :binary:`~bin.mongod` and :binary:`~bin.mongos` instances): + You can use TLS for internal authentication between each member of + your replica set (each :binary:`~bin.mongod` instance) or sharded + cluster (each :binary:`~bin.mongod` and :binary:`~bin.mongos` + instance). + + To use TLS for internal authentication, use the following settings: - :setting:`security.clusterAuthMode` or :option:`--clusterAuthMode ` set to ``x509`` - :setting:`net.tls.clusterFile` or :option:`--tlsClusterFile - ` (*both new in MongoDB 4.2*) - - However, if no cluster file is specified, members can use their - certificate key file specified in + ` (*available starting in MongoDB 4.2*) + + :binary:`~bin.mongod` and :option:`mongos ` instances use their certificate key file to + prove their identity to clients, but it can also be used for + membership authentication. If you do not specify a cluster file, + members use their certificate key file for membership authentication. + The certificate key file is the file you specify with :setting:`net.tls.certificateKeyFile` or :option:`--tlsCertificateKeyFile ` - (*both new in MongoDB 4.2*) for membership authentication. This - :setting:`certificate key file ` is used - by :binary:`~bin.mongod` (and :option:`mongos - `) instances to prove their identity - to clients, but can also be used for membership authentication. To - use for both client authentication and membership authentication, - the certificate must either: + (*available starting in MongoDB 4.2*). - - Omit ``extendedKeyUsage`` or + To use the :setting:`certificate key file + ` for both client authentication and + membership authentication, the certificate must either: - - Specify ``extendedKeyUsage`` values - - .. note:: - - Athough still available, :setting:`net.ssl.clusterFile` (and the - correponding :option:`--sslClusterFile `) and :setting:`net.ssl.PEMKeyFile` (and the - corresponding :option:`--sslPEMKeyFile `) - are :ref:`deprecated as of MongoDB 4.2 <4.2-tls>`. - - For deployments using MongoDB version 4.0 and earlier, use - :setting:`net.ssl.clusterFile` (or the corresponding - :option:`--sslClusterFile `) and - :setting:`net.ssl.PEMKeyFile` (or the corresponding - :option:`--sslPEMKeyFile `). - - - The x.509 certificate must *not* be expired. - - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst + - Omit ``extendedKeyUsage`` or + - Specify ``extendedKeyUsage = serverAuth, clientAuth`` ... diff --git a/source/includes/fact-5.0-multiple-partial-index.rst b/source/includes/fact-5.0-multiple-partial-index.rst new file mode 100644 index 00000000000..9f44b95f3ab --- /dev/null +++ b/source/includes/fact-5.0-multiple-partial-index.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, multiple +:doc:`partial indexes ` +can be created using the same :ref:`key pattern` as long +as the :ref:`partialFilterExpression ` +fields do not express equivalent filters. + +In earlier versions of MongoDB, creating multiple +:doc:`partial indexes` is not allowed when +using the same key pattern with different +:ref:`partialFilterExpressions `. diff --git a/source/includes/fact-5.0-non-transactional-config-reads.rst b/source/includes/fact-5.0-non-transactional-config-reads.rst new file mode 100644 index 00000000000..a1fe1c0738c --- /dev/null +++ b/source/includes/fact-5.0-non-transactional-config-reads.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, non-transaction reads are not allowed on +the :data:`config.transactions` collection with the following +read concerns and options: + +- :readconcern:`"snapshot"` +- :readconcern:`"majority"` and the + :ref:`afterClusterTime` option is set +- When using a :driver:`MongoDB Driver ` + and :readconcern:`"majority"` + within a :ref:`causally consistent session` \ No newline at end of file diff --git a/source/includes/fact-ObjectId-construct.rst b/source/includes/fact-ObjectId-construct.rst index 6aea30714a0..9f6abc15072 100644 --- a/source/includes/fact-ObjectId-construct.rst +++ b/source/includes/fact-ObjectId-construct.rst @@ -1,7 +1,8 @@ - a 4-byte *timestamp value*, representing the ObjectId's creation, measured in seconds since the Unix epoch -- a 5-byte *random value* +- a 5-byte *random value* generated once per process. This random value + is unique to the machine and process. - a 3-byte *incrementing counter*, initialized to a random value diff --git a/source/includes/fact-authenticate.rst b/source/includes/fact-authenticate.rst deleted file mode 100644 index 1cb3cf469f5..00000000000 --- a/source/includes/fact-authenticate.rst +++ /dev/null @@ -1,20 +0,0 @@ -To authenticate as a user, you must provide a username, password, and -the :ref:`authentication database ` -associated with that user. - -To authenticate using :binary:`~bin.mongosh`, either: - -- Use the :binary:`~bin.mongosh` command-line authentication options - (:option:`--username `, - :option:`--password `, and - :option:`--authenticationDatabase `) - when connecting to the :binary:`~bin.mongod` or - :binary:`~bin.mongos` instance, or - -- Connect first to the :binary:`~bin.mongod` or :binary:`~bin.mongos` - instance, and then run the :dbcommand:`authenticate` command or the - :method:`db.auth()` method against the :ref:`authentication database - `. - -For examples of authenticating using a MongoDB driver, see the -`driver documentation `__. diff --git a/source/includes/fact-case-sensitivity-limitation-code.rst b/source/includes/fact-case-sensitivity-limitation-code.rst new file mode 100644 index 00000000000..ea35a2174af --- /dev/null +++ b/source/includes/fact-case-sensitivity-limitation-code.rst @@ -0,0 +1,31 @@ + +.. example:: + + If the database ``salesDB`` already exists MongoDB will + return an error if if you attempt to create a database named ``salesdb``. + + .. code-block:: javascript + + mixedCase = db.getSiblingDB('salesDB') + lowerCase = db.getSiblingDB('salesdb') + + mixedCase.retail.insertOne({ "widgets": 1, "price": 50 }) + + The operation succeeds and :method:`~db.collection.insertOne()` implicitly + creates the ``SalesDB`` database. + + .. code-block:: javascript + + lowerCase.retail.insertOne({ "widgets": 1, "price": 50 }) + + The operation fails. :method:`~db.collection.insertOne()` tries to + create a ``salesdb`` database and is blocked by the naming + restriction. Database names must differ on more than just case. + + .. code-block:: javascript + + lowerCase.retail.find() + + This operation does not return any results because the database names are case + sensitive. There is no error because :method:`~db.collection.find()` doesn't + implicitly create a new database. \ No newline at end of file diff --git a/source/includes/fact-enable-runtime-audit-configuration.rst b/source/includes/fact-enable-runtime-audit-configuration.rst new file mode 100644 index 00000000000..21f3e16c7df --- /dev/null +++ b/source/includes/fact-enable-runtime-audit-configuration.rst @@ -0,0 +1,27 @@ +Starting in MongoDB 5.0, audit configurations for :binary:`~bin.mongod` +and :binary:`~bin.mongos` nodes can be configured at runtime. A group +of these nodes can take part in a distributed audit configuration. + +To include a node in a distributed audit configuration, update the +node's configuration file as follows and restart the server. + +.. list-table:: + :header-rows: 1 + + * - Parameter + - Value + * - :setting:`auditLog.runtimeConfiguration` + - ``true`` + * - :setting:`auditLog.filter` + - Unset + * - :parameter:`auditAuthorizationSuccess` + - Unset + +The server logs an error and fails to start if: + +- ``runtimeConfiguration`` is ``true`` and +- either :setting:`auditLog.filter` or :parameter:`auditAuthorizationSuccess` is set. + +To modify audit filters and the :parameter:`auditAuthorizationSuccess` parameter at +runtime, see :dbcommand:`setAuditConfig`. + diff --git a/source/includes/fact-mongodb-intro.rst b/source/includes/fact-mongodb-intro.rst new file mode 100644 index 00000000000..838af6cb1c2 --- /dev/null +++ b/source/includes/fact-mongodb-intro.rst @@ -0,0 +1,24 @@ +Welcome to the MongoDB {+version+} Manual! MongoDB is a +document database designed for ease of development +and scaling. The Manual introduces key concepts in MongoDB, presents the +query language, and provides operational and administrative +considerations and procedures as well as a comprehensive reference +section. + +MongoDB offers both local and cloud-hosted deployment options: + +- For locally hosted deployments, MongoDB offers both a *Community* + and an *Enterprise* version of the database: + + - MongoDB Community is the {+source-available+} edition of MongoDB. + + - MongoDB Enterprise is available as part of the MongoDB Enterprise + Advanced subscription and includes comprehensive support for your + MongoDB deployment. MongoDB Enterprise also adds enterprise-focused + features such as LDAP and Kerberos support, on-disk encryption, + and auditing. + +- `MongoDB Atlas `__ + is a hosted MongoDB Enterprise service option in the cloud which + requires no installation overhead and offers a free tier to get + started. diff --git a/source/includes/fact-selinux-redhat-options.rst b/source/includes/fact-selinux-redhat-options.rst index 5642952170a..5201f00adc6 100644 --- a/source/includes/fact-selinux-redhat-options.rst +++ b/source/includes/fact-selinux-redhat-options.rst @@ -73,13 +73,20 @@ to your SELinux policy: module mongodb_proc_net 1.0; require { - type proc_net_t; - type mongod_t; - class file { open read }; + type sysctl_net_t; + type mongod_t; + class dir search; + class file { getattr open read }; } - + #============= mongod_t ============== - allow mongod_t proc_net_t:file { open read }; + + #!!!! This avc is allowed in the current policy + allow mongod_t sysctl_net_t:dir search; + allow mongod_t sysctl_net_t:file open; + + #!!!! This avc is allowed in the current policy + allow mongod_t sysctl_net_t:file { getattr read }; EOF #. Once created, compile and load the custom policy module by diff --git a/source/includes/fact-server-status-num-hosts-targeted.rst b/source/includes/fact-server-status-num-hosts-targeted.rst new file mode 100644 index 00000000000..8f675b436ea --- /dev/null +++ b/source/includes/fact-server-status-num-hosts-targeted.rst @@ -0,0 +1,18 @@ +.. list-table:: + :header-rows: 1 + :widths: 20 40 + + * - Name + - Description + + * - ``allShards`` + - A command targeted all shards + + * - ``manyShards`` + - A command targeted more than one shard + + * - ``oneShard`` + - A command targeted one shard + + * - ``unsharded`` + - A command was run on an unsharded collection \ No newline at end of file diff --git a/source/includes/fact-set-global-write-concern-before-reconfig.rst b/source/includes/fact-set-global-write-concern-before-reconfig.rst index 4e09a2139b0..e56e787e6ab 100644 --- a/source/includes/fact-set-global-write-concern-before-reconfig.rst +++ b/source/includes/fact-set-global-write-concern-before-reconfig.rst @@ -1,6 +1,6 @@ Starting in MongoDB 5.0, you must explicitly set the global default :ref:`write concern ` before attempting to reconfigure a -:ref:`non-sharded ` :term:`replica set ` with a +:term:`replica set ` with a :doc:`configuration ` that would change the implicit default write concern. To set the global default write concern, use the :dbcommand:`setDefaultRWConcern` command. diff --git a/source/includes/fact-ssl-certificate-authorities.rst b/source/includes/fact-ssl-certificate-authorities.rst index 904b71469e3..eacaf18f476 100644 --- a/source/includes/fact-ssl-certificate-authorities.rst +++ b/source/includes/fact-ssl-certificate-authorities.rst @@ -1,6 +1,6 @@ For production use, your MongoDB deployment should use valid certificates generated and signed by a certificate authority. You or your organization can generate and maintain an independent certificate -authority, or use certificates generated by third-party TLS/SSL -vendors. Obtaining and managing certificates is beyond the scope of -this documentation. +authority, or use certificates generated by third-party TLS vendors. +Obtaining and managing certificates is beyond the scope of this +documentation. diff --git a/source/includes/fact-timeZoneInfo.rst b/source/includes/fact-timeZoneInfo.rst index 9af599d1cfc..fad8926aa94 100644 --- a/source/includes/fact-timeZoneInfo.rst +++ b/source/includes/fact-timeZoneInfo.rst @@ -1,12 +1,13 @@ The full path from which to load the time zone database. If this option is not provided, then MongoDB will use its built-in time zone database. -The configuration file included with Linux and macOS packages sets the time -zone database path to ``/usr/share/zoneinfo`` by default. +The configuration file included with Linux and macOS packages sets the +time zone database path to ``/usr/share/zoneinfo`` by default. The built-in time zone database is a copy of the `Olson/IANA time zone -database `_. It is updated along with MongoDB -releases, but the release cycle of the time zone database differs from the -release cycle of MongoDB. A copy of the most recent release of the time zone -database can be downloaded from -https://downloads.mongodb.org/olson_tz_db/timezonedb-latest.zip. +database `_. It is updated along with +MongoDB releases, but the time zone database release cycle +differs from the MongoDB release cycle. The most recent release of +the time zone database is available on our `download site +`_. + diff --git a/source/includes/fact-tls-libraries.rst b/source/includes/fact-tls-libraries.rst index cdaa2f17fa1..085a41ff0c8 100644 --- a/source/includes/fact-tls-libraries.rst +++ b/source/includes/fact-tls-libraries.rst @@ -1,4 +1,4 @@ -Starting in version 4.0, MongoDB uses the native TLS/SSL OS libraries: +MongoDB uses the native TLS/SSL OS libraries: .. list-table:: :header-rows: 1 diff --git a/source/includes/fact-update-field-order.rst b/source/includes/fact-update-field-order.rst index 179752df4d6..c87dd51cd83 100644 --- a/source/includes/fact-update-field-order.rst +++ b/source/includes/fact-update-field-order.rst @@ -1,7 +1,7 @@ .. order-of-document-fields -MongoDB preserves the order of the document fields following write -operations *except* for the following cases: +For write operations, MongoDB preserves the order of the document fields +*except* for the following cases: - The ``_id`` field is always the first field in the document. diff --git a/source/includes/fact-update-operator-processing-order.rst b/source/includes/fact-update-operator-processing-order.rst new file mode 100644 index 00000000000..3eddf446867 --- /dev/null +++ b/source/includes/fact-update-operator-processing-order.rst @@ -0,0 +1,4 @@ +Starting in MongoDB 5.0, update operators process document fields with +string-based names in lexicographic order. Fields with numeric names are +processed in numeric order. See :ref:`Update Operators Behavior +` for details. diff --git a/source/includes/fact-validate-standalone-inconsistencies.rst b/source/includes/fact-validate-standalone-inconsistencies.rst index 6e48632f1ca..93bbfb6128b 100644 --- a/source/includes/fact-validate-standalone-inconsistencies.rst +++ b/source/includes/fact-validate-standalone-inconsistencies.rst @@ -10,4 +10,8 @@ Index inconsistencies include: If any inconsistencies are detected by the :method:`db.collection.validate()` command, a warning is returned -and the repair flag on the index is set to ``true``. \ No newline at end of file +and the repair flag on the index is set to ``true``. + +:method:`db.collection.validate()` also validates any documents that +violate the collection's +:ref:`schema validation rules `. \ No newline at end of file diff --git a/source/includes/fact-virtualbox-not-supported.rst b/source/includes/fact-virtualbox-not-supported.rst new file mode 100644 index 00000000000..f68bf362ba1 --- /dev/null +++ b/source/includes/fact-virtualbox-not-supported.rst @@ -0,0 +1,7 @@ +Oracle offers `experimental support +`__ +for VirtualBox on Windows hosts where Hyper-V is running. However, +Microsoft does not support `VirtualBox on Hyper-V +`__. + +Disable Hyper-V if you want to install MongoDB on Windows using VirtualBox. diff --git a/source/includes/important-delayed-replica-set-members.rst b/source/includes/important-delayed-replica-set-members.rst new file mode 100644 index 00000000000..46fae1f58d9 --- /dev/null +++ b/source/includes/important-delayed-replica-set-members.rst @@ -0,0 +1,34 @@ +.. important:: + + If your replica set contains :doc:`delayed members + ` ensure that the delayed + members are hidden and non-voting. + + Hiding delayed replica set members prevents applications from seeing + and querying delayed data without a direct connection to that member. + Making delayed replica set members non-voting means they will not + count towards acknowledging write operations with write concern + :writeconcern:`"majority"`. + + If you do not hide delayed members and one or more nodes + become unavailable, the replica set has to wait for the delayed + member and the commit point lags. A lagged commit point can lead to + performance issues. + + For example, consider a Primary-Secondary-Delayed replica set + configuration where the delayed secondary is voting with a 10 + minute delay. + + With one non-delayed secondary unavailable, the degraded configuration + of Primary-Delayed must wait at least 10 minutes to acknowledge a write + operation with :writeconcern:`"majority"`.The majority commit point + will take longer to advance, leading to cache pressure similar + performance issues with a + :ref:`Primary with a Secondary and an Arbiter` + (PSA) replica set. + + For more information on the majority commit point, see + :doc:`Causal Consistency and Read and Write Concerns + `. For additional + details on resolving performance issues see the + :ref:`replica set maintenance tutorial`. diff --git a/source/includes/intro-rbac.rst b/source/includes/intro-rbac.rst deleted file mode 100644 index 59d30a68acd..00000000000 --- a/source/includes/intro-rbac.rst +++ /dev/null @@ -1,10 +0,0 @@ -MongoDB employs role-based access control (RBAC) to determine access -for users. A user is granted one or more :ref:`roles ` that -determine the user's access or privileges to MongoDB :ref:`resources -` and the :ref:`actions ` -that user can perform. A user should have only the minimal set of -privileges required to ensure a system of :term:`least privilege`. - -Each application and user of a MongoDB system should map to a distinct -user. This *access isolation* facilitates -access revocation and ongoing user maintenance. diff --git a/source/includes/list-table-3.0-driver-compatibility.rst b/source/includes/list-table-3.0-driver-compatibility.rst index e3420c82239..71c85c68203 100644 --- a/source/includes/list-table-3.0-driver-compatibility.rst +++ b/source/includes/list-table-3.0-driver-compatibility.rst @@ -9,35 +9,41 @@ * - :driver:`C ` - `1.1.0 `_ - - :driver:`Perl ` - - `1.0.0 `__ + - :driver:`PHP ` + - `1.0 `_ - * - `C++ `_ + * - :driver:`C++ ` - `1.0.0 `__ - - :driver:`PHP ` - - `1.0 `_ + - :driver:`Python ` + - `2.8 `_ * - :driver:`C# ` - `1.10 `_ - - :driver:`Python ` - - `2.8 `_ + - :driver:`Perl ` + - `1.0.0 `__ + + * - :driver:`Go ` + - `1.0.0 `__ + + - :driver:`Ruby ` + - `1.12 `_ * - :driver:`Java ` - `2.13 `_ - - :driver:`Motor ` + - :driver:`Rust ` + - `1.0.0 `__ + + * - :driver:`Motor ` - `0.4 `_ + - :driver:`Scala ` + - `2.8.0 `_ + * - :driver:`Node.js ` - `1.4.29 `_ - - :driver:`Ruby ` - - `1.12 `_ - - * - - - - - - :driver:`Scala ` - - `2.8.0 `_ + - :driver:`Swift ` + - `1.0.0 `__ diff --git a/source/includes/steps-5.0-downgrade-mongod.yaml b/source/includes/steps-5.0-downgrade-mongod.yaml index c3364828113..a5edf657a7e 100644 --- a/source/includes/steps-5.0-downgrade-mongod.yaml +++ b/source/includes/steps-5.0-downgrade-mongod.yaml @@ -26,6 +26,15 @@ content: | :binary:`~bin.mongod` completes all pending operations, flushes all data to data files, and closes all data files. --- +title: "Update configuration files." +level: 4 +ref: 5.0-downgrade-configuration-files +content: | + + Disable any configurable |newversion| features by updating the + :binary:`~bin.mongod` instance's configuration file before + restarting. +--- title: "Restart with the latest |oldversion| ``mongod`` instance." level: 4 ref: 5.0-downgrade-restart-instance @@ -33,5 +42,5 @@ content: | Replace the |newversion| binary with the downloaded |oldversion| :binary:`~bin.mongod` binary and restart. - + ... diff --git a/source/includes/steps-authorization-create-users.yaml b/source/includes/steps-authorization-create-users.yaml new file mode 100644 index 00000000000..43be6ede609 --- /dev/null +++ b/source/includes/steps-authorization-create-users.yaml @@ -0,0 +1,184 @@ +title: Connect and authenticate +level: 4 +stepnum: 1 +ref: auth-as-admin +content: | + Using :binary:`~bin.mongosh`, connect to your primary + :binary:`~bin.mongod` or, in a sharded cluster, connect to your + :binary:`~bin.mongos` and authenticate as a user administrator or a + user with the :ref:`required privileges `: + + .. tabs:: + + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p + + Enter your password when prompted. + + - id: authafter + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to your database + deployment: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: + + .. code-block:: javascript + + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password when prompted. +--- +title: Create additional users for your deployment +level: 4 +stepnum: 2 +ref: create-additionalusers +pre: | + + .. note:: + + The following step uses :ref:`authentication-scram` authentication. + For additional information on other authentication mechanisms, see + :ref:`create-users-examples`. + + After authenticating as the user administrator, use the + :method:`db.createUser()` method to create additional users. You can assign + any :doc:`built-in roles ` or + :doc:`user-defined roles ` to the + users. + +action: + pre: | + The following operation adds a user ``myTester`` to the ``test`` + database who has the :authrole:`readWrite` role in the ``test`` + database as well as the :authrole:`read` role in the ``reporting`` + database. + + language: javascript + code: | + use test + db.createUser( + { + user: "myTester", + pwd: passwordPrompt(), // or cleartext password + roles: [ { role: "readWrite", db: "test" }, + { role: "read", db: "reporting" } ] + } + ) + +post: | + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + The database where you create the user (in this example, ``test``) is + that user's :ref:`authentication database + `. Although the user authenticates to + this database, the user can have roles in other databases. The + user's authentication database does not limit the user's privileges. + + After creating the additional users, exit :binary:`~bin.mongosh`. + +--- +title: Connect to the instance and authenticate as ``myTester`` +level: 4 +ref: auth-as-mytester +content: | + + .. important:: + + It is not possible to switch between users in the same + :binary:`~bin.mongosh` session. Authenticating as a different user + means the session has the privileges of **both** authenticated + users. To switch between users exit and relaunch + :binary:`~bin.mongosh`. + + After exiting :binary:`~bin.mongosh` as ``myUserAdmin``, reconnect as + ``myTester``: + + .. tabs:: + + tabs: + - id: cmdline2 + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: + + .. code-block:: bash + + mongosh --port 27017 -u "myTester" \ + --authenticationDatabase "test" -p + + Enter the password for the user when prompted. + + - id: authafter2 + name: Authenticate after Connection + content: | + + Using :binary:`~bin.mongosh`, connect to your database + deployment: + + .. code-block:: bash + + mongosh --port 27017 + + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: + + .. code-block:: javascript + + use test + db.auth("myTester", passwordPrompt()) // or cleartext password + + .. tip:: + + .. include:: /includes/extracts/mongosh-password-prompt.rst + + Enter the password for the user when prompted. +--- +title: Insert a document as ``myTester`` +level: 4 +ref: insert-as-mytester +content: | + + As the user ``myTester``, you have privileges to perform read and + write operations in the ``test`` database (as well as perform read + operations in the ``reporting`` database). Once authenticated as + ``myTester``, insert a document into a collection in the ``test`` + database. For example, you can perform the following insert + operation in the ``test`` database: + + .. code-block:: javascript + + db.foo.insert( { x: 1, y: 1 } ) +... diff --git a/source/includes/steps-compass-manual-queries.yaml b/source/includes/steps-compass-manual-queries.yaml index cec87ce5ace..909f42f6f52 100644 --- a/source/includes/steps-compass-manual-queries.yaml +++ b/source/includes/steps-compass-manual-queries.yaml @@ -1,34 +1,17 @@ -title: Enter a query in the query bar +title: Enter a document filter level: 4 ref: enter-query action: pre: | - Queries entered in the query bar must be valid MongoDB syntax. Only - :dbcommand:`finds ` will be executed. - - This example manually selects documents whose ``departureAirportFsCode`` is - "JFK". - - .. figure:: /images/compass/manual-query.png - :alt: Compass query bar with query entered - - When a valid query is entered, the bar is colored green and can be - executed. Invalid queries are colored red. The UI will automatically update - to indicate which fields and values are selected in the query. + A document filter must use valid MongoDB syntax. Only + :dbcommand:`finds ` can be executed. Invalid filters are + colored red. --- -title: Apply the query +title: Apply a document filter level: 4 ref: apply action: pre: | - After entering a query, run it by clicking the Apply button. To clear the - query, use the Reset button. - - Continuing with the example, executing the query displays information on the - matching documents. - - .. figure:: /images/compass/manual-query-results.png - :alt: Compass Apply button executes query - - To clear a query, use the Reset button. + To run a filter, click the :guilabel:`FIND` button. To clear a + filter, click the :guilabel:`RESET` button. ... diff --git a/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml b/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml index 25cd399b289..02102d14e96 100644 --- a/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml +++ b/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml @@ -111,12 +111,9 @@ action: Kerberos name, ensure that you specify the fully qualified domain name (FQDN) for the ``--host`` option, rather than an IP address or unqualified hostname. - - If you are connecting to a system whose hostname does not - match the Kerberos name, use :option:`--gssapiHostName ` - to specify the Kerberos FQDN that it responds to. - pre: | - Alternatively, you can first connect :binary:`mongo.exe + If you are connecting to a system whose hostname does not + match the Kerberos name, first connect :binary:`mongo.exe ` to the :binary:`~bin.mongod.exe`, and then from the :binary:`mongo.exe ` shell, use the :method:`db.auth()` method to authenticate in the ``$external`` diff --git a/source/includes/steps-control-access-to-mongodb-with-kerberos-authentication.yaml b/source/includes/steps-control-access-to-mongodb-with-kerberos-authentication.yaml index 67c609c3a3f..340be414cb4 100644 --- a/source/includes/steps-control-access-to-mongodb-with-kerberos-authentication.yaml +++ b/source/includes/steps-control-access-to-mongodb-with-kerberos-authentication.yaml @@ -118,15 +118,12 @@ action: Kerberos name, ensure that you specify the fully qualified domain name (FQDN) for the ``--host`` option, rather than an IP address or unqualified hostname. - - If you are connecting to a system whose hostname does not - match the Kerberos name, use :option:`--gssapiHostName ` - to specify the Kerberos FQDN that it responds to. - pre: | - Alternatively, you can first connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`, and then from :binary:`~bin.mongosh`, use - the :method:`db.auth()` method to authenticate in the - ``$external`` database. + If you are connecting to a system whose hostname does not + match the Kerberos name, first connect :binary:`~bin.mongosh` + to the :binary:`~bin.mongod`, and then from + :binary:`~bin.mongosh`, use the :method:`db.auth()` method to + authenticate in the ``$external`` database. language: javascript code: | use $external diff --git a/source/includes/steps-create-admin-then-enable-authentication.yaml b/source/includes/steps-create-admin-then-enable-authentication.yaml index 9f70d46eed9..a3ca858308b 100644 --- a/source/includes/steps-create-admin-then-enable-authentication.yaml +++ b/source/includes/steps-create-admin-then-enable-authentication.yaml @@ -1,286 +1,202 @@ -title: Start MongoDB without access control. +title: Start MongoDB without access control stepnum: 1 level: 4 ref: start-without-auth pre: | - Start a standalone :binary:`~bin.mongod` instance without access - control. - - For example, open a terminal and issue the following: + Start a standalone :binary:`~bin.mongod` instance without access + control. + + Open a terminal and run the following command: action: language: sh code: | mongod --port 27017 --dbpath /var/lib/mongodb +post: | + The :binary:`~bin.mongod` instance in this tutorial uses + :option:`port 27017 ` and the ``/var/lib/mongodb`` + data directory. The tutorial assumes that the ``/var/lib/mongodb`` + directory exists and is the default :setting:`~storage.dbPath`. You + may specify a different data directory or port as needed. + --- stepnum: 2 -title: Connect to the instance. +title: Connect to the instance level: 4 ref: connect pre: | - For example, open a new terminal and connect :binary:`~bin.mongosh` - to the instance: + Open a new terminal and connect to the database deployment with + :binary:`~bin.mongosh`: action: language: sh code: | - mongosh --port 27017 + mongosh --port 27017 post: | - Specify additional command line options as appropriate to connect - :binary:`~bin.mongosh` to your deployment, such as ``--host``. + If you are connecting to a different deployment, specify additional + command line options, such as :option:`--host `, as + needed to connect. --- stepnum: 3 -title: Create the user administrator. +title: Create the user administrator level: 4 ref: create-user-admin pre: | - From :binary:`~bin.mongosh`, add a user with the - :authrole:`userAdminAnyDatabase` role in the ``admin`` database. Include additional roles as - needed for this user. For example, the following - creates the user ``myUserAdmin`` in the ``admin`` database with the - :authrole:`userAdminAnyDatabase` role and the - :authrole:`readWriteAnyDatabase` role. + .. _create-user-admin: -action: - pre: | + .. important:: Localhost Exception - .. tip:: + You can create the user administrator either before or after + enabling access control. If you enable access control before + creating any user, MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + Using :binary:`~bin.mongosh`: + 1. switch to the ``admin`` database + 2. add the ``myUserAdmin`` user with the + :authrole:`userAdminAnyDatabase` and + :authrole:`readWriteAnyDatabase` roles": + +action: language: javascript code: | + use admin db.createUser( { user: "myUserAdmin", pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "userAdminAnyDatabase", db: "admin" }, "readWriteAnyDatabase" ] + roles: [ + { role: "userAdminAnyDatabase", db: "admin" }, + { role: "readWriteAnyDatabase", db: "admin" } + ] } ) post: | - .. note:: - The database where you create the user (in this example, - ``admin``) is the user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can - have roles in other databases; i.e. the user's authentication - database does not limit the user's privileges. ---- -title: Re-start the MongoDB instance with access control. -level: 4 -stepnum: 4 -ref: restart-with-auth -content: | - - a. Shut down the :binary:`~bin.mongod` instance. For example, from - :binary:`~bin.mongosh`, issue the following command: - - .. code-block:: javascript - db.adminCommand( { shutdown: 1 } ) + .. tip:: - #. Exit :binary:`~bin.mongosh`. + .. include:: /includes/extracts/mongosh-password-prompt.rst - #. Start the :binary:`~bin.mongod` with access control enabled. + The :authrole:`userAdminAnyDatabase` role allows this user to: - - If you start the :binary:`~bin.mongod` from the command line, add - the :option:`--auth ` command line option: + - create users + - grant or revoke roles from users + - create or modify customs roles - .. code-block:: bash + You can assign your user additional :ref:`built-in roles + ` or :ref:`user-defined roles ` + as needed. - mongod --auth --port 27017 --dbpath /var/lib/mongodb + The database where you create the user, in this example ``admin``, + is the user's :ref:`authentication database + `. Although the user needs to + authenticate to this database, the user can have roles in other + databases. The user's authentication database doesn't limit the + user's privileges. - - If you start the :binary:`~bin.mongod` using a - :ref:`configuration file `, add the - :setting:`security.authorization` configuration file setting: - - .. code-block:: bash - - security: - authorization: enabled - - Clients that connect to this instance must now authenticate - themselves as a MongoDB user. Clients can only perform actions as - determined by their assigned roles. --- -title: Connect and authenticate as the user administrator. +title: Re-start the MongoDB instance with access control level: 4 -stepnum: 5 -ref: auth-as-admin +stepnum: 4 +ref: restart-with-auth content: | - Using :binary:`~bin.mongosh`, you can: - - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - - .. tabs:: - - tabs: - - id: cmdline - name: Authenticate during Connection - content: | - Start :binary:`~bin.mongosh` with the :option:`-u - \ `, :option:`-p `, and the - :option:`--authenticationDatabase \ ` command line options: - .. code-block:: bash + Shut down the :binary:`~bin.mongod` instance. Using + :binary:`~bin.mongosh`, issue the following command: - mongosh --port 27017 --authenticationDatabase "admin" -u "myUserAdmin" -p + .. code-block:: javascript - Enter your password when prompted. + db.adminCommand( { shutdown: 1 } ) - - id: authafter - name: Authenticate after Connection - content: | - - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: + Exit :binary:`~bin.mongosh`. - .. code-block:: bash + Start the :binary:`~bin.mongod` with access control enabled. - mongosh --port 27017 + - If you start the :binary:`~bin.mongod` from the command line, add + the :option:`--auth ` command line option: + .. code-block:: bash - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``admin``), and - use :method:`db.auth(\, \) ` - method to authenticate: + mongod --auth --port 27017 --dbpath /var/lib/mongodb - .. tip:: + - If you start the :binary:`~bin.mongod` using a + :ref:`configuration file `, add the + :setting:`security.authorization` configuration file setting: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. code-block:: bash - .. code-block:: javascript + security: + authorization: enabled - use admin - db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - - Enter the password when prompted. ---- -title: Create additional users as needed for your deployment. -level: 4 -stepnum: 6 -ref: create-additionalusers -pre: | - Once authenticated as the user administrator, use - :method:`db.createUser()` to create additional users. You can assign - any :doc:`built-in roles ` or - :doc:`user-defined roles ` to the - users. - -action: - pre: | - The following operation adds a user ``myTester`` to the ``test`` - database who has :authrole:`readWrite` role in the ``test`` - database as well as :authrole:`read` role in the ``reporting`` - database. - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst - - language: javascript - code: | - use test - db.createUser( - { - user: "myTester", - pwd: passwordPrompt(), // or cleartext password - roles: [ { role: "readWrite", db: "test" }, - { role: "read", db: "reporting" } ] - } - ) + Clients that connect to this instance must now authenticate + themselves and can only perform actions as determined by their + assigned roles. -post: | + .. important:: Localhost Exception - .. note:: - The database where you create the user (in this example, - ``test``) is that user's :ref:`authentication database - `. Although the user would - authenticate to this database, the user can have roles in other - databases; i.e. the user's authentication database does not limit - the user's privileges. + You can create users either before or after enabling access + control. If you enable access control before creating any user, + MongoDB provides a :ref:`localhost exception + ` which allows you to create a user + administrator in the ``admin`` database. Once created, you must + authenticate as the user administrator to create additional users. - After creating the additional users, disconnect - :binary:`~bin.mongosh`. --- -title: Connect to the instance and authenticate as ``myTester``. +title: Connect and authenticate as the user administrator level: 4 -ref: auth-as-mytester +stepnum: 5 +ref: auth-as-admin content: | + Using :binary:`~bin.mongosh`, you can: - After disconnecting :binary:`~bin.mongosh` as - ``myUserAdmin``, reconnect as ``myTester``. You can: - - - Connect with authentication by passing in user credentials, or - - - Connect first without authentication, and then issue the - :method:`db.auth()` method to authenticate. - - .. tabs:: + .. tabs:: - tabs: - - id: cmdline2 - name: Authenticate during Connection - content: | - Start :binary:`~bin.mongosh` with the :option:`-u - \ `, :option:`-p `, and the - :option:`--authenticationDatabase \ ` command line options: + tabs: + - id: cmdline + name: Authenticate during Connection + content: | + Start :binary:`~bin.mongosh` with the :option:`-u + \ `, :option:`-p `, and the + :option:`--authenticationDatabase \ ` command line options: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 -u "myTester" --authenticationDatabase "test" -p + mongosh --port 27017 --authenticationDatabase \ + "admin" -u "myUserAdmin" -p - Enter the password for the user when prompted. + Enter your password when prompted. - - id: authafter2 - name: Authenticate after Connection - content: | + - id: authafter + name: Authenticate after Connection + content: | - Connect :binary:`~bin.mongosh` to the - :binary:`~bin.mongod`: + Using :binary:`~bin.mongosh`, connect to your database + deployment: - .. code-block:: bash + .. code-block:: bash - mongosh --port 27017 + mongosh --port 27017 - In :binary:`~bin.mongosh`, switch to the - authentication database (in this case, ``test``), and use - :method:`db.auth(\, \) ` - method to authenticate: - - .. tip:: + In :binary:`~bin.mongosh`, switch to the + authentication database (in this case, ``admin``), and + use the :method:`db.auth(\, \) + ` method to authenticate: - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + .. code-block:: javascript - .. code-block:: javascript + use admin + db.auth("myUserAdmin", passwordPrompt()) // or cleartext password - use test - db.auth("myTester", passwordPrompt()) // or cleartext password + .. tip:: - Enter the password for the user when prompted. ---- -title: Insert a document as ``myTester``. -level: 4 -ref: insert-as-mytester -content: | + .. include:: /includes/extracts/mongosh-password-prompt.rst - As ``myTester``, you have privileges to perform read and write - operations in the ``test`` database (as well as perform read - operations in the ``reporting`` database). Once authenticated as - ``myTester``, insert a document into a collection in ``test`` - database. For example, you can perform the following insert - operation in the ``test`` database: - - .. code-block:: javascript - - db.foo.insert( { x: 1, y: 1 } ) -... + Enter the password when prompted. diff --git a/source/includes/steps-deploy-replica-set-with-auth.yaml b/source/includes/steps-deploy-replica-set-with-auth.yaml index 5cae223df0d..9283414a010 100644 --- a/source/includes/steps-deploy-replica-set-with-auth.yaml +++ b/source/includes/steps-deploy-replica-set-with-auth.yaml @@ -3,7 +3,9 @@ title: Create a keyfile. ref: deploy-repset-generate-keyfile level: 4 pre: | + .. include:: /includes/extracts/keyfile-intro-replica-set.rst + action: language: sh code: | @@ -140,7 +142,9 @@ title: Create the user administrator. level: 4 ref: deploy-repset-user-admin pre: | + .. important:: + After you create the first user, the :ref:`localhost exception ` is no longer available. @@ -164,6 +168,7 @@ pre: | :authrole:`userAdminAnyDatabase` role on the ``admin`` database. .. important:: + Passwords should be random, long, and complex to ensure system security and to prevent or delay malicious access. diff --git a/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml b/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml index d6c62b5d8e6..e7b4510e5fc 100644 --- a/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml +++ b/source/includes/steps-install-mongodb-enterprise-on-red-hat.yaml @@ -27,9 +27,9 @@ post: | version (e.g. ``{{distro_num}}``), then MongoDB :doc:`release version ` (e.g. ``{+version+}``), then architecture (e.g. ``x86_64``). - Odd-numbered MongoDB release versions, such as - ``{+version-dev+}``, are development versions and are - unsuitable for production deployment. + + .. include:: /includes/5.0-changes/fact-odd-number-releases.rst + replacement: distro_name: "redhat" distro_link: "`MongoDB repository `_" diff --git a/source/includes/steps-install-mongodb-on-red-hat.yaml b/source/includes/steps-install-mongodb-on-red-hat.yaml index 682703d0a58..c6fb79ab530 100644 --- a/source/includes/steps-install-mongodb-on-red-hat.yaml +++ b/source/includes/steps-install-mongodb-on-red-hat.yaml @@ -20,9 +20,9 @@ post: | version (e.g. ``{{distro_num}}``), then MongoDB :doc:`release version ` (e.g. ``{+version+}``), then architecture (e.g. ``x86_64``). - Odd-numbered MongoDB release versions, such as - ``{+version-dev+}``, are development versions and are - unsuitable for production deployment. + + .. include:: /includes/5.0-changes/fact-odd-number-releases.rst + replacement: distro_name: "redhat" distro_link: "`MongoDB repository `_" diff --git a/source/includes/steps-use-x509-authentication.yaml b/source/includes/steps-use-x509-authentication.yaml new file mode 100644 index 00000000000..9086bbeb208 --- /dev/null +++ b/source/includes/steps-use-x509-authentication.yaml @@ -0,0 +1,268 @@ +stepnum: 1 +level: 4 +title: Deploy with x.509 Authentication +stepnum: 2 +level: 4 +ref: deploy-x509 +content: | + + .. _x509-deploy-tls: + + .. tabs:: + + tabs: + + - id: cmdline + name: Command Options + content: | + + You can configure a :binary:`~bin.mongod` instance for x.509 + authentication from the command-line. + + To configure a standalone :binary:`~bin.mongod` instance, run + the following command: + + .. code-block:: bash + + mongod --tlsMode requireTLS \ + --tlsCertificateKeyFile \ + --tlsCAFile --bind_ip + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tlsMode ` + + - Specify ``requireTLS``. + + * - :option:`--tlsCertificateKeyFile ` + + - Specify the instance's x.509 certificate to present to + clients. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + - id: cfg + name: Configuration File + content: | + + You can configure a :binary:`~bin.mongod` for x.509 + authentication in the :doc:`configuration file + `. + + To configure a standalone :binary:`~bin.mongod` instance, add + the following configuration options to your configuration + file: + + .. code-block:: yaml + + net: + tls: + mode: requireTLS + certificateKeyFile: + CAFile: + + Include additional options as required for your configuration. + + The x.509 configuration requires: + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :setting:`net.tls.mode` + + - Specify ``requireTLS``. + + * - :setting:`net.tls.certificateKeyFile` + - Specify the instance's x.509 certificate to present to + clients. + + * - :setting:`net.tls.CAFile` + + - Specify the Certificate Authority file to verify the + certificates presented to the instance. + + To set up x.509 authentication for replica sets or sharded clusters, + see :ref:`x509-internal-authentication`. + +--- +title: Add x.509 Certificate ``subject`` as a User +stepnum: 2 +level: 4 +ref: x509-add-user +content: | + + .. _addX509SubjectUser: + + To authenticate with a client certificate, you must first add the value + of the ``subject`` from the client certificate as a MongoDB user to the + ``$external`` database. Each unique x.509 client certificate + corresponds to a single MongoDB user. You cannot use a single client + certificate to authenticate more than one MongoDB user. + + .. note:: Username Requirements + + - .. include:: /includes/extracts/sessions-external-username-limit.rst + + - The RDNs in the ``subject`` string must be compatible with the + `RFC2253 `_ standard. + + #. You can retrieve the ``RFC2253`` formatted ``subject`` from the + client certificate with the following command: + + .. code-block:: bash + + openssl x509 -in -inform PEM -subject -nameopt RFC2253 + + The command returns the ``subject`` string and the certificate: + + .. code-block:: bash + + subject= CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry + -----BEGIN CERTIFICATE----- + # ... + -----END CERTIFICATE----- + + + #. Add the ``RFC2253`` compliant value of the ``subject`` as a user. + Omit spaces as needed. + + The following example adds a user and grants the user + :authrole:`readWrite` role in the ``test`` database and the + :authrole:`userAdminAnyDatabase` role: + + .. code-block:: javascript + + db.getSiblingDB("$external").runCommand( + { + createUser: "CN=myName,OU=myOrgUnit,O=myOrg,L=myLocality,ST=myState,C=myCountry", + roles: [ + { role: "readWrite", db: "test" }, + { role: "userAdminAnyDatabase", db: "admin" } + ], + writeConcern: { w: "majority" , wtimeout: 5000 } + } + ) + + See :doc:`/tutorial/manage-users-and-roles` for details on adding a user + with roles. +--- +title: Authenticate with a x.509 Certificate +stepnum: 3 +level: 4 +ref: x509-authenticate +content: | + + .. _authenticate-with-x509-cert: + + After you have :ref:`added the x.509 client certificate subject as a + corresponding MongoDB user `, you can + authenticate with the client certificate: + + .. tabs:: + + tabs: + + - id: connect + name: Connect with Authentication + content: | + + To authenticate during connection, run the following command: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile \ + --authenticationDatabase '$external' \ + --authenticationMechanism MONGODB-X509 + + .. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify the + certificate presented by the :binary:`~bin.mongod` + instance. + + * - :option:`--authenticationDatabase ` + - Specify ``'$external'``. + + * - :option:`--authenticationMechanism ` + - Specify ``MONGODB-X509``. + + - id: authafter + name: Authenticate after Connection + content: | + + You can connect without authentication and use the + :method:`db.auth()` method to authenticate after + connection. + + For example, if using :binary:`~bin.mongosh`, + + 1. Connect :binary:`~bin.mongosh` to the + :binary:`~bin.mongod`: + + .. code-block:: bash + + mongosh --tls --tlsCertificateKeyFile \ + --tlsCAFile + + .. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Option + - Notes + + * - :option:`--tls ` + - + + * - :option:`--tlsCertificateKeyFile ` + - Specify the client's x.509 file. + + * - :option:`--tlsCAFile ` + + - Specify the Certificate Authority file to verify + the certificate presented by the + :binary:`~bin.mongod` or :binary:`~bin.mongos` + instance. + + #. To authenticate, use the :method:`db.auth()` method in + the ``$external`` database. For the ``mechanism`` field, + specify ``"MONGODB-X509"``. + + .. code-block:: javascript + + db.getSiblingDB("$external").auth( + { + mechanism: "MONGODB-X509" + } + ) +... diff --git a/source/includes/table-update-with-aggregation-availability.rst b/source/includes/table-update-with-aggregation-availability.rst index 50499322efc..93a36cdeeef 100644 --- a/source/includes/table-update-with-aggregation-availability.rst +++ b/source/includes/table-update-with-aggregation-availability.rst @@ -13,7 +13,6 @@ - | :ref:`db.collection.updateOne() ` | :ref:`db.collection.updateMany() ` - | :ref:`db.collection.update() ` | :ref:`Bulk.find.update() ` | :ref:`Bulk.find.updateOne() ` diff --git a/source/includes/transactionLifetimeLimitSeconds-parameter.rst b/source/includes/transactionLifetimeLimitSeconds-parameter.rst new file mode 100644 index 00000000000..f4ab8602719 --- /dev/null +++ b/source/includes/transactionLifetimeLimitSeconds-parameter.rst @@ -0,0 +1,10 @@ +Starting in MongoDB 5.0, if you change the +:parameter:`transactionLifetimeLimitSeconds` parameter, you must also +change :parameter:`transactionLifetimeLimitSeconds` to the same value on +all config server replica set members. Keeping this value consistent: + +- Ensures the routing table history is retained for at least as long as + the transaction lifetime limit on the shard replica set members. + +- Reduces the transaction retry frequency and therefore improves + performance. \ No newline at end of file diff --git a/source/includes/upgrade-downgrade-replica-set.rst b/source/includes/upgrade-downgrade-replica-set.rst new file mode 100644 index 00000000000..4fe8e76ff67 --- /dev/null +++ b/source/includes/upgrade-downgrade-replica-set.rst @@ -0,0 +1,5 @@ +.. important:: + + Before you upgrade or downgrade a replica set, ensure all replica set + members are running. If you do not, the upgrade or downgrade will not + complete until all members are started. \ No newline at end of file diff --git a/source/includes/warning-timeZoneInfo.rst b/source/includes/warning-timeZoneInfo.rst new file mode 100644 index 00000000000..2c3e81e2cc8 --- /dev/null +++ b/source/includes/warning-timeZoneInfo.rst @@ -0,0 +1,14 @@ +.. warning:: + + MongoDB uses the third party `timelib + `_ library to provide accurate + conversions between timezones. Due to a recent update, ``timelib`` + could create inaccurate time zone conversions in older versions of + MongoDB. + + To explicitly link to the time zone database in versions of MongoDB + prior to 5.0, 4.4.7, 4.2.14, and 4.0.25, download the `time zone + database + `_. + and use the :option:`timeZoneInfo ` parameter. + diff --git a/source/index.txt b/source/index.txt index f6afd19f37b..e3f59ceb0ff 100644 --- a/source/index.txt +++ b/source/index.txt @@ -1,192 +1,233 @@ -:orphan: +:template: product-landing +:hidefeedback: header +:noprevnext: -============================ -The MongoDB |version| Manual -============================ +================ +What is MongoDB? +================ -.. default-domain:: mongodb +.. introduction:: -.. note:: MongoDB 5.0 Released Jul 13, 2021 + MongoDB is a document database designed for ease of application + development and scaling. - For new features in MongoDB 5.0, see :doc:`/release-notes/5.0`. + Run MongoDB with - To download MongoDB 5.0, go to the `MongoDB Download Center - `_. + - `MongoDB Atlas + `__ fully managed in + the cloud, + - the source available and free-to-use :doc:`MongoDB + Community `, or + - the :doc:`MongoDB Enterprise Advanced + ` subscription. -Welcome to the MongoDB |version| Manual! MongoDB is a -document database designed for ease of development -and scaling. The Manual introduces key concepts in MongoDB, presents the -query language, and provides operational and administrative -considerations and procedures as well as a comprehensive reference -section. + .. button:: Install MongoDB + :uri: /installation -MongoDB offers both a *Community* and an *Enterprise* version of the -database: + `Get started with MongoDB Atlas `__ -- MongoDB Community is the {+source-available+} edition of MongoDB. +.. image:: /images/hero.png + :alt: Homepage hero image -- MongoDB Enterprise is available as part of the MongoDB Enterprise - Advanced subscription and includes comprehensive support for your - MongoDB deployment. MongoDB Enterprise also adds enterprise-focused - features such as LDAP and Kerberos support, on-disk encryption, - and auditing. +.. kicker:: What You Can Do -MongoDB also offers -`Atlas `__, -a hosted MongoDB Enterprise service option in the cloud which requires -no installation overhead and offers a free tier to get started. +Work with your data in MongoDB +------------------------------ -The Manual documents both MongoDB Community and Enterprise features and -functionality. +.. tabs:: -Getting Started ---------------- + .. tab:: Store and query your data + :tabid: store -MongoDB provides a Getting Started Guide in the following editions: + .. procedure:: -.. list-table:: - :class: index-table + .. step:: Model your data - * - :doc:`mongo Shell Edition ` + Design your data schema to support frequent access patterns. + You can update or enforce your schema at any point. - `Node.JS Edition `_ + :doc:`To learn more, see Data Modeling Introduction ` - - :driver:`Python Edition ` + .. step:: Connect to MongoDB - `C++ Edition `_ + Import data from CSV or JSON files into your MongoDB + database. - - `Java Edition `_ + `To learn more, see MongoDB Shell (mongosh) `__ - `C# Edition `_ + .. step:: Insert, query, update, or delete documents - - `Ruby Edition `_ + Use the MongoDB Query API to perform CRUD operations on your + data - with or without transactions. -Once you complete the Getting Started Guide, you may find the following topics -useful. + :ref:`To learn more, see MongoDB CRUD Operations ` -.. list-table:: - :header-rows: 1 - :class: index-table + .. code-block:: javascript - * - Introduction - - Developers - - Administrators - - Reference + ➜ mongosh --port 27017 + Current Mongosh Log ID: 123a4bc5d67891011ef1213g + Connecting to: mongodb://127.0.0.1:27017/ - * - :doc:`/introduction` + For mongosh info see: https://docs.mongodb.com/mongodb-shell/ - :doc:`Installation Guides ` + test> db.messages.insertMany([ + { + message: "Hello World!", + author: "MongoDB", + comments: [], + _id: 1 + } + ]) + { acknowledged: true, insertedIds: { '0': 1 } } - :doc:`/core/databases-and-collections` + test> db.messages.findOne({ _id: 1 }) + { _id: 1, message: 'Hello World!', author: 'MongoDB', comments: [] } - :doc:`/core/document` + .. tab:: Transform data with Aggregations + :tabid: transform - - :doc:`CRUD Operations ` + .. procedure:: - :doc:`Aggregation ` + .. step:: Import your data - :doc:`SQL to MongoDB ` + Import data from a CSV or JSON file with mongoimport. - :doc:`/indexes` + `To learn more, see mongoimport `__ - - :doc:`/administration/production-notes` + .. step:: Aggregate your data - :doc:`Replica Sets ` + Use aggregation pipelines to process your data in multiple stages and return the computed results. - :doc:`Sharded Clusters ` + :doc:`To learn more, see Aggregation ` - :doc:`MongoDB Security ` + .. code-block:: javascript - - :doc:`Shell Methods ` + test> db.orders.insertMany([ + { "item" : "almonds", "price" : 12, "quantity" : 2 }, + { "item" : "pecans", "price" : 20, "quantity" : 1 }, + ]) - :doc:`Query Operators ` + test> db.inventory.insertMany([ + { "sku" : "almonds", "description": "product 1", "instock" : 120 }, + { "sku" : "cashews", "description": "product 3", "instock" : 60 }, + { "sku" : "pecans", "description": "product 4", "instock" : 70 } + ]) - :doc:`Reference ` + test> db.orders.aggregate([ + { $match: { price: { $lt: 15 } } }, + { $lookup: { + from: "inventory", + localField: "item", + foreignField: "sku", + as: "inventory_docs" + } }, + { $sort: { price: 1 } }, + ]) - :doc:`/reference/glossary` + .. tab:: Secure access to your data + :tabid: create -Support -------- + .. procedure:: -.. include:: /includes/fact-support.rst + .. step:: Authenticate a client -.. _`Stack Overflow`: http://stackoverflow.com/questions/tagged/mongodb + Verify the identity of a user, replica set member, or + sharded cluster member with authentication. -Issues ------- + :ref:`To learn more, see Authentication ` -For instructions on how to file a JIRA ticket for the MongoDB server or -one of the related projects, see -``_. + .. step:: Control access to your database + Enable Role-Based Access Controls to manage user privileges + on your entire database cluster or individual collections. -Community ---------- + :ref:`To learn more, see Role-Based Access Controls ` -Getting involved in the MongoDB community is a great way to build -relationships with other talented and like-minded engineers, increase -awareness for the interesting work that you are doing, and sharpen your -skills. To learn about the MongoDB community, see -`Get Involved with MongoDB `_. + .. step:: Encrypt your most sensitive data -Learning MongoDB ----------------- + Client-side field level encryption protects data while it is + in-use by the database. Fields are encrypted before they + leave your application, protecting them over the network, in + memory and at rest. -In addition to the documentation, there are many ways to learn to use -MongoDB. You can: + :doc:`To learn more, see Client-Side Field Level Encryption ` -- Enroll in a free online course at `MongoDB University - `_ + .. image:: /images/security.png + :alt: MongoDB Security -- Browse the archive of `MongoDB Presentations - `_ + .. tab:: Deploy and scale your database + :tabid: deploy -- Join a local `MongoDB User Group (MUG) - `_ + .. procedure:: -- Attend an upcoming MongoDB `event `_ or - `webinar `_ + .. step:: Deploy a replica set -- Read the `MongoDB blog `_ + Provide redundancy and resilience for your database by deploying a replica set. -- Download the `Architecture Guide - `_ + :ref:`To learn more, see Replication ` -- Read the `Practical MongoDB Aggregations - `__ e-book + .. step:: Scale out your database -Licensing ---------- + Use sharding to horizontally scale your database or to ensure location-based separation of data. -The manual is licensed under a `Creative Commons -Attribution-NonCommercial-ShareAlike 3.0 United States License -`_. + :ref:`To learn more, see Sharding ` -For information on MongoDB licensing, see `MongoDB Licensing -`_. + .. image:: /images/scaling.png + :alt: MongoDB Deploy and Scale +.. kicker:: Related Products & Resources -Additional Resources --------------------- +Go Further with MongoDB +----------------------- -`MongoDB, Inc.`_ - The company behind MongoDB. +Explore libraries and tools for MongoDB. -`MongoDB Atlas `_ - Database as a service. +.. card-group:: + :columns: 3 + :style: compact -|mms-home| - A cloud-based hosted operations management solution for MongoDB. + .. card:: + :cta: Learn about Drivers + :url: https://docs.mongodb.com/drivers/ + :icon: /images/icons/drivers.svg + :icon-alt: MongoDB Atlas icon -`MongoDB Ops Manager `_ - Enterprise operations management solution for MongoDB: includes - Automation, Backup, and Monitoring. + Use MongoDB in your application’s language -`MongoDB Drivers `_ - The documentation available for the drivers for use with MongoDB. + .. card:: + :cta: View Compass Docs + :url: https://docs.mongodb.com/compass/current/ + :icon: /images/icons/compass.svg + :icon-alt: MongoDB University icon -.. _`MongoDB, Inc.`: https://www.mongodb.com?tck=docs_server + Visually explore your data with MongoDB Compass -.. include:: /includes/replacement-mms.rst + .. card:: + :cta: View Ops Manager + :url: https://docs.opsmanager.mongodb.com/current/ + :icon: /images/icons/opsmanager.svg + :icon-alt: MongoDB Server icon -.. |arrow| unicode:: U+27A4 + Manage and monitor your deployments + +.. toctree:: + :titlesonly: + + Introduction + Installation + MongoDB Shell (mongosh) + /crud + /aggregation + /data-modeling + /core/transactions + /indexes + /security + /changeStreams + /replication + /sharding + /administration + /storage + /faq + /reference + /release-notes + /support diff --git a/source/indexes.txt b/source/indexes.txt index eb6a7646d2f..2d3458a1b5e 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -295,8 +295,6 @@ page `. .. include:: /includes/extracts/collation-index-type-restrictions.rst -.. _indexes-covered-queries: - Covered Queries --------------- diff --git a/source/introduction.txt b/source/introduction.txt index 55409b60083..8741eaed4b9 100644 --- a/source/introduction.txt +++ b/source/introduction.txt @@ -10,23 +10,7 @@ Introduction to MongoDB :depth: 1 :class: singlecol -Welcome to the MongoDB |version| Manual! MongoDB is a -document database designed for ease of development -and scaling. The Manual introduces key concepts in MongoDB, presents the -query language, and provides operational and administrative -considerations and procedures as well as a comprehensive reference -section. - -MongoDB offers both a *Community* and an *Enterprise* version of the -database: - -- MongoDB Community is the {+source-available+} edition of MongoDB. - -- MongoDB Enterprise is available as part of the MongoDB Enterprise - Advanced subscription and includes comprehensive support for your - MongoDB deployment. MongoDB Enterprise also adds enterprise-focused - features such as LDAP and Kerberos support, on-disk encryption, - and auditing. +.. include:: /includes/fact-mongodb-intro.rst Document Database ----------------- diff --git a/source/reference/audit-message.txt b/source/reference/audit-message.txt index 56784e2f75e..e00e54ef9d9 100644 --- a/source/reference/audit-message.txt +++ b/source/reference/audit-message.txt @@ -178,7 +178,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authenticate: - :authaction:`authenticate` + ``authenticate`` - .. code-block:: none :copyable: false @@ -189,7 +189,7 @@ associated ``param`` details and the ``result`` values, if any. mechanism: } - Starting in MongoDB 5.0, :authaction:`authenticate`: + Starting in MongoDB 5.0, ``authenticate``: - Is logged for incomplete authentication attempts. @@ -207,7 +207,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-authCheck: - :authaction:`authCheck` + ``authCheck`` - .. code-block:: none :copyable: false @@ -227,8 +227,8 @@ associated ``param`` details and the ``result`` values, if any. .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst - Starting in MongoDB 5.0, :authaction:`authCheck` is not logged - for actions that are generated internally. + Starting in MongoDB 5.0, ``authCheck`` is not logged for actions + that are generated internally. .. versionchanged:: 5.0 @@ -238,7 +238,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-clientMetadata: - :authaction:`clientMetadata` + ``clientMetadata`` - .. code-block:: none :copyable: false @@ -308,7 +308,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`createDatabase` + * - ``createDatabase`` - .. code-block:: none :copyable: false @@ -367,7 +367,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-directAuthMutation: - :authaction:`directAuthMutation` + ``directAuthMutation`` - .. code-block:: none :copyable: false @@ -389,7 +389,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`renameCollection` + * - ``renameCollection`` - .. code-block:: none :copyable: false @@ -495,7 +495,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllUsersFromDatabase` + * - ``dropAllUsersFromDatabase`` - .. code-block:: none :copyable: false @@ -505,7 +505,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateUser` + * - ``updateUser`` - .. code-block:: none :copyable: false @@ -529,7 +529,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToUser` + * - ``grantRolesToUser`` - .. code-block:: none :copyable: false @@ -549,7 +549,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromUser` + * - ``revokeRolesFromUser`` - .. code-block:: none :copyable: false @@ -601,7 +601,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`updateRole` + * - ``updateRole`` - .. code-block:: none :copyable: false @@ -646,7 +646,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`dropAllRolesFromDatabase` + * - ``dropAllRolesFromDatabase`` - .. code-block:: none :copyable: false @@ -656,7 +656,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantRolesToRole` + * - ``grantRolesToRole`` - .. code-block:: none :copyable: false @@ -676,7 +676,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokeRolesFromRole` + * - ``revokeRolesFromRole`` - .. code-block:: none :copyable: false @@ -696,7 +696,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`grantPrivilegesToRole` + * - ``grantPrivilegesToRole`` - .. code-block:: none :copyable: false @@ -719,7 +719,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`revokePrivilegesFromRole` + * - ``revokePrivilegesFromRole`` - .. code-block:: none :copyable: false @@ -779,7 +779,7 @@ associated ``param`` details and the ``result`` values, if any. - ``0`` - Success - * - :authaction:`shardCollection` + * - ``shardCollection`` - .. code-block:: none :copyable: false @@ -861,7 +861,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-logout: - :authaction:`logout` + ``logout`` - .. code-block:: none :copyable: false @@ -895,7 +895,7 @@ associated ``param`` details and the ``result`` values, if any. * - .. _audit-message-startup: - :authaction:`startup` + ``startup`` - .. code-block:: none :copyable: false diff --git a/source/reference/built-in-roles.txt b/source/reference/built-in-roles.txt index 3bd33ec5e2e..7a50fd15cc9 100644 --- a/source/reference/built-in-roles.txt +++ b/source/reference/built-in-roles.txt @@ -72,6 +72,7 @@ Every database includes the following client roles: The role provides the following actions on those collections: + - :authaction:`changeStream` - :authaction:`collStats` - :authaction:`convertToCapped` - :authaction:`createCollection` @@ -246,9 +247,7 @@ Cluster Administration Roles - :authaction:`cleanupOrphaned` - :authaction:`flushRouterConfig` - :authaction:`getDefaultRWConcern` (New in version 4.4) - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`removeShard` - :authaction:`replSetConfigure` @@ -256,9 +255,7 @@ Cluster Administration Roles - :authaction:`replSetGetStatus` - :authaction:`replSetStateChange` - :authaction:`resync` - - :authaction:`setDefaultRWConcern` (New in version 4.4) - - :authaction:`setFeatureCompatibilityVersion` - :authaction:`setFreeMonitoring` @@ -398,16 +395,13 @@ Cluster Administration Roles - :authaction:`hostInfo` - :authaction:`inprog` - :authaction:`listDatabases` - - :authaction:`listSessions` (New in version 3.6) - - :authaction:`listShards` - :authaction:`netstat` - :authaction:`replSetGetConfig` - :authaction:`replSetGetStatus` - :authaction:`serverStatus` - :authaction:`setFreeMonitoring` (New in version 4.0) - - :authaction:`shardingState` - :authaction:`top` diff --git a/source/reference/command.txt b/source/reference/command.txt index 8beeec2528c..856adba74a4 100644 --- a/source/reference/command.txt +++ b/source/reference/command.txt @@ -29,7 +29,22 @@ To run an administrative command against the ``admin`` database, use :method:`db db.adminCommand( { } ) -.. include:: /includes/extracts/commands-toc-explanation.rst +.. note:: + + For details on specific commands, including syntax and examples, + click on the specific command to go to its reference page. + +Command Syntax +-------------- + +When you run a database command, you specify the command as a document +to :method:`db.runCommand()`. The document's key is the command to run, +and the value is typically supplied as ``1``. The value does not affect +the output of the command for example: + +.. code-block:: javascript + + db.runCommand( { hello: 1 } ) User Commands ------------- diff --git a/source/reference/command/currentOp.txt b/source/reference/command/currentOp.txt index 9b95c889658..06e8bdf0f4b 100644 --- a/source/reference/command/currentOp.txt +++ b/source/reference/command/currentOp.txt @@ -26,12 +26,9 @@ Definition { currentOp: 1 } - :binary:`~bin.mongosh` provides the :method:`db.currentOp()` - wrapper for the :dbcommand:`currentOp` command. - .. note:: - .. include:: /includes/fact-currentop.rst + .. include:: /includes/5.0-fact-currentop.rst Behavior -------- @@ -1124,7 +1121,8 @@ Output Fields :ref:`resharding operation `. The time is set to -1 when a new resharding operation starts. - Only present when a resharding operation is taking place. + Only present on a :ref:`recipient shard ` + when a resharding operation is taking place. .. versionadded:: 5.0 diff --git a/source/reference/command/dataSize.txt b/source/reference/command/dataSize.txt index eee67ed19a0..c43843a09a6 100644 --- a/source/reference/command/dataSize.txt +++ b/source/reference/command/dataSize.txt @@ -15,8 +15,8 @@ Definition .. dbcommand:: dataSize - The :dbcommand:`dataSize` command returns the data size for a set - of data within a certain range: + The :dbcommand:`dataSize` command returns the size in bytes for + the specified data: .. code-block:: javascript @@ -104,9 +104,9 @@ and the upper bound of the key to be examined being ``{field: 100}``. db.runCommand({ dataSize: "database.collection", keyPattern: { field: 1 }, min: { field: 10 }, max: { field: 100 } }) -This will return a document that contains the size of all matching -documents. Replace ``database.collection`` value with database -and collection from your deployment. +This returns a document with the size in bytes for all matching +documents. Replace ``database.collection`` with the database and +collection from your deployment. The amount of time required to return :dbcommand:`dataSize` depends on the amount of data in the collection. diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index bc3211c29d9..aa35cb0daf4 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -344,7 +344,11 @@ The ``lastErrorObject`` embedded document contains the following fields: - boolean - - Contains ``true`` if an ``update`` operation modified an existing document. + - Contains ``true`` if an ``update`` operation: + + - Modified an existing document. + - Found the document, but it was already in the + desired destination state so no update actually occurred. diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index 370384114b3..54d0f15cc08 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -370,7 +370,7 @@ collection `: - :authaction:`find`, - :authaction:`insert`, -- :authaction:`replace` +- :authaction:`remove` Map-reduce with the ``merge`` or ``reduce`` actions when :ref:`outputting to a collection `: diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 6cceb331a2f..d415077f5d8 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -220,5 +220,14 @@ while :dbcommand:`moveChunk` is running, you may see this error. You may retry the :dbcommand:`moveChunk` operation without side effects. +``maxCatchUpPercentageBeforeBlockingWrites`` Server Parameter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0 (and 4.4.7, 4.2.15, 4.0.26), you can set the +:parameter:`maxCatchUpPercentageBeforeBlockingWrites` to specify the +maximum allowed percentage of data not yet migrated +during a :dbcommand:`moveChunk` operation when compared to the +total size (in MBs) of the chunk being transferred. + .. admin-only diff --git a/source/reference/command/replSetResizeOplog.txt b/source/reference/command/replSetResizeOplog.txt index 0f0cde4efa1..a5d32474eaa 100644 --- a/source/reference/command/replSetResizeOplog.txt +++ b/source/reference/command/replSetResizeOplog.txt @@ -15,17 +15,16 @@ Definition .. dbcommand:: replSetResizeOplog - .. versionadded:: 3.6 - - Use the :dbcommand:`replSetResizeOplog` administrative command to - change the size of a replica set member's oplog. [#oplog]_ - - .. versionadded:: 4.4 :dbcommand:`replSetResizeOplog` also supports specifying the minimum number of hours to preserve an oplog entry. + .. versionchanged:: 5.0 + + To set the ``replSetOplog`` size in :binary:`~bin.mongosh`, use + the ``Double()`` constructor. + :dbcommand:`replSetResizeOplog` enables you to resize the oplog or its minimum retention period dynamically without restarting the :binary:`~bin.mongod` process. @@ -72,6 +71,10 @@ Definition - The maximum size you can specify is 1 petabytes. + - Explicitly cast the ``size`` as a double in + :binary:`~bin.mongosh` with ``Double()``. See + :ref:`oplog-ex-change-size`. + * - :ref:`minRetentionHours ` - double @@ -119,6 +122,8 @@ You can only use :dbcommand:`replSetResizeOplog` on See the :ref:`tutorial-change-oplog-size` tutorial for a procedure on using :dbcommand:`replSetResizeOplog` command to resize the oplog. +.. include:: /includes/fact-oplog-size.rst + Starting in MongoDB 4.0, MongoDB forbids dropping the ``local.oplog.rs`` collection. For more information on this restriction, see :ref:`oplog-coll-behavior`. @@ -227,6 +232,8 @@ For more information on locking in MongoDB, see :doc:`/faq/concurrency`. Examples -------- +.. _oplog-ex-change-size: + Change the Maximum Oplog Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -249,7 +256,7 @@ oplog size of this member to 16384 megabytes: .. code-block:: javascript - db.adminCommand({ "replSetResizeOplog": 1, size: 16384}) + db.adminCommand({ "replSetResizeOplog": 1, size: Double(16384)}) To verify the new oplog size, rerun the :method:`db.collection.stats()` method: @@ -269,9 +276,6 @@ The above command returns: may cause replica members syncing with that node to become stale. To resync those members, see :doc:`/tutorial/resync-replica-set-member`. -.. [#oplog] - - .. include:: /includes/fact-oplog-size.rst Change the Minimum Oplog Retention Period ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index d06bc7e4671..a50bb7a6e9d 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -2391,6 +2391,12 @@ repl "primary" : , "me" : , "electionId" : ObjectId(""), + "primaryOnlyServices": { + "ReshardingRecipientService": { "state": , "numInstances": }, + "RenameCollectionParticipantService": { "state": , "numInstances": }, + "ShardingDDLCoordinator": { "state": , "numInstances": }, + "ReshardingDonorService": { "state": , "numInstances": } + }, "rbid" : , "replicationProgress" : [ { @@ -2441,6 +2447,76 @@ repl The hostname and port information (``"host:port"``) for the current member of the replica set. +.. serverstatus:: repl.primaryOnlyServices + + Document that contains the number and status of + instances of each primary service active on the server. Primary + services can only start when a server is primary but can continue running to + completion after the server changes state. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ReshardingRecipientService + + Document that contains the state and number of instances of the + ``ReshardingRecipientService``. + + Recipients are the shards,that would own the chunks after as a + result of the resharding operation, according to the new + :manual:`shard key` and + :manual:`zones`. + + The resharding coordinator instructs each donor and recipient shard + primary, to rename the temporary sharded collection. + The temporary collection becomes the new resharded collection. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.RenameCollectionParticipantService + + Document that contains the state and number of instances of the + ``RenameCollectionParticipantService``. + + The ``RenameCollectionParticipantService`` ensures that, after a shard + receives a + :manual:`renameCollection` + request, the shard is able to resume the local rename in case of + system failure. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ShardingDDLCoordinator + + Document that contains the state and number of instances of the + ``ShardingDDLCoordinator``. + + The ``ShardingDDLCoordinator`` service manages DDL operations for + :manual:`primary` + databases such as: + :manual:`create database`, + :manual:`drop database`, + :manual:`renameCollection`. + + The ``ShardingDDLCoordinator`` ensures that one DDL operation for + each database can happen at any one specific point in time within a + sharded cluster. + + .. versionadded:: 5.0 + +.. serverstatus:: repl.primaryOnlyServices.ReshardingDonorService + + Document that contains the state and number of instances of the + ``ReshardingDonorService``. + + Donors are the shards that own chunks of the sharded collection + before the rename operation completes. + + The resharding coordinator instructs each donor and recipient shard + primary, to rename the temporary sharded collection. + The temporary collection becomes the new resharded collection. + + .. versionadded:: 5.0 + .. serverstatus:: repl.rbid :term:`Rollback ` identifier. Used to determine if a rollback has @@ -2761,7 +2837,8 @@ shardingStatistics "donorState" : , "recipientState" : , "coordinatorState" : , - "opStatus" : + "opStatus" : , + "lastOpEndingChunkImbalance": NumberLong() } }, @@ -2774,6 +2851,39 @@ shardingStatistics .. code-block:: javascript "shardingStatistics" : { + "numHostsTargeted": { + "find" : { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "insert": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "update": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "delete": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + }, + "aggregate": { + "allShards": NumberLong(), + "manyShards": NumberLong(), + "oneShard": NumberLong(), + "unsharded": NumberLong() + } + } + }, "catalogCache" : { "numDatabaseEntries" : NumberLong(), "numCollectionEntries" : NumberLong(), @@ -3364,6 +3474,29 @@ shardingStatistics .. versionadded:: 5.0 +.. serverstatus:: shardingStatistics.numHostsTargeted + + Indicates the number of shards targeted for ``CRUD`` operations and + aggregation commands. When a ``CRUD`` operation or aggregation + command is run, the following metrics will be incremented. + + .. include:: /includes/fact-server-status-num-hosts-targeted.rst + + .. note:: + + Running the :dbcommand:`serverStatus` command on :binary:`mongos` + will provide insight into the CRUD and aggregation operations that + run on a sharded cluster. + + Multi-shard operations can either be + :ref:`scatter-gather` + or shard specific. Multi-shard scatter-gather operations can + :ref:`consume more resources`. + By using the + :serverstatus:`shardingStatistics.numHostsTargeted` + metrics you can tune the aggregation queries that run on a + sharded cluster. + .. serverstatus:: shardingStatistics.resharding.coordinatorState State of the resharding coordinator for the current :ref:`resharding @@ -3473,6 +3606,20 @@ shardingStatistics .. versionadded:: 5.0 +.. serverstatus:: shardingStatistics.resharding.lastOpEndingChunkImbalance + + This field contains the highest numeric difference for + (``maxNumChunksInShard - minNumChunksInShard``) among all + :ref:`zones ` for the + collection that was processed by the most recent + :ref:`resharding operation `. + + See :ref:`sharding-chunk-size`. + + *Only updated on config servers.* + + .. versionadded:: 5.0 + .. _server-status-sharded-index-consistency: shardedIndexConsistency @@ -4758,7 +4905,10 @@ metrics }, "operatorCounters" : { "expressions" : { - "" : Long("0") + "" : Long() + }, + "match" : { + "" : Long() } }, "queryExecutor": { @@ -4884,6 +5034,37 @@ metrics .. versionadded:: 5.0 +.. serverstatus:: metrics.operatorCounters.match + + A document with a number that indicates how often + :ref:`match expressions ` ran. For + some operators, the number reported is a multiple of the times the + operator actually ran. + + :ref:`Match expression operators ` + also increment as part of an aggregation pipeline :pipeline:`$match` + stage. If the ``$match`` stage uses the :query:`$expr` operator, the + counter for ``$expr`` increments, but the component counters do not + increment. + + Consider the following query: + + .. code-block:: javascript + :copyable: false + + db.matchCount.aggregate( + [ + { $match: + { $expr: { $gt: [ "$_id", 0 ] } } + } + ] + ) + + The counter for ``$expr`` increments when the query runs. The + counter for ``$gt`` does not. + + .. versionadded:: 5.1 + .. serverstatus:: metrics.commands A document that reports on the use of database commands. The fields @@ -5616,7 +5797,3 @@ watchdog The value set by :parameter:`watchdogPeriodSeconds`. This is the period between status checks. -Output Changelog ----------------- - -.. include:: /includes/extracts/serverStatus-command-output-change.rst diff --git a/source/reference/command/setAuditConfig.txt b/source/reference/command/setAuditConfig.txt index 94cae1f0de1..136b7100fdf 100644 --- a/source/reference/command/setAuditConfig.txt +++ b/source/reference/command/setAuditConfig.txt @@ -59,14 +59,13 @@ Behavior Enable :doc:`Auditing ` to use :dbcommand:`setAuditConfig` at runtime. -:parameter:`auditAuthorizationSuccess` enables -:doc:`auditing ` of authorization success for the -:ref:`authCheck ` action. The parameter -value must be ``true`` to audit :authaction:`read` and -:authaction:`write` operations. However, when +:parameter:`auditAuthorizationSuccess` enables :doc:`auditing +` of authorization success for the :ref:`authCheck +` action. The parameter value must be +``true`` to audit read and write operations. However, when :parameter:`auditAuthorizationSuccess` is ``false`` auditing has less -performance impact because the :doc:`audit system ` -only logs authorization failures. +performance impact because the :doc:`audit system ` only +logs authorization failures. Configuration updates are distributed via the :term:`oplog` mechanism which means updates on :binary:`~bin.mongod` nodes are distributed to @@ -146,8 +145,8 @@ Audit Document Interactions ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set :parameter:`auditAuthorizationSuccess` to ``true`` and create a -filter which includes actions of interest to audit :authaction:`read` -and :authaction:`write` operations. +filter which includes actions of interest to audit read and write +operations. .. code-block:: javascript diff --git a/source/reference/command/validate.txt b/source/reference/command/validate.txt index cdd3dba2de0..71c88115c86 100644 --- a/source/reference/command/validate.txt +++ b/source/reference/command/validate.txt @@ -28,6 +28,10 @@ Definition The :dbcommand:`validate` command does not support :doc:`views ` and raises an error when run against a view. + The :method:`db.collection.validate()` method in + :binary:`~bin.mongosh` provides a wrapper around + :dbcommand:`validate`. + Syntax ------ @@ -96,6 +100,9 @@ The command takes the following fields: Behavior -------- +Performance +~~~~~~~~~~~ + The :dbcommand:`validate` command can be slow, particularly on larger data sets. @@ -105,6 +112,17 @@ until the operation finishes. When run on a secondary, the :dbcommand:`validate` operation can block all other operations on that secondary until it finishes. +.. warning:: + + Due to the performance impact of validation, consider running + :dbcommand:`validate` only on :term:`secondary` replica set nodes. + You can use :method:`rs.stepDown()` to instruct the current + :term:`primary` node to become a secondary to avoid impacting a live + primary node. + +Data Throughput Metrics +~~~~~~~~~~~~~~~~~~~~~~~ + .. include:: /includes/extracts/4.4-validate-data-throughput.rst Restrictions diff --git a/source/reference/config-database.txt b/source/reference/config-database.txt index e733bc179f1..cafd1e88efa 100644 --- a/source/reference/config-database.txt +++ b/source/reference/config-database.txt @@ -26,6 +26,8 @@ The collections in the ``config`` database support: Restrictions ------------ +.. include:: /includes/fact-5.0-non-transactional-config-reads.rst + .. important:: The schema of the ``config`` database is *internal* and may change between releases of MongoDB. The ``config`` database is not a dependable API, and users should not diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index 50ec1d45002..54d2300594b 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -734,7 +734,8 @@ Core Options *Type*: string .. include:: /includes/fact-timeZoneInfo.rst - + + .. include:: /includes/warning-timeZoneInfo.rst .. _free-monitoring-configuration-options: @@ -867,6 +868,7 @@ Core Options allowInvalidHostnames: disabledProtocols: FIPSMode: + logVersions: compression: compressors: @@ -908,12 +910,16 @@ Core Options may attach :binary:`~bin.mongos` or :binary:`~bin.mongod` to any interface. To bind to multiple addresses, enter a list of comma-separated values. - .. example:: ``localhost,/tmp/mongod.sock`` + .. example:: + + ``localhost,/tmp/mongod.sock`` You can specify both IPv4 and IPv6 addresses, or hostnames that resolve to an IPv4 or IPv6 address. - .. example:: ``localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513`` + .. example:: + + ``localhost, 2001:0DB8:e132:ba26:0d5c:2774:e7f9:d513`` .. note:: @@ -928,7 +934,9 @@ Core Options `zone index `_ to that address (i.e. ``fe80::
%``). - .. example:: ``localhost,fe80::a00:27ff:fee0:1fcf%enp0s3`` + .. example:: + + ``localhost,fe80::a00:27ff:fee0:1fcf%enp0s3`` .. include:: /includes/tip-hostnames.rst @@ -1149,6 +1157,7 @@ Core Options allowInvalidHostnames: disabledProtocols: FIPSMode: + logVersions: .. setting:: net.tls.mode @@ -1610,6 +1619,23 @@ Core Options .. include:: /includes/note-fips-is-enterprise-only.rst +.. setting:: net.tls.logVersions + + *Type*: string + + Instructs :binary:`~bin.mongos` or :binary:`~bin.mongod` to log a + message when a client connects using a specified TLS version. + + Specify either a single TLS version or a comma-separated list of + multiple TLS versions. + + .. example:: + + To instruct :binary:`~bin.mongos` or :binary:`~bin.mongod` to + log a message when a client connects using either TLS 1.2 or + TLS 1.3, set :setting:`net.tls.logVersions` to + ``"TLS1_2,TLS1_3"``. + .. _net-ssl-conf-options: @@ -2843,11 +2869,6 @@ Key Management Configuration Options and Kerberos authentication. The SASL hostname overrides the hostname only for the configuration of SASL and Kerberos. - For :binary:`~bin.mongosh` and other MongoDB tools to connect to - the new :setting:`~security.sasl.hostName`, see the - ``gssapiHostName`` option in :binary:`~bin.mongosh` and other - tools. - .. setting:: security.sasl.serviceName @@ -4204,7 +4225,12 @@ LDAP Parameters Starting in MongoDB 5.0, :setting:`~replication.enableMajorityReadConcern` cannot be changed - and is always set to ``true``. In earlier versions of MongoDB, + and is always set to ``true``. Attempting to start a storage engine + that does not support majority read concern with the + ``--enableMajorityReadConcern`` option will fail and return an error + message. + + In earlier versions of MongoDB, :setting:`~replication.enableMajorityReadConcern` was configurable. .. warning:: diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 15e27b90a10..2b5130d2921 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -122,6 +122,25 @@ Examples .. include:: /includes/fact-pct-encode-uri.rst + - id: atlas + name: Atlas Deployment + content: | + + MongoDB Atlas provides the connection strings for + your deployment when you click the :atlas:`Connect + ` button in the Atlas UI. + To register a new Atlas account, start at the + `MongoDB Atlas registration page + `__. To learn more, see + :atlas:`Get Started with Atlas `. + + Your Atlas connection string might resemble the following + example: + + .. code-block:: bash + + mongosh "mongodb+srv://cluster0.example.mongodb.net myFirstDatabase" --username JohnDoe + For more examples, see :ref:`connections-connection-examples`. Components @@ -1214,8 +1233,10 @@ Miscellaneous Configuration - the :data:`system.profile.appName` field in the :doc:`database profiler ` output. - If you do not specify a custom app name, :binary:`~bin.mongosh` - uses the default "``MongoDB Shell``". + The :urioption:`appName` connection option is only applicable + when provided to a :ecosystem:`MongoDB Driver `. This + parameter has no effect when supplied to a client application + such as :compass:`MongoDB Compass ` or :binary:`~bin.mongosh`. .. versionadded:: 4.0 diff --git a/source/reference/database-references.txt b/source/reference/database-references.txt index c738fef7f87..6057eed6b4c 100644 --- a/source/reference/database-references.txt +++ b/source/reference/database-references.txt @@ -221,6 +221,12 @@ Driver Support for DBRefs - Please see the :driver:`C# driver page ` for more information. + * - Go + + - Not Supported + + - You can traverse references manually. + * - Haskell - Not Supported diff --git a/source/reference/limits.txt b/source/reference/limits.txt index 79d7c45ac32..154f673564e 100644 --- a/source/reference/limits.txt +++ b/source/reference/limits.txt @@ -36,8 +36,11 @@ Naming Restrictions .. limit:: Database Name Case Sensitivity - Since database names are case *insensitive* in MongoDB, database - names cannot differ only by the case of the characters. + Database names are case-sensitive in MongoDB. They also have an + additional restriction, case cannot be the only difference between + database names. + + .. include:: /includes/fact-case-sensitivity-limitation-code.rst .. limit:: Restrictions on Database Names for Windows diff --git a/source/reference/log-messages.txt b/source/reference/log-messages.txt index c11e50962b7..f6079ba167c 100644 --- a/source/reference/log-messages.txt +++ b/source/reference/log-messages.txt @@ -1330,3 +1330,87 @@ attribute object: "request": "RemoteCommand 229 -- target:localhost:27003 db:admin cmd:{ replSetRequestVotes: 1, setName: \"my-replica-name\", dryRun: true, term: 3, candidateIndex: 0, configVersion: 2, configTerm: 3, lastAppliedOpTime: { ts: Timestamp(1589915409, 1), t: 3 } }" } } + +.. _log-message-view-example: + +View +~~~~ + +Starting in MongoDB 5.0, :ref:`log messages for slow queries +` on :doc:`views ` include a +``resolvedViews`` field that contains the view details: + +.. code-block:: javascript + :copyable: false + + "resolvedViews": [ { + "viewNamespace": , // namespace and view name + "dependencyChain": , // view name and collection + "resolvedPipeline": // aggregation pipeline for view + } ] + +The following example uses the ``test`` database and creates a view +named ``myView`` that sorts the documents in ``myCollection`` by the +``firstName`` field: + +.. code-block:: javascript + + use test + db.createView( "myView", "myCollection", [ { $sort: { "firstName" : 1 } } ] ) + +Assume a :ref:`slow query ` is run on ``myView``. +The following example log message contains a ``resolvedViews`` field for +``myView``: + +.. code-block:: javascript + :copyable: false + + { + "t": { + "$date": "2021-09-30T17:53:54.646+00:00" + }, + "s": "I", + "c": "COMMAND", + "id": 51803, + "ctx": "conn249", + "msg": "Slow query", + "attr": { + "type": "command", + "ns": "test.myView", + "appName": "MongoDB Shell", + "command": { + "find": "myView", + "filter": {}, + "lsid": { + "id": { "$uuid": "ad176471-60e5-4e82-b977-156a9970d30f" } + }, + "$db": "test" + }, + "planSummary":"COLLSCAN", + "resolvedViews": [ { + "viewNamespace": "test.myView", + "dependencyChain": [ "myView", "myCollection" ], + "resolvedPipeline": [ { "$sort": { "firstName": 1 } } ] + } ], + "keysExamined": 0, + "docsExamined": 1, + "hasSortStage": true, + "cursorExhausted": true, + "numYields": 0, + "nreturned": 1, + "queryHash": "3344645B", + "planCacheKey": "1D3DE690", + "reslen": 134, + "locks": { "ParallelBatchWriterMode": { "acquireCount": { "r": 1 } }, + "ReplicationStateTransition": { "acquireCount": { "w": 1 } }, + "Global": { "acquireCount": { "r": 4 } }, + "Database": { "acquireCount": {"r": 1 } }, + "Collection": { "acquireCount": { "r": 1 } }, + "Mutex": { "acquireCount": { "r": 4 } } }, + "storage": {}, + "remote": "127.0.0.1:34868", + "protocol": "op_msg", + "durationMillis": 0 + } + } + } diff --git a/source/reference/method/db.collection.createIndexes.txt b/source/reference/method/db.collection.createIndexes.txt index 151f400f228..b5db7454f07 100644 --- a/source/reference/method/db.collection.createIndexes.txt +++ b/source/reference/method/db.collection.createIndexes.txt @@ -38,7 +38,9 @@ Definition - document - - An array containing index specification documents. Each document + - .. _key_patterns: + + An array containing index specification documents. Each document contains field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of ``1``; for @@ -270,7 +272,9 @@ otherwise specified: - document - - Optional. If specified, the indexes only reference documents that match the + - .. _partialFilterExpression: + + Optional. If specified, the indexes only reference documents that match the filter expression. See :doc:`/core/index-partial` for more information. diff --git a/source/reference/method/db.collection.findOneAndUpdate.txt b/source/reference/method/db.collection.findOneAndUpdate.txt index 498ad2f6c47..4571641b83b 100644 --- a/source/reference/method/db.collection.findOneAndUpdate.txt +++ b/source/reference/method/db.collection.findOneAndUpdate.txt @@ -75,8 +75,8 @@ Definition Starting in MongoDB 4.2 (and 4.0.12+, 3.6.14+, and 3.4.23+), the operation errors if the query argument is not a document. + If no document matches the ``filter``, no document is updated. - * - ``update`` - document or array @@ -176,9 +176,7 @@ Definition modify for an update operation on an array field. .. include:: /includes/extracts/arrayFilters-details.rst - - - + For examples, see :ref:`findOneAndUpdate-arrayFilters`. .. note:: @@ -186,11 +184,6 @@ Definition .. include:: /includes/extracts/arrayFilters-update-aggregation-restriction.rst .. versionadded:: 3.6 - - - - - :returns: @@ -204,7 +197,9 @@ Document Match ~~~~~~~~~~~~~~ :method:`db.collection.findOneAndUpdate()` updates the first matching -document in the collection that matches the ``filter``. +document in the collection that matches the ``filter``. If no document +matches the ``filter``, no document is updated. + The ``sort`` parameter can be used to influence which document is updated. Projection diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index fa85443e91b..4b740850396 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -68,7 +68,7 @@ warnings and messages. :dbcommand:`renameCollection` command create an :ref:`change-event-invalidate` for any existing :doc:`/changeStreams` opened on the source or target collection. - + - The method has the following limitations: - :method:`db.collection.renameCollection()` cannot move a collection @@ -83,6 +83,9 @@ warnings and messages. - :method:`db.collection.renameCollection()` is not supported on :term:`time series collections