Skip to content

DOCSP-16018 install guide for online audit #5891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 27, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions source/includes/fact-enable-runtime-audit-configuration.rst
Original file line number Diff line number Diff line change
@@ -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`.

11 changes: 10 additions & 1 deletion source/includes/steps-5.0-downgrade-mongod.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.

...
3 changes: 2 additions & 1 deletion source/release-notes/5.0-compatibility.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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+.

Expand Down
30 changes: 27 additions & 3 deletions source/release-notes/5.0-downgrade-replica-set.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
9 changes: 6 additions & 3 deletions source/release-notes/5.0-downgrade-sharded-cluster.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down
10 changes: 7 additions & 3 deletions source/release-notes/5.0-downgrade-standalone.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -132,3 +135,4 @@ Procedure
prerequisites have been completed.

.. include:: /includes/steps/5.0-downgrade-mongod.rst

2 changes: 1 addition & 1 deletion source/release-notes/5.0-upgrade-replica-set.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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|.

Expand Down
9 changes: 8 additions & 1 deletion source/release-notes/5.0.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
13 changes: 1 addition & 12 deletions source/tutorial/configure-audit-filters.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
77 changes: 74 additions & 3 deletions source/tutorial/configure-auditing.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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`

12 changes: 9 additions & 3 deletions source/tutorial/upgrade-revision.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down