mirror of
https://github.com/mongodb/mongo.git
synced 2024-12-01 09:32:32 +01:00
1726 lines
42 KiB
Groff
1726 lines
42 KiB
Groff
.\" Man page generated from reStructuredText.
|
|
.
|
|
.TH "MONGO" "1" "Aug 16, 2019" "4.2" "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.
|
|
The \fI\%mongo\fP shell is part of the \fI\%MongoDB distributions\fP\&.
|
|
.sp
|
|
\fBNOTE:\fP
|
|
.INDENT 0.0
|
|
.INDENT 3.5
|
|
.INDENT 0.0
|
|
.IP \(bu 2
|
|
Starting in MongoDB 4.2, 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 <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 <hostname>
|
|
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
|
|
<replSetName>/<hostname1><:port>,<hostname2><: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 <javascript>
|
|
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 <username>, \-u <username>
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-password <password>, \-p <password>
|
|
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.
|
|
.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 <string>
|
|
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 <mongod/mongos IPv6 address>\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 <db name>
|
|
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 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\-0800 E QUERY [thread1] TypeError: doc.jsFunc is
|
|
not a function :
|
|
@(shell):1:1
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B <file.js>
|
|
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 <dbname>
|
|
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.
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-authenticationMechanism <name>
|
|
\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.0: MongoDB removes support for the deprecated MongoDB
|
|
Challenge\-Response (\fBMONGODB\-CR\fP) authentication mechanism.
|
|
.sp
|
|
MongoDB adds support for SCRAM mechanism using the SHA\-256 hash
|
|
function (\fBSCRAM\-SHA\-256\fP).
|
|
|
|
.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{
|
|
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
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
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
|
|
New in version 2.6.
|
|
|
|
.sp
|
|
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 <filename>
|
|
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
|
|
For more information about TLS/SSL and MongoDB, see
|
|
/tutorial/configure\-ssl and
|
|
/tutorial/configure\-ssl\-clients .
|
|
.UNINDENT
|
|
.INDENT 0.0
|
|
.TP
|
|
.B \-\-tlsCertificateKeyFilePassword <value>
|
|
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 <filename>
|
|
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 <filename>
|
|
New in version 4.2.
|
|
|
|
.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 .
|
|
.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
|
|
# We created a separate blurb for tls in the ssl\-clients page.
|
|
.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 <parameter>=<value>
|
|
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<property>=<value>\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 \-\-tlsDisabledProtocols <string>
|
|
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), \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 <filename>
|
|
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 <value>
|
|
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 <filename>
|
|
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 <parameter>=<value>
|
|
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<property>=<value>\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 <filename>
|
|
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
|
|
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
|
|
# We created a separate blurb for tls in the ssl\-clients page.
|
|
.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 <string>
|
|
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
|
|
.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 </etc/mongorc.js>\fP exists
|
|
in the \fB%ProgramData%\eMongoDB\fP directory.
|
|
.TP
|
|
.B \fB/tmp/mongo_edit\fP\fI<time_t>\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<time_t>\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 <user> \-\-password \-\-host <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 <user> \-p \-\-host <host> \-\-port 28015
|
|
.ft P
|
|
.fi
|
|
.UNINDENT
|
|
.UNINDENT
|
|
.sp
|
|
Replace \fB<user>\fP and \fB<host>\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 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 <user> \-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 Print Query Results as JSON
|
|
.sp
|
|
To print return a query as JSON, from the system prompt using
|
|
the \fI\%\-\-eval\fP option, use 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
|
|
Use single quotes (e.g. \fB\(aq\fP) to enclose the JavaScript, as well as
|
|
the additional JavaScript required to generate this output.
|
|
.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-2019
|
|
.\" Generated by docutils manpage writer.
|
|
.
|