mongosh
Options
On this page
Use the following options to control various aspects of your MongoDB Shell connection and behavior.
General Options
--build-info
Returns a JSON-formatted document with information about the
mongosh
build.
--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.
To get output suitable for automated parsing, use
EJSON.stringify()
.mongosh --quiet --host rs0/centos1104 --port 27500 \ --eval "EJSON.stringify(rs.status().members.map( \ m => ({'id':m._id, 'name':m.name, 'stateStr':m.stateStr})));" \ | jq After parsing with
jq
, the output resembles this:[ { "id": 0, "name": "centos1104:27500", "stateStr": "PRIMARY" }, { "id": 1, "name": "centos1104:27502", "stateStr": "SECONDARY" }, { "id": 2, "name": "centos1104:27503", "stateStr": "SECONDARY" } ] NoteEJSON
has built in formatting options which may eliminate the need for a parser likejq
. For example, the following code produces output that is formatted the same as above.mongosh --quiet --host rs0/centos1104 --port 27500 \ --eval "EJSON.stringify( rs.status().members.map( \ ({ _id, name, stateStr }) => ({ _id, name, stateStr })), null, 2);"
--quiet
Skips all messages during startup (such as welcome messages and startup warnings) and goes directly to the prompt.
--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.
Connection Options
--host <hostname>
Specifies the name of the host machine where the
mongod
ormongos
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 theSAN
(or, ifSAN
is not present, theCN
) in the certificate presented by themongod
ormongos
. IfSAN
is present, the MongoDB Shell does not match against theCN
. If the hostname does not match theSAN
(orCN
), 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. TheauthSource
andreplicaSet
options, if included in the connection string, overrides any corresponding DNS-configured options set in the TXT record. Use of themongodb+srv:
connection string implicitly enables TLS / SSL (normally set withtls=true
) for the client connection. The TLS option can be turned off by settingtls=false
in the query string.Examplemongodb+srv://server.example.com/?connectionTimeout=3000ms
--port <port>
Specifies the port where the
mongod
ormongos
instance is listening. If--port
is not specified, the MongoDB Shell attempts to connect to port27017
.
TLS Options
--tls
Enables connection to a
mongod
ormongos
that has TLS / SSL support enabled.To learn more about TLS/SSL and MongoDB, see:
--tlsCertificateKeyFile <filename>
Specifies the
.pem
file that contains both the TLS / SSL certificate and key formongosh
. 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 amongod
ormongos
instance that requires client certificates. That is, the MongoDB Shell presents this certificate to the server.NoteTo learn more about TLS/SSL and MongoDB, see:
--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.
To learn more about TLS/SSL and MongoDB, see:
--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 themongod
/mongos
instance.Specify the file name of the
.pem
file using relative or absolute paths.To learn more about TLS/SSL and MongoDB, see:
--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.To learn more about TLS/SSL and MongoDB, see:
--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.To learn more about TLS/SSL and MongoDB, see:
--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.NoteStarting 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.WarningAlthough 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 expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. If you only need to disable the validation of the hostname in the TLS / SSL certificates, see--tlsAllowInvalidHostnames
.To learn more about TLS/SSL and MongoDB, see:
--tlsCertificateSelector <parameter>=<value>
Available on Windows and macOS as an alternative to
--tlsCertificateKeyFile
.ImportantWindows and Importing Private KeysWhen you import your private key, you must mark it as exportable. The Windows Certificate Import Wizard doesn't check this option by default.
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:PropertyValue typeDescriptionsubject
ASCII stringSubject name or common name on certificatethumbprint
hex stringA sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA-1 digest.
The
thumbprint
is sometimes referred to as afingerprint
.When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates.
--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 bothTLS1_0
andTLS1_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
.
Authentication Options
--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
ormongos
.NoteStarting 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
).
ValueDescriptionRFC 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 usePLAIN
for authenticating in-database users.PLAIN
transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.- MongoDB removes support for the deprecated MongoDB
Challenge-Response (
--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 theCANONICALIZE_HOST_NAME:true|false
key-pair in theauthMechanismProperties
portion of the connection string.If
--sspiHostnameCanonicalization
is set to:forwardAndReverse
, performs a forward DNS lookup and then a reverse lookup. New inmongosh
1.3.0.forward
, the effect is the same as settingauthMechanismProperties=CANONICALIZE_HOST_NAME:true
.none
, the effect is the same as settingauthMechanismProperties=CANONICALIZE_HOST_NAME:false
.
--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.
Session Options
--retryWrites
Enables Retryable Writes. Retryable writes are enabled by default in
mongosh
. Retryable writes are disabled by default in the legacymongo
shell. To disable retryable writes, use--retryWrites=false
.For more information on sessions, see Client Sessions and Causal Consistency Guarantees.
Client-Side Field Level Encryption Options
For information on Client-Side Field Level Encryption Options, refer to the MongoDB Manual.