DOCSP-35286 tlsUseSystemCA Parameter (#5938) (#6032)

* DOCSP-35286 tlsUseSystemCA Parameter

* typo

* JA feedback

Author: ajhuh-mdb

source/includes/extracts-ssl-facts.yaml

@@ -16,9 +16,9 @@ content: |
 
    If ``--tlsCAFile``/``net.tls.CAFile`` (or
    their aliases ``--sslCAFile``/``net.ssl.CAFile``) is not specified
-   and you are not using x.509 authentication, the system-wide CA
-   certificate store will be used when connecting to an TLS/SSL-enabled
-   server.
+   and you are not using x.509 authentication, you must set the 
+   :parameter:`tlsUseSystemCA` parameter to ``true``. This makes MongoDB use 
+   the system-wide CA certificate store when connecting to a TLS-enabled server.
 
    .. include:: /includes/extracts/ssl-facts-x509-ca-file.rst
 

source/includes/extracts-tls-facts.yaml

@@ -13,9 +13,9 @@ ref: tls-facts-ca-file
 content: |
 
    If ``--tlsCAFile`` or ``tls.CAFile`` is not
-   specified and you are not using x.509 authentication, the
-   system-wide CA certificate store will be used when connecting to an
-   TLS-enabled server.
+   specified and you are not using x.509 authentication, you must set the 
+   :parameter:`tlsUseSystemCA` parameter to ``true``. This makes MongoDB use 
+   the system-wide CA certificate store when connecting to a TLS-enabled server.
 
    .. include:: /includes/extracts/tls-facts-x509-ca-file.rst
 

source/includes/fact-ssl-tlsCAFile-tlsUseSystemCA.rst

@@ -0,0 +1,8 @@
+When starting a :binary:`~bin.mongod` instance with 
+:ref:`TLS/SSL enabled <configure-mongod-mongos-for-tls-ssl>`, you must 
+specify a value for the :option:`--tlsCAFile <mongod --tlsCAFile>` flag, the 
+:setting:`tls.CAFile` configuration option, or the :parameter:`tlsUseSystemCA` 
+parameter. 
+
+``--tlsCAFile``, ``tls.CAFile``, and ``tlsUseSystemCA`` are all mutually 
+exclusive.

source/reference/parameters.txt

@@ -889,6 +889,32 @@ Authentication Parameters
       - :parameter:`ocspValidationRefreshPeriodSecs`
       - :parameter:`tlsOCSPStaplingTimeoutSecs`
 
+.. parameter:: tlsUseSystemCA 
+
+   |mongod-only|
+
+   *Type*: boolean
+
+   *Default*: false
+
+   Specifies whether MongoDB loads TLS certificates that are already 
+   available to the operating system's certificate authority. 
+
+   .. important:: 
+
+      .. include:: /includes/fact-ssl-tlsCAFile-tlsUseSystemCA.rst
+
+   You can set ``tlsUseSystemCA`` only during startup in the 
+   :setting:`configuration file <setParameter>` or with the ``--setParameter`` 
+   option on the command line. For example, to set ``tlsUseSystemCA`` to 
+   ``true``: 
+
+   .. code-block:: bash 
+
+      mongod --setParameter tlsUseSystemCA=true
+
+   .. include:: /includes/extracts/ssl-facts-see-more.rst
+
 .. parameter:: tlsWithholdClientCertificate
 
    *Default*: false

source/reference/program/mongod.txt

@@ -1956,8 +1956,6 @@ TLS Options
    .. include:: /includes/extracts/tls-facts-ca-file.rst
 
    .. include:: /includes/extracts/tls-facts-see-more.rst
-   
-
 
 .. option:: --tlsClusterFile <filename>
 
@@ -2114,6 +2112,10 @@ TLS Options
    Specifies the :file:`.pem` file that contains the root certificate
    chain from the Certificate Authority. Specify the file name of the
    :file:`.pem` file using relative or absolute paths.
+
+   .. important:: 
+
+      .. include:: /includes/fact-ssl-tlsCAFile-tlsUseSystemCA.rst
 
    Windows/macOS Only
      If using :option:`--tlsCertificateSelector` and/or

source/tutorial/configure-ssl.txt

@@ -336,6 +336,10 @@ your :binary:`mongod` / :binary:`mongos` instance's
        certificate chain includes the certificate of the root
        Certificate Authority.
 
+.. important:: 
+
+   .. include:: /includes/fact-ssl-tlsCAFile-tlsUseSystemCA.rst
+
 For example, consider the following :ref:`configuration file
 <conf-file>` for a :binary:`~bin.mongod` instance:
 

source/tutorial/upgrade-cluster-to-ssl.txt

@@ -61,7 +61,7 @@ process.
 
             .. code-block:: bash
 
-               mongod --replSet <name> --tlsMode allowTLS --tlsCertificateKeyFile <TLS/SSL certificate and key file> --sslCAFile <path to root CA PEM file> <additional options>
+               mongod --replSet <name> --tlsMode allowTLS --tlsCertificateKeyFile <TLS/SSL certificate and key file> --tlsCAFile <path to root CA PEM file> <additional options>
 
         - id: config
           name: Configuration File Options