From b7e3940823ee83fa0ab8ad77afce887b74187331 Mon Sep 17 00:00:00 2001 From: Dave Cuthbert Date: Wed, 30 Jun 2021 15:40:46 -0400 Subject: [PATCH] DOCSP-16015 add getAuditConfig and API --- source/reference/command/getAuditConfig.txt | 118 ++++++++++++ .../reference/command/nav-administration.txt | 19 +- source/reference/configuration-options.txt | 57 +++--- source/reference/parameters.txt | 178 ++++++++++-------- source/release-notes/5.0-compatibility.txt | 96 ++++++---- source/release-notes/5.0.txt | 20 ++ source/tutorial/configure-audit-filters.txt | 64 ++++--- 7 files changed, 381 insertions(+), 171 deletions(-) create mode 100644 source/reference/command/getAuditConfig.txt diff --git a/source/reference/command/getAuditConfig.txt b/source/reference/command/getAuditConfig.txt new file mode 100644 index 00000000000..c2780ae35f0 --- /dev/null +++ b/source/reference/command/getAuditConfig.txt @@ -0,0 +1,118 @@ +============== +getAuditConfig +============== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +Definition +---------- + +.. dbcommand:: getAuditConfig + + .. versionadded:: 5.0 + + :dbcommand:`getAuditConfig` is an administrative command that + retrieves audit configurations from :binary:`~bin.mongod` and + :binary:`~bin.mongos` server instances. + + Use the + :method:`db.adminCommand( { command } )` method + to run :dbcommand:`getAuditConfig` against the ``admin`` database. + + .. code-block:: javascript + + db.adminCommand( { getAuditConfig: 1 } ) + +Behavior +-------- + +:doc:`Auditing ` must be enabled in order to use +:dbcommand:`getAuditConfig`. + +Nodes that are not participating in a runtime audit configuration +return their current configuration file settings for +``auditLog.filter`` and ``setParameter.auditAuthorizationSuccess``. + +Nodes that are participating in the runtime audit synthesize their +current configuration from memory. Configuration updates are +distributed via the :term:`oplog` mechanism which means updates on +:binary:`~bin.mongod` nodes are distributed to secondary nodes very +quickly. However, the distribution mechanism is different on +:binary:`~bin.mongos` nodes. :binary:`~bin.mongos` nodes have to +:parameter:`poll ` the primary server +at regular intervals for configuration updates. You may see stale data +due to polling delay if you run ``setAuditConfig`` on the primary +server and :dbcommand:`getAuditConfig` on a :doc:`shard ` +before the shard has polled the primary server for updated +configuration details. + +.. note:: + + If you are writing automated audit scripts, note that the quoting + style and the types used to represent the cluster signature differ + between ``mongosh`` and the legacy ``mongo`` shell. In ``mongosh`` + the types are Binary and Long. The corresponding types in the legacy + shell are BinData and NumberLong. + + .. code-block:: javascript + :copyable: false + + // mongosh + signature: { + hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0), + keyId: Long("0") + } + + // mongo + "signature" : { + "hash" : BinData(0,"AAAAAAAAAAAAAAAAAAAAAAAAAAA="), + "keyId" : NumberLong(0) + } + +Examples +-------- + +Run :dbcommand:`getAuditConfig` on the ``admin`` database . + +.. code-block:: javascript + + db.adminCommand({getAuditConfig: 1}) + +The example server is configured to audit read and write operations. It +has a filter which captures the desired operations and the +``auditAuthorizationSuccess`` value has been set to ``true``. + +.. code-block:: javascript + :copyable: false + :emphasize-lines: 3-7, 9 + + { + generation: ObjectId("60e73e74680a655705f16525"), + filter: { + atype: 'authCheck', + 'param.command': { + '$in': [ 'find', 'insert', 'delete', 'update', 'findandmodify' ] + } + }, + auditAuthorizationSuccess: true, + ok: 1, + '$clusterTime': { + clusterTime: Timestamp(1, 1625767540), + signature: { + hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0), + keyId: Long("0") + } + }, + operationTime: Timestamp(1, 1625767540) + } + +.. seealso:: + + :method:`db.adminCommand`, :doc:`configure audit filters` + diff --git a/source/reference/command/nav-administration.txt b/source/reference/command/nav-administration.txt index 90ea9cb13c9..4d4a00834b2 100644 --- a/source/reference/command/nav-administration.txt +++ b/source/reference/command/nav-administration.txt @@ -81,12 +81,18 @@ Administration Commands - Unlocks one fsync lock. * - :dbcommand:`getDefaultRWConcern` - - - Retrieves the global default read and write concern options + + - Retrieves the global default read and write concern options for the deployment. .. versionadded:: 4.4 + * - :dbcommand:`getAuditConfig` + + - Retrieves details on audit configuration and filters. + + .. versionadded:: 5.0 + * - :dbcommand:`getParameter` - Retrieves configuration options. @@ -145,8 +151,8 @@ Administration Commands * - :dbcommand:`setDefaultRWConcern` - - Sets the global default read and write concern options for the - deployment. + - Sets the global default read and write concern options for the + deployment. .. versionadded:: 4.4 @@ -156,8 +162,8 @@ Administration Commands .. toctree:: - :titlesonly: - :hidden: + :titlesonly: + :hidden: /reference/command/cloneCollectionAsCapped /reference/command/collMod @@ -174,6 +180,7 @@ Administration Commands /reference/command/filemd5 /reference/command/fsync /reference/command/fsyncUnlock + /reference/command/getAuditConfig /reference/command/getDefaultRWConcern /reference/command/getParameter /reference/command/killCursors diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index 4b6e6032ee2..50ec1d45002 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -4322,6 +4322,32 @@ LDAP Parameters .. include:: /includes/note-audit-in-enterprise-only.rst +.. setting:: auditLog.filter + + *Type*: string representation of a document + + The filter to limit the :ref:`types of operations + ` the :doc:`audit system + ` records. The option takes a string representation + of a query document of the form: + + .. code-block:: javascript + + { : , ... } + + The ```` can be :doc:`any field in the audit message + `, including fields returned in the + :ref:`param ` document. The + ```` is a :ref:`query condition expression + `. + + .. include:: /includes/fact-audit-filter-single-quotes.rst + + .. include:: /includes/fact-audit-filter-yaml-configuration.rst + + .. include:: /includes/note-audit-in-enterprise-only.rst + + .. setting:: auditLog.format *Type*: string @@ -4353,7 +4379,6 @@ LDAP Parameters .. include:: /includes/note-audit-in-enterprise-only.rst - .. setting:: auditLog.path *Type*: string @@ -4361,35 +4386,17 @@ LDAP Parameters The output file for :doc:`auditing ` if :setting:`~auditLog.destination` has value of ``file``. The :setting:`auditLog.path` option can take either a full path name or a relative path name. - - .. include:: /includes/note-audit-in-enterprise-only.rst +.. setting:: auditLog.runtimeConfiguration -.. setting:: auditLog.filter - - *Type*: string representation of a document - - The filter to limit the :ref:`types of operations - ` the :doc:`audit system - ` records. The option takes a string representation - of a query document of the form: - - .. code-block:: javascript - - { : , ... } - - The ```` can be :doc:`any field in the audit message - `, including fields returned in the - :ref:`param ` document. The - ```` is a :ref:`query condition expression - `. - - .. include:: /includes/fact-audit-filter-single-quotes.rst + *Type*: boolean - .. include:: /includes/fact-audit-filter-yaml-configuration.rst + Specifies if a node allows runtime configuration of audit filters + and the auditAuthorizationSuccess variable. If ``true`` the node + can take part in Online Audit Filter Management. - .. include:: /includes/note-audit-in-enterprise-only.rst + .. include:: /includes/note-audit-in-enterprise-only.rst ``snmp`` Options ~~~~~~~~~~~~~~~~ diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index e2e137c51ec..f45730228c9 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -261,7 +261,7 @@ Authentication Parameters :dbcommand:`validate` command. If the limit is exceeded, :dbcommand:`validate` returns as many results as possible and warns that not all corruption might be reported because of the limit. - + You can set :parameter:`maxValidateMemoryUsageMB` during startup, and can change this setting using the :dbcommand:`setParameter` database command. @@ -405,7 +405,7 @@ Authentication Parameters cipher suites during TLS/SSL encryption. This parameter is not supported for use with TLS 1.3. - + Ephemeral Diffie-Hellman (DHE) cipher suites (and Ephemeral Elliptic Curve Diffie-Hellman (ECDHE) cipher suites) provide :ref:`tls-forward-secrecy`. :ref:`tls-forward-secrecy` cipher suites @@ -415,7 +415,7 @@ Authentication Parameters sessions with the compromised key. .. note:: - + Starting in MongoDB 4.2, if :parameter:`opensslDiffieHellmanParameters` is unset but :ref:`ECDHE ` is enabled, MongoDB enables DHE using the @@ -763,10 +763,10 @@ Authentication Parameters You can only set :parameter:`tlsX509ExpirationWarningThresholdDays` during ``mongod/mongos`` startup using either: - + - The :setting:`setParameter` configuration setting, *or* - - - The :option:`mongod --setParameter ` / + + - The :option:`mongod --setParameter ` / :option:`mongos --setParameter ` command line option. @@ -1043,7 +1043,7 @@ General Parameters - **MongoDB 4.2** *deprecates* the :parameter:`failIndexKeyTooLong` parameter and *removes* the - :limit:`Index Key Length Limit ` for + :limit:`Index Key Length Limit ` for :ref:`featureCompatibilityVersion ` (fCV) set to ``"4.2"`` or greater. @@ -1171,10 +1171,10 @@ General Parameters macOS 10.11 (El Capitan) and later support TFO. Linux - Linux operating systems running Linux Kernel 3.7 or later + Linux operating systems running Linux Kernel 3.7 or later can support inbound TFO. - Set the value of ``/proc/sys/net/ipv4/tcp_fastopen`` to + Set the value of ``/proc/sys/net/ipv4/tcp_fastopen`` to enable inbound TFO connections: - Set to ``2`` to enable only inbound TFO connections. @@ -1216,7 +1216,7 @@ General Parameters - ``1`` to enable only outbound TFO connections. - ``3`` to enable inbound and outbound TFO connections. - + This parameter has no effect if the host operating system does not support *or* is not configured to support TFO connections. @@ -1253,8 +1253,8 @@ General Parameters - Increasing the default queue size may improve the effect of TFO on network performance. However, large queue sizes also - increase the risk of server resource exhaustion due to excessive - incoming TFO requests. + increase the risk of server resource exhaustion due to excessive + incoming TFO requests. - Decreasing the default queue size may reduce the risk of resource server resource exhaustion due to excessive incoming TFO requests. @@ -1270,11 +1270,11 @@ General Parameters MongoDB TFO support. .. seealso:: - - - `RFC7413 TCP Fast Open Section 5: Security Considerations + + - `RFC7413 TCP Fast Open Section 5: Security Considerations `__ - - `RFC7413 TCP Fast Open Section 6: TFO Applicability + - `RFC7413 TCP Fast Open Section 6: TFO Applicability `__ .. parameter:: disableJavaScriptJIT @@ -1312,7 +1312,7 @@ General Parameters .. versionadded:: 3.4 - *Default*: + *Default*: - 200 (For versions 4.2.3 and later) @@ -1398,7 +1398,7 @@ General Parameters it can take a maximum of nearly *twice* the value of :parameter:`watchdogPeriodSeconds` to terminate the :binary:`~bin.mongod`. - + - If any of its monitored directory is a symlink to other volumes, the Storage Node Watchdog does not monitor the symlink target. For example, if the :binary:`~bin.mongod` uses @@ -1455,7 +1455,7 @@ General Parameters Specifies the tcmalloc release rate (`TCMALLOC_RELEASE_RATE `_). Per https://gperftools.github.io/gperftools/tcmalloc.html#runtime - TCMALLOC_RELEASE_RATE is described as the "Rate at which we release + TCMALLOC_RELEASE_RATE is described as the "Rate at which we release unused memory to the system, via madvise(MADV_DONTNEED), on systems that support it. Zero means we never release memory back to the system. Increase this flag to @@ -1476,7 +1476,7 @@ General Parameters mongod --setParameter "tcmallocReleaseRate=5.0" - + Logging Parameters ~~~~~~~~~~~~~~~~~~ @@ -1629,7 +1629,7 @@ Logging Parameters Specifies the maxium size, in kilobytes, for an individual attribute field in a log entry; attributes exceeding this limit are truncated. - + Truncated attribute fields print field content up to the :parameter:`maxLogSizeKB` limit and excise field content past that limit, retaining valid JSON formating. Log entires that contain @@ -1784,7 +1784,7 @@ name. For example, if :binary:`~bin.mongos` has ``--logpath /var/log/mongodb/mongos.log.201708015``, then the diagnostic data directory is ``/var/log/mongodb/mongos.diagnostic.data/`` directory. To -specify a different diagnostic data directory for :binary:`~bin.mongos`, +specify a different diagnostic data directory for :binary:`~bin.mongos`, set the :parameter:`diagnosticDataCollectionDirectoryPath` parameter. The following parameters support diagnostic data capture (FTDC): @@ -2089,7 +2089,7 @@ Logical Session *Type*: boolean *Default*: true - + Enables or disables the mechanism that controls the rate at which the primary applies its writes with the goal of keeping the secondary members' :data:`majority committed @@ -2107,7 +2107,7 @@ Logical Session *Type*: integer *Default*: 10 - + The target maximum :data:`majority committed ` lag when running with flow control. When flow control is enabled, the mechanism @@ -2127,15 +2127,15 @@ Logical Session .. versionadded:: 4.2 *Type*: integer - + *Default*: 10 The amount of time to wait to log a warning once the flow control mechanism detects the majority commit point has not moved. The specified value must be greater than or equal to 0, with 0 to - disable warnings. - + disable warnings. + .. parameter:: initialSyncTransientErrorRetryPeriodSeconds .. versionadded:: 4.4 @@ -2144,8 +2144,8 @@ Logical Session *Default*: 86400 - The amount of time in seconds a secondary performing initial sync - attempts to resume the process if interrupted by a transient + The amount of time in seconds a secondary performing initial sync + attempts to resume the process if interrupted by a transient network error. The default value is equivalent to 24 hours. .. parameter:: initialSyncSourceReadPreference @@ -2154,7 +2154,7 @@ Logical Session *Type*: String - |mongod-only| + |mongod-only| The preferred source for performing :ref:`initial sync `. Specify one of the following read @@ -2168,10 +2168,10 @@ Logical Session If the replica set has disabled :rsconf:`chaining `, the default - :parameter:`initialSyncSourceReadPreference` read preference mode + :parameter:`initialSyncSourceReadPreference` read preference mode is :readmode:`primary`. - You cannot specify a tag set or ``maxStalenessSeconds`` to + You cannot specify a tag set or ``maxStalenessSeconds`` to :parameter:`initialSyncSourceReadPreference`. If the :binary:`~bin.mongod` cannot find a sync source based on the @@ -2188,9 +2188,9 @@ Logical Session :rsconf:`~settings.chainingAllowed` when selecting a replication sync source. - You can only set this parameter on startup, using either the + You can only set this parameter on startup, using either the :setting:`setParameter` - configuration file setting or the + configuration file setting or the :option:`--setParameter ` command line option. .. parameter:: oplogFetcherUsesExhaust @@ -2201,20 +2201,20 @@ Logical Session *Type*: boolean - *Default*: true + *Default*: true + + Enables or disables :ref:`streaming replication + `. Set the value to ``true`` to enable + streaming replication. - Enables or disables :ref:`streaming replication - `. Set the value to ``true`` to enable - streaming replication. - - Set the value to ``false`` to disable streaming replication. If - disabled, secondaries fetch batches of :doc:`oplog ` - entries by issuing a request to their *sync from* source and waiting for a - response. This requires a network roundtrip for each batch of :doc:`oplog + Set the value to ``false`` to disable streaming replication. If + disabled, secondaries fetch batches of :doc:`oplog ` + entries by issuing a request to their *sync from* source and waiting for a + response. This requires a network roundtrip for each batch of :doc:`oplog ` entries. - You can only set this parameter on startup, using either the - :setting:`setParameter` configuration file setting or the + You can only set this parameter on startup, using either the + :setting:`setParameter` configuration file setting or the :option:`--setParameter ` command line option. .. parameter:: oplogInitialFindMaxSeconds @@ -2289,7 +2289,7 @@ Logical Session after the common point (the last point where the source node and the to-be-rolledback node had the same data) exceeds this value, the rollback will fail. - + In MongoDB 4.0.0-4.0.12, if the time between the end of the to-be-rolledback instance's oplog and the common point (the last point where the source node and the to-be-rolledback node had the same data) exceeds @@ -2376,12 +2376,12 @@ Logical Session A flag that can reduce the downtime after the primary steps down from either the :method:`rs.stepDown()` method or the :dbcommand:`replSetStepDown` command. - + If the flag is true, when a primary steps down after :method:`rs.stepDown()` (or the :dbcommand:`replSetStepDown` command without the ``force: true``), the primary nominates an eligible secondary to call an election immediately. - + If the flag is false, after the step down, secondaries can wait up to :rsconf:`settings.electionTimeoutMillis` before calling an election. @@ -2425,7 +2425,7 @@ Logical Session .. parameter:: mirrorReads - |mongod-only| + |mongod-only| *New in version 4.4* @@ -2491,7 +2491,7 @@ Logical Session * - ``maxTimeMS`` - The maximum time in milliseconds for the mirrored reads. The - default value is ``1000``. + default value is ``1000``. The ``maxTimeMS`` for the mirrored reads is separate from the ``maxTimeMS`` of the original read being mirrored. @@ -2512,7 +2512,7 @@ Logical Session Or, to specify in a configuration file: .. code-block:: yaml - + setParameter: mirrorReads: '{samplingRate: 0.10}' @@ -2629,7 +2629,7 @@ Sharding Parameters You can only set the parameter during startup, and cannot change this setting using the :dbcommand:`setParameter` database command. - + For example, the following sets the interval at 300000 milliseconds (5 minutes) at startup: @@ -2653,10 +2653,10 @@ Sharding Parameters |both| - This parameter allows the catalog cache to be refreshed only if the - shard needs to be refreshed. If disabled, any stale chunk will cause - the entire chunk distribution for a collection to be considered stale - and force all :ref:`routers ` who + This parameter allows the catalog cache to be refreshed only if the + shard needs to be refreshed. If disabled, any stale chunk will cause + the entire chunk distribution for a collection to be considered stale + and force all :ref:`routers ` who contact the shard to refresh their shard catalog cache. You can only set this parameter during start-up and cannot change @@ -2666,8 +2666,8 @@ Sharding Parameters mongod --setParameter enableFinerGrainedCatalogCacheRefresh=true mongos --setParameter enableFinerGrainedCatalogCacheRefresh=true - - .. seealso:: + + .. seealso:: - :ref:`sharding-background` - :serverstatus:`shardingStatistics.catalogCache` @@ -2691,7 +2691,7 @@ Sharding Parameters For example, to set the limit to 200 milliseconds, you can issue the following during startup: - + .. code-block:: bash mongos --setParameter maxTimeMSForHedgedReads=200 @@ -2756,14 +2756,14 @@ Sharding Parameters Or if using the :dbcommand:`setParameter` command in a :binary:`~bin.mongosh` session that is connected to a running :binary:`~bin.mongos`: - + .. code-block:: javascript db.adminCommand( { setParameter: 1, readHedgingMode: "off" } ) - .. seealso:: - - - :ref:`mongos-hedged-reads` + .. seealso:: + + - :ref:`mongos-hedged-reads` - :parameter:`maxTimeMSForHedgedReads` .. parameter:: shutdownTimeoutMillisForSignaledShutdown @@ -2775,14 +2775,14 @@ Sharding Parameters *Default*: 15000 |mongod-only| - + Specifies the time (in milliseconds) to wait for any ongoing database operations to complete before initiating a shutdown of :binary:`~bin.mongod` in response to a ``SIGTERM`` signal. For example, to set the time to 250 milliseconds, you can issue the following during startup: - + .. code-block:: bash mongod --setParameter shutdownTimeoutMillisForSignaledShutdown=250 @@ -2804,14 +2804,14 @@ Sharding Parameters *Default*: 15000 |mongos-only| - + Specifies the time (in milliseconds) to wait for any ongoing database operations to complete before initiating a shutdown of :binary:`~bin.mongos` in response to a ``SIGTERM`` signal. For example, to set the time to 250 milliseconds, you can issue the following during startup: - + .. code-block:: bash mongos --setParameter mongosShutdownTimeoutMillisForSignaledShutdown=250 @@ -2845,7 +2845,7 @@ Sharding Parameters - For MongoDB 3.2.0-3.2.9, the monitoring :binary:`~bin.mongod` or :binary:`~bin.mongos` instance will become unusable and needs to be restarted. See the :v3.2:`v3.2 troubleshooting guide - ` + ` for more details. - For MongoDB 3.2.10 and later 3.2-series, see also @@ -3001,7 +3001,7 @@ Sharding Parameters :parameter:`taskExecutorPoolSize`. .. seealso:: - + - :parameter:`ShardingTaskExecutorPoolMaxSize` - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartup` @@ -3259,7 +3259,7 @@ Sharding Parameters of initial client connections once started. :parameter:`loadRoutingTableOnStartup` is enabled by default. - + You can only set this parameter on startup, using either the :setting:`setParameter` configuration file setting or the :option:`--setParameter ` command line option. @@ -3299,7 +3299,7 @@ Sharding Parameters :option:`--setParameter ` command line option. .. seealso:: - + - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS` - :parameter:`ShardingTaskExecutorPoolMinSize` @@ -3326,7 +3326,7 @@ Sharding Parameters :option:`--setParameter ` command line option. .. seealso:: - + - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartup` - :parameter:`ShardingTaskExecutorPoolMinSize` @@ -3723,7 +3723,7 @@ WiredTiger Parameters You can only set this parameter during runtime using the :dbcommand:`setParameter` database command: - + .. code-block:: javascript db.adminCommand( { setParameter: 1, wiredTigerMaxCacheOverflowSizeGB: 100 } ) @@ -3731,9 +3731,8 @@ WiredTiger Parameters To set the maximum size during start up, use the :setting:`storage.wiredTiger.engineConfig.maxCacheOverflowFileSizeGB` instead. - - *Available starting in MongoDB 4.2.1 (and 4.0.12)* + *Available starting in MongoDB 4.2.1 (and 4.0.12)* .. parameter:: wiredTigerConcurrentReadTransactions @@ -3802,7 +3801,9 @@ Auditing Parameters .. parameter:: auditAuthorizationSuccess - *Default*: ``false`` + *Type*: boolean + + *Default*: false .. include:: /includes/note-audit-in-enterprise-only.rst @@ -3825,10 +3826,35 @@ Auditing Parameters .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst + If :ref:`runtime audit configuration ` + is enabled, the :parameter:`auditAuthorizationSuccess` parameter + should not appear in the ``mongod`` or ``mongos`` configuration + file. The server will fail to start if the parameter is present. + .. seealso:: :dbcommand:`getParameter` +.. parameter:: auditConfigPollingFrequencySecs + + .. versionadded:: 5.0 + + *Type*: integer + + *Default*: 300 + + A sharded cluster may have servers which maintain audit + configuration settings for the cluster. Set the interval, in + seconds, for non-configured servers to poll a config server for the + current audit generation. If this value returned differs from the + previously known value, the initiating node will request the current + configuration and update its internal state. + + .. note:: + + Using the default value of 300 seconds, non-config nodes may lag up + to 5 minutes behind a setAuditConfig command. + Transaction Parameters ~~~~~~~~~~~~~~~~~~~~~~ @@ -3976,7 +4002,7 @@ Transaction Parameters - ``true`` to enable. (*Default*) - ``false`` to disable. - + You can set the parameter during startup or runtime. .. important:: diff --git a/source/release-notes/5.0-compatibility.txt b/source/release-notes/5.0-compatibility.txt index 35fd80f4e72..00bfa069c64 100644 --- a/source/release-notes/5.0-compatibility.txt +++ b/source/release-notes/5.0-compatibility.txt @@ -13,11 +13,11 @@ Compatibility Changes in MongoDB 5.0 The following 5.0 changes can affect compatibility with older versions of MongoDB. -Certain Commands Only Accept Recognized Parameters +Certain Commands Only Accept Recognized Parameters -------------------------------------------------- -Starting in MongoDB 5.0, certain database commands raise an error if -passed a parameter not explicitly accepted by the command. In MongoDB +Starting in MongoDB 5.0, certain database commands raise an error if +passed a parameter not explicitly accepted by the command. In MongoDB 4.4 and earlier, unrecognized parameters are silently ignored. Affected Commands: @@ -78,7 +78,7 @@ Starting in MongoDB 5.0, these database commands and * - ``Mongo.getSecondaryOk()`` - :doc:`/reference/method/Mongo.getReadPrefMode` - + * - ``Mongo.isCausalConsistency`` - Not available @@ -134,7 +134,7 @@ Shell Changes The ``mongo`` shell has been deprecated in MongoDB v5.0. The replacement shell is :binary:`~bin.mongosh`. -Shell packaging also changes in MongoDB v5.0. Refer to the +Shell packaging also changes in MongoDB v5.0. Refer to the :mongosh:`installation instructions ` for further details. Replica Sets @@ -151,7 +151,7 @@ Replica Sets ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Starting in MongoDB 5.0, :rsconf:`~members[n].secondaryDelaySecs` -replaces ``slaveDelay``. This change is not backwards compatible. +replaces ``slaveDelay``. This change is not backwards compatible. Manual Oplog Writes ~~~~~~~~~~~~~~~~~~~ @@ -217,63 +217,81 @@ created (meaning that the operation is a no-op). ``listDatabases`` Output Changes -------------------------------- -Starting in MongoDB 5.0, output from the :dbcommand:`listDatabases` -command running against a :binary:`~bin.mongod` is more consistent with -output from :dbcommand:`listDatabases` running against a +Starting in MongoDB 5.0, output from the :dbcommand:`listDatabases` +command running against a :binary:`~bin.mongod` is more consistent with +output from :dbcommand:`listDatabases` running against a :binary:`~bin.mongos`. The following table shows the differences in data types for :dbcommand:`listDatabases` output fields between MongoDB 5.0 and earlier -versions. Only fields which differ between 5.0 and earlier versions are -listed. +versions. Only fields which differ between 5.0 and earlier versions are +listed. .. list-table:: :header-rows: 1 :widths: 25 25 25 25 - + * - Field - - - Type in MongoDB 5.0 + + - Type in MongoDB 5.0 - Type in MongoDB 4.4 and earlier (``mongod``) - Type in MongoDB 4.4 and earlier (``mongos``) - + * - ``sizeOnDisk`` - + - integer - + - double - integer - + * - ``totalSize`` - + - integer - + - double - integer - + * - ``totalSizeMb`` - + - integer - not present (see below) - - integer + - integer -The output from :dbcommand:`listDatabases` now includes the -``totalSizeMb`` field when run against either a :binary:`~bin.mongos` or -a :binary:`~bin.mongod`. In MongoDB 4.4 and earlier, ``totalSizeMb`` -only appears when run against :binary:`~bin.mongos`. ``totalSizeMb`` is -the sum of the ``sizeOnDisk`` fields, expressed in megabytes. +The output from :dbcommand:`listDatabases` now includes the +``totalSizeMb`` field when run against either a :binary:`~bin.mongos` or +a :binary:`~bin.mongod`. In MongoDB 4.4 and earlier, ``totalSizeMb`` +only appears when run against :binary:`~bin.mongos`. ``totalSizeMb`` is +the sum of the ``sizeOnDisk`` fields, expressed in megabytes. When run against :binary:`~bin.mongos`, the ``shards`` field in the :dbcommand:`listDatabases` output contains a field-value pair for each -collection on a particular shard. Size values in the ``shards`` field +collection on a particular shard. Size values in the ``shards`` field are expressed as integers. +Auditing +-------- + +MongoDB 5.0 adds auditing capabilities that can be configured at +runtime. + +If ``auditLog.runtimeConfiguration`` is set to ``true``, then the +``mongod`` and ``mongos`` configuration files can no longer set +``setParameter.auditAuthorizationSuccess`` or +:doc:`configure audit filters +`. If the server configuration files +contain these settings the server will fail to start and will log an +error. + +If ``auditLog.runtimeConfiguration`` is set to ``false`` and an audit +filter config document is present, then a startup warning will be +issued but the server will not abort. + General Changes --------------- @@ -300,14 +318,14 @@ General Changes - MongoDB 5.0 removes the ``--serviceExecutor`` command-line option and the corresponding ``net.serviceExecutor`` configuration option. -- Starting in MongoDB 5.0, you may not authenticate as multiple - simultaneous users on the same client session if the - :option:`--apiStrict` option is set. Attempting to - authenticate as a new user while currently logged in as an existing - user when the :option:`--apiStrict` option is set will generate an +- Starting in MongoDB 5.0, you may not authenticate as multiple + simultaneous users on the same client session if the + :option:`--apiStrict` option is set. Attempting to + authenticate as a new user while currently logged in as an existing + user when the :option:`--apiStrict` option is set will generate an error message once per authentication attempt. If you are not using the :option:`--apiStrict` option, authenticating as a new user while - currently logged in as an existing user will write a warning to the + currently logged in as an existing user will write a warning to the log once per authentication attempt. - .. include:: /includes/fact-set-global-write-concern-before-reconfig.rst @@ -339,13 +357,13 @@ Deprecations instead. - :dbcommand:`logout` - - *Deprecated in version 5.0:* Disconnect from the server to end your + + *Deprecated in version 5.0:* Disconnect from the server to end your session instead. - + - :method:`db.logout()` - *Deprecated in version 5.0:* Disconnect from the server to end your + *Deprecated in version 5.0:* Disconnect from the server to end your session instead. Deprecated Wire Protocol Opcodes diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 77cb81cadc7..906246efeee 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -153,6 +153,26 @@ stage supports :ref:`concise correlated subqueries ` that improve joins between collections. +.. _5.0-rel-notes-auditing: + +Auditing +-------- + +MongDB 5.0 adds the ability to configure auditing filters at runtime. + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Operator + - Description + + * - :dbcommand:`getAuditConfig` + - Retrieves audit configurations from ``mongod`` and ``mongos``. + + * - :parameter:`auditConfigPollingFrequencySecs` + - Defines the polling interval for checking audit configuration + .. _5.0-rel-notes-change-streams: Change Streams diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index 5f8fd3f884e..755a053989b 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -18,7 +18,7 @@ Configure Audit Filters MongoDB Atlas supports auditing for all ``M10`` and larger clusters. Atlas supports specifying a JSON-formatted audit filter as documented below and using the Atlas audit filter - builder for simplified auditing configuration. To learn more, see + builder for simplified auditing configuration. To learn more, see the Atlas documentation for :atlas:`Set Up Database Auditing ` and @@ -28,37 +28,51 @@ Configure Audit Filters supports :ref:`auditing ` of various operations. When :doc:`enabled `, the audit facility, by default, records all auditable operations as detailed in -:ref:`audit-action-details-results`. To specify which events to record, -the audit feature includes the ``--auditFilter`` option. +:ref:`audit-action-details-results`. You can specify event filters to +limit which events are recorded. Filters can be configured at +:ref:`startup ` or MongoDB can be +configured to allow +:ref:`runtime specification `. -.. note:: +.. _configure-audit-filters-at-runtime: - .. include:: /includes/extracts/default-bind-ip-security.rst +Filter Configuration at Runtime +------------------------------- - Before you bind to other ip addresses, consider :ref:`enabling - access control ` and other security measures listed - in :doc:`/administration/security-checklist` to prevent unauthorized - access. +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. A node will be included in the distributed audit configuration +if: -``--auditFilter`` Option ------------------------- +- :setting:`auditLog.runtimeConfiguration` is ``true``, +- :setting:`auditLog.filter` is not set, and +- :parameter:`auditAuthorizationSuccess` is not set -The ``--auditFilter`` option takes a string representation of a -query document of the form: +When ``runtimeConfiguration`` is ``true``, the server will log an error +and fail to start if either one of the other variables is set. -.. code-block:: javascript +.. _configure-audit-filters-at-startup: - { : , ... } +Filter Configuration at System Startup +-------------------------------------- -- The ```` can be :doc:`any field in the audit message - `, including fields returned in the - :ref:`param ` document. +Audit filters can be specified on the command line or else in the +:ref:`configuration file ` used to start the +``mongod`` or ``mongos`` instance. -- The ```` is a :ref:`query condition expression - `. +Configuration File Usage +~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: /includes/fact-audit-filter-single-quotes.rst -.. include:: /includes/fact-audit-filter-yaml-configuration.rst +Filters can be specified in YAML under the ``auditLog`` session of the +:ref:`configuration file `. See the examples +below for sample configurations. + +.. note:: + + If ``runtimeConfiguration`` is enabled, then the + :ref:`configuration file ` cannot be used to + specify audit filters. Examples -------- @@ -217,7 +231,7 @@ audit, you must also enable the audit system to log authorization successes using the :parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ -.. note:: +.. note:: .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst @@ -262,13 +276,13 @@ audit, you must also enable the audit system to log authorization successes using the :parameter:`auditAuthorizationSuccess` parameter. [#authorization-agnostic]_ -.. note:: +.. note:: .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst The following example audits the :method:`~db.collection.find()`, :method:`~db.collection.insert()`, :method:`~db.collection.remove()`, -:method:`~db.collection.update()`, and +:method:`~db.collection.update()`, and :method:`~db.collection.findAndModify()` operations for the collection ``orders`` in the database ``test`` by using the filter: