URI Options Specification

  • Status: Accepted

  • Minimum Server Version: N/A

Abstract

Historically, URI options have been defined in individual specs, and drivers have defined any additional options independently of one another. Because of the frustration due to there not being a single place where all of the URI options are defined, this spec aims to do just that—namely, provide a canonical list of URI options that each driver defines.

THIS SPEC DOES NOT REQUIRE DRIVERS TO MAKE ANY BREAKING CHANGES.

META

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Specification

Conflicting TLS options

Per the Connection String spec, the behavior of duplicates of most URI options is undefined. However, due to the security implications of certain options, drivers MUST raise an error to the user during parsing if any of the following circumstances occur:

  1. Both tlsInsecure and tlsAllowInvalidCertificates appear in the URI options.
  2. Both tlsInsecure and tlsAllowInvalidHostnames appear in the URI options.
  3. Both tlsInsecure and tlsDisableOCSPEndpointCheck appear in the URI options.
  4. Both tlsInsecure and tlsDisableCertificateRevocationCheck appear in the URI options.
  5. Both tlsAllowInvalidCertificates and tlsDisableOCSPEndpointCheck appear in the URI options.
  6. Both tlsAllowInvalidCertificates and tlsDisableCertificateRevocationCheck appear in the URI options.
  7. Both tlsDisableOCSPEndpointCheck and tlsDisableCertificateRevocationCheck appear in the URI options.
  8. All instances of tls and ssl in the URI options do not have the same value. If all instances of tls and ssl have the same value, an error MUST NOT be raised.

directConnection URI option with multiple seeds or SRV URI

The driver MUST report an error if the directConnection=true URI option is specified with multiple seeds.

The driver MUST report an error if the directConnection=true URI option is specified with an SRV URI, because the URI may resolve to multiple hosts. The driver MUST allow specifying directConnection=false URI option with an SRV URI.

srvServiceName and srvMaxHosts URI options

For URI option validation pertaining to srvServiceName and srvMaxHosts, please see the Initial DNS Seedlist Discovery spec for details.

Load Balancer Mode

For URI option validation in Load Balancer mode (i.e. loadBalanced=true), please see the Load Balancer spec for details.

SOCKS5 options

For URI option validation pertaining to proxyHost, proxyPort, proxyUsername and proxyPassword please see the SOCKS5 support spec for details.

List of specified options

Each driver option below MUST be implemented in each driver unless marked as optional. If an option is marked as optional, a driver MUST meet any conditions specified for leaving it out if it is not included. If a driver already provides the option under a different name, the driver MAY implement the old and new names as aliases. All keys and values MUST be encoded in UTF-8. All integer options are 32-bit unless specified otherwise. Note that all requirements and recommendations described in the Connection String spec pertaining to URI options apply here.

NameAccepted ValuesDefault ValueOptional to implement?Description
appnameany string that meets the criteria listed in the handshake specno appname specifiednoPassed into the server in the client metadata as part of the connection handshake
authMechanismany string; valid values are defined in the auth specNone; default values for authentication exist for constructing authentication credentials per the auth spec, but there is no default for the URI option itself.noThe authentication mechanism method to use for connection to the server
authMechanismPropertiescomma separated key:value pairs, e.g. "opt1:val1,opt2:val2"no properties specifiednoAdditional options provided for authentication (e.g. to enable hostname canonicalization for GSSAPI)
authSourceany stringNone; default values for authentication exist for constructing authentication credentials per the auth spec, but there is no default for the URI option itself.noThe database that connections should authenticate against
compressorscomma separated list of strings, e.g. "snappy,zlib"defined in compression specnoThe list of allowed compression types for wire protocol messages sent or received from the server
connectTimeoutMSnon-negative integer; 0 means "no timeout"10,000 ms (unless a driver already has a different default)noAmount of time to wait for a single TCP socket connection to the server to be established before erroring; note that this applies to SDAM hello and legacy hello operations
directConnection"true" or "false"defined in SDAM specnoWhether to connect to the deployment in Single topology.
heartbeatFrequencyMSinteger greater than or equal to 500defined in SDAM specnothe interval between regular server monitoring checks
journal"true" or "false"no "j" field specifiednoDefault write concern "j" field for the client
loadBalanced"true" or "false"defined in Load Balancer specnoWhether the driver is connecting to a load balancer.
localThresholdMSnon-negative integer; 0 means 0 ms (i.e. the fastest eligible server must be selected)defined in the server selection specnoThe amount of time beyond the fastest round trip time that a given server’s round trip time can take and still be eligible for server selection
maxIdleTimeMSnon-negative integer; 0 means no minimumdefined in the Connection Pooling specrequired for drivers with connection poolsThe amount of time a connection can be idle before it's closed
maxPoolSizenon-negative integer; 0 means no maximumdefined in the Connection Pooling specrequired for drivers with connection poolsThe maximum number of clients or connections able to be created by a pool at a given time. This count includes connections which are currently checked out.
maxConnectingpositive integerdefined in the Connection Pooling specrequired for drivers with connection poolsThe maximum number of Connections a Pool may be establishing concurrently.
maxStalenessSeconds-1 (no max staleness check) or integer >= 90defined in max staleness specnoThe maximum replication lag, in wall clock time, that a secondary can suffer and still be eligible for server selection
minPoolSizenon-negative integerdefined in the Connection Pooling specrequired for drivers with connection poolsThe number of connections the driver should create and maintain in the pool even when no operations are occurring. This count includes connections which are currently checked out.
proxyHostany stringdefined in the SOCKS5 support specnoThe IPv4/IPv6 address or domain name of a SOCKS5 proxy server used for connecting to MongoDB services.
proxyPortnon-negative integerdefined in the SOCKS5 support specnoThe port of the SOCKS5 proxy server specified in proxyHost.
proxyUsernameany stringdefined in the SOCKS5 support specnoThe username for username/password authentication to the SOCKS5 proxy server specified in proxyHost.
proxyPasswordany stringdefined in the SOCKS5 support specnoThe password for username/password authentication to the SOCKS5 proxy server specified in proxyHost.
readConcernLevelany string (to allow for forwards compatibility with the server)no read concern specifiednoDefault read concern for the client
readPreferenceany string; currently supported values are defined in the server selection spec, but must be lowercase camelCase, e.g. "primaryPreferred"defined in server selection specnoDefault read preference for the client (excluding tags)
readPreferenceTagscomma-separated key:value pairs (e.g. "dc:ny,rack:1" and "dc:ny)

can be specified multiple times; each instance of this key is a separate tag set
no tags specifiednoDefault read preference tags for the client; only valid if the read preference mode is not primary

The order of the tag sets in the read preference is the same as the order they are specified in the URI
replicaSetany stringno replica set name providednoThe name of the replica set to connect to
retryReads"true" or "false"defined in retryable reads specnoEnables retryable reads on server 3.6+
retryWrites"true" or "false"defined in retryable writes specnoEnables retryable writes on server 3.6+
serverMonitoringMode"stream", "poll", or "auto"defined in SDAM specrequired for multi-threaded or asynchronous driversConfigures which server monitoring protocol to use.
serverSelectionTimeoutMSpositive integer; a driver may also accept 0 to be used for a special case, provided that it documents the meaningdefined in server selection specnoA timeout in milliseconds to block for server selection before raising an error
serverSelectionTryOnce"true" or "false"defined in server selection specrequired for single-threaded driversScan the topology only once after a server selection failure instead of repeatedly until the server selection times out
socketTimeoutMSnon-negative integer; 0 means no timeoutno timeoutnoNOTE: This option is deprecated in favor of timeoutMS

Amount of time spent attempting to send or receive on a socket before timing out; note that this only applies to application operations, not SDAM.
srvMaxHostsnon-negative integer; 0 means no maximumdefined in the Initial DNS Seedlist Discovery specnoThe maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology.
srvServiceNamea valid SRV service name according to RFC 6335"mongodb"nothe service name to use for SRV lookup in initial DNS seedlist discovery and SRV polling
ssl"true" or "false"same as "tls"noalias of "tls"; required to ensure that Atlas connection strings continue to work
tls"true" or "false"TLS required if "mongodb+srv" scheme; otherwise, drivers may may enable TLS by default if other "tls"-prefixed options are present

Drivers MUST clearly document the conditions under which TLS is enabled implicitly
noWhether or not to require TLS for connections to the server
tlsAllowInvalidCertificates"true" or "false"error on invalid certificatesrequired if the driver’s language/runtime allows bypassing hostname verificationSpecifies whether or not the driver should error when the server’s TLS certificate is invalid
tlsAllowInvalidHostnames"true" or "false"error on invalid certificatesrequired if the driver’s language/runtime allows bypassing hostname verificationSpecifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate
tlsCAFileany stringno certificate authorities specifiedrequired if the driver's language/runtime allows non-global configurationPath to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection
tlsCertificateKeyFileany stringno client certificate specifiedrequired if the driver's language/runtime allows non-global configurationPath to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated
tlsCertificateKeyFilePasswordany stringno password specifiedrequired if the driver's language/runtime allows non-global configurationPassword to decrypt the client private key to be used for TLS connections
tlsDisableCertificateRevocationCheck"true" or "false"false i.e. driver will reach check a certificate's revocation statusYesControls whether or not the driver will check a certificate's revocation status via CRLs or OCSP. See the OCSP Support Spec for additional information.
tlsDisableOCSPEndpointCheck"true" or "false"false i.e. driver will reach out to OCSP endpoints if needed.YesControls whether or not the driver will reach out to OCSP endpoints if needed. See the OCSP Support Spec for additional information.
tlsInsecure"true" or "false"No TLS constraints are relaxednoRelax TLS constraints as much as possible (e.g. allowing invalid certificates or hostname mismatches); drivers must document the exact constraints which are relaxed by this option being true
wnon-negative integer or stringno "w" value specifiednoDefault write concern "w" field for the client
waitQueueTimeoutMSpositive numberdefined in the Connection Pooling specrequired for drivers with connection pools, with exceptions described in the Connection Pooling specNOTE: This option is deprecated in favor of timeoutMS

Amount of time spent attempting to check out a connection from a server's connection pool before timing out
wTimeoutMSnon-negative 64-bit integer; 0 means no timeoutno timeoutnoNOTE: This option is deprecated in favor of timeoutMS

Default write concern "wtimeout" field for the client
zlibCompressionLevelinteger between -1 and 9 (inclusive)-1 (default compression level of the driver)noSpecifies the level of compression when using zlib to compress wire protocol messages; -1 signifies the default level, 0 signifies no compression, 1 signifies the fastest speed, and 9 signifies the best compression

Test Plan

Tests are implemented and described in the tests directory.

Design Rationale

Why allow drivers to provide the canonical names as aliases to existing options?

First and foremost, this spec aims not to introduce any breaking changes to drivers. Forcing a driver to change the name of an option that it provides will break any applications that use the old option. Moreover, it is already possible to provide duplicate options in the URI by specifying the same option more than once; drivers can use the same semantics to resolve the conflicts as they did before, whether it's raising an error, using the first option provided, using the last option provided, or simply telling users that the behavior is not defined.

Technically speaking, drivers already only support TLS, which supersedes SSL. While SSL is commonly used in parlance to refer to TLS connections, the fact remains that SSL is a weaker cryptographic protocol than TLS, and we want to accurately reflect the strict requirements that drivers have in ensuring the security of a TLS connection.

Why use the names "tlsAllowInvalidHostnames" and "tlsAllowInvalidCertificates"?

The "tls" prefix is used for the same reasons described above. The use of the terms "AllowInvalidHostnames" and "AllowInvalidCertificates" is an intentional choice in order to convey the inherent unsafety of these options, which should only be used for testing purposes. Additionally, both the server and the shell use "AllowInvalid" for their equivalent options.

Why provide multiple implementation options for the insecure TLS options (i.e. "tlsInsecure" vs. "tlsAllowInvalidHostnames"/"tlsAllowInvalidCertificates"?

Some TLS libraries (e.g. Go's standard library implementation) do not provide the ability to distinguish between allow invalid certificates and hostnames, meaning they either both are allowed, or neither are. However, when more granular options are available, it's better to expose these to the user to allow them to relax security constraints as little as they need.

Why leave the decision up to drivers to enable TLS implicitly when TLS options are present?

It can be useful to turn on TLS implicitly when options such as "tlsCAFile" are present and "tls" is not present. However, with options such as "tlsAllowInvalidHostnames", some drivers may not have the ability to distinguish between "false" being provided and the option not being specified. To keep the implicit enabling of TLS consistent between such options, we defer the decision to enable TLS based on the presence of "tls"-prefixed options (besides "tls" itself) to drivers.

Reference Implementations

Ruby and Python

Security Implication

Each of the "insecure" TLS options (i.e. "tlsInsecure", "tlsAllowInvalidHostnames", "tlsAllowInvalidCertificates", "tlsDisableOCSPEndpointCheck", and "tlsDisableCertificateRevocationCheck") default to the more secure option when TLS is enabled. In order to be backwards compatible with existing driver behavior, neither TLS nor authentication is enabled by default.

Future Work

This specification is intended to represent the current state of drivers URI options rather than be a static description of the options at the time it was written. Whenever another specification is written or modified in a way that changes the name or the semantics of a URI option or adds a new URI option, this specification MUST be updated to reflect those changes.

Changelog

  • 2024-05-08: Migrated from reStructuredText to Markdown.

  • 2023-08-21: Add serverMonitoringMode option.

  • 2022-10-05: Remove spec front matter and reformat changelog.

  • 2022-01-19: Add the timeoutMS option and deprecate some existing timeout options

  • 2021-12-14: Add SOCKS5 options

  • 2021-11-08: Add maxConnecting option.

  • 2021-10-14: Add srvMaxHosts option. Merge headings discussing URI validation
    for directConnection option.

  • 2021-09-15: Add srvServiceName option

  • 2021-09-13: Fix link to load balancer spec

  • 2021-04-15: Adding in behaviour for load balancer mode.

  • 2021-04-08: Updated to refer to hello and legacy hello

  • 2020-03-03: Add tlsDisableCertificateRevocationCheck option

  • 2020-02-26: Add tlsDisableOCSPEndpointCheck option

  • 2019-09-08: Add retryReads option

  • 2019-04-26: authSource and authMechanism have no default value

  • 2019-02-04: Specified errors for conflicting TLS-related URI options

  • 2019-01-25: Updated to reflect new Connection Monitoring and Pooling Spec