Skip to content

Commit 4870b61

Browse files
jeff-allen-mongojeff-allen-mongo
committed
Merge remote-tracking branch 'upstream/v5.3' into v5.3-temp
2 parents 7673546 + 9318da7 commit 4870b61

17 files changed

+392
-20
lines changed

‎snooty.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -209,7 +209,7 @@ package-name-org = "mongodb-org"
209209
package-name-enterprise = "mongodb-enterprise"
210210
version = "5.0"
211211
release = "5.0.5"
212-
version-dev = "5.2"
212+
version-dev = "5.3"
213213
pgp-version = "{+version+}"
214214
rsa-key = "4B7C549A058F8B6B"
215215
pgp-fingerprint = "E162F504A20CDF15827F718D4B7C549A058F8B6B"

‎source/core/security-encryption-at-rest.txt

Lines changed: 45 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -111,21 +111,54 @@ transport encryption.
111111

112112
For details, see :ref:`rotate-encryption-keys`.
113113

114-
Logging
115-
~~~~~~~
114+
Audit Log
115+
~~~~~~~~~
116116

117-
.. versionadded:: 3.4 Available in MongoDB Enterprise only
117+
Available in MongoDB Enterprise only.
118118

119-
The log file is not encrypted as a part of MongoDB's encrypted storage engine.
120-
A :binary:`~bin.mongod` running with :ref:`logging <monitoring-standard-loggging>`
121-
may output potentially sensitive information to log files as a part of normal
122-
operations, depending on the configured :ref:`log verbosity
123-
<log-messages-configure-verbosity>`.
119+
.. _security-encryption-at-rest-audit-log:
124120

125-
MongoDB 3.4 Enterprise provides the :setting:`security.redactClientLogData`
126-
setting to prevent potentially sensitive information from entering the
127-
:binary:`~bin.mongod` process log. :setting:`~security.redactClientLogData`
128-
reduces detail in the log and may complicate log diagnostics.
121+
Use KMIP Server to Manage Keys for Encrypting the MongoDB Audit Log
122+
```````````````````````````````````````````````````````````````````
123+
124+
Starting in MongoDB 5.3 Enterprise, you can use an external Key
125+
Management Interoperability Protocol (KMIP) server to securely manage
126+
the keys for encrypting the MongoDB audit log.
127+
128+
To use a KMIP server with audit log encryption, configure these settings
129+
and parameters:
130+
131+
- :setting:`auditLog.auditEncryptionKeyIdentifier` setting
132+
- :setting:`auditLog.compressionMode` setting
133+
- :parameter:`auditEncryptionHeaderMetadataFile` parameter
134+
- :parameter:`auditEncryptKeyWithKMIPGet` parameter
135+
136+
For testing audit log encryption, you can also use the
137+
:setting:`auditLog.localAuditKeyFile` setting.
138+
139+
.. note::
140+
141+
For audit log encryption, the audit log destination must be a
142+
file. :term:`syslog` cannot be used as the destination.
143+
144+
Unencrypted Audit Log and Process Log
145+
`````````````````````````````````````
146+
147+
This section applies if you are not using an external Key Management
148+
Interoperability Protocol (KMIP) server to manage keys for encrypting
149+
the audit log as shown in the previous section.
150+
151+
The audit log file is not encrypted as a part of MongoDB's encrypted
152+
storage engine. A :binary:`~bin.mongod` running with :ref:`logging
153+
<monitoring-standard-loggging>` may output potentially sensitive
154+
information to log files as a part of normal operations, depending on
155+
the configured :ref:`log verbosity <log-messages-configure-verbosity>`.
156+
157+
Use the :setting:`security.redactClientLogData` setting to prevent
158+
potentially sensitive information from entering the
159+
:binary:`~bin.mongod` process log.
160+
:setting:`~security.redactClientLogData` reduces detail in the log and
161+
may complicate log diagnostics.
129162

130163
See the :ref:`log redaction <monitoring-log-redaction>` manual entry for
131164
more information.

‎source/core/timeseries-collections.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,8 @@ Other options allowed with the ``timeseries`` option are:
130130

131131
:method:`db.createCollection()` and :dbcommand:`create`.
132132

133+
.. _timeseries-collections-insert:
134+
133135
Insert Measurements into a Time Series Collection
134136
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
135137

‎source/core/timeseries/timeseries-limitations.txt

Lines changed: 74 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
.. _manual-timeseries-collection-limitations:
22

3-
==================================
4-
Time Series Collection Limitations
5-
==================================
3+
============================================
4+
Time Series Collection Notes and Limitations
5+
============================================
66

77
.. default-domain:: mongodb
88

@@ -59,14 +59,79 @@ To remove all documents from a collection, use the
5959

6060
.. _timeseries-limitations-secondary-indexes:
6161

62-
Secondary Indexes
63-
~~~~~~~~~~~~~~~~~
62+
Time Series Secondary Indexes
63+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6464

6565
You can add :term:`secondary indexes <secondary index>` on the fields
6666
specified as the ``timeField`` and the ``metaField``. If the field value
6767
for the ``metaField`` field is a document, you can also create secondary
6868
indexes on fields inside that document.
6969

70+
The following sections describe:
71+
72+
- Additional secondary indexes you can add.
73+
74+
- Secondary index limitations.
75+
76+
Time Series Secondary Indexes in MongoDB 5.3
77+
````````````````````````````````````````````
78+
79+
Starting in MongoDB 5.3:
80+
81+
- You can add the following secondary indexes to a :ref:`time series
82+
collection <manual-timeseries-collection>`:
83+
84+
- :doc:`Partial
85+
</core/index-partial>`, :doc:`2d </core/2d>`, and :doc:`2dsphere
86+
</core/2dsphere>` indexes to a metadata field.
87+
88+
- :doc:`2dsphere </core/2dsphere>` and :doc:`partial
89+
</core/index-partial>` indexes to a measurement field.
90+
91+
- :doc:`Compound index </core/index-compound>` on time, metadata, or
92+
measurement fields.
93+
94+
- If you need to downgrade the Feature Compatibility Version (FCV),
95+
you must first drop any indexes that are incompatible with the
96+
downgraded FCV. See :dbcommand:`setFeatureCompatibilityVersion`.
97+
98+
- You can use the :query:`$or`, :query:`$in`, and :query:`$geoWithin`
99+
operators with :doc:`partial indexes </core/index-partial>` on a time
100+
series collection.
101+
102+
- You can use the :pipeline:`$geoNear` pipeline operator with a:
103+
104+
.. include:: /includes/geoNear-time-series.rst
105+
106+
For example, the following ``sensorData`` collection contains
107+
temperature readings:
108+
109+
.. code-block:: javascript
110+
111+
db.sensorData.insertMany( [
112+
{
113+
"metadata": { "sensorId": 5578, "type": "temperature" },
114+
"timestamp": ISODate("2022-01-15T00:00:00.000Z"),
115+
"temperatureReading": 12
116+
},
117+
{
118+
"metadata": { "sensorId": 5578, "type": "temperature" },
119+
"timestamp": ISODate("2022-01-15T04:00:00.000Z"),
120+
"temperatureReading": 11
121+
}
122+
] )
123+
124+
The following example creates an ascending secondary index on the
125+
``metadata.sensorId`` and ``temperatureReading`` fields in the
126+
``sensorData`` collection:
127+
128+
.. code-block:: javascript
129+
130+
db.sensorData.createIndex( { "metadata.sensorId": 1, "temperatureReading": 1 } )
131+
132+
Secondary Index Limitations
133+
```````````````````````````
134+
70135
In MongoDB 5.1, the ``metaField`` doesn't support :doc:`text
71136
</core/index-text>` indexes.
72137

@@ -79,9 +144,12 @@ types:
79144

80145
Secondary indexes don't support the following index properties:
81146

147+
- :doc:`2d </core/2d>` in MongoDB 5.2 and lower
148+
- :doc:`2dsphere </core/2dsphere>` in MongoDB 5.2 and lower
82149
- :doc:`TTL </core/index-ttl>`
83150
- :doc:`Unique </core/index-unique>`
84-
- :doc:`Partial </core/index-partial>`
151+
- :doc:`Partial </core/index-partial>` in MongoDB 5.2 and lower
152+
- :doc:`Multikey index </core/index-multikey>` on a measurement field
85153

86154
``reIndex``
87155
~~~~~~~~~~~

‎source/includes/audit-compression-mode-option.rst

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the compression mode for :ref:`audit log encryption
4+
<security-encryption-at-rest-audit-log>`. You must also enable audit log
5+
encryption using either |audit-encryption-key-identifier-option| or
6+
|audit-local-keyfile-option|.
7+
8+
|audit-compression-mode-option| can be set to one of these values:
9+
10+
.. list-table::
11+
:header-rows: 1
12+
:widths: 15 50
13+
14+
* - Value
15+
- Description
16+
17+
* - ``zstd``
18+
- Use the :term:`zstd` algorithm to compress the audit log.
19+
20+
* - ``none`` *(default)*
21+
- Do not compress the audit log.
22+
23+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/audit-encryption-key-identifier-option.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the unique identifier of the Key Management
4+
Interoperability Protocol (KMIP) key for :ref:`audit log encryption
5+
<security-encryption-at-rest-audit-log>`.
6+
7+
You cannot use |audit-encryption-key-identifier-option| and
8+
|audit-local-keyfile-option| together.
9+
10+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/audit-local-key-file-option.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. versionadded:: 5.3
2+
3+
Specifies the path and file name for a local audit key file for
4+
:ref:`audit log encryption <security-encryption-at-rest-audit-log>`.
5+
6+
.. note::
7+
8+
Only use |audit-local-keyfile-option| for testing because the key is
9+
not secured. To secure the key, use
10+
|audit-encryption-key-identifier-option| and an external Key
11+
Management Interoperability Protocol (KMIP) server.
12+
13+
You cannot use |audit-local-keyfile-option| and
14+
|audit-encryption-key-identifier-option| together.
15+
16+
.. include:: /includes/note-audit-in-enterprise.rst

‎source/includes/geoNear-time-series.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
- :doc:`2dsphere </core/2dsphere>` index on a :ref:`time series
2+
collection <manual-timeseries-collection>`.
3+
4+
- Query on any field in a time series collection, including
5+
metadata fields.

‎source/includes/note-audit-in-enterprise.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. note::
2+
3+
Available only in `MongoDB Enterprise
4+
<http://www.mongodb.com/products/mongodb-enterprise-advanced?tck=docs_server>`_.
5+
MongoDB Enterprise and Atlas have different configuration
6+
requirements.

‎source/reference/configuration-file-settings-command-line-options-mapping.txt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,13 @@ and :binary:`~bin.mongos` command-line options.
1717
* - Configuration File Setting
1818
- ``mongod`` and ``mongos`` Command-Line Options
1919

20+
* - :setting:`auditLog.auditEncryptionKeyIdentifier`
21+
- | :option:`mongod --auditEncryptionKeyUID`
22+
| :option:`mongos --auditEncryptionKeyUID`
23+
24+
* - :setting:`auditLog.compressionMode`
25+
- | :option:`mongod --auditCompressionMode`
26+
| :option:`mongos --auditCompressionMode`
2027

2128
* - :setting:`auditLog.destination`
2229
- | :option:`mongod --auditDestination`
@@ -30,6 +37,10 @@ and :binary:`~bin.mongos` command-line options.
3037
- | :option:`mongod --auditFormat`
3138
| :option:`mongos --auditFormat`
3239

40+
* - :setting:`auditLog.localAuditKeyFile`
41+
- | :option:`mongod --auditLocalKeyFile`
42+
| :option:`mongos --auditLocalKeyFile`
43+
3344
* - :setting:`auditLog.path`
3445
- | :option:`mongod --auditPath`
3546
| :option:`mongos --auditPath`

‎source/reference/configuration-options.txt

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4305,6 +4305,24 @@ LDAP Parameters
43054305
path: <string>
43064306
filter: <string>
43074307

4308+
.. |audit-compression-mode-option| replace:: :setting:`auditLog.compressionMode`
4309+
.. |audit-encryption-key-identifier-option| replace:: :setting:`auditLog.auditEncryptionKeyIdentifier`
4310+
.. |audit-local-keyfile-option| replace:: :setting:`auditLog.localAuditKeyFile`
4311+
4312+
.. setting:: auditLog.auditEncryptionKeyIdentifier
4313+
4314+
*Type*: string
4315+
4316+
.. include:: /includes/audit-encryption-key-identifier-option.rst
4317+
4318+
.. setting:: auditLog.compressionMode
4319+
4320+
*Type*: string
4321+
4322+
.. |option-1| replace:: :setting:`auditLog.compressionMode`
4323+
4324+
.. include:: /includes/audit-compression-mode-option.rst
4325+
43084326
.. setting:: auditLog.destination
43094327

43104328
*Type*: string
@@ -4402,6 +4420,12 @@ LDAP Parameters
44024420

44034421
.. include:: /includes/note-audit-in-enterprise-only.rst
44044422

4423+
.. setting:: auditLog.localAuditKeyFile
4424+
4425+
*Type*: string
4426+
4427+
.. include:: /includes/audit-local-key-file-option.rst
4428+
44054429
.. setting:: auditLog.path
44064430

44074431
*Type*: string

‎source/reference/operator/aggregation/geoNear.txt

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,13 +201,18 @@ When using :pipeline:`$geoNear`, consider that:
201201

202202
- .. include:: /includes/extracts/views-unsupported-geoNear.rst
203203

204-
- Starting in version 4.2, :pipeline:`$geoNear` no longer has a default
204+
- Starting in MongoDB 4.2, :pipeline:`$geoNear` no longer has a default
205205
limit of 100 documents.
206206

207207
- Starting in MongoDB 5.1, the ``near`` parameter supports the
208208
:ref:`let option <geoNear_let_example>` and
209209
:ref:`bound let option <geoNear_bounded_let_example>`.
210210

211+
- Starting in MongoDB 5.3, you can use the :pipeline:`$geoNear` pipeline
212+
operator with a:
213+
214+
.. include:: /includes/geoNear-time-series.rst
215+
211216
Examples
212217
--------
213218

‎source/reference/parameters.txt

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4191,6 +4191,58 @@ Auditing Parameters
41914191
Using the default value of 300 seconds, non-config nodes may lag up
41924192
to 5 minutes behind a setAuditConfig command.
41934193

4194+
.. parameter:: auditEncryptionHeaderMetadataFile
4195+
4196+
.. versionadded:: 5.3
4197+
4198+
*Type*: string
4199+
4200+
.. include:: /includes/note-audit-in-enterprise.rst
4201+
4202+
|both|
4203+
4204+
Path and file name for logging metadata audit headers for :ref:`audit
4205+
log encryption <security-encryption-at-rest-audit-log>`. A header is
4206+
placed at the top of each audit log file and contains metadata for
4207+
decrypting the audit log. The headers are also stored in the
4208+
:doc:`audit log </core/auditing>`.
4209+
4210+
You can only set :parameter:`auditEncryptionHeaderMetadataFile`
4211+
during startup in the :setting:`configuration file <setParameter>` or
4212+
with the ``--setParameter`` option on the command line. For example,
4213+
the following sets the path and file for
4214+
:parameter:`auditEncryptionHeaderMetadataFile`:
4215+
4216+
.. code-block:: bash
4217+
4218+
mongod --setParameter auditEncryptionHeaderMetadataFile=/auditFiles/auditHeadersMetadataFile.log
4219+
4220+
.. parameter:: auditEncryptKeyWithKMIPGet
4221+
4222+
.. versionadded:: 5.3
4223+
4224+
*Type*: boolean
4225+
4226+
*Default*: false
4227+
4228+
.. include:: /includes/note-audit-in-enterprise.rst
4229+
4230+
|both|
4231+
4232+
Enables :ref:`audit log encryption
4233+
<security-encryption-at-rest-audit-log>` for Key Management
4234+
Interoperability Protocol (KMIP) servers that only support KMIP
4235+
protocol version 1.0 or 1.1.
4236+
4237+
You can only set :parameter:`auditEncryptKeyWithKMIPGet` during
4238+
startup in the :setting:`configuration file <setParameter>` or with
4239+
the ``--setParameter`` option on the command line. For example, the
4240+
following sets :parameter:`auditEncryptKeyWithKMIPGet` to ``true``:
4241+
4242+
.. code-block:: bash
4243+
4244+
mongod --setParameter auditEncryptKeyWithKMIPGet=true
4245+
41944246
Transaction Parameters
41954247
~~~~~~~~~~~~~~~~~~~~~~
41964248

0 commit comments

Comments
 (0)