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/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/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index c7d9ec95b92..974cc155ca1 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -483,7 +483,8 @@ features include: - Creation of :ref:`time series collections ` requires fCV set to 5.0+. -- Configuring Runtime Audit Filter Management requires fCV set to 5.0+. +- :ref:`Configuring Runtime Audit Filter Management + ` requires fCV set to 5.0+. - Usage of ``.`` and ``$`` in field names requires fCV set to 5.0+. diff --git a/source/release-notes/5.0-downgrade-replica-set.txt b/source/release-notes/5.0-downgrade-replica-set.txt index 471a0e3da4b..3cc159574f4 100644 --- a/source/release-notes/5.0-downgrade-replica-set.txt +++ b/source/release-notes/5.0-downgrade-replica-set.txt @@ -151,9 +151,33 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + +- Reset the defaults on the :term:`primary` server in the group with + ``db.admin.runCommand``. The primary should be the last + configuration server in the group to be updated. + + .. code-block:: javascript + + db.admin.runCommand( + { + setAuditConfig: 1, + filter: {}, + auditAuthorizationSuccess: false + } + ) + + The configuration document can also be removed after downgrade: + + .. code-block:: javascript + + config.settings.remove({_id: 'audit'}); + +- Disable Runtime Audit Filter Management on each node by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + +- Update the audit filters for this instance in the local + configuration file. .. |binary| replace:: any replica set member diff --git a/source/release-notes/5.0-downgrade-sharded-cluster.txt b/source/release-notes/5.0-downgrade-sharded-cluster.txt index 55e7a02cb0b..ddb7deffa6f 100644 --- a/source/release-notes/5.0-downgrade-sharded-cluster.txt +++ b/source/release-notes/5.0-downgrade-sharded-cluster.txt @@ -179,9 +179,12 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + - Disable Runtime Audit Filter Management by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + + - Update the audit filters for this :binary:`~bin.mongod` or + :binary:`~bin.mongos` instance in the local configuration file. 7. Remove |newversion| Features ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/5.0-downgrade-standalone.txt b/source/release-notes/5.0-downgrade-standalone.txt index 575c105c176..092e9010679 100644 --- a/source/release-notes/5.0-downgrade-standalone.txt +++ b/source/release-notes/5.0-downgrade-standalone.txt @@ -107,9 +107,12 @@ Time-series Collections `. Runtime Audit Filter Management - Disable runtime audit filter management by setting the - ``auditLog.runtimeConfiguration`` configuration file setting to - ``false``. + - Disable Runtime Audit Filter Management by setting + ``auditLog.runtimeConfiguration`` to ``false`` in the node's + configuration file. + + - Update the audit filters for this instance in the local + configuration file. .. |binary| replace:: the :binary:`~bin.mongod` instance @@ -132,3 +135,4 @@ Procedure prerequisites have been completed. .. include:: /includes/steps/5.0-downgrade-mongod.rst + diff --git a/source/release-notes/5.0-upgrade-replica-set.txt b/source/release-notes/5.0-upgrade-replica-set.txt index 2ff72aba373..7b60c666438 100644 --- a/source/release-notes/5.0-upgrade-replica-set.txt +++ b/source/release-notes/5.0-upgrade-replica-set.txt @@ -35,7 +35,7 @@ All Members Version All replica set members must be running version |oldversion|. To upgrade a replica set from an |olderseries| and earlier, *first* :doc:`upgrade all members of the replica set to the latest -4.2-series release `, and +5.0-series release `, and then follow the procedure to upgrade from MongoDB |oldversion| to |newversion|. diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 8d3dbd73a81..fa167c78909 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -242,7 +242,11 @@ See :ref:`lookup-uncorrelated-subquery`. Auditing -------- -MongDB 5.0 adds the ability to configure auditing filters at runtime. +Runtime Audit Filter Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +MongoDB 5.0 adds the ability to :ref:`configure auditing filters +` at runtime. .. list-table:: :header-rows: 1 @@ -262,6 +266,9 @@ MongDB 5.0 adds the ability to configure auditing filters at runtime. - Sets new audit configurations for :binary:`~bin.mongod` and :binary:`~bin.mongos` instances at runtime. +General Auditing Updates +~~~~~~~~~~~~~~~~~~~~~~~~ + Starting in MongoDB 5.0: - :ref:`System event auditing ` has: diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index b09d9bed348..7e1dbf83bbd 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -39,18 +39,7 @@ configured to allow Filter Configuration at Runtime ------------------------------- -Starting in MongDB 5.0, a :binary:`~bin.mongod` or -:binary:`~bin.mongos` instance can be part of a distributed audit -configuration. Audit filters on these nodes can be configured at -runtime using the :dbcommand:`setAuditConfig` command. A node will be -included in the distributed audit configuration if: - -- :setting:`auditLog.runtimeConfiguration` is ``true``, -- :setting:`auditLog.filter` is not set, and -- :parameter:`auditAuthorizationSuccess` is not set - -When ``runtimeConfiguration`` is ``true``, the server will log an error -and fail to start if either one of the other variables is set. +.. include:: /includes/fact-enable-runtime-audit-configuration.rst .. _configure-audit-filters-at-startup: diff --git a/source/tutorial/configure-auditing.txt b/source/tutorial/configure-auditing.txt index 7390770b9c8..93714b76a49 100644 --- a/source/tutorial/configure-auditing.txt +++ b/source/tutorial/configure-auditing.txt @@ -228,16 +228,87 @@ You may also specify these options in the :doc:`configuration file format: BSON path: data/db/auditLog.bson -To view the contents of the file, pass the file to the MongoDB utility -:binary:`~bin.bsondump`. For example, the following converts the audit log -into a human-readable form and output to the terminal: +The following example converts the audit log into readable form using +:binary:`~bin.bsondump` and outputs the result: .. code-block:: bash bsondump data/db/auditLog.bson +.. _runtime-audit-configuration: + +Runtime Audit Filter Management +------------------------------- + +Starting in MongoDB 5.0, audit filters can be configured at runtime. +Runtime Audit Filter Management provides three benefits compared to +audit filter configurations that are specified in a local +:binary:`~bin.mongod` or :binary:`~bin.mongos` configuration file: + +- :ref:`rafm-separation` +- :ref:`rafm-configurability` +- :ref:`rafm-consistency` + +.. _rafm-separation: + +Separation of Concerns +~~~~~~~~~~~~~~~~~~~~~~ + +Prior to MongoDB 5.0, anyone auditing a MongoDB :binary:`~bin.mongod` +or :binary:`~bin.mongos` instance had to have write access to the host +server's file system in order to update audit filters. Runtime Audit +Filter Management improves security by separating audit access from +administrative access. + +Using Runtime Audit Filter Management instead of editing configuration +files directly means: + +- File system access is not required so an auditor does not need access + to the :binary:`~bin.mongod` or :binary:`~bin.mongos` host server. + +- There is no direct access to the :binary:`~bin.mongod` or + :binary:`~bin.mongos` instance's configuration file. + +- Runtime Audit Filter Management only exposes :ref:`audit filters + ` and the :parameter:`auditAuthorizationSuccess` + parameter. + +.. _rafm-configurability: + +Runtime Configurability +~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in MongoDB 5.0, when Runtime Audit Filter Management is +enabled, auditing can be reconfigured at runtime without restarting the +:binary:`~bin.mongod` or :binary:`~bin.mongos` instance. A statically +configured instance has to be restarted to update its audit settings. + +Audit filter modifications made at runtime persist when an instance is +shutdown and restarted. + +.. _rafm-consistency: + +Consistency +~~~~~~~~~~~ + +Within a cluster, if all participating :binary:`~bin.mongod` and +:binary:`~bin.mongos` nodes are configured to use Runtime Audit Filter +Management, then every node will use the same audit filters. In +contrast, if each node has its own locally configured audit filters, +there is no guarantee of audit filter consistency across nodes. + +.. _rafm-enable: + +Enable Runtime Audit Filter Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/fact-enable-runtime-audit-configuration.rst + .. seealso:: - :doc:`/tutorial/configure-audit-filters` - :doc:`/core/auditing` - :doc:`/reference/audit-message` + - :dbcommand:`setAuditConfig` + - :dbcommand:`getAuditConfig` + diff --git a/source/tutorial/upgrade-revision.txt b/source/tutorial/upgrade-revision.txt index 125e994199a..50124278581 100644 --- a/source/tutorial/upgrade-revision.txt +++ b/source/tutorial/upgrade-revision.txt @@ -96,7 +96,8 @@ Follow this upgrade procedure: #. Upgrade sharded clusters, as described in :ref:`upgrade-sharded-cluster`. -#. Upgrade any standalone instances. See :ref:`upgrade-mongodb-instance`. +#. Upgrade any standalone instances. See + :ref:`upgrade-mongodb-instance`. #. Upgrade any replica sets that are not part of a sharded cluster, as described in :ref:`upgrade-replica-set`. @@ -106,8 +107,8 @@ Follow this upgrade procedure: Upgrade a MongoDB Instance -------------------------- -To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, use one -of the following approaches: +To upgrade a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance, +use one of these approaches: - Upgrade the instance using the operating system's package management tool and the official MongoDB packages. This is the preferred @@ -116,6 +117,9 @@ of the following approaches: - Upgrade the instance by replacing the existing binaries with new binaries. See :ref:`upgrade-replace-binaries`. +- Make any required configuration file changes before restarting the + instance. + .. _upgrade-replace-binaries: Replace the Existing Binaries @@ -140,6 +144,8 @@ replacing the existing binaries: #. Replace the existing MongoDB binaries with the downloaded binaries. +#. Make any required configuration file changes. + #. Restart the instance. .. _`MongoDB Download Page`: https://www.mongodb.com/try/download/community?tck=docs_server