.\" Man page generated from reStructuredText. . .TH "MONGO" "1" "Jun 23, 2020" "4.4" "mongodb-manual" .SH NAME mongo \- MongoDB Shell . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .SS On this page .INDENT 0.0 .IP \(bu 2 \fI\%Description\fP .IP \(bu 2 \fI\%Syntax\fP .IP \(bu 2 \fI\%Options\fP .IP \(bu 2 \fI\%Files\fP .IP \(bu 2 \fI\%Environment\fP .IP \(bu 2 \fI\%Keyboard Shortcuts\fP .IP \(bu 2 \fI\%Use\fP .UNINDENT .SH DESCRIPTION .sp \fI\%mongo\fP is an interactive JavaScript shell interface to MongoDB, which provides a powerful interface for system administrators as well as a way for developers to test queries and operations directly with the database. \fI\%mongo\fP also provides a fully functional JavaScript environment for use with a MongoDB. .sp The \fI\%mongo\fP shell is included as part of the MongoDB Server installation. MongoDB also provides the \fI\%mongo\fP shell as a standalone package. To download the standalone \fI\%mongo\fP shell package: .INDENT 0.0 .IP 1. 3 Access the Download Center for your Edition of MongoDB: .INDENT 3.0 .IP \(bu 2 \fI\%MongoDB Community Download Center\fP .IP \(bu 2 \fI\%MongoDB Enterprise Download Center\fP .UNINDENT .IP 2. 3 Select your preferred Version and Platform from the dropdowns. .IP 3. 3 Select the Package to download according to your platform: .TS center; |l|l|. _ T{ Platform T} T{ Download Package T} _ T{ \fIWindows\fP T} T{ Select the \fBzip\fP package to download an archive which includes the \fI\%mongo\fP shell. T} _ T{ \fImacOS\fP T} T{ Select the \fBtgz\fP package to download an archive which includes the \fI\%mongo\fP shell. T} _ T{ \fILinux\fP T} T{ Select the \fBshell\fP package to download the \fI\%mongo\fP shell. T} _ .TE .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Starting in MongoDB 4.2 (and 4.0.13), the \fI\%mongo\fP shell displays a warning message when connected to non\-genuine MongoDB instances as these instances may behave differently from the official MongoDB instances; e.g. missing or incomplete features, different feature behaviors, etc. .IP \(bu 2 Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see 4.0\-disable\-tls\&. .UNINDENT .UNINDENT .UNINDENT .SH SYNTAX .INDENT 0.0 .IP \(bu 2 You can run \fI\%mongo\fP shell without any command\-line options use the default settings: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mongo .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 You can run \fI\%mongo\fP shell with a connection string that specifies the host and port and other connection options. For example, the following includes the \fBtls\fP: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mongo "mongodb://mongodb0.example.com:27017/testdb?tls=true" .ft P .fi .UNINDENT .UNINDENT .sp The \fBtls\fP option is available starting in MongoDB 4.2. In earlier version, use the \fBssl\fP option. .sp To connect \fI\%mongo\fP shell to a replica set, you can specify in the connection string the replica set members and name: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mongo "mongodb://mongodb0.example.com.local:27017,mongodb1.example.com.local:27017,mongodb2.example.com.local:27017/?replicaSet=replA" .ft P .fi .UNINDENT .UNINDENT .sp For more information on the connection string options, see /reference/connection\-string\&. .IP \(bu 2 You can run \fI\%mongo\fP shell with various command\-line options. For example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-host mongodb0.example.com:27017 [additional options] mongo \-\-host mongodb0.example.com \-\-port 27017 [additional options] .ft P .fi .UNINDENT .UNINDENT .sp For more information on the options available, see \fI\%Options\fP\&. .UNINDENT .SH OPTIONS .INDENT 0.0 .INDENT 3.5 .IP "Starting in version 4.2" .INDENT 0.0 .IP \(bu 2 MongoDB deprecates the SSL options and insteads adds new corresponding TLS options. .UNINDENT .UNINDENT .UNINDENT .SS Core Options .INDENT 0.0 .TP .B \-\-shell Enables the shell interface. If you invoke the \fBmongo\fP command and specify a JavaScript file as an argument, or use \fI\%\-\-eval\fP to specify JavaScript on the command line, the \fI\%\-\-shell\fP option provides the user with a shell prompt after the file finishes executing. .UNINDENT .INDENT 0.0 .TP .B \-\-nodb Prevents the shell from connecting to any database instances. Later, to connect to a database within the shell, see mongo\-shell\-new\-connections\&. .UNINDENT .INDENT 0.0 .TP .B \-\-norc Prevents the shell from sourcing and evaluating \fB~/.mongorc.js\fP on start up. .UNINDENT .INDENT 0.0 .TP .B \-\-quiet Silences output from the shell during the connection process. .UNINDENT .INDENT 0.0 .TP .B \-\-port Specifies the port where the \fBmongod\fP or \fBmongos\fP instance is listening. If \fI\%\-\-port\fP is not specified, \fBmongo\fP attempts to connect to port \fB27017\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-host Specifies the name of the host machine where the \fBmongod\fP or \fBmongos\fP is running. If this is not specified, \fBmongo\fP attempts to connect to a MongoDB process running on the localhost. .INDENT 7.0 .TP .B To connect to a replica set, Specify the \fBreplica set name\fP and a seed list of set members. Use the following form: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C /<:port>,<:port>,<...> .ft P .fi .UNINDENT .UNINDENT .TP .B For TLS/SSL connections (\fB\-\-ssl\fP), The \fI\%mongo\fP shell verifies that the hostname (specified in \fI\%\-\-host\fP option or the connection string) matches the \fBSAN\fP (or, if \fBSAN\fP is not present, the \fBCN\fP) in the certificate presented by the \fBmongod\fP or \fBmongos\fP\&. If \fBSAN\fP is present, \fI\%mongo\fP does not match against the \fBCN\fP\&. If the hostname does not match the \fBSAN\fP (or \fBCN\fP), the \fI\%mongo\fP shell will fail to connect. .sp Starting in MongoDB 4.2, when performing comparison of SAN, MongoDB supports comparison of DNS names or IP addresses. In previous versions, MongoDB only supports comparisons of DNS names. .TP .B For \fI\%DNS seedlist connections\fP, Specify the connection protocol as \fBmongodb+srv\fP, followed by the DNS SRV hostname record and any options. The \fBauthSource\fP and \fBreplicaSet\fP options, if included in the connection string, will override any corresponding DNS\-configured options set in the TXT record. Use of the \fBmongodb+srv:\fP connection string implicitly enables TLS/SSL (normally set with \fBssl=true\fP) for the client connection. The TLS/SSL option can be turned off by setting \fBssl=false\fP in the query string. .sp Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mongodb+srv://server.example.com/?connectionTimeout=3000ms .ft P .fi .UNINDENT .UNINDENT .sp New in version 3.6. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-eval Evaluates a JavaScript expression that is specified as an argument. \fBmongo\fP does not load its own environment when evaluating code. As a result many options of the shell environment are not available. .UNINDENT .INDENT 0.0 .TP .B \-\-username , \-u Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the \fI\%\-\-password\fP and \fI\%\-\-authenticationDatabase\fP options. .sp If connecting to a \fI\%MongoDB Atlas\fP cluster using the \fBMONGODB\-AWS\fP \fI\%authentication mechanism\fP, specify your AWS access key ID in this field, or in the connection string\&. Alternatively, this value may also be supplied as the environment variable \fBAWS_ACCESS_KEY_ID\fP\&. See \fI\%Connect to a MongoDB Atlas Cluster using AWS IAM Credentials\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-password , \-p Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the \fI\%\-\-username\fP and \fI\%\-\-authenticationDatabase\fP options. To force \fBmongo\fP to prompt for a password, enter the \fI\%\-\-password\fP option as the last option and leave out the argument. .sp If connecting to a \fI\%MongoDB Atlas\fP cluster using the \fBMONGODB\-AWS\fP \fI\%authentication mechanism\fP, specify your AWS secret access key in this field, or in the connection string\&. Alternatively, this value may also be supplied as the environment variable \fBAWS_SECRET_ACCESS_KEY\fP\&. See \fI\%Connect to a MongoDB Atlas Cluster using AWS IAM Credentials\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-awsIamSessionToken If connecting to a \fI\%MongoDB Atlas\fP cluster using the \fBMONGODB\-AWS\fP \fI\%authentication mechanism\fP and using session tokens in addition to your AWS access key ID and secret access key, specify your AWS session token in this field, or in the connection string\&. Alternatively, this value may also be supplied as the environment variable \fBAWS_SESSION_TOKEN\fP\&. See \fI\%Connect to a MongoDB Atlas Cluster using AWS IAM Credentials\fP\&. .sp Only valid when using the \fBMONGODB\-AWS\fP \fI\%authentication mechanism\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-help, \-h Returns information on the options and use of \fBmongo\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-version Returns the \fBmongo\fP release number. .UNINDENT .INDENT 0.0 .TP .B \-\-verbose Increases the verbosity of the output of the shell during the connection process. .UNINDENT .INDENT 0.0 .TP .B \-\-networkMessageCompressors New in version 3.4. .sp Enables network compression for communication between this \fBmongo\fP shell and: .INDENT 7.0 .IP \(bu 2 a \fBmongod\fP instance .IP \(bu 2 a \fBmongos\fP instance. .UNINDENT .sp You can specify the following compressors: .INDENT 7.0 .IP \(bu 2 snappy .IP \(bu 2 zlib (Available starting in MongoDB 3.6) .IP \(bu 2 zstd (Available starting in MongoDB 4.2) .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 7.0 .INDENT 3.5 Messages are compressed when both parties enable network compression. Otherwise, messages between the parties are uncompressed. .UNINDENT .UNINDENT .sp If you specify multiple compressors, then the order in which you list the compressors matter as well as the communication initiator. For example, if a \fI\%mongo\fP shell specifies the following network compressors \fBzlib,snappy\fP and the \fBmongod\fP specifies \fBsnappy,zlib\fP, messages between \fI\%mongo\fP shell and \fBmongod\fP uses \fBzlib\fP\&. .sp If the parties do not share at least one common compressor, messages between the parties are uncompressed. For example, if a \fI\%mongo\fP shell specifies the network compressor \fBzlib\fP and \fBmongod\fP specifies \fBsnappy\fP, messages between \fI\%mongo\fP shell and \fBmongod\fP are not compressed. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 Enables IPv6 support. \fBmongo\fP disables IPv6 by default. .sp To connect to a MongoDB cluster via IPv6, you must specify both \fI\%\-\-ipv6\fP \fIand\fP \fI\%\-\-host \fP when starting the \fBmongo\fP shell. .sp \fBmongod\fP and \fBmongos\fP disable IPv6 support by default. Specifying \fI\%\-\-ipv6\fP when connecting to a \fBmongod/mongos\fP does not enable IPv6 support on the \fBmongod/mongos\fP\&. For documentation on enabling IPv6 support on the \fBmongod/mongos\fP, see \fBnet.ipv6\fP\&. .UNINDENT .INDENT 0.0 .TP .B Specifies the name of the database to connect to. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mongo admin .ft P .fi .UNINDENT .UNINDENT .sp The above command will connect the \fBmongo\fP shell to the admin database of the MongoDB deployment running on the local machine. You may specify a remote database instance, with the resolvable hostname or IP address. Separate the database name from the hostname using a \fB/\fP character. See the following examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C mongo mongodb1.example.net/test mongo mongodb1/admin mongo 10.8.8.10/test .ft P .fi .UNINDENT .UNINDENT .sp This syntax is the \fIonly\fP way to connect to a specific database. .sp To specify alternate hosts and a database, you must use this syntax and cannot use \fI\%\-\-host\fP or \fI\%\-\-port\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-enableJavaScriptJIT New in version 4.0. .sp Enable the JavaScript engine\(aqs JIT compiler. .UNINDENT .INDENT 0.0 .TP .B \-\-disableJavaScriptJIT Changed in version 4.0: The JavaScript engine\(aqs JIT compiler is now disabled by default. .sp Disables the JavaScript engine\(aqs JIT compiler. .UNINDENT .INDENT 0.0 .TP .B \-\-disableJavaScriptProtection New in version 3.4. .sp Allows fields of type javascript and javascriptWithScope (*Deprecated*) to be automatically marshalled to JavaScript functions in the \fI\%mongo\fP shell. .sp With the \fB\-\-disableJavaScriptProtection\fP flag set, it is possible to immediately execute JavaScript functions contained in documents. The following example demonstrates this behavior within the shell: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C > db.test.insert({ _id: 1, jsFunc: function(){ print("hello") } } ) WriteResult({ "nInserted" : 1 }) > var doc = db.test.findOne({ _id: 1 }) > doc { "_id" : 1, "jsFunc" : function (){ print ("hello") } } > typeof doc.jsFunc function > doc.jsFunc() hello .ft P .fi .UNINDENT .UNINDENT .sp The default behavior (when \fI\%mongo\fP starts \fIwithout\fP the \fB\-\-disableJavaScriptProtection\fP flag) is to convert embedded JavaScript functions to the non\-executable MongoDB shell type \fBCode\fP\&. The following example demonstrates the default behavior within the shell: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C > db.test.insert({ _id: 1, jsFunc: function(){ print("hello") } } ) WriteResult({ "nInserted" : 1 }) > var doc = db.test.findOne({ _id: 1 }) > doc { "_id" : 1, "jsFunc" : { "code" : "function (){print(\e"hello\e")}" } } > typeof doc.func object > doc.func instanceof Code true > doc.jsFunc() 2016\-11\-09T12:30:36.808\-08:00 E QUERY [thread1] TypeError: doc.jsFunc is not a function : @(shell):1:1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Specifies a JavaScript file to run and then exit. Generally this should be the last option specified. .INDENT 7.0 .INDENT 3.5 .SS Optional .sp To specify a JavaScript file to execute \fIand\fP allow \fBmongo\fP to prompt you for a password using \fI\%\-\-password\fP, pass the filename as the first parameter with \fI\%\-\-username\fP and \fI\%\-\-password\fP as the last options, as in the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo file.js \-\-username username \-\-password .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Use the \fI\%\-\-shell\fP option to return to a shell after the file finishes running. .UNINDENT .SS Authentication Options .INDENT 0.0 .TP .B \-\-authenticationDatabase Specifies the authentication database where the specified \fI\%\-\-username\fP has been created. See user\-authentication\-database\&. .sp If you do not specify a value for \fI\%\-\-authenticationDatabase\fP, \fBmongo\fP uses the database specified in the connection string. .sp If using the GSSAPI (Kerberos), PLAIN (LDAP SASL), or \fBMONGODB\-AWS\fP \fI\%authentication mechanisms\fP, you must set \fI\%\-\-authenticationDatabase\fP to \fB$external\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-authenticationMechanism \fIDefault\fP: SCRAM\-SHA\-1 .sp Specifies the authentication mechanism the \fBmongo\fP instance uses to authenticate to the \fBmongod\fP or \fBmongos\fP\&. .sp Changed in version 4.4: With MongoDB 4.4, the \fBmongo\fP shell adds support for the new \fBMONGODB\-AWS\fP authentication mechanism when connecting to a \fI\%MongoDB Atlas\fP cluster. .TS center; |l|l|. _ T{ Value T} T{ Description T} _ T{ SCRAM\-SHA\-1 T} T{ \fI\%RFC 5802\fP standard Salted Challenge Response Authentication Mechanism using the SHA\-1 hash function. T} _ T{ SCRAM\-SHA\-256 T} T{ \fI\%RFC 7677\fP standard Salted Challenge Response Authentication Mechanism using the SHA\-256 hash function. .sp Requires featureCompatibilityVersion set to \fB4.0\fP\&. .sp New in version 4.0. T} _ T{ MONGODB\-X509 T} T{ MongoDB TLS/SSL certificate authentication. T} _ T{ \fBMONGODB\-AWS\fP T} T{ External authentication using AWS IAM credentials for use in connecting to a \fI\%MongoDB Atlas\fP cluster. See \fI\%Connect to a MongoDB Atlas Cluster using AWS IAM Credentials\fP\&. .sp New in version 4.4. T} _ T{ GSSAPI (Kerberos) T} T{ External authentication using Kerberos. This mechanism is available only in \fI\%MongoDB Enterprise\fP\&. T} _ T{ PLAIN (LDAP SASL) T} T{ External authentication using LDAP. You can also use \fBPLAIN\fP for authenticating in\-database users. \fBPLAIN\fP transmits passwords in plain text. This mechanism is available only in \fI\%MongoDB Enterprise\fP\&. T} _ .TE .UNINDENT .INDENT 0.0 .TP .B \-\-gssapiHostName Specify the hostname of a service using GSSAPI/Kerberos\&. \fIOnly\fP required if the hostname of a machine does not match the hostname resolved by DNS. .sp This option is available only in MongoDB Enterprise. .UNINDENT .INDENT 0.0 .TP .B \-\-gssapiServiceName Specify the name of the service using GSSAPI/Kerberos\&. Only required if the service does not use the default name of \fBmongodb\fP\&. .sp This option is available only in MongoDB Enterprise. .UNINDENT .SS TLS Options .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see 4.0\-disable\-tls\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .SS See .sp /tutorial/configure\-ssl for full documentation of MongoDB\(aqs support. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-tls New in version 4.2. .sp Enables connection to a \fBmongod\fP or \fBmongos\fP that has TLS/SSL support enabled. .sp Starting in version 3.2.6, if \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP (or their aliases \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP) is not specified, the system\-wide CA certificate store will be used when connecting to an TLS/SSL\-enabled server. In previous versions of MongoDB, the \fI\%mongo\fP shell exited with an error that it could not validate the certificate. .sp To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP must be specified unless using \fB\-\-tlsCertificateSelector\fP or \fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, \fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using \fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsCertificateKeyFile New in version 4.2. .sp Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate and key for the \fI\%mongo\fP shell. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp This option is required when using the \fI\%\-\-tls\fP option to connect to a \fBmongod\fP or \fBmongos\fP instance that requires client certificates\&. That is, the \fI\%mongo\fP shell present this certificate to the server. .sp Changed in version 4.4: \fBmongod\fP / \fBmongos\fP logs a warning on connection if the presented x.509 certificate expires within \fB30\fP days of the \fBmongod/mongos\fP host system time. See 4.4\-rel\-notes\-certificate\-expiration\-warning for more information. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsCertificateKeyFilePassword New in version 4.2. .sp Specifies the password to de\-crypt the certificate\-key file (i.e. \fI\%\-\-tlsCertificateKeyFile\fP). .sp Use the \fI\%\-\-tlsCertificateKeyFilePassword\fP option only if the certificate\-key file is encrypted. In all cases, the \fBmongo\fP will redact the password from all logging and reporting output. .sp If the private key in the PEM file is encrypted and you do not specify the \fI\%\-\-tlsCertificateKeyFilePassword\fP option, the \fBmongo\fP will prompt for a passphrase. See ssl\-certificate\-password\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsCAFile New in version 4.2. .sp Specifies the \fB\&.pem\fP file that contains the root certificate chain from the Certificate Authority. This file is used to validate the certificate presented by the \fBmongod\fP/\fBmongos\fP instance. .sp Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp Starting in version 3.2.6, if \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP (or their aliases \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP) is not specified, the system\-wide CA certificate store will be used when connecting to an TLS/SSL\-enabled server. In previous versions of MongoDB, the \fI\%mongo\fP shell exited with an error that it could not validate the certificate. .sp To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP must be specified unless using \fB\-\-tlsCertificateSelector\fP or \fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, \fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using \fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsCRLFile New in version 4.2: In MongoDB 4.0 and earlier, see \fI\%\-\-sslCRLFile\fP\&. .sp Specifies the \fB\&.pem\fP file that contains the Certificate Revocation List. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Starting in version 4.4, to check for certificate revocation, MongoDB \fBenables\fP the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-tlsAllowInvalidHostnames New in version 4.2. .sp Disables the validation of the hostnames in the certificate presented by the \fBmongod\fP/\fBmongos\fP instance. Allows \fBmongo\fP to connect to MongoDB instances even if the hostname in the server certificates do not match the server\(aqs host. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsAllowInvalidCertificates New in version 4.2. .sp Bypasses the validation checks for the certificates presented by the \fBmongod\fP/\fBmongos\fP instance and allows connections to servers that present invalid certificates. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Starting in MongoDB 4.0, if you specify \fB\-\-sslAllowInvalidCertificates\fP or \fBnet.ssl.allowInvalidCertificates: true\fP (or in MongoDB 4.2, the alias \fB\-\-tlsAllowInvalidateCertificates\fP or \fBnet.tls.allowInvalidCertificates: true\fP) when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is \fIinsufficient\fP for authentication. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Although available, avoid using the \fB\-\-sslAllowInvalidCertificates\fP option if possible. If the use of \fB\-\-sslAllowInvalidCertificates\fP is necessary, only use the option on systems where intrusion is not possible. .sp If the \fI\%mongo\fP shell (and other mongodb\-tools\-support\-ssl) runs with the \fB\-\-sslAllowInvalidCertificates\fP option, the \fI\%mongo\fP shell (and other mongodb\-tools\-support\-ssl) will not attempt to validate the server certificates. This creates a vulnerability to expired \fBmongod\fP and \fBmongos\fP certificates as well as to foreign processes posing as valid \fBmongod\fP or \fBmongos\fP instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see \fB\-\-sslAllowInvalidHostnames\fP\&. .UNINDENT .UNINDENT .sp When using the \fBallowInvalidCertificates\fP setting, MongoDB logs as a warning the use of the invalid certificate. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-tlsFIPSMode New in version 4.2. .sp Directs the \fBmongo\fP to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS compliant library to use the \fI\%\-\-tlsFIPSMode\fP option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 FIPS\-compatible TLS/SSL is available only in \fI\%MongoDB Enterprise\fP\&. See /tutorial/configure\-fips for more information. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-tlsCertificateSelector = New in version 4.2: Available on Windows and macOS as an alternative to \fI\%\-\-tlsCertificateKeyFile\fP\&. .sp The \fI\%\-\-tlsCertificateKeyFile\fP and \fI\%\-\-tlsCertificateSelector\fP options are mutually exclusive. You can only specify one. .sp Specifies a certificate property in order to select a matching certificate from the operating system\(aqs certificate store. .sp \fI\%\-\-tlsCertificateSelector\fP accepts an argument of the format \fB=\fP where the property can be one of the following: .TS center; |l|l|l|. _ T{ Property T} T{ Value type T} T{ Description T} _ T{ \fBsubject\fP T} T{ ASCII string T} T{ Subject name or common name on certificate T} _ T{ \fBthumbprint\fP T} T{ hex string T} T{ A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA\-1 digest. .sp The \fBthumbprint\fP is sometimes referred to as a \fBfingerprint\fP\&. T} _ .TE .sp When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates. .sp Changed in version 4.4: \fBmongod\fP / \fBmongos\fP logs a warning on connection if the presented x.509 certificate expires within \fB30\fP days of the \fBmongod/mongos\fP host system time. See 4.4\-rel\-notes\-certificate\-expiration\-warning for more information. .UNINDENT .INDENT 0.0 .TP .B \-\-tlsDisabledProtocols New in version 4.2. .sp Disables the specified TLS protocols. The option recognizes the following protocols: \fBTLS1_0\fP, \fBTLS1_1\fP, \fBTLS1_2\fP, and starting in version 4.0.4 (and 3.6.9 and 3.4.24), \fBTLS1_3\fP\&. .INDENT 7.0 .IP \(bu 2 On macOS, you cannot disable \fBTLS1_1\fP and leave both \fBTLS1_0\fP and \fBTLS1_2\fP enabled. You must also disable at least one of the other two; for example, \fBTLS1_0,TLS1_1\fP\&. .IP \(bu 2 To list multiple protocols, specify as a comma separated list of protocols. For example \fBTLS1_0,TLS1_1\fP\&. .IP \(bu 2 The specified disabled protocols overrides any default disabled protocols. .UNINDENT .sp 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 \fBnone\fP to \fI\%\-\-tlsDisabledProtocols\fP\&. See 4.0\-disable\-tls\&. .UNINDENT .SS SSL Options (Deprecated) .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Starting in version 4.2, the SSL options are deprecated. Use the TLS counterparts instead. The SSL protocol is deprecated and MongoDB supports TLS 1.0 and later. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Starting in version 4.0, \fI\%mongo\fP disables support for TLS 1.0 encryption on systems where TLS 1.1+ is available. For more details, see 4.0\-disable\-tls\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-ssl Deprecated since version 4.2: Use \fI\%\-\-tls\fP instead. .sp Enables connection to a \fBmongod\fP or \fBmongos\fP that has TLS/SSL support enabled. .sp Starting in version 3.2.6, if \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP (or their aliases \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP) is not specified, the system\-wide CA certificate store will be used when connecting to an TLS/SSL\-enabled server. In previous versions of MongoDB, the \fI\%mongo\fP shell exited with an error that it could not validate the certificate. .sp To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP must be specified unless using \fB\-\-tlsCertificateSelector\fP or \fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, \fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using \fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslPEMKeyFile Deprecated since version 4.2: Use \fI\%\-\-tlsCertificateKeyFile\fP instead. .sp Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate and key. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp This option is required when using the \fB\-\-ssl\fP option to connect to a \fBmongod\fP or \fBmongos\fP that has \fBCAFile\fP enabled \fIwithout\fP \fBallowConnectionsWithoutCertificates\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslPEMKeyPassword Deprecated since version 4.2: Use \fI\%\-\-tlsCertificateKeyFilePassword\fP instead. .sp Specifies the password to de\-crypt the certificate\-key file (i.e. \fB\-\-sslPEMKeyFile\fP). Use the \fI\%\-\-sslPEMKeyPassword\fP option only if the certificate\-key file is encrypted. In all cases, the \fBmongo\fP will redact the password from all logging and reporting output. .sp If the private key in the PEM file is encrypted and you do not specify the \fI\%\-\-sslPEMKeyPassword\fP option, the \fBmongo\fP will prompt for a passphrase. See ssl\-certificate\-password\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslCAFile Deprecated since version 4.2: Use \fI\%\-\-tlsCAFile\fP instead. .sp Specifies the \fB\&.pem\fP file that contains the root certificate chain from the Certificate Authority. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp Starting in version 3.2.6, if \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP (or their aliases \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP) is not specified, the system\-wide CA certificate store will be used when connecting to an TLS/SSL\-enabled server. In previous versions of MongoDB, the \fI\%mongo\fP shell exited with an error that it could not validate the certificate. .sp To use x.509 authentication, \fB\-\-tlsCAFile\fP or \fBnet.tls.CAFile\fP must be specified unless using \fB\-\-tlsCertificateSelector\fP or \fB\-\-net.tls.certificateSelector\fP\&. Or if using the \fBssl\fP aliases, \fB\-\-sslCAFile\fP or \fBnet.ssl.CAFile\fP must be specified unless using \fB\-\-sslCertificateSelector\fP or \fBnet.ssl.certificateSelector\fP\&. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslCertificateSelector = Deprecated since version 4.2: Use \fI\%\-\-tlsCertificateSelector\fP instead. .sp New in version 4.0: Available on Windows and macOS as an alternative to \fI\%\-\-tlsCertificateKeyFile\fP\&. .sp \fI\%\-\-tlsCertificateKeyFile\fP and \fI\%\-\-sslCertificateSelector\fP options are mutually exclusive. You can only specify one. .sp Specifies a certificate property in order to select a matching certificate from the operating system\(aqs certificate store. .sp \fI\%\-\-sslCertificateSelector\fP accepts an argument of the format \fB=\fP where the property can be one of the following: .TS center; |l|l|l|. _ T{ Property T} T{ Value type T} T{ Description T} _ T{ \fBsubject\fP T} T{ ASCII string T} T{ Subject name or common name on certificate T} _ T{ \fBthumbprint\fP T} T{ hex string T} T{ A sequence of bytes, expressed as hexadecimal, used to identify a public key by its SHA\-1 digest. .sp The \fBthumbprint\fP is sometimes referred to as a \fBfingerprint\fP\&. T} _ .TE .sp When using the system SSL certificate store, OCSP (Online Certificate Status Protocol) is used to validate the revocation status of certificates. .UNINDENT .INDENT 0.0 .TP .B \-\-sslCRLFile Deprecated since version 4.2: Use \fI\%\-\-tlsCRLFile\fP instead. .sp Specifies the \fB\&.pem\fP file that contains the Certificate Revocation List. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Starting in version 4.4, to check for certificate revocation, MongoDB \fBenables\fP the use of OCSP (Online Certificate Status Protocol) by default as an alternative to specifying a CRL file or using the system SSL certificate store. .UNINDENT .UNINDENT .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslFIPSMode Deprecated since version 4.2: Use \fI\%\-\-tlsFIPSMode\fP instead. .sp Directs the \fBmongo\fP to use the FIPS mode of the TLS/SSL library. Your system must have a FIPS compliant library to use the \fI\%\-\-sslFIPSMode\fP option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 FIPS\-compatible TLS/SSL is available only in \fI\%MongoDB Enterprise\fP\&. See /tutorial/configure\-fips for more information. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-sslAllowInvalidCertificates Deprecated since version 4.2: Use \fI\%\-\-tlsAllowInvalidCertificates\fP instead. .sp Bypasses the validation checks for server certificates and allows the use of invalid certificates to connect. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Starting in MongoDB 4.0, if you specify \fB\-\-sslAllowInvalidCertificates\fP or \fBnet.ssl.allowInvalidCertificates: true\fP (or in MongoDB 4.2, the alias \fB\-\-tlsAllowInvalidateCertificates\fP or \fBnet.tls.allowInvalidCertificates: true\fP) when using x.509 authentication, an invalid certificate is only sufficient to establish a TLS/SSL connection but is \fIinsufficient\fP for authentication. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Although available, avoid using the \fB\-\-sslAllowInvalidCertificates\fP option if possible. If the use of \fB\-\-sslAllowInvalidCertificates\fP is necessary, only use the option on systems where intrusion is not possible. .sp If the \fI\%mongo\fP shell (and other mongodb\-tools\-support\-ssl) runs with the \fB\-\-sslAllowInvalidCertificates\fP option, the \fI\%mongo\fP shell (and other mongodb\-tools\-support\-ssl) will not attempt to validate the server certificates. This creates a vulnerability to expired \fBmongod\fP and \fBmongos\fP certificates as well as to foreign processes posing as valid \fBmongod\fP or \fBmongos\fP instances. If you only need to disable the validation of the hostname in the TLS/SSL certificates, see \fB\-\-sslAllowInvalidHostnames\fP\&. .UNINDENT .UNINDENT .sp When using the \fBallowInvalidCertificates\fP setting, MongoDB logs as a warning the use of the invalid certificate. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslAllowInvalidHostnames Deprecated since version 4.2: Use \fI\%\-\-tlsAllowInvalidHostnames\fP instead. .sp Disables the validation of the hostnames in TLS/SSL certificates. Allows \fBmongo\fP to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname. .sp For more information about TLS/SSL and MongoDB, see /tutorial/configure\-ssl and /tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP .B \-\-sslDisabledProtocols Deprecated since version 4.2: Use \fI\%\-\-tlsDisabledProtocols\fP instead. .sp Disables the specified TLS protocols. The option recognizes the following protocols: \fBTLS1_0\fP, \fBTLS1_1\fP, \fBTLS1_2\fP, and starting in version 4.0.4 (and 3.6.9), \fBTLS1_3\fP\&. .INDENT 7.0 .IP \(bu 2 On macOS, you cannot disable \fBTLS1_1\fP and leave both \fBTLS1_0\fP and \fBTLS1_2\fP enabled. You must also disable at least one of the other two; for example, \fBTLS1_0,TLS1_1\fP\&. .IP \(bu 2 To list multiple protocols, specify as a comma separated list of protocols. For example \fBTLS1_0,TLS1_1\fP\&. .IP \(bu 2 The specified disabled protocols overrides any default disabled protocols. .UNINDENT .sp 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 \fBnone\fP to \fI\%\-\-sslDisabledProtocols\fP\&. See 4.0\-disable\-tls\&. .sp New in version 3.6.5. .UNINDENT .SS Sessions .INDENT 0.0 .TP .B \-\-retryWrites New in version 3.6. .sp Enables retryable writes as the default for sessions in the \fI\%mongo\fP shell. .sp For more information on sessions, see sessions\&. .UNINDENT .SS Client\-Side Field Level Encryption Options .INDENT 0.0 .TP .B \-\-awsAccessKeyId An AWS \fI\%Access Key\fP associated to an IAM user with \fBList\fP and \fBRead\fP permissions for the AWS Key Management Service (KMS). The \fBmongo\fP shell uses the specified \fI\%\-\-awsAccessKeyId\fP to access the KMS. .sp \fI\%\-\-awsAccessKeyId\fP is required for enabling /core/security\-client\-side\-encryption for the \fBmongo\fP shell session. \fI\%\-\-awsAccessKeyId\fP requires \fIall\fP of the following command line options: .INDENT 7.0 .IP \(bu 2 \fI\%\-\-awsSecretAccessKey\fP .IP \(bu 2 \fI\%\-\-keyVaultNamespace\fP .UNINDENT .sp If \fI\%\-\-awsAccessKeyId\fP is omitted, use the \fBMongo()\fP constructor within the shell session to enable client\-side field level encryption. .sp To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to \fI\%\-\-awsAccessKeyId\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-awsSecretAccessKey An AWS \fI\%Secret Key\fP associated to the specified \fI\%\-\-awsAccessKeyId\fP\&. .sp \fI\%\-\-awsSecretAccessKey\fP is required for enabling /core/security\-client\-side\-encryption for the \fBmongo\fP shell session. \fI\%\-\-awsSecretAccessKey\fP requires \fIall\fP of the following command line options: .INDENT 7.0 .IP \(bu 2 \fI\%\-\-awsAccessKeyId\fP .IP \(bu 2 \fI\%\-\-keyVaultNamespace\fP .UNINDENT .sp If \fI\%\-\-awsSecretAccessKey\fP and its supporting options are omitted, use \fBMongo()\fP within the shell session to enable client\-side field level encryption. .sp To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to \fI\%\-\-awsSecretAccessKey\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-awsSessionToken An AWS \fI\%Session Token\fP associated to the specified \fI\%\-\-awsAccessKeyId\fP\&. .sp \fI\%\-\-awsSessionToken\fP is required for enabling /core/security\-client\-side\-encryption for the \fBmongo\fP shell session. \fI\%\-\-awsSessionToken\fP requires \fIall\fP of the following command line options: .INDENT 7.0 .IP \(bu 2 \fI\%\-\-awsAccessKeyId\fP .IP \(bu 2 \fI\%\-\-awsSecretAccessKey\fP .IP \(bu 2 \fI\%\-\-keyVaultNamespace\fP .UNINDENT .sp If \fI\%\-\-awsSessionToken\fP and its supporting options are omitted, use \fBMongo()\fP within the shell session to enable client\-side field level encryption. .sp To mitigate the risk of leaking access keys into logs, consider specifying an environmental variable to \fI\%\-\-awsSessionToken\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-keyVaultNamespace The full namespace (\fB.\fP) of the collection used as a key vault for /core/security\-client\-side\-encryption\&. \fI\%\-\-keyVaultNamespace\fP is required for enabling client\-side field level encryption. for the \fBmongo\fP shell session. \fBmongo\fP creates the specified namespace if it does not exist. .sp \fI\%\-\-keyVaultNamespace\fP requires \fIall\fP of the following command line options: .INDENT 7.0 .IP \(bu 2 \fI\%\-\-awsAccessKeyId\fP .IP \(bu 2 \fI\%\-\-awsSecretAccessKey\fP .UNINDENT .sp If \fI\%\-\-keyVaultNamespace\fP and its supporting options are omitted, use the \fBMongo()\fP constructor within the shell session to enable client\-side field level encryption. .UNINDENT .SH FILES .INDENT 0.0 .TP .B \fB~/.dbshell\fP \fI\%mongo\fP maintains a history of commands in the \fB\&.dbshell\fP file. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fI\%mongo\fP does not record interaction related to authentication in the history file, including \fBauthenticate\fP and \fBdb.createUser()\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fB~/.mongorc.js\fP \fI\%mongo\fP will read the \fB\&.mongorc.js\fP file from the home directory of the user invoking \fI\%mongo\fP\&. In the file, users can define variables, customize the \fI\%mongo\fP shell prompt, or update information that they would like updated every time they launch a shell. If you use the shell to evaluate a JavaScript file or expression either on the command line with \fI\%mongo \-\-eval\fP or by specifying \fI\%a .js file to mongo\fP, \fI\%mongo\fP will read the \fB\&.mongorc.js\fP file \fIafter\fP the JavaScript has finished processing. .sp Specify the \fI\%\-\-norc\fP option to disable reading \fB\&.mongorc.js\fP\&. .UNINDENT .INDENT 0.0 .TP .B \fB/etc/mongorc.js\fP Global \fBmongorc.js\fP file which the \fI\%mongo\fP shell evaluates upon start\-up. If a user also has a \fB\&.mongorc.js\fP file located in the \fI\%HOME\fP directory, the \fI\%mongo\fP shell evaluates the global \fB/etc/mongorc.js\fP file \fIbefore\fP evaluating the user\(aqs \fB\&.mongorc.js\fP file. .sp \fB/etc/mongorc.js\fP must have read permission for the user running the shell. The \fI\%\-\-norc\fP option for \fI\%mongo\fP suppresses only the user\(aqs \fB\&.mongorc.js\fP file. .sp On Windows, the global \fBmongorc.js \fP exists in the \fB%ProgramData%\eMongoDB\fP directory. .TP .B \fB/tmp/mongo_edit\fP\fI\fP\fB\&.js\fP Created by \fI\%mongo\fP when editing a file. If the file exists, \fI\%mongo\fP will append an integer from \fB1\fP to \fB10\fP to the time value to attempt to create a unique file. .TP .B \fB%TEMP%mongo_edit\fP\fI\fP\fB\&.js\fP Created by \fBmongo.exe\fP on Windows when editing a file. If the file exists, \fI\%mongo\fP will append an integer from \fB1\fP to \fB10\fP to the time value to attempt to create a unique file. .UNINDENT .SH ENVIRONMENT .INDENT 0.0 .TP .B EDITOR Specifies the path to an editor to use with the \fBedit\fP shell command. A JavaScript variable \fBEDITOR\fP will override the value of \fI\%EDITOR\fP\&. .UNINDENT .INDENT 0.0 .TP .B HOME Specifies the path to the home directory where \fI\%mongo\fP will read the \fB\&.mongorc.js\fP file and write the \fB\&.dbshell\fP file. .UNINDENT .INDENT 0.0 .TP .B HOMEDRIVE On Windows systems, \fI\%HOMEDRIVE\fP specifies the path the directory where \fI\%mongo\fP will read the \fB\&.mongorc.js\fP file and write the \fB\&.dbshell\fP file. .UNINDENT .INDENT 0.0 .TP .B HOMEPATH Specifies the Windows path to the home directory where \fI\%mongo\fP will read the \fB\&.mongorc.js\fP file and write the \fB\&.dbshell\fP file. .UNINDENT .SH KEYBOARD SHORTCUTS .sp The \fI\%mongo\fP shell supports the following keyboard shortcuts: [1] .TS center; |l|l|. _ T{ \fBKeybinding\fP T} T{ \fBFunction\fP T} _ T{ Up arrow T} T{ Retrieve previous command from history T} _ T{ Down\-arrow T} T{ Retrieve next command from history T} _ T{ Home T} T{ Go to beginning of the line T} _ T{ End T} T{ Go to end of the line T} _ T{ Tab T} T{ Autocomplete method/command T} _ T{ Left\-arrow T} T{ Go backward one character T} _ T{ Right\-arrow T} T{ Go forward one character T} _ T{ Ctrl\-left\-arrow T} T{ Go backward one word T} _ T{ Ctrl\-right\-arrow T} T{ Go forward one word T} _ T{ Meta\-left\-arrow T} T{ Go backward one word T} _ T{ Meta\-right\-arrow T} T{ Go forward one word T} _ T{ Ctrl\-A T} T{ Go to the beginning of the line T} _ T{ Ctrl\-B T} T{ Go backward one character T} _ T{ Ctrl\-C T} T{ Exit the \fI\%mongo\fP shell T} _ T{ Ctrl\-D T} T{ Delete a char (or exit the \fI\%mongo\fP shell) T} _ T{ Ctrl\-E T} T{ Go to the end of the line T} _ T{ Ctrl\-F T} T{ Go forward one character T} _ T{ Ctrl\-G T} T{ Abort T} _ T{ Ctrl\-J T} T{ Accept/evaluate the line T} _ T{ Ctrl\-K T} T{ Kill/erase the line T} _ T{ Ctrl\-L or type \fBcls\fP T} T{ Clear the screen T} _ T{ Ctrl\-M T} T{ Accept/evaluate the line T} _ T{ Ctrl\-N T} T{ Retrieve next command from history T} _ T{ Ctrl\-P T} T{ Retrieve previous command from history T} _ T{ Ctrl\-R T} T{ Reverse\-search command history T} _ T{ Ctrl\-S T} T{ Forward\-search command history T} _ T{ Ctrl\-T T} T{ Transpose characters T} _ T{ Ctrl\-U T} T{ Perform Unix line\-discard T} _ T{ Ctrl\-W T} T{ Perform Unix word\-rubout T} _ T{ Ctrl\-Y T} T{ Yank T} _ T{ Ctrl\-Z T} T{ Suspend (job control works in linux) T} _ T{ Ctrl\-H T} T{ Backward\-delete a character T} _ T{ Ctrl\-I T} T{ Complete, same as Tab T} _ T{ Meta\-B T} T{ Go backward one word T} _ T{ Meta\-C T} T{ Capitalize word T} _ T{ Meta\-D T} T{ Kill word T} _ T{ Meta\-F T} T{ Go forward one word T} _ T{ Meta\-L T} T{ Change word to lowercase T} _ T{ Meta\-U T} T{ Change word to uppercase T} _ T{ Meta\-Y T} T{ Yank\-pop T} _ T{ Meta\-Backspace T} T{ Backward\-kill word T} _ T{ Meta\-< T} T{ Retrieve the first command in command history T} _ T{ Meta\-> T} T{ Retrieve the last command in command history T} _ .TE .IP [1] 5 MongoDB accommodates multiple keybinding. Since 2.0, \fI\%mongo\fP includes support for basic emacs keybindings. .SH USE .sp Typically users invoke the shell with the \fI\%mongo\fP command at the system prompt. Consider the following examples for other scenarios. .SS Connect to a \fBmongod\fP Instance with Access Control .sp To connect to a database on a remote host using authentication and a non\-standard port, use the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-username \-\-password \-\-host \-\-port 28015 .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, consider the following short form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-u \-p \-\-host \-\-port 28015 .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB\fP and \fB\fP with the appropriate values for your situation and substitute or omit the \fI\%\-\-port\fP as needed. .sp If you do not specify the password to the \fI\%\-\-password\fP or \fI\%\-p\fP command\-line option, the \fI\%mongo\fP shell prompts for the password. .SS Connect to a Replica Set Using the DNS Seedlist Connection Format .sp New in version 3.6. .sp To connect to a replica set described using the connections\-dns\-seedlist, use the \fI\%\-\-host\fP option to specify the connection string to the \fI\%mongo\fP shell. In the following example, the DNS configuration resembles: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Record TTL Class Priority Weight Port Target _mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27317 mongodb1.example.com. _mongodb._tcp.server.example.com. 86400 IN SRV 0 5 27017 mongodb2.example.com. .ft P .fi .UNINDENT .UNINDENT .sp The TXT record for the DNS entry includes the \fBreplicaSet\fP and \fBauthSource\fP options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Record TTL Class Text server.example.com. 86400 IN TXT "replicaSet=rs0&authSource=admin" .ft P .fi .UNINDENT .UNINDENT .sp The following command then connects the \fI\%mongo\fP shell to the replica set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-host "mongodb+srv://server.example.com/?username=allison" .ft P .fi .UNINDENT .UNINDENT .sp The \fI\%mongo\fP shell will automatically prompt you to provide the password for the user specified in the \fBusername\fP option. .SS Connect to a MongoDB Atlas Cluster using AWS IAM Credentials .sp New in version 4.4. .sp To connect to a \fI\%MongoDB Atlas\fP cluster which has been configured to support authentication via \fI\%AWS IAM credentials\fP, provide a connection string to the \fI\%mongo\fP shell similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \(aqmongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB\-AWS\(aq .ft P .fi .UNINDENT .UNINDENT .sp Connecting to Atlas using AWS IAM credentials in this manner uses the \fBMONGODB\-AWS\fP \fBauthentication mechanism\fP and the \fB$external\fP \fBauthSource\fP, as shown in this example. .sp If using an \fI\%AWS session token\fP as well, provide it with the \fBAWS_SESSION_TOKEN\fP \fBauthMechanismProperties\fP value in your connection string, as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \(aqmongodb+srv://:@cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB\-AWS&authMechanismProperties=AWS_SESSION_TOKEN:\(aq .ft P .fi .UNINDENT .UNINDENT .sp If the AWS access key ID, secret access key, or session token include the \(aqat\(aq sign \fB@\fP, colon \fB:\fP, slash \fB/\fP, or the percent sign \fB%\fP characters, those characters must be converted using \fI\%percent encoding\fP\&. .sp Alternatively, the AWS access key ID, and secret access key, and optionally session token can each be provided outside of the connection string using the \fI\%\-\-username\fP, \fI\%\-\-password\fP, and \fI\%\-\-awsIamSessionToken\fP options instead, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \(aqmongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB\-AWS\(aq \-\-username \-\-password \-\-awsIamSessionToken .ft P .fi .UNINDENT .UNINDENT .sp When provided as command line parameters, these three options do not require percent encoding. .sp You may also set these credentials on your platform using standard \fI\%AWS IAM environment variables\fP\&. The \fI\%mongo\fP shell checks for the following environment variables when you use the \fBMONGODB\-AWS\fP \fBauthentication mechanism\fP: .INDENT 0.0 .IP \(bu 2 \fBAWS_ACCESS_KEY_ID\fP .IP \(bu 2 \fBAWS_SECRET_ACCESS_KEY\fP .IP \(bu 2 \fBAWS_SESSION_TOKEN\fP .UNINDENT .sp If set, these credentials do not need to be specified in the connection string or via the explicit options to the \fI\%mongo\fP shell (i.e. \fI\%\-\-username\fP and \fI\%\-\-password\fP). .sp The following example sets these environment variables in the \fBbash\fP shell: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C export AWS_ACCESS_KEY_ID=\(aq\(aq export AWS_SECRET_ACCESS_KEY=\(aq\(aq export AWS_SESSION_TOKEN=\(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp Syntax for setting environment variables in other shells will be different. Consult the documentation for your platform for more information. .sp You can verify that these environment variables have been set with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C env | grep AWS .ft P .fi .UNINDENT .UNINDENT .sp Once set, the following example connects to a MongoDB Atlas cluster using these environment variables: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \(aqmongodb+srv://cluster0.example.com/testdb?authSource=$external&authMechanism=MONGODB\-AWS\(aq .ft P .fi .UNINDENT .UNINDENT .SS Execute JavaScript Against the \fI\%mongo\fP Shell .sp To execute a JavaScript file without evaluating the \fB~/.mongorc.js\fP file before starting a shell session, use the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-shell \-\-norc alternate\-environment.js .ft P .fi .UNINDENT .UNINDENT .sp To execute a JavaScript file with authentication, with password prompted rather than provided on the command\-line, use the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo script\-file.js \-u \-p .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBisInteractive()\fP .UNINDENT .UNINDENT .SS Use \fI\%\-\-eval\fP to Execute JavaScript Code .sp You may use the \fI\%\-\-eval\fP option to execute JavaScript directly from the command line. .sp For example, the following operation evaluates a JavaScript string which queries a collection and prints the results as JSON. .sp On Linux and macOS, you will need to use single quotes (e.g. \fB\(aq\fP) to enclose the JavaScript, using the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-eval \(aqdb.collection.find().forEach(printjson)\(aq .ft P .fi .UNINDENT .UNINDENT .sp On Windows, you will need to use double quotes (e.g. \fB"\fP) to enclose the JavaScript, using the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo \-\-eval "db.collection.find().forEach(printjson)" .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 /reference/mongo\-shell .IP \(bu 2 /reference/method .IP \(bu 2 /mongo .IP \(bu 2 \fBisInteractive()\fP .UNINDENT .UNINDENT .UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT 2008-2020 .\" Generated by docutils manpage writer. .