Docs Menu

mongosh Options

On this page

  • General Options
  • Connection Options
  • TLS Options
  • Authentication Options
  • Session Options
  • Client-Side Field Level Encryption Options

Use the following options to control various aspects of your MongoDB Shell connection and behavior.

--shell

Enables the shell interface. If you invoke the mongosh command and specify a JavaScript file as an argument, or use --eval to specify JavaScript on the command line, the --shell option provides the user with a shell prompt after the file finishes executing.

--eval <javascript>

Evaluates a JavaScript expression that is specified as an argument. mongosh does not load its own environment when evaluating code. As a result many options of the shell environment are not available.

The result of evaluating a JavaScript argument is printed to your command line.

--help, -h

Returns information on the options and use of the MongoDB Shell.

--nodb

Prevents the shell from connecting to any database instances.

--norc

Prevents the shell from sourcing and evaluating ~/.mongoshrc.js on startup.

--quiet

Skips all messages during startup (such as welcome messages and startup warnings) and goes directly to the prompt.

--verbose

Increases the verbosity of the shell output during the connection process and when running commands.

--version

Returns the MongoDB Shell release number.

--host <hostname>

Specifies the name of the host machine where the mongod or mongos is running. If this is not specified, the MongoDB Shell attempts to connect to a MongoDB process running on the localhost.

To connect to a replica set,

Specify the replica set name and a seed list of set members. Use the following form:

<replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
For TLS/SSL connections (--tls),
The MongoDB Shell shell verifies that the hostname (specified in the --host option or the connection string) matches the SAN (or, if SAN is not present, the CN) in the certificate presented by the mongod or mongos. If SAN is present, the MongoDB Shell does not match against the CN. If the hostname does not match the SAN (or CN), the MongoDB Shell shell fails to connect.
For DNS seedlist connections,

Specify the connection protocol as mongodb+srv, followed by the DNS SRV hostname record and any options. The authSource and replicaSet options, if included in the connection string, overrides any corresponding DNS-configured options set in the TXT record. Use of the mongodb+srv: connection string implicitly enables TLS SSL (normally set with tls=true) for the client connection. The TLS option can be turned off by setting tls=false in the query string.

Example
mongodb+srv://server.example.com/?connectionTimeout=3000ms
--port <port>

Specifies the port where the mongod or mongos instance is listening. If --port is not specified, the MongoDB Shell attempts to connect to port 27017.

--tls

Enables connection to a mongod or mongos that has TLS SSL support enabled.

To learn more about TLS SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients.

--tlsCertificateKeyFile <filename>

Specifies the .pem file that contains both the TLS SSL certificate and key for mongosh. Specify the file name of the .pem file using relative or absolute paths.

This option is required when using the --tls option to connect to a mongod or mongos instance that requires client certificates. That is, the MongoDB Shell presents this certificate to the server.

Note

Starting in version 4.4, mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time.

To learn more about TLS SSL and MongoDB, see Configure mongod and mongos for TLS/SSL and TLS/SSL Configuration for Clients.

--tlsCertificateKeyFilePassword <value>

Specifies the password to de-crypt the certificate-key file (i.e. --tlsCertificateKeyFile).

Use the --tlsCertificateKeyFilePassword option only if the certificate-key file is encrypted. In all cases, the MongoDB Shell redacts the password from all logging and reporting output.

If the private key in the PEM file is encrypted and you do not specify the --tlsCertificateKeyFilePassword option; the MongoDB Shell prompts for a passphrase.

See TLS/SSL Certificate Passphrase.

--tlsCAFile <filename>

Specifies the .pem file that contains the root certificate chain from the Certificate Authority. This file is used to validate the certificate presented by the mongod/mongos instance.

Specify the file name of the .pem file using relative or absolute paths.

--tlsCRLFile <filename>

Specifies the .pem file that contains the Certificate Revocation List. Specify the file name of the .pem file using relative or absolute paths.

--tlsAllowInvalidHostnames

Disables the validation of the hostnames in the certificate presented by the mongod/mongos instance. Allows the MongoDB Shell to connect to MongoDB instances even if the hostname in the server certificates do not match the server's host.

--tlsAllowInvalidCertificates

New in version 4.2.

Bypasses the validation checks for the certificates presented by the mongod/mongos instance and allows connections to servers that present invalid certificates.

Note

Starting in MongoDB 4.0, if you specify --tlsAllowInvalidCertificates when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS SSL connection but is insufficient for authentication.

Warning

Although available, avoid using the --tlsAllowInvalidCertificates option if possible. If the use of --tlsAllowInvalidCertificates is necessary, only use the option on systems where intrusion is not possible.

If the MongoDB Shell shell (and other MongoDB Tools) runs with the --tlsAllowInvalidCertificates option, the shell (and other MongoDB Tools) do not attempt to validate the server certificates. This creates a vulnerability to expired mongod and mongos certificates as well as to foreign processes posing as valid mongod or mongos instances. If you only need to disable the validation of the hostname in the TLS SSL certificates, see --tlsAllowInvalidHostnames.

--tlsCertificateSelector <parameter>=<value>

Available on Windows and macOS as an alternative to --tlsCertificateKeyFile.

Important
Windows and Importing Private Keys

When you import your private key, you must mark it as exportable. The Windows Certificate Import Wizard doesn't check this option by default.

Microsoft Certificate Import Wizard where the key marked as exportable

The --tlsCertificateKeyFile and --tlsCertificateSelector options are mutually exclusive. You can only specify one.

Specifies a certificate property in order to select a matching certificate from the operating system's certificate store.

--tlsCertificateSelector accepts an argument of the format <property>=<value> where the property can be one of the following:

Property
Value type
Description
subject
ASCII string
Subject name or common name on certificate
thumbprint
hex string

A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.

The thumbprint is sometimes referred to as a fingerprint.

When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.

Note

Starting in version 4.4, mongod / mongos logs a warning on connection if the presented x.509 certificate expires within 30 days of the mongod/mongos host system time.

--tlsDisabledProtocols <string>

Disables the specified TLS protocols. The option recognizes the following protocols:

  • TLS1_0
  • TLS1_1
  • TLS1_2
  • (Starting in version 4.0.4, 3.6.9, 3.4.24) TLS1_3
  • On macOS, you cannot disable TLS1_1 and leave both TLS1_0 and TLS1_2 enabled. You must also disable at least one of the other two; for example, TLS1_0,TLS1_1.
  • To list multiple protocols, specify as a comma separated list of protocols. For example TLS1_0,TLS1_1.
  • The specified disabled protocols overrides any default disabled protocols.

Starting in version 4.0, MongoDB disables the use of TLS 1.0 if TLS 1.1+ is available on the system. To enable the disabled TLS 1.0, specify none to --tlsDisabledProtocols.

--authenticationDatabase <dbname>

Specifies the authentication database where the specified --username has been created. See Authentication Database.

If you do not specify a value for --authenticationDatabase, the MongoDB Shell uses the database specified in the connection string.

--authenticationMechanism <name>

Default: SCRAM-SHA-1

Specifies the authentication mechanism the MongoDB Shell uses to authenticate to the mongod or mongos.

Note

Starting in version 4.0:

  • MongoDB removes support for the deprecated MongoDB Challenge-Response (MONGODB-CR) authentication mechanism.
  • MongoDB adds support for SCRAM mechanism using the SHA-256 hash function (SCRAM-SHA-256).
Value
Description
RFC 5802 standard Salted Challenge Response Authentication Mechanism using the SHA-1 hash function.

RFC 7677 standard Salted Challenge Response Authentication Mechanism using the SHA-256 hash function.

Requires featureCompatibilityVersion set to 4.0.

MongoDB TLS SSL certificate authentication.
GSSAPI (Kerberos)
External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.
PLAIN (LDAP SASL)
External authentication using LDAP. You can also use PLAIN for authenticating in-database users. PLAIN transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.
--gssapiServiceName

Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of mongodb.

This option is available only in MongoDB Enterprise.

--sspiHostnameCanonicalization <string>

Specifies whether or not to use Hostname Canonicalization.

--sspiHostnameCanonicalization has the same effect as setting the CANONICALIZE_HOST_NAME:true|false key-pair in the authMechanismProperties portion of the connection string.

If --sspiHostnameCanonicalization is set to:

  • forward, the effect is the same as setting authMechanismProperties=CANONICALIZE_HOST_NAME:true.
  • none, the effect is the same as setting authMechanismProperties=CANONICALIZE_HOST_NAME:false.

--sspiHostnameCanonicalization cannot be set to forwardAndReverse.

--password <password>, -p <password>

Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --username and --authenticationDatabase options.

To force the MongoDB Shell to prompt for a password, enter the --password option as the last option and leave out the argument.

--username <username>, -u <username>

Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the --password and --authenticationDatabase options.

--retryWrites

Enables retryable writes as the default for sessions in the MongoDB Shell.

For more information on sessions, see Client Sessions and Causal Consistency Guarantees.

For information on Client-Side Field Level Encryption Options, refer to the MongoDB Manual.

Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.