Skip to content

Commit 6a8c568

Browse files
ajhuh-mdbajhuh-mdb
authored
DOCSP-26175 auditConfig Cluster Parameters (#4790)
* DOCSP-32722 Cluster Parameter Reference Page (#4471) (#4682) * DOCSP-32722 Cluster Parameter Reference Page * wording * * * typo * JA feedback * adjust wording under Syntax section * nit edits * DOCSP-32723 changeStreamOptions Reference Page (#4592) (#4710) * DOCSP-32723 changeStreamOptions Reference Page * text styling * indentations * move text to include * JD feedback * DOCSP-32724 auditConfig Cluster Parameter (#4691) * DOCSP-32724 auditConfig Cluster Parameter * build errors * add to release notes * build errors * JD feedback [still in progress] * deprecation warnings * compatibility changes * external review feedback * typo
1 parent 7606b4f commit 6a8c568

19 files changed

+387
-79
lines changed

‎snooty.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ toc_landing_pages = [
120120
"/reference/aggregation",
121121
"/reference/bson-types",
122122
"/reference/change-events",
123+
"/reference/cluster-parameters",
123124
"/reference/collation",
124125
"/reference/command",
125126
"/reference/command/nav-administration",

‎source/includes/deprecated-get-set-auditconfig.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
*Deprecated in version 7.1:* Use the :parameter:`auditConfig` cluster
2+
parameter instead.

‎source/includes/fact-auditConfig.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
Object that contains information on audit configurations from
2+
:binary:`~bin.mongod` and :binary:`~bin.mongos` server instances.

‎source/includes/fact-changeStreamOptions.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
An object that contains :ref:`change stream <changeStreams>` configuration
2+
options.
3+
4+
You can only set ``changeStreamOptions`` on :binary:`~bin.mongos` or a
5+
replica set primary. The value is set cluster-wide.

‎source/includes/fact-enable-runtime-audit-configuration.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,5 @@ The server logs an error and fails to start if:
2323
- either :setting:`auditLog.filter` or :parameter:`auditAuthorizationSuccess` is set.
2424

2525
To modify audit filters and the :parameter:`auditAuthorizationSuccess` parameter at
26-
runtime, see :dbcommand:`setAuditConfig`.
26+
runtime, see :parameter:`auditConfig`.
2727

‎source/reference.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ Reference
106106
:titlesonly:
107107
:hidden:
108108

109+
/reference/cluster-parameters
109110
/reference/collation
110111
/reference/configuration-options
111112
/reference/connection-string
@@ -116,7 +117,6 @@ Reference
116117
/reference/explain-results
117118
/reference/glossary
118119
/reference/log-messages
119-
/reference/cluster-parameters
120120
/reference/limits
121121
/reference/program
122122
/reference/parameters

‎source/reference/audit-message.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _audit-message:
2+
13
===========================
24
System Event Audit Messages
35
===========================

‎source/reference/cluster-parameters.txt‎

Lines changed: 52 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _cluster-parameters:
22

3-
==========================
4-
MongoDB Cluster Parameters
5-
==========================
3+
==================
4+
Cluster Parameters
5+
==================
66

77
.. default-domain:: mongodb
88

@@ -12,25 +12,28 @@ MongoDB Cluster Parameters
1212
:depth: 2
1313
:class: singlecol
1414

15-
Synopsis
16-
--------
15+
You can use MongoDB cluster parameters to specify configuration options that
16+
affect all nodes in a replica set or sharded cluster.
1717

18-
You can specify configuration options which affect all nodes in a
19-
replica set or sharded cluster. To set these options, use the
20-
:dbcommand:`setClusterParameter` command:
18+
Syntax
19+
------
20+
21+
To set cluster parameters for your deployment, run the following command on the
22+
``admin`` database:
2123

2224
.. code-block:: javascript
2325

2426
db.adminCommand( { setClusterParameter:{ <parameter>: <value> } } )
2527

26-
To view the current values of cluster parameters, use the
27-
:dbcommand:`getClusterParameter` command:
28+
To view the current cluster parameter values, run the following command on the
29+
``admin`` database:
2830

2931
.. code-block:: javascript
3032

31-
db.adminCommand( { getClusterParameter: <parameter> } )
33+
db.adminCommand( { getClusterParameter: "*" } )
3234

33-
.. include:: /includes/reference/fact-setClusterParameter-availability.rst
35+
To learn more about setting and viewing cluster parameters, see
36+
:dbcommand:`setClusterParameter` and :dbcommand:`getClusterParameter`.
3437

3538
Parameters
3639
----------
@@ -41,48 +44,40 @@ Parameters
4144

4245
.. |both| replace:: Available for both :binary:`~bin.mongod` and :binary:`~bin.mongos`.
4346

44-
.. parameter:: changeStreamOptions
45-
46-
.. versionadded:: 6.0
47-
48-
|both|
49-
50-
This is an object containing :ref:`change stream <change-streams-update-event>`
51-
configuration options.
52-
53-
You can only set ``changeStreamOptions`` on mongos or a
54-
replica set primary. The value is set cluster-wide.
55-
56-
.. parameter:: changeStreamOptions.preAndPostImages.expireAfterSeconds
57-
58-
.. versionadded:: 6.0
59-
60-
*Default*: off
61-
62-
Controls the retention policy of change stream pre- and post-images.
63-
Pre- and post-images are the versions of a document before and after
64-
document modification respectively. ``expireAfterSeconds``
65-
controls how long pre- and post-images are retained.
66-
67-
When ``expireAfterSeconds`` is ``off``, MongoDB uses the default retention
68-
policy: pre- and post-images are retained until the corresponding change
69-
stream events are removed from the :term:`oplog`.
70-
71-
To specify the minimum pre- and post-image retention time:
72-
73-
- Set ``expireAfterSeconds`` using an integer.
74-
75-
- If a change stream event is removed from the oplog, then the
76-
corresponding pre- and post-images are also deleted regardless of the
77-
``expireAfterSeconds`` pre- and post-image retention time.
78-
79-
The following example sets the retention time for pre- and post-images in
80-
change streams to ``100 seconds``:
81-
82-
.. code-block:: javascript
83-
84-
db.runCommand( {
85-
setClusterParameter: {
86-
changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } }
87-
}
88-
} )
47+
MongoDB provides the following cluster parameters:
48+
49+
.. list-table::
50+
:widths: 20, 30, 50
51+
:header-rows: 1
52+
53+
* - Name
54+
55+
- Availability
56+
57+
- Description
58+
59+
* - :parameter:`auditConfig`
60+
61+
- |both|
62+
63+
- .. include:: /includes/fact-auditConfig.rst
64+
65+
* - :parameter:`changeStreamOptions`
66+
67+
- |both|
68+
69+
- .. include:: /includes/fact-changeStreamOptions.rst
70+
71+
Learn More
72+
----------
73+
74+
- :dbcommand:`getClusterParameter`
75+
76+
- :dbcommand:`setClusterParameter`
77+
78+
.. toctree::
79+
:titlesonly:
80+
:hidden:
81+
82+
/reference/cluster-parameters/auditConfig
83+
/reference/cluster-parameters/changeStreamOptions

‎source/reference/cluster-parameters/auditConfig.txt‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
.. _auditConfig:
2+
3+
===========
4+
auditConfig
5+
===========
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 2
13+
:class: singlecol
14+
15+
.. |both| replace:: Available for both :binary:`~bin.mongod` and :binary:`~bin.mongos`.
16+
17+
Definition
18+
----------
19+
20+
.. parameter:: auditConfig
21+
22+
.. versionadded:: 7.1
23+
24+
|both|
25+
26+
.. include:: /includes/fact-auditConfig.rst
27+
28+
Syntax
29+
------
30+
31+
To set ``auditConfig`` for your deployment, run the following command on
32+
the ``admin`` database:
33+
34+
.. code-block:: javascript
35+
36+
db.adminCommand( { setClusterParameter: { auditConfig: <value> } } )
37+
38+
To view current values for the ``auditConfig`` cluster parameter, run
39+
the following command on the ``admin`` database:
40+
41+
.. code-block:: javascript
42+
43+
db.adminCommand( { getClusterParameter: "auditConfig" } )
44+
45+
Parameter Fields
46+
----------------
47+
48+
.. parameter:: auditConfig.auditAuthorizationSuccess
49+
50+
*Type*: boolean
51+
52+
*Default*: false
53+
54+
Enables the :ref:`auditing <auditing>` of authorization
55+
successes for the :ref:`authCheck <audit-action-details-results>`
56+
action.
57+
58+
To audit read and write operations, ``auditConfig.auditAuthorizationSuccess``
59+
must be set to ``true``.
60+
61+
When ``auditConfig.auditAuthorizationSuccess`` is ``false``, the
62+
audit system only logs the authorization failures for ``authCheck``. When
63+
:parameter:`auditAuthorizationSuccess` is ``false``, auditing has less
64+
performance impact because the audit system only logs authorization failures.
65+
66+
.. parameter:: auditConfig.filter
67+
68+
*Type*: document
69+
70+
*Default*: none
71+
72+
Filter expression that controls which :ref:`types of operations
73+
<audit-action-details-results>` that the :ref:`audit system <auditing>`
74+
records.
75+
76+
The document fields can be :ref:`any field in the audit message
77+
<audit-message>`, including fields returned in the
78+
:ref:`param <audit-action-details-results>` document. The field values are
79+
:ref:`query condition expressions <query-selectors>`.
80+
81+
To view a sample filter document, see the :ref:`Examples section
82+
<auditconfig-example>`.
83+
84+
Behavior
85+
--------
86+
87+
Auditing must be enabled to use ``auditConfig``.
88+
89+
Retrieving Audit Configurations
90+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91+
92+
If :ref:`runtime audit configuration <configure-audit-filters-at-runtime>`
93+
is enabled, the ``auditAuthorizationSuccess`` parameter doesn't appear in the
94+
``mongod`` or ``mongos`` configuration file. The server will fail to start if
95+
the parameter is present.
96+
97+
If you run ``getClusterParameter`` on ``auditConfig``, nodes that do not
98+
participate in a runtime audit configuration return their current configuration
99+
file settings for ``auditLog.filter`` and
100+
``setParameter.auditAuthorizationSuccess``.
101+
102+
Setting Audit Configurations
103+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
104+
105+
When you set audit configurations with :dbcommand:`setClusterParameter`, changes
106+
immediately take effect on all :ref:`config servers <sharding-config-server>`
107+
and shards in a sharded cluster.
108+
109+
Setting too wide of an audit filter or enabling
110+
``auditConfig.auditAuthorizationSuccess`` can degrade performance.
111+
112+
.. _auditconfig-example:
113+
114+
Example
115+
-------
116+
117+
The following example uses the ``setClusterParameter`` command to enable
118+
auditing when a collection is created or deleted. The audit messages have been
119+
reformatted. They appear on a single line in the log file.
120+
121+
.. code-block:: javascript
122+
123+
db.adminCommand(
124+
{
125+
setClusterParameter: {
126+
auditConfig: {
127+
filter: {
128+
atype: {
129+
$in: [ "createCollection", "dropCollection" ]
130+
}
131+
},
132+
auditAuthorizationSuccess: false
133+
}
134+
}
135+
}
136+
)
137+
138+
After setting the ``auditConfig`` parameter, if you create an ``inventory``
139+
collection in the ``sales`` database, the audit system logs a message that
140+
resembles the following:
141+
142+
.. code-block:: javascript
143+
.. copyable: false
144+
145+
{
146+
"atype" : "createCollection",
147+
"ts" : { "$date" : "2021-08-09T13:45:05.372+00:00" },
148+
"uuid" : { "$binary" : "RKU/YLizS6K9se2GUU7ZVQ==", "$type" : "04" },
149+
"local" : { "ip" : "127.0.0.1", "port" : 27502 },
150+
"remote" : { "ip" : "127.0.0.1", "port" : 51918 },
151+
"users" : [],
152+
"roles" : [],
153+
"param" : { "ns" : "sales.inventory" },
154+
"result" : 0
155+
}
156+
157+
If the ``inventory`` collection is dropped from the ``sales`` database, the
158+
audit system logs a message similar to the following:
159+
160+
.. code-block:: javascript
161+
.. copyable: false
162+
163+
{
164+
"atype" : "dropCollection",
165+
"ts" : { "$date" : "2021-08-09T13:45:00.661+00:00" },
166+
"uuid" : { "$binary" : "0gle4/pSQli+LUcz43ykag==", "$type" : "04" },
167+
"local" : { "ip" : "127.0.0.1", "port" : 27502 },
168+
"remote" : { "ip" : "127.0.0.1", "port" : 51928 },
169+
"users" : [],
170+
"roles" : [],
171+
"param" : { "ns" : "sales.inventory" },
172+
"result" : 0
173+
}
174+
175+
Learn More
176+
----------
177+
178+
- :ref:`auditing`
179+
- :ref:`audit-action-details-results`
180+
- :ref:`cluster-parameters`
181+
- :ref:`configure-audit-filters-at-runtime`
182+
- :ref:`audit-message`

0 commit comments

Comments
 (0)