SERVER-5307 New man pages generated from docs by samk@10gen.com

1 files changed, 666 insertions, 61 deletions

diff --git a/debian/mongo.1 b/debian/mongo.1
index 04f35a5afe7..7ff976330a5 100644
--- a/debian/mongo.1
+++ b/debian/mongo.1
@@ -1,76 +1,681 @@
-.TH MONGO "1" "June 2009" "10gen" "Mongo Database"
-.SH "NAME"
-mongo \- the Mongo command\-line tool
-.SH "SYNOPSIS"
-\fBmongo [\fIOPTIONS\fR] [\fIDB_ADDRESS\fR] [\fIFILE+\fR]\fR
-.SH "DESCRIPTION"
-.PP
-\fBmongo\fR
-is a JavaScript shell (with GNU
-readline
-capabilities).  It supports interactive and non\-interactive use.  When used interactively, JavaScript can be used to query the database or perform any other function normally available with SpiderMonkey.  Database output is displayed in JSON format.
-.PP
-If JavaScript files are specified on the command line, the shell will run non\-interactively, running each one in sequence and then exiting.
-.SH "EXAMPLES"
-.TP
-.B mongo
-start the shell, connecting to the server at localhost:27017 and using the test database
-.TP
-.B mongo foo
-start the shell using the foo database at localhost:27017
-.TP
-.B mongo 192.169.0.5/foo
-start the shell using the foo database at 192.169.0.5:27017
-.TP
-.B mongo 192.169.0.5:9999/foo
-start the shell using the foo database at 192.169.0.5:9999
-.TP
-.B mongo script1.js script2.js script3.js
-run three scripts and exit
-.SH "OPTIONS"
+.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
-run the shell after executing files
+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 \-\-help
-show usage information
+.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 \-\-host HOST
-server to connect to (default HOST=localhost)
+.B \-\-norc
+Prevents the shell from sourcing and evaluating
+\fB~/.mongorc.js\fP on start up.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-\-port PORT
-port to connect to (default PORT=27017)
+.B \-\-quiet
+Silences output from the shell during the connection process.
+.UNINDENT
+.INDENT 0.0
 .TP
-.B \-\-nodb 
-do not connect to mongod
+.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 \-\-eval SCRIPT
-evaluate JavaScript
+.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 \-\-shell
-run the shell after executing files
+.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 \-\-quiet
-be less chatty
+.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
-show version information
+Returns the version of the shell.
+.UNINDENT
+.INDENT 0.0
 .TP
 .B \-\-verbose
-increase verbosity
+Increases the verbosity of the output of the shell during the
+connection process.
+.UNINDENT
+.INDENT 0.0
 .TP
 .B \-\-ipv6
-enable IPv6 support (disabled by default)
-.TP
-.B \-u|\-\-username USERNAME
-specify user to log in as
-.TP
-.B \-p|\-\-password PASSWORD
-specify password of user
-.SH "COPYRIGHT"
-.PP
-Copyright 2007\-2011 10gen
-.SH "SEE ALSO"
-For more information, please refer to the mongo page in the MongoDB manual, available at http://dochub.mongodb.org/core/mongomanpage
-.SH "AUTHOR"
-Kristina Chodorow
+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.
+.