path: root/debian/mongo.1

.TH "MONGO" "1" "March 14, 2013" "2.2.3" "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
..
.\" Man page generated from reStructuredText.
.
.SH DESCRIPTION
.sp
\fI\%mongo\fP is an interactive JavaScript shell interface to
MongoDB, which provides a powerful interface for systems
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. This
document addresses the basic invocation of the \fI\%mongo\fP shell
and an overview of its usage.
.SH SYNOPSIS
.INDENT 0.0
.TP
.B mongo [\-\-shell] [\-\-nodb] [\-\-norc] [\-\-quiet] [\-\-port <port>] [\-\-host <host>] [\-\-eval <JavaScript>] [\-u <username>] [\-\-username <username>] [\-p <password>] [\-\-password <password>] [\-\-help] [\-h] [\-\-version] [\-\-verbose] [\-\-ipv6] [database] [file.js]
.UNINDENT
.SH INTERFACE
.SS Options
.INDENT 0.0
.TP
.B \-\-shell
Enables the shell interface after evaluating a \fIJavaScript\fP file.
If you invoke the \fI\%mongo\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
\fImongo\-shell\-new\-connections\fP.
.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. Unless specified \fI\%mongo\fP connects
to \fBmongod\fP instances on port \fB27017\fP, which is the default
\fBmongod\fP port.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-host <hostname>
specifies the host where the \fBmongod\fP or \fBmongos\fP is running to
connect to as \fB<hostname>\fP. By default \fI\%mongo\fP will attempt
to connect to a MongoDB process running on the localhost.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-eval <javascript>
Evaluates a JavaScript expression specified as an argument to this
option. \fI\%mongo\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 to authenticate to the MongoDB instance.
Use in conjunction with the
\fI\%--password\fP option to supply a password.
If you specify a username and password but the default database
or the specified database do not require authentication,
\fI\%mongo\fP will exit with an exception.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-password <password>, \-p <password>
Specifies a password to authenticate to the MongoDB instance.
Use in conjunction with the
\fI\%--username\fP option to supply a username. If you
specify a \fI\%--username\fP without the
\fI\%--password\fP option, \fI\%mongo\fP will prompt for a
password interactively, if the \fBmongod\fP or
\fBmongos\fP requires authentication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-authenticationDatabase <dbname>
New in version 2.4.
.sp
Specifies the database that holds the user\(aqs (e.g
\fI\%--username\fP) credentials.
.sp
By default, \fI\%mongo\fP assumes that the database name specified
in the \fI\%db address\fP holds the user\(aqs
credentials, unless you specify \fI\%--authenticationDatabase\fP.
.sp
See \fBuserSource\fP,
\fB/reference/privilege\-documents\fP and
\fB/reference/user\-privileges\fP for more information about
delegated authentication in MongoDB.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-authenticationMechanism <name>
New in version 2.4.
.sp
Specifies the authentication mechanism. By default, the
authentication mechanism is \fBMONGODB\-CR\fP, which is the MongoDB
challenge/response authentication mechanism. In the MongoDB Subscriber Edition,
\fI\%mongo\fP also includes support for \fBGSSAPI\fP to handle
Kerberos authentication.
.sp
See \fB/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication\fP
for more information about Kerberos authentication.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-ssl
Enable connection to a \fBmongod\fP or
\fBmongos\fP that has SSL encryption.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-sslPEMKeyFile <filename>
New in version 2.4.
.IP Note
The \fI\%default distribution of MongoDB\fP does \fBnot\fP contain support
for SSL. To use SSL you can either compile MongoDB with SSL
support or use the MongoDB Subscriber Edition. See \fB/administration/ssl\fP for
more information about SSL and MongoDB.
.RE
.sp
Specifies the \fB.pem\fP file that contains both the SSL
certificate and key. Specify the file name of the \fB.pem\fP
file using relative or absolute paths
.sp
Required when using the \fI\%--ssl\fP option if the
\fBmongod\fP or \fBmongos\fP has \fBsslCAFile\fP
enabled \fIwithout\fP \fBsslWeakCertificateValidation\fP.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-sslPEMKeyPassword <value>
New in version 2.4.
.IP Note
The \fI\%default distribution of MongoDB\fP does \fBnot\fP contain support
for SSL. To use SSL you can either compile MongoDB with SSL
support or use the MongoDB Subscriber Edition. See \fB/administration/ssl\fP for
more information about SSL and MongoDB.
.RE
.sp
Specifies the password to decrypt the root certificate chain
specified by \fI\%--sslPEMKeyFile\fP.
.sp
Only required if the certificate\-key file is encrypted.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-sslCAFile <filename>
New in version 2.4.
.IP Note
The \fI\%default distribution of MongoDB\fP does \fBnot\fP contain support
for SSL. To use SSL you can either compile MongoDB with SSL
support or use the MongoDB Subscriber Edition. See \fB/administration/ssl\fP for
more information about SSL and MongoDB.
.RE
.sp
Specifies the \fB.pem\fP file that contains the certificate from
the Certificate Authority. Specify the file name of the \fB.pem\fP
file using relative or absolute paths
.UNINDENT
.INDENT 0.0
.TP
.B \-\-help, \-h
Returns a basic help and usage text.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-version
Returns the version of the shell.
.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 \-\-ipv6
Enables IPv6 support that allows \fI\%mongo\fP to connect
to the MongoDB instance using an IPv6 network. All MongoDB programs
and processes, including \fI\%mongo\fP, disable IPv6
support by default.
.UNINDENT
.INDENT 0.0
.TP
.B <db address>
Specifies the "database address" of the database to connect to. For
example:
.sp
.nf
.ft C
mongo admin
.ft P
.fi
.sp
The above command will connect the \fI\%mongo\fP shell to the
\fIadmin database\fP 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:
.sp
.nf
.ft C
mongo mongodb1.example.net
mongo mongodb1/admin
mongo 10.8.8.10/test
.ft P
.fi
.UNINDENT
.INDENT 0.0
.TP
.B <file.js>
Specifies a JavaScript file to run and then exit.
Must be the last option specified.
Use the
\fI\%--shell\fP option to return to a shell after the file
finishes running.
.UNINDENT
.SS Files
.sp
\fB~/.dbshell\fP
.INDENT 0.0
.INDENT 3.5
\fI\%mongo\fP maintains a history of commands in the \fB.dbshell\fP
file.
.IP Note
\fI\%mongo\fP does not recorded interaction related to
authentication in the history file, including
\fBauthenticate\fP and \fBdb.addUser()\fP.
.RE
.IP Warning
Versions of Windows \fBmongo.exe\fP earlier than 2.2.0 will
save the \fI.dbshell\fP file in the \fBmongo.exe\fP working
directory.
.RE
.UNINDENT
.UNINDENT
.sp
\fB~/.mongorc.js\fP
.INDENT 0.0
.INDENT 3.5
\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\%--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
.UNINDENT
.sp
\fB/tmp/mongo_edit\fI<time_t>\fP.js\fP
.INDENT 0.0
.INDENT 3.5
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.
.UNINDENT
.UNINDENT
.sp
\fB%TEMP%mongo_edit\fI<time_t>\fP.js\fP
.INDENT 0.0
.INDENT 3.5
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
.UNINDENT
.SS 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.
.sp
To connect to a database on a remote host using authentication and a
non\-standard port, use the following form:
.sp
.nf
.ft C
mongo \-\-username <user> \-\-password <pass> \-\-hostname <host> \-\-port 28015
.ft P
.fi
.sp
Alternatively, consider the following short form:
.sp
.nf
.ft C
mongo \-u <user> \-p <pass> \-\-host <host> \-\-port 28015
.ft P
.fi
.sp
Replace \fB<user>\fP, \fB<pass>\fP, and \fB<host>\fP with the appropriate
values for your situation and substitute or omit the \fI\%--port\fP
as needed.
.sp
To execute a JavaScript file without evaluating the \fB~/.mongorc.js\fP
file before starting a shell session, use the following form:
.sp
.nf
.ft C
mongo \-\-shell \-\-norc alternate\-environment.js
.ft P
.fi
.sp
To print return a query as \fIJSON\fP, from the system prompt using
the \fI\%--eval\fP option, use the following form:
.sp
.nf
.ft C
mongo \-\-eval \(aqdb.collection.find().forEach(printjson)\(aq
.ft P
.fi
.sp
Use single quotes (e.g. \fB\(aq\fP) to enclose the JavaScript, as well as
the additional JavaScript required to generate this output.
.SH AUTHOR
MongoDB Documentation Project
.SH COPYRIGHT
2011-2013, 10gen, Inc.
.\" Generated by docutils manpage writer.
.