DOCSP-16018 install guide for online audit

mungitoperrito · jeff-allen-mongo · commit 7e0483db6fb7 · 2021-09-27T18:08:08.000-04:00
diff --git a/source/includes/fact-enable-runtime-audit-configuration.rst 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
@@ -26,12 +26,21 @@ 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
 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
@@ -483,7 +483,8 @@ features include:
 - Creation of :ref:`time series collections
   <manual-timeseries-collection>` requires fCV set to 5.0+.
 
-- Configuring Runtime Audit Filter Management requires fCV set to 5.0+.
+- :ref:`Configuring Runtime Audit Filter Management
+  <configure-audit-filters-at-runtime>` 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
@@ -151,9 +151,33 @@ Time-series Collections
   <manual-timeseries-collection>`.
 
 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
@@ -179,9 +179,12 @@ Time-series Collections
   <manual-timeseries-collection>`.
 
 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
@@ -107,9 +107,12 @@ Time-series Collections
   <manual-timeseries-collection>`.
 
 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
@@ -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 </release-notes/4.2-upgrade-replica-set>`, and
+5.0-series release </release-notes/5.0-upgrade-replica-set>`, 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
@@ -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
+<configure-audit-filters-at-runtime>` 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 <audit-message-format>` has:
diff --git 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
@@ -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
+  <audit-filter>` 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
@@ -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
