DOCSP-16015 add getAuditConfig and API

Author: mungitoperrito

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 } )<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>`
+

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

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
+   <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
@@ -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
 ~~~~~~~~~~~~~~~~