Skip to content

DOCSP-16015 add getAuditConfig and API #5629

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
Jul 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
118 changes: 118 additions & 0 deletions source/reference/command/getAuditConfig.txt
Original file line number Diff line number Diff line change
@@ -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 } )<db.adminCommand()>` method
to run :dbcommand:`getAuditConfig` against the ``admin`` database.

.. code-block:: javascript

db.adminCommand( { getAuditConfig: 1 } )

Behavior
--------

:doc:`Auditing </core/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 <auditConfigPollingFrequencySecs>` 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 </sharding>`
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</tutorial/configure-audit-filters>`

19 changes: 13 additions & 6 deletions source/reference/command/nav-administration.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -156,8 +162,8 @@ Administration Commands


.. toctree::
:titlesonly:
:hidden:
:titlesonly:
:hidden:

/reference/command/cloneCollectionAsCapped
/reference/command/collMod
Expand All @@ -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
Expand Down
57 changes: 32 additions & 25 deletions source/reference/configuration-options.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
<audit-action-details-results>` the :doc:`audit system
</core/auditing>` records. The option takes a string representation
of a query document of the form:

.. code-block:: javascript

{ <field1>: <expression1>, ... }

The ``<field>`` can be :doc:`any field in the audit message
</reference/audit-message>`, including fields returned in the
:ref:`param <audit-action-details-results>` document. The
``<expression>`` is a :ref:`query condition expression
<query-selectors>`.

.. 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
Expand Down Expand Up @@ -4353,43 +4379,24 @@ LDAP Parameters

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


.. setting:: auditLog.path

*Type*: string

The output file for :doc:`auditing </core/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
<audit-action-details-results>` the :doc:`audit system
</core/auditing>` records. The option takes a string representation
of a query document of the form:

.. code-block:: javascript

{ <field1>: <expression1>, ... }

The ``<field>`` can be :doc:`any field in the audit message
</reference/audit-message>`, including fields returned in the
:ref:`param <audit-action-details-results>` document. The
``<expression>`` is a :ref:`query condition expression
<query-selectors>`.

.. 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
~~~~~~~~~~~~~~~~
Expand Down
Loading