SERVER-11045 Update man pages from the MongoDB Manual

1 files changed, 237 insertions, 86 deletions

diff --git a/debian/mongodump.1 b/debian/mongodump.1
index 8809181c81c..e7f797de680 100644
--- a/debian/mongodump.1
+++ b/debian/mongodump.1
@@ -1,4 +1,6 @@
-.TH "MONGODUMP" "1" "March 14, 2013" "2.2.3" "mongodb-manual"
+.\" Man page generated from reStructuredText.
+.
+.TH "MONGODUMP" "1" "October 03, 2013" "2.4" "mongodb-manual"
 .SH NAME
 mongodump \- MongoDB
 .
@@ -28,24 +30,55 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.\" Man page generated from reStructuredText.
-.
+.INDENT 0.0
+.IP \(bu 2
+\fI\%Synopsis\fP
+.IP \(bu 2
+\fI\%Options\fP
+.IP \(bu 2
+\fI\%Behavior\fP
+.IP \(bu 2
+\fI\%Required User Privileges\fP
+.IP \(bu 2
+\fI\%Usage\fP
+.UNINDENT
 .SH SYNOPSIS
 .sp
-\fI\%mongodump\fP is a utility for creating a binary export of the
+\fBmongodump\fP is a utility for creating a binary export of the
 contents of a database. Consider using this utility as part an
-effective \fBbackup strategy\fP. Use in
-conjunction with \fBmongorestore\fP to provide restore
-functionality.
-.IP Note
-The format of data created by \fI\%mongodump\fP tool from the
+effective \fBbackup strategy\fP\&. Use
+\fBmongodump\fP in conjunction with \fBmongorestore\fP to
+restore databases.
+.sp
+\fBmongodump\fP can read data from either \fBmongod\fP or \fBmongos\fP
+instances, in addition to reading directly from MongoDB data files
+without an active \fBmongod\fP\&.
+.sp
+\fBIMPORTANT:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBmongodump\fP does \fInot\fP create output for the
+\fBlocal\fP database.
+.UNINDENT
+.UNINDENT
+.sp
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+The format of data created by \fBmongodump\fP tool from the
 2.2 distribution or later is different and incompatible with
-earlier versions of \fBmongod\fP.
-.RE
-.IP "See also"
+earlier versions of \fBmongod\fP\&.
+.UNINDENT
+.UNINDENT
 .sp
-"\fBmongorestore\fP" and "\fB/administration/backups\fP".
-.RE
+\fBSEE ALSO:\fP
+.INDENT 0.0
+.INDENT 3.5
+\fBmongorestore\fP,
+http://docs.mongodb.org/manual/tutorial/backup\-sharded\-cluster\-with\-database\-dumps
+and http://docs.mongodb.org/manual/core/backups\&.
+.UNINDENT
+.UNINDENT
 .SH OPTIONS
 .INDENT 0.0
 .TP
@@ -53,6 +86,10 @@ earlier versions of \fBmongod\fP.
 .UNINDENT
 .INDENT 0.0
 .TP
+.B mongodump
+.UNINDENT
+.INDENT 0.0
+.TP
 .B \-\-help
 Returns a basic help and usage text.
 .UNINDENT
@@ -61,35 +98,39 @@ Returns a basic help and usage text.
 .B \-\-verbose, \-v
 Increases the amount of internal reporting returned on the command
 line. Increase the verbosity with the \fB\-v\fP form by including the
-option multiple times, (e.g. \fB\-vvvvv\fP.)
+option multiple times, (e.g. \fB\-vvvvv\fP\&.)
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-version
-Returns the version of the \fI\%mongodump\fP utility and exits.
+Returns the version of the \fBmongodump\fP utility and exits.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-host <hostname><:port>
 Specifies a resolvable hostname for the \fBmongod\fP that you wish to
-use to create the database dump. By default \fI\%mongodump\fP will
+use to create the database dump. By default \fBmongodump\fP will
 attempt to connect to a MongoDB process ruining on the localhost
-port number \fB27017\fP.
+port number \fB27017\fP\&.
 .sp
 Optionally, specify a port number to connect a MongoDB instance
-running on a port other than \fB27017\fP.
+running on a port other than \fB27017\fP\&.
 .sp
-To connect to a replica set, use the \fI\%--host\fP
+To connect to a replica set, use the \fI\-\-host\fP
 argument with a setname, followed by a slash and a comma\-separated
-list of host names and port numbers. The \fI\%mongodump\fP
+list of host names and port numbers. The \fBmongodump\fP
 utility will, given the seed of at least one connected set member,
 connect to the primary member of that set. This option would resemble:
+.INDENT 7.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 mongodump \-\-host repl0/mongo0.example.net,mongo0.example.net:27018,mongo1.example.net,mongo2.example.net
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
 You can always connect directly to a single MongoDB instance by
 specifying the host and port number directly.
@@ -99,32 +140,38 @@ specifying the host and port number directly.
 .B \-\-port <port>
 Specifies the port number, if the MongoDB instance is not running
 on the standard port. (i.e. \fB27017\fP) You may also specify a port
-number using the \fI\%--host\fP option.
+number using the \fI\-\-host\fP option.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-ipv6
-Enables IPv6 support that allows \fI\%mongodump\fP to connect to
+Enables IPv6 support that allows \fBmongodump\fP to connect to
 the MongoDB instance using an IPv6 network. All MongoDB programs
-and processes, including \fI\%mongodump\fP, disable IPv6 support
+and processes, including \fBmongodump\fP, disable IPv6 support
 by default.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-ssl
 New in version 2.4: MongoDB added support for SSL connections to \fBmongod\fP
-instances in mongodump.
-.IP Note
+instances in mongodump\&.
+
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
 SSL support in mongodump is not compiled into the default
-distribution of MongoDB. See \fB/administration/ssl\fP for more
-information on SSL and MongoDB.
+distribution of MongoDB. See
+http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information on SSL
+and MongoDB.
 .sp
 Additionally, mongodump does not support connections to
 \fBmongod\fP instances that require client certificate
 validation.
-.RE
+.UNINDENT
+.UNINDENT
 .sp
-Allows \fI\%mongodump\fP to connect to \fBmongod\fP
+Allows \fBmongodump\fP to connect to \fBmongod\fP
 instance over an SSL connection.
 .UNINDENT
 .INDENT 0.0
@@ -132,59 +179,63 @@ instance over an SSL connection.
 .B \-\-username <username>, \-u <username>
 Specifies a username to authenticate to the MongoDB instance, if
 your database requires authentication. Use in conjunction with the
-\fI\%--password\fP option to supply a
+\fI\-\-password\fP option to supply a
 password.
 .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
+in conjunction with the \fI\-\-username\fP
 option to supply a username.
 .sp
-If you specify a \fI\%--username\fP
-without the \fI\%--password\fP option, \fI\%mongodump\fP will
-prompt for a password interactively.
+If you specify a \fI\-\-username\fP and do
+not pass an argument to \fI\%--password\fP, \fBmongodump\fP
+will prompt for a password interactively. If you do not specify a
+password on the command line, \fI\%--password\fP must be the last
+argument specified.
 .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.
+\fI\-\-username\fP) credentials.
 .sp
-By default, \fI\%mongodump\fP assumes that the database specified to the
+By default, \fBmongodump\fP assumes that the database specified to the
 \fI\%--db\fP argument holds the user\(aqs credentials, unless you
-specify \fI\%--authenticationDatabase\fP.
+specify \fI\%--authenticationDatabase\fP\&.
 .sp
 See \fBuserSource\fP,
-\fB/reference/privilege\-documents\fP and
-\fB/reference/user\-privileges\fP for more information about
+http://docs.mongodb.org/manual/reference/privilege\-documents and
+http://docs.mongodb.org/manual/reference/user\-privileges 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\%mongodump\fP also includes support for \fBGSSAPI\fP to handle
+challenge/response authentication mechanism. In MongoDB Enterprise,
+\fBmongodump\fP also includes support for \fBGSSAPI\fP to handle
 Kerberos authentication.
 .sp
-See \fB/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication\fP
+See http://docs.mongodb.org/manual/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication
 for more information about Kerberos authentication.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-dbpath <path>
 Specifies the directory of the MongoDB data files. If used, the
-\fI\%--dbpath\fP option enables \fI\%mongodump\fP to attach
+\fI\%--dbpath\fP option enables \fBmongodump\fP to attach
 directly to local data files and copy the data without the
-\fBmongod\fP. To run with \fI\%--dbpath\fP,
-\fI\%mongodump\fP needs to restrict access to the data
+\fBmongod\fP\&. To run with \fI\%--dbpath\fP,
+\fBmongodump\fP needs to restrict access to the data
 directory: as a result, no \fBmongod\fP can access the same
 path while the process runs.
 .UNINDENT
@@ -192,15 +243,15 @@ path while the process runs.
 .TP
 .B \-\-directoryperdb
 Use the \fI\%--directoryperdb\fP in conjunction with the
-corresponding option to \fBmongod\fP. This option allows
-\fI\%mongodump\fP to read data files organized with each
+corresponding option to \fBmongod\fP\&. This option allows
+\fBmongodump\fP to read data files organized with each
 database located in a distinct directory. This option is only
 relevant when specifying the \fI\%--dbpath\fP option.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-journal
-Allows \fI\%mongodump\fP operations to use the durability
+Allows \fBmongodump\fP operations to use the durability
 \fIjournal\fP to ensure that the export is in a
 consistent state. This option is only relevant when specifying the
 \fI\%--dbpath\fP option.
@@ -209,8 +260,8 @@ consistent state. This option is only relevant when specifying the
 .TP
 .B \-\-db <db>, \-d <db>
 Use the \fI\%--db\fP option to specify a database for
-\fI\%mongodump\fP to backup. If you do not specify a DB,
-\fI\%mongodump\fP copies all databases in this instance into the
+\fBmongodump\fP to backup. If you do not specify a DB,
+\fBmongodump\fP copies all databases in this instance into the
 dump files. Use this option to backup or copy a smaller subset of
 your data.
 .UNINDENT
@@ -218,7 +269,7 @@ your data.
 .TP
 .B \-\-collection <collection>, \-c <collection>
 Use the \fI\%--collection\fP option to specify a collection for
-\fI\%mongodump\fP to backup. If you do not specify a collection,
+\fBmongodump\fP to backup. If you do not specify a collection,
 this option copies all collections in the specified database or
 instance to the dump files. Use this option to backup or copy a
 smaller subset of your data.
@@ -226,40 +277,51 @@ smaller subset of your data.
 .INDENT 0.0
 .TP
 .B \-\-out <path>, \-o <path>
-Specifies a path where \fI\%mongodump\fP and store the output
-the database dump. To output the database dump to standard output,
-specify a \fB\-\fP rather than a path.
+Specifies a directory where \fBmongodump\fP saves the output of
+the database dump. By default, \fBmongodump\fP saves output
+files in a directory named \fBdump\fP in the current working directory.
+.sp
+To send the database dump to standard output, specify "\fB\-\fP"
+instead of a path. Write to standard output if you want process the
+output before saving it, such as to use \fBgzip\fP to compress the
+dump. When writing standard output, \fBmongodump\fP does not
+write the metadata that writes in a \fB<dbname>.metadata.json\fP file
+when writing to files directly.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-query <json>, \-q <json>
 Provides a query to limit (optionally) the documents included in
-the output of \fI\%mongodump\fP.
+the output of \fBmongodump\fP\&.
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-oplog
-Use this option to ensure that \fI\%mongodump\fP creates a dump
+Use this option to ensure that \fBmongodump\fP creates a dump
 of the database that includes an \fIoplog\fP, to create a
 point\-in\-time snapshot of the state of a \fBmongod\fP instance. To
 restore to a specific point\-in\-time backup, use the output created
-with this option in conjunction with \fImongorestore \-\-oplogReplay\fP.
+with this option in conjunction with \fImongorestore \-\-oplogReplay\fP\&.
 .sp
 Without \fI\%--oplog\fP, if there are write operations during the
 dump operation, the dump will not reflect a single moment in
 time. Changes made to the database during the update process can
 affect the output of the backup.
 .sp
-\fI\%--oplog\fP has no effect when running \fI\%mongodump\fP
+\fI\%--oplog\fP has no effect when running \fBmongodump\fP
 against a \fBmongos\fP instance to dump the entire contents of
 a sharded cluster. However, you can use \fI\%--oplog\fP to dump
 individual shards.
-.IP Note
-\fI\%--oplog\fP only works against nodes that maintain a
-\fIoplog\fP. This includes all members of a replica set, as
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+\fI\%--oplog\fP only works against nodes that maintain an
+\fIoplog\fP\&. This includes all members of a replica set, as
 well as \fImaster\fP nodes in master/slave replication
 deployments.
-.RE
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .INDENT 0.0
 .TP
@@ -268,12 +330,21 @@ Use this option to run a repair option in addition to dumping the
 database. The repair option attempts to repair a database that may
 be in an inconsistent state as a result of an improper shutdown or
 \fBmongod\fP crash.
+.sp
+\fBNOTE:\fP
+.INDENT 7.0
+.INDENT 3.5
+The \fI\%--repair\fP option uses aggressive
+data\-recovery algorithms that may produce a large amount of
+duplication.
+.UNINDENT
+.UNINDENT
 .UNINDENT
 .INDENT 0.0
 .TP
 .B \-\-forceTableScan
-Forces \fI\%mongodump\fP to scan the data store directly:
-typically, \fI\%mongodump\fP saves entries as they appear in the
+Forces \fBmongodump\fP to scan the data store directly:
+typically, \fBmongodump\fP saves entries as they appear in the
 index of the \fB_id\fP field. Use \fI\%--forceTableScan\fP to skip
 the index and scan the data directly. Typically there are two cases
 where this behavior is preferable to the default:
@@ -285,71 +356,151 @@ in the \fB_id\fP index.
 Your database uses a custom \fB_id\fP field.
 .UNINDENT
 .sp
-When you run with \fI\%--forceTableScan\fP, \fI\%mongodump\fP
-does not use \fB$snapshot\fP. As a result, the dump produced
-by \fI\%mongodump\fP can reflect the state of the database at
+When you run with \fI\%--forceTableScan\fP, \fBmongodump\fP
+does not use \fB$snapshot\fP\&. As a result, the dump produced
+by \fBmongodump\fP can reflect the state of the database at
 many different points in time.
-.IP Warning
+.sp
+\fBIMPORTANT:\fP
+.INDENT 7.0
+.INDENT 3.5
 Use \fI\%--forceTableScan\fP with extreme caution
 and consideration.
-.RE
-.IP Warning
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.SH BEHAVIOR
+.sp
+When running \fBmongodump\fP against a \fBmongos\fP instance
+where the \fIsharded cluster\fP consists of \fIreplica sets\fP, the \fIread preference\fP of the operation will prefer reads
+from \fIsecondary\fP members of the set.
+.sp
+\fBWARNING:\fP
+.INDENT 0.0
+.INDENT 3.5
 Changed in version 2.2: When used in combination with \fBfsync\fP or
 \fBdb.fsyncLock()\fP, \fBmongod\fP may block some
-reads, including those from \fI\%mongodump\fP, when
+reads, including those from \fBmongodump\fP, when
 queued write operation waits behind the \fBfsync\fP
 lock.
-.RE
+
 .UNINDENT
-.SH BEHAVIOR
+.UNINDENT
+.SH REQUIRED USER PRIVILEGES
 .sp
-When running \fI\%mongodump\fP against a \fBmongos\fP instance
-where the \fIsharded cluster\fP consists of \fIreplica sets\fP, the \fIread preference\fP of the operation will prefer reads
-from \fIsecondary\fP members of the set.
+\fBNOTE:\fP
+.INDENT 0.0
+.INDENT 3.5
+User privileges changed in MongoDB 2.4.
+.UNINDENT
+.UNINDENT
+.sp
+The user must have appropriate privileges to read data from database
+holding collections in order to use \fBmongodump\fP\&. Consider the
+following \fBrequired privileges\fP for
+the following \fBmongodump\fP operations:
+.TS
+center;
+|l|l|.
+_
+T{
+Task
+T}	T{
+Required Privileges
+T}
+_
+T{
+All collections in a database except \fBsystem.users\fP\&.
+T}	T{
+\fBread\fP\&. [1]
+T}
+_
+T{
+All collections in a database, including \fBsystem.users\fP\&.
+T}	T{
+\fBread\fP [1] and \fBuserAdmin\fP\&.
+T}
+_
+T{
+All databases. [3]
+T}	T{
+\fBreadAnyDatabase\fP, \fBuserAdminAnyDatabase\fP,
+and \fBclusterAdmin\fP\&. [2]
+T}
+_
+.TE
+.sp
+See http://docs.mongodb.org/manual/reference/user\-privileges and
+http://docs.mongodb.org/manual/reference/privilege\-documents for more information on user
+roles.
+.IP [1] 5
+You may provision \fBreadWrite\fP
+instead of \fBread\fP\&.
+.IP [2] 5
+\fBclusterAdmin\fP provides the ability to
+run the \fBlistDatabases\fP command, to list all existing
+databases.
+.IP [3] 5
+If any database runs with profiling enabled,
+\fBmongodump\fP may need the
+\fBdbAdminAnyDatabase\fP privilege to dump the
+\fBsystem.profile\fP collection.
 .SH USAGE
 .sp
-See the \fB/tutorial/backup\-databases\-with\-binary\-database\-dumps\fP
-for a larger overview of \fI\%mongodump\fP usage. Also see the
-"\fBmongorestore\fP" document for an overview of the
+See the http://docs.mongodb.org/manual/tutorial/backup\-databases\-with\-binary\-database\-dumps
+for a larger overview of \fBmongodump\fP usage. Also see the
+\fBmongorestore\fP document for an overview of the
 \fBmongorestore\fP, which provides the related inverse
 functionality.
 .sp
-The following command, creates a dump file that contains only the
-collection named \fBcollection\fP in the database named \fBtest\fP. In
+The following command creates a dump file that contains only the
+collection named \fBcollection\fP in the database named \fBtest\fP\&. In
 this case the database is running on the local interface on port
 \fB27017\fP:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 mongodump \-\-collection collection \-\-db test
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
-In the next example, \fI\%mongodump\fP creates a backup of the
+In the next example, \fBmongodump\fP creates a backup of the
 database instance stored in the \fB/srv/mongodb\fP directory on the
 local machine. This requires that no \fBmongod\fP instance is
 using the \fB/srv/mongodb\fP directory.
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
 mongodump \-\-dbpath /srv/mongodb
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .sp
-In the final example, \fI\%mongodump\fP creates a database dump
+In the final example, \fBmongodump\fP creates a database dump
 located at \fB/opt/backup/mongodump\-2011\-10\-24\fP, from a database
 running on port \fB37017\fP on the host \fBmongodb1.example.net\fP and
 authenticating using the username \fBuser\fP and the password
 \fBpass\fP, as follows:
+.INDENT 0.0
+.INDENT 3.5
 .sp
 .nf
 .ft C
-mongodump \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass /opt/backup/mongodump\-2011\-10\-24
+mongodump \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass \-\-out /opt/backup/mongodump\-2011\-10\-24
 .ft P
 .fi
+.UNINDENT
+.UNINDENT
 .SH AUTHOR
 MongoDB Documentation Project
 .SH COPYRIGHT
-2011-2013, 10gen, Inc.
+2011-2013, MongoDB, Inc.
 .\" Generated by docutils manpage writer.
 .