diff options
| -rw-r--r-- | debian/bsondump.1 | 64 | ||||
| -rw-r--r-- | debian/mongo.1 | 264 | ||||
| -rw-r--r-- | debian/mongod.1 | 639 | ||||
| -rw-r--r-- | debian/mongodump.1 | 323 | ||||
| -rw-r--r-- | debian/mongoexport.1 | 281 | ||||
| -rw-r--r-- | debian/mongofiles.1 | 251 | ||||
| -rw-r--r-- | debian/mongoimport.1 | 209 | ||||
| -rw-r--r-- | debian/mongooplog.1 | 218 | ||||
| -rw-r--r-- | debian/mongoperf.1 | 120 | ||||
| -rw-r--r-- | debian/mongorestore.1 | 254 | ||||
| -rw-r--r-- | debian/mongos.1 | 270 | ||||
| -rw-r--r-- | debian/mongosniff.1 | 84 | ||||
| -rw-r--r-- | debian/mongostat.1 | 203 | ||||
| -rw-r--r-- | debian/mongotop.1 | 140 |
14 files changed, 2159 insertions, 1161 deletions
diff --git a/debian/bsondump.1 b/debian/bsondump.1 index 75eda143a32..5aec65755da 100644 --- a/debian/bsondump.1 +++ b/debian/bsondump.1 @@ -1,4 +1,6 @@ -.TH "BSONDUMP" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "BSONDUMP" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME bsondump \- MongoDB BSON utility . @@ -28,13 +30,19 @@ 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. -. .SH SYNOPSIS .sp -The \fI\%bsondump\fP converts \fIBSON\fP files into human\-readable -formats, including \fIJSON\fP. For example, \fI\%bsondump\fP is useful -for reading the output files generated by \fBmongodump\fP. +The \fBbsondump\fP converts \fIBSON\fP files into human\-readable +formats, including \fIJSON\fP\&. For example, \fBbsondump\fP is useful +for reading the output files generated by \fBmongodump\fP\&. +.sp +\fBIMPORTANT:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBbsondump\fP is a diagnostic tool for inspecting +BSON files, not a tool for data ingestion or other application use. +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -42,6 +50,10 @@ for reading the output files generated by \fBmongodump\fP. .UNINDENT .INDENT 0.0 .TP +.B bsondump +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -50,79 +62,89 @@ 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.) +the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%bsondump\fP utility. +Returns the version of the \fBbsondump\fP utility. .UNINDENT .INDENT 0.0 .TP .B \-\-objcheck Validates each \fIBSON\fP object before outputting it in -\fIJSON\fP format. By default, \fI\%bsondump\fP enables -\fI\%--objcheck\fP by default. For objects with a high degree of -sub\-document nesting, \fI\%--objcheck\fP can have a small impact -on performance. You can set \fI\%--noobjcheck\fP to disable +\fIJSON\fP format. By default, \fBbsondump\fP enables +\fI\-\-objcheck\fP\&. For objects with a high degree of +sub\-document nesting, \fI\-\-objcheck\fP can have a small impact +on performance. You can set \fI\-\-noobjcheck\fP to disable object checking. .sp -Changed in version 2.4: MongoDB enables \fI\%--objcheck\fP by default, to prevent any +Changed in version 2.4: MongoDB enables \fI\-\-objcheck\fP by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database. + .UNINDENT .INDENT 0.0 .TP .B \-\-noobjcheck New in version 2.4. + .sp -Disables the default document validation that \fI\%bsondump\fP +Disables the default document validation that \fBbsondump\fP performs on all BSON documents. .UNINDENT .INDENT 0.0 .TP .B \-\-filter \(aq<JSON>\(aq -Limits the documents that \fI\%bsondump\fP exports to only those +Limits the documents that \fBbsondump\fP exports to only those documents that match the \fIJSON document\fP specified as -\fB\(aq<JSON>\(aq\fP. Be sure to include the document in single quotes to +\fB\(aq<JSON>\(aq\fP\&. Be sure to include the document in single quotes to avoid interaction with your system\(aqs shell environment. .UNINDENT .INDENT 0.0 .TP .B \-\-type <=json|=debug> -Changes the operation of \fI\%bsondump\fP from outputting "\fIJSON\fP" (the +Changes the operation of \fBbsondump\fP from outputting "\fIJSON\fP" (the default) to a debugging format. .UNINDENT .INDENT 0.0 .TP .B <bsonfilename> -The final argument to \fI\%bsondump\fP is a document containing -\fIBSON\fP. This data is typically generated by +The final argument to \fBbsondump\fP is a document containing +\fIBSON\fP\&. This data is typically generated by \fBmongodump\fP or by MongoDB in a \fIrollback\fP operation. .UNINDENT .SH USAGE .sp -By default, \fI\%bsondump\fP outputs data to standard output. To +By default, \fBbsondump\fP outputs data to standard output. To create corresponding \fIJSON\fP files, you will need to use the shell redirect. See the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C bsondump collection.bson > collection.json .ft P .fi +.UNINDENT +.UNINDENT .sp Use the following command (at the system shell) to produce debugging output for a \fIBSON\fP file: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C bsondump \-\-type=debug collection.bson .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. . diff --git a/debian/mongo.1 b/debian/mongo.1 index 7ff976330a5..daff93bb7c8 100644 --- a/debian/mongo.1 +++ b/debian/mongo.1 @@ -1,4 +1,6 @@ -.TH "MONGO" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGO" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongo \- MongoDB Shell . @@ -28,29 +30,26 @@ 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. -. .SH DESCRIPTION .sp -\fI\%mongo\fP is an interactive JavaScript shell interface to +\fBmongo\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 +operations directly with the database. \fBmongo\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 +document addresses the basic invocation of the \fBmongo\fP shell and an overview of its usage. -.SH SYNOPSIS +.SH INTERFACE +.SS Options .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] +.B mongo .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 +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 @@ -61,7 +60,7 @@ executing. .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. +\fImongo\-shell\-new\-connections\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -78,7 +77,7 @@ Silences output from the shell during the connection process. .TP .B \-\-port <port> Specifies the port where the \fBmongod\fP or \fBmongos\fP -instance is listening. Unless specified \fI\%mongo\fP connects +instance is listening. Unless specified \fBmongo\fP connects to \fBmongod\fP instances on port \fB27017\fP, which is the default \fBmongod\fP port. .UNINDENT @@ -86,14 +85,14 @@ to \fBmongod\fP instances on port \fB27017\fP, which is the default .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 +connect to as \fB<hostname>\fP\&. By default \fBmongo\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 +option. \fBmongo\fP does not load its own environment when evaluating code: as a result many options of the shell environment are not available. .UNINDENT @@ -102,51 +101,57 @@ available. .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. +\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. +\fBmongo\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 +\fI\-\-username\fP option to supply a username. If you +specify a \fI\-\-username\fP and do not pass an argument to the +\fI\-\-password\fP option, \fBmongo\fP will prompt for a password interactively, if the \fBmongod\fP or \fBmongos\fP requires authentication. +.sp +If you chose not to provide an argument so that \fBmongo\fP +will prompt for a password, \fI\-\-password\fP must be the last +option. .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\%mongo\fP assumes that the database name specified +By default, \fBmongo\fP assumes that the database name specified in the \fI\%db address\fP holds the user\(aqs -credentials, unless you specify \fI\%--authenticationDatabase\fP. +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 +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\%mongo\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongo\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 @@ -159,34 +164,44 @@ Enable connection to a \fBmongod\fP or .TP .B \-\-sslPEMKeyFile <filename> New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -Specifies the \fB.pem\fP file that contains both the SSL -certificate and key. Specify the file name of the \fB.pem\fP +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 +Required when using the \fI\-\-ssl\fP option if the \fBmongod\fP or \fBmongos\fP has \fBsslCAFile\fP -enabled \fIwithout\fP \fBsslWeakCertificateValidation\fP. +enabled \fIwithout\fP \fBsslWeakCertificateValidation\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-sslPEMKeyPassword <value> New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp Specifies the password to decrypt the root certificate chain -specified by \fI\%--sslPEMKeyFile\fP. +specified by \fI\-\-sslPEMKeyFile\fP\&. .sp Only required if the certificate\-key file is encrypted. .UNINDENT @@ -194,15 +209,20 @@ Only required if the certificate\-key file is encrypted. .TP .B \-\-sslCAFile <filename> New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -Specifies the \fB.pem\fP file that contains the certificate from -the Certificate Authority. Specify the file name of the \fB.pem\fP +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 @@ -224,9 +244,9 @@ connection process. .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongo\fP to connect +Enables IPv6 support that allows \fBmongo\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongo\fP, disable IPv6 +and processes, including \fBmongo\fP, disable IPv6 support by default. .UNINDENT .INDENT 0.0 @@ -234,18 +254,24 @@ support by default. .B <db address> Specifies the "database address" 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 \fI\%mongo\fP shell to the +The above command will connect the \fBmongo\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: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -255,68 +281,99 @@ mongo 10.8.8.10/test .ft P .fi .UNINDENT +.UNINDENT +.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. +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 s 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 Files .sp \fB~/.dbshell\fP .INDENT 0.0 .INDENT 3.5 -\fI\%mongo\fP maintains a history of commands in the \fB.dbshell\fP +\fBmongo\fP maintains a history of commands in the \fB\&.dbshell\fP file. -.IP Note -\fI\%mongo\fP does not recorded interaction related to +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBmongo\fP does not recorded interaction related to authentication in the history file, including -\fBauthenticate\fP and \fBdb.addUser()\fP. -.RE -.IP Warning +\fBauthenticate\fP and \fBdb.addUser()\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 Versions of Windows \fBmongo.exe\fP earlier than 2.2.0 will -save the \fI.dbshell\fP file in the \fBmongo.exe\fP working +save the \fI\&.dbshell\fP file in the \fBmongo.exe\fP working directory. -.RE +.UNINDENT +.UNINDENT .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, +\fBmongo\fP will read the \fB\&.mongorc.js\fP file from the home +directory of the user invoking \fBmongo\fP\&. In the file, users +can define variables, customize the \fBmongo\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 +\fBmongo\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. +reading \fB\&.mongorc.js\fP\&. .UNINDENT .UNINDENT .sp -\fB/tmp/mongo_edit\fI<time_t>\fP.js\fP +\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 +Created by \fBmongo\fP when editing a file. If the file +exists \fBmongo\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 +\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 +exists \fBmongo\fP will append an integer from \fB1\fP to \fB10\fP to the time value to attempt to create a unique file. .UNINDENT .UNINDENT @@ -326,32 +383,32 @@ the time value to attempt to create a unique file. .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. +\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 +Specifies the path to the home directory where \fBmongo\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. +directory where \fBmongo\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. +\fBmongo\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: +The \fBmongo\fP shell supports the following keyboard shortcuts: [1] .TS center; @@ -444,13 +501,13 @@ _ T{ Ctrl\-C T} T{ -Exit the \fI\%mongo\fP shell +Exit the \fBmongo\fP shell T} _ T{ Ctrl\-D T} T{ -Delete a char (or exit the \fI\%mongo\fP shell) +Delete a char (or exit the \fBmongo\fP shell) T} _ T{ @@ -623,59 +680,88 @@ T} _ .TE .IP [1] 5 -MongoDB accommodates multiple keybinding, -Since 2.0, \fI\%mongo\fP includes support for basic emacs +MongoDB accommodates multiple keybinding. +Since 2.0, \fBmongo\fP includes support for basic emacs keybindings. .SH USE .sp -Typically users invoke the shell with the \fI\%mongo\fP command at +Typically users invoke the shell with the \fBmongo\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: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C -mongo \-\-username <user> \-\-password <pass> \-\-hostname <host> \-\-port 28015 +mongo \-\-username <user> \-\-password <pass> \-\-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 <pass> \-\-host <host> \-\-port 28015 .ft P .fi +.UNINDENT +.UNINDENT .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 +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: +.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 To print return a query as \fIJSON\fP, from the system prompt using -the \fI\%--eval\fP option, use the following form: +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. .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, 10gen, Inc. +2011-2013, MongoDB, Inc. .\" Generated by docutils manpage writer. . diff --git a/debian/mongod.1 b/debian/mongod.1 index fc9569149f3..285b3c2f8c8 100644 --- a/debian/mongod.1 +++ b/debian/mongod.1 @@ -1,4 +1,6 @@ -.TH "MONGOD" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOD" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongod \- MongoDB Server . @@ -28,21 +30,20 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongod\fP is the primary daemon process for the MongoDB +\fBmongod\fP is the primary daemon process for the MongoDB system. It handles data requests, manages data format, and performs background management operations. .sp This document provides a complete overview of all command line options -for \fI\%mongod\fP. These options are primarily useful for testing +for \fBmongod\fP\&. These options are primarily useful for testing purposes. In common operation, use the \fBconfiguration file options\fP to control the behavior of your database, which is fully capable of all operations described below. .SH OPTIONS +.SS Core Options .INDENT 0.0 .TP .B mongod @@ -55,7 +56,7 @@ Returns a basic help and usage text. .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongod\fP daemon. +Returns the version of the \fBmongod\fP daemon. .UNINDENT .INDENT 0.0 .TP @@ -64,28 +65,37 @@ Specifies a configuration file, that you can use to specify runtime\-configurations. While the options are equivalent and accessible via the other command line arguments, the configuration file is the preferred method for runtime configuration of -mongod. See the "\fB/reference/configuration\-options\fP" document +mongod. See the http://docs.mongodb.org/manual/reference/configuration\-options document for more information about these options. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Ensure the configuration file uses ASCII +encoding. \fBmongod\fP does not support configuration files +with non\-ASCII encoding, including UTF\-8. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-verbose, \-v Increases the amount of internal reporting returned on standard -output or in the log file specified by \fI\%--logpath\fP. Use the +output or in the log file specified by \fI\-\-logpath\fP\&. Use the \fB\-v\fP form to control the level of verbosity 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 \-\-quiet -Runs the \fI\%mongod\fP instance in a quiet mode that attempts to limit +Runs the \fBmongod\fP instance in a quiet mode that attempts to limit the amount of output. This option suppresses: .INDENT 7.0 .IP \(bu 2 output from \fIdatabase commands\fP, including \fBdrop\fP, \fBdropIndexes\fP, \fBdiagLogging\fP, \fBvalidate\fP, and -\fBclean\fP. +\fBclean\fP\&. .IP \(bu 2 replication activity. .IP \(bu 2 @@ -97,8 +107,8 @@ connection closed events. .INDENT 0.0 .TP .B \-\-port <port> -Specifies a TCP port for the \fI\%mongod\fP to listen for client -connections. By default \fI\%mongod\fP listens for connections on +Specifies a TCP port for the \fBmongod\fP to listen for client +connections. By default \fBmongod\fP listens for connections on port 27017. .sp UNIX\-like systems require root privileges to use ports with numbers @@ -107,44 +117,50 @@ lower than 1024. .INDENT 0.0 .TP .B \-\-bind_ip <ip address> -The IP address that the \fI\%mongod\fP process will bind to and -listen for connections. By default \fI\%mongod\fP listens for -connections on the localhost (i.e. \fB127.0.0.1\fP address.) You may -attach \fI\%mongod\fP to any interface; however, if you attach -\fI\%mongod\fP to a publicly accessible interface ensure that -you have implemented proper authentication and/or firewall -restrictions to protect the integrity of your database. +The IP address that the \fBmongod\fP process will bind to and +listen for connections. By default \fBmongod\fP listens for +connections all interfaces. You may attach \fBmongod\fP to any +interface; however, when attaching \fBmongod\fP to a publicly +accessible interface ensure that you have implemented proper +authentication and/or firewall restrictions to protect the +integrity of your database. .UNINDENT .INDENT 0.0 .TP .B \-\-maxConns <number> Specifies the maximum number of simultaneous connections that -\fI\%mongod\fP will accept. This setting will have no effect if +\fBmongod\fP will accept. This setting will have no effect if it is higher than your operating system\(aqs configured maximum connection tracking threshold. -.IP Note +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 You cannot set \fBmaxConns\fP to a value higher -than \fI20000\fP. -.RE +than \fI20000\fP\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-objcheck -Forces the \fI\%mongod\fP to validate all requests from clients +Forces the \fBmongod\fP to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database. For objects with a high degree of sub\-document -nesting, \fI\%--objcheck\fP can have a small impact on -performance. You can set \fI\%--noobjcheck\fP to disable object +nesting, \fI\-\-objcheck\fP can have a small impact on +performance. You can set \fI\-\-noobjcheck\fP to disable object checking at run\-time. .sp -Changed in version 2.4: MongoDB enables \fI\%--objcheck\fP by default, to prevent any +Changed in version 2.4: MongoDB enables \fI\-\-objcheck\fP by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database. + .UNINDENT .INDENT 0.0 .TP .B \-\-noobjcheck New in version 2.4. + .sp Disables the default document validation that MongoDB performs on all incoming BSON documents. @@ -155,19 +171,23 @@ incoming BSON documents. Specify a path for the log file that will hold all diagnostic logging information. .sp -Unless specified, \fI\%mongod\fP will output all log information +Unless specified, \fBmongod\fP will output all log information to the standard output. Additionally, unless you also specify -\fI\%--logappend\fP, the logfile will be overwritten when the +\fI\-\-logappend\fP, the logfile will be overwritten when the process restarts. -.IP Note +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 The behavior of the logging system may change in the near future in response to the \fI\%SERVER-4499\fP case. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-logappend -When specified, this option ensures that \fI\%mongod\fP appends +When specified, this option ensures that \fBmongod\fP appends new entries to the end of the logfile rather than overwriting the content of the log when the process restarts. .UNINDENT @@ -175,22 +195,27 @@ content of the log when the process restarts. .TP .B \-\-syslog New in version 2.1.0. + .sp Sends all logging output to the host\(aqs \fIsyslog\fP system rather -than to standard output or a log file as with \fI\%--logpath\fP. -.IP Warning -You cannot use \fI\%--syslog\fP with \fI\%--logpath\fP. -.RE +than to standard output or a log file as with \fI\-\-logpath\fP\&. +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +You cannot use \fI\-\-syslog\fP with \fI\-\-logpath\fP\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-pidfilepath <path> Specify a file location to hold the "\fIPID\fP" or process ID of -the \fI\%mongod\fP process. Useful for tracking the -\fI\%mongod\fP process in combination with the \fI\%mongod --fork\fP +the \fBmongod\fP process. Useful for tracking the +\fBmongod\fP process in combination with the \fImongod \-\-fork\fP option. .sp -Without a specified \fI\%--pidfilepath\fP option, +Without a specified \fI\-\-pidfilepath\fP option, \fBmongos\fP creates no PID file. .UNINDENT .INDENT 0.0 @@ -199,29 +224,38 @@ Without a specified \fI\%--pidfilepath\fP option, Specify the path to a key file to store authentication information. This option is only useful for the connection between replica set members. -.IP "See also" .sp -"\fIReplica Set Security\fP" -and "\fB/administration/replica\-sets\fP." -.RE +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +\fIReplica Set Security\fP +and http://docs.mongodb.org/manual/administration/replica\-sets\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-nounixsocket -Disables listening on the UNIX socket. Unless set to false, -\fI\%mongod\fP and \fBmongos\fP provide a UNIX\-socket. +Disables listening on the UNIX socket. \fBmongod\fP always +listens on the UNIX socket, unless \fI\-\-nounixsocket\fP is set, +\fI\-\-bind_ip\fP is \fInot\fP set, or \fI\-\-bind_ip\fP does \fInot\fP +specify \fB127.0.0.1\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-unixSocketPrefix <path> Specifies a path for the UNIX socket. Unless this option has a -value, \fI\%mongod\fP and \fBmongos\fP, create a socket -with the \fB/tmp\fP as a prefix. +value \fBmongod\fP creates a socket with \fB/tmp\fP as a +prefix. +.sp +MongoDB will \fIalways\fP create and listen on a UNIX socket, unless +\fI\-\-nounixsocket\fP is set, \fI\-\-bind_ip\fP is \fInot\fP set, +or \fI\-\-bind_ip\fP does \fInot\fP specify \fB127.0.0.1\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-fork -Enables a \fIdaemon\fP mode for \fI\%mongod\fP that runs the +Enables a \fIdaemon\fP mode for \fBmongod\fP that runs the process to the background. This is the normal mode of operation, in production and production\-like environments, but may \fInot\fP be desirable for testing. @@ -230,7 +264,7 @@ desirable for testing. .TP .B \-\-auth Enables database authentication for users connecting from remote -hosts. configure users via the \fBmongo shell shell\fP. If no users exist, the localhost interface +hosts. Configure users via the \fBmongo shell\fP\&. If no users exist, the localhost interface will continue to have access to the database until the you create the first user. .sp @@ -240,23 +274,23 @@ page for more information regarding this functionality. .INDENT 0.0 .TP .B \-\-cpu -Forces \fI\%mongod\fP to report the percentage of CPU time in -write lock. \fI\%mongod\fP generates output every four +Forces \fBmongod\fP to report the percentage of CPU time in +write lock. \fBmongod\fP generates output every four seconds. MongoDB writes this data to standard output or the logfile if using the \fBlogpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-dbpath <path> -Specify a directory for the \fI\%mongod\fP instance to store its +Specify a directory for the \fBmongod\fP instance to store its data. Typical locations include: \fB/srv/mongodb\fP, \fB/var/lib/mongodb\fP or \fB/opt/mongodb\fP .sp -Unless specified, \fI\%mongod\fP will look for data files in the +Unless specified, \fBmongod\fP will look for data files in the default \fB/data/db\fP directory. (Windows systems use the \fB\edata\edb\fP directory.) If you installed using a package management system. Check the \fB/etc/mongodb.conf\fP file provided by -your packages to see the configuration of the \fBdbpath\fP. +your packages to see the configuration of the \fBdbpath\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -315,41 +349,104 @@ You can use the \fBmongosniff\fP tool to replay this output for investigation. Given a typical diaglog file, located at \fB/data/db/diaglog.4f76a58c\fP, you might use a command in the following form to read these files: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C mongosniff \-\-source DIAGLOG /data/db/diaglog.4f76a58c .ft P .fi +.UNINDENT +.UNINDENT .sp \fI\%--diaglog\fP is for internal use and not intended for most users. -.IP Warning -Setting the diagnostic level to \fB0\fP will cause \fI\%mongod\fP +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Setting the diagnostic level to \fB0\fP will cause \fBmongod\fP to stop writing data to the \fIdiagnostic log\fP file. However, -the \fI\%mongod\fP instance will continue to keep the file open, +the \fBmongod\fP instance will continue to keep the file open, even if it is no longer writing data to the file. If you want to rename, move, or delete the diagnostic log you must cleanly shut -down the \fI\%mongod\fP instance before doing so. -.RE +down the \fBmongod\fP instance before doing so. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb Alters the storage pattern of the data directory to store each database\(aqs files in a distinct folder. This option will create -directories within the \fI\%--dbpath\fP named for each directory. +directories within the \fI\-\-dbpath\fP named for each directory. .sp Use this option in conjunction with your file system and device configuration so that MongoDB will store data on a number of distinct disk devices to increase write throughput or disk capacity. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +If you have an existing \fBmongod\fP instance and +\fBdbpath\fP, and you want to enable +\fI\-\-directoryperdb\fP, you \fBmust\fP migrate your existing +databases to directories before setting \fI\-\-directoryperdb\fP +to access those databases. +.INDENT 0.0 +.INDENT 3.5 +.SS Example +.sp +Given a \fBdbpath\fP directory with the following items: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +journal +mongod.lock +local.0 +local.1 +local.ns +test.0 +test.1 +test.ns +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To enable \fI\-\-directoryperdb\fP you would need to modify the +\fBdbpath\fP to resemble the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +journal +mongod.lock +local/local.0 +local/local.1 +local/local.ns +test/test.0 +test/test.1 +test/test.ns +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-journal Enables operation journaling to ensure write durability and data -consistency. \fI\%mongod\fP enables journaling by default on +consistency. \fBmongod\fP enables journaling by default on 64\-bit builds of versions after 2.0. .UNINDENT .INDENT 0.0 @@ -361,24 +458,30 @@ affect database integrity. .INDENT 0.0 .TP .B \-\-journalCommitInterval <value> -Specifies the maximum amount of time for \fI\%mongod\fP to allow -between journal operations. The default value is 100 milliseconds, -while possible values range from 2 to 300 milliseconds. Lower -values increase the durability of the journal, at the expense of -disk performance. -.sp -To force \fI\%mongod\fP to commit to the journal more frequently, -you can specify \fBj:true\fP. When a write operation with \fBj:true\fP -pending, \fI\%mongod\fP will reduce +Specifies the maximum amount of time for \fBmongod\fP to allow +between journal operations. Possible values are between 2 and 300 +milliseconds. Lower values increase the durability of the journal, +at the expense of disk performance. +.sp +The default journal commit interval is 100 milliseconds if a single +block device (e.g. physical volume, RAID device, or LVM volume) +contains both the journal and the data files. +.sp +If different block devices provide the journal and data files the +default journal commit interval is 30 milliseconds. +.sp +To force \fBmongod\fP to commit to the journal more frequently, +you can specify \fBj:true\fP\&. When a write operation with \fBj:true\fP +is pending, \fBmongod\fP will reduce \fBjournalCommitInterval\fP to a third of the set value. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 Specify this option to enable IPv6 support. This will allow clients -to connect to \fI\%mongod\fP using IPv6 -networks. \fI\%mongod\fP disables IPv6 support by default in -\fI\%mongod\fP and all utilities. +to connect to \fBmongod\fP using IPv6 +networks. \fBmongod\fP disables IPv6 support by default in +\fBmongod\fP and all utilities. .UNINDENT .INDENT 0.0 .TP @@ -397,11 +500,19 @@ compatibility and clarity. .TP .B \-\-nohttpinterface Disables the HTTP interface. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +In MongoDB Enterprise, the HTTP Console does not support Kerberos +Authentication. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-nojournal -Disables the durability journaling. By default, \fI\%mongod\fP +Disables the durability journaling. By default, \fBmongod\fP enables journaling in 64\-bit versions after v2.0. .UNINDENT .INDENT 0.0 @@ -424,7 +535,7 @@ Forbids operations that require a table scan. .INDENT 0.0 .TP .B \-\-nssize <value> -Specifies the default size for namespace files (i.e \fB.ns\fP). This +Specifies the default size for namespace files (i.e \fB\&.ns\fP). This option has no impact on the size of existing namespace files. The maximum size is 2047 megabytes. .sp @@ -436,7 +547,7 @@ a namespace. .TP .B \-\-profile <level> Changes the level of database profiling, which inserts information -about operation performance into output of \fI\%mongod\fP or the log +about operation performance into output of \fBmongod\fP or the log file. The following levels are available: .TS center; @@ -497,60 +608,79 @@ Enables the simple \fIREST\fP API. Runs a repair routine on all databases. This is equivalent to shutting down and running the \fBrepairDatabase\fP database command on all databases. -.IP Warning -In general, if you have an intact copy of your data, such as -would exist on a very recent backup or an intact member of a -\fIreplica set\fP, \fBdo not\fP use \fBrepairDatabase\fP -or related options like \fBdb.repairDatabase()\fP in the -\fBmongo\fP shell or \fI\%mongod --repair\fP. Restore -from an intact copy of your data. -.RE -.IP Note +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +During normal operations, only use the \fBrepairDatabase\fP +command and wrappers including \fBdb.repairDatabase()\fP in the +\fBmongo\fP shell and \fImongod \-\-repair\fP, to compact +database files and/or reclaim disk space. Be aware that these +operations remove and do not save any corrupt data during the +repair process. +.sp +If you are trying to repair a \fIreplica set\fP member, and you +have access to an intact copy of your data (e.g. a recent backup or +an intact member of the \fIreplica set\fP), you should restore +from that intact copy, and \fBnot\fP use \fBrepairDatabase\fP\&. +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 When using \fIjournaling\fP, there is almost never -any need to run \fBrepairDatabase\fP. In the event of an +any need to run \fBrepairDatabase\fP\&. In the event of an unclean shutdown, the server will be able restore the data files to a pristine state automatically. -.RE +.UNINDENT +.UNINDENT .sp Changed in version 2.1.2. + .sp If you run the repair option \fIand\fP have data in a journal file, -\fI\%mongod\fP will refuse to start. In these cases you should -start \fI\%mongod\fP without the \fI\%--repair\fP option to -allow \fI\%mongod\fP to recover data from the journal. This will +\fBmongod\fP will refuse to start. In these cases you should +start \fBmongod\fP without the \fI\-\-repair\fP option to +allow \fBmongod\fP to recover data from the journal. This will complete more quickly and will result in a more consistent and complete data set. .sp To continue the repair operation despite the journal files, shut down -\fI\%mongod\fP cleanly and restart with the \fI\%--repair\fP +\fBmongod\fP cleanly and restart with the \fI\-\-repair\fP option. -.IP Note -\fI\%--repair\fP copies data from the source data files into +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fI\-\-repair\fP copies data from the source data files into new data files in the \fBrepairpath\fP, and then replaces the original data files with the repaired data files. \fIIf\fP \fBrepairpath\fP is on the same device as -\fBdbpath\fP, you \fImay\fP interrupt a \fI\%mongod\fP -running \fI\%--repair\fP without affecting the integrity of +\fBdbpath\fP, you \fImay\fP interrupt a \fBmongod\fP +running \fI\-\-repair\fP without affecting the integrity of the data set. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-repairpath <path> Specifies the root directory containing MongoDB data files, to use -for the \fI\%--repair\fP operation. Defaults to a \fB_tmp\fP -directory within the \fBdbpath\fP. +for the \fI\-\-repair\fP operation. Defaults to a \fB_tmp\fP +directory within the \fBdbpath\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-setParameter <options> New in version 2.4. + .sp Specifies an option to configure on startup. Specify multiple -options with multiple \fI\%--setParameter\fP options. See -\fB/reference/parameters\fP for full documentation of these +options with multiple \fI\-\-setParameter\fP options. See +http://docs.mongodb.org/manual/reference/parameters for full documentation of these parameters. The \fBsetParameter\fP database command provides -access to many of these parameters. \fI\%--setParameter\fP supports the +access to many of these parameters. \fI\-\-setParameter\fP supports the following options: .INDENT 7.0 .IP \(bu 2 @@ -576,6 +706,8 @@ following options: .IP \(bu 2 \fBsyncdelay\fP .IP \(bu 2 +\fBtextSearchEnabled\fP +.IP \(bu 2 \fBtraceExceptions\fP .UNINDENT .UNINDENT @@ -585,7 +717,7 @@ following options: Defines the value of "slow," for the \fI\%--profile\fP option. The database logs all slow queries to the log, even when the profiler is not turned on. When the database profiler is on, -\fI\%mongod\fP the profiler writes to the \fBsystem.profile\fP +\fBmongod\fP the profiler writes to the \fBsystem.profile\fP collection. See the \fBprofile\fP command for more information on the database profiler. .UNINDENT @@ -600,7 +732,7 @@ megabytes. \fI\%--smallfiles\fP also reduces the size of each .sp Use \fI\%--smallfiles\fP if you have a large number of databases that each holds a small quantity of data. \fI\%--smallfiles\fP can -lead your \fI\%mongod\fP to create a large number of files, +lead your \fBmongod\fP to create a large number of files, which may affect performance for larger databases. .UNINDENT .INDENT 0.0 @@ -608,17 +740,17 @@ which may affect performance for larger databases. .B \-\-shutdown Used in \fIcontrol scripts\fP, the \fI\%--shutdown\fP will cleanly and safely terminate the -\fI\%mongod\fP process. When invoking \fI\%mongod\fP with this -option you must set the \fI\%--dbpath\fP option either directly -or by way of the \fBconfiguration file\fP and the \fI\%--config\fP +\fBmongod\fP process. When invoking \fBmongod\fP with this +option you must set the \fI\-\-dbpath\fP option either directly +or by way of the \fBconfiguration file\fP and the \fI\-\-config\fP option. .sp -\fI\%--shutdown\fP is only available on Linux systems. +The \fI\%--shutdown\fP option is available only on Linux systems. .UNINDENT .INDENT 0.0 .TP .B \-\-syncdelay <value> -\fI\%mongod\fP writes data very quickly to the journal, and +\fBmongod\fP writes data very quickly to the journal, and lazily to the data files. \fI\%--syncdelay\fP controls how much time can pass before MongoDB flushes data to the \fIdatabase files\fP via an \fIfsync\fP operation. The default setting is 60 seconds. @@ -630,12 +762,16 @@ thread\(aqs status via the \fBbackgroundFlushing\fP field. .sp \fBsyncdelay\fP has no effect on the \fBjournal\fP -files or \fBjournaling\fP. -.IP Warning +files or \fBjournaling\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 If you set \fI\%--syncdelay\fP to \fB0\fP, MongoDB will not sync the memory mapped files to disk. Do not set this value on production systems. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -648,16 +784,20 @@ and the number of available physical pages. .TP .B \-\-upgrade Upgrades the on\-disk data format of the files specified by the -\fI\%--dbpath\fP to the latest version, if needed. +\fI\-\-dbpath\fP to the latest version, if needed. .sp -This option only affects the operation of \fI\%mongod\fP if the +This option only affects the operation of \fBmongod\fP if the data files are in an old format. -.IP Note +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 In most cases you should \fBnot\fP set this value, so you can exercise the most control over your upgrade process. See the MongoDB \fI\%release notes\fP (on the download page) for more information about the upgrade process. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -669,24 +809,36 @@ For internal diagnostic use only. .TP .B \-\-replSet <setname> Use this option to configure replication with replica sets. Specify -a setname as an argument to this set. All hosts must have the same -set name. -.IP "See also" +a replica set name as an argument to this set. All hosts in the +replica set must have the same set name. .sp -"\fB/replication\fP," -"\fB/administration/replica\-sets\fP," and -"\fB/reference/replica\-configuration\fP" -.RE +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +If your application connects to more than one replica set, each set +should have a distinct name. Some drivers group replica set +connections by replica set name. +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +http://docs.mongodb.org/manual/replication, +http://docs.mongodb.org/manual/administration/replica\-sets, and +http://docs.mongodb.org/manual/reference/replica\-configuration +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-oplogSize <value> Specifies a maximum size in megabytes for the replication operation -log (e.g. \fIoplog\fP.) By \fI\%mongod\fP creates an +log (e.g. \fIoplog\fP\&.) By \fBmongod\fP creates an \fIoplog\fP based on the maximum amount of space available. For 64\-bit systems, the op log is typically 5% of available disk space. .sp -Once the \fI\%mongod\fP has created the oplog for the first +Once the \fBmongod\fP has created the oplog for the first time, changing \fI\%--oplogSize\fP will not affect the size of the oplog. .UNINDENT @@ -696,22 +848,27 @@ the oplog. In the context of \fIreplica set\fP replication, set this option if you have seeded this member with a snapshot of the \fIdbpath\fP of another member of the set. Otherwise the -\fI\%mongod\fP will attempt to perform an initial sync, +\fBmongod\fP will attempt to perform an initial sync, as though the member were a new member. -.IP Warning +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 If the data is not perfectly synchronized \fIand\fP -\fI\%mongod\fP starts with \fBfastsync\fP, then the +\fBmongod\fP starts with \fBfastsync\fP, then the secondary or slave will be permanently out of sync with the primary, which may cause significant consistency problems. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-replIndexPrefetch New in version 2.2. + .sp You must use \fI\%--replIndexPrefetch\fP in conjunction with -\fBreplSet\fP. The default value is \fBall\fP and available +\fBreplSet\fP\&. The default value is \fBall\fP and available options are: .INDENT 7.0 .IP \(bu 2 @@ -726,7 +883,7 @@ By default \fIsecondary\fP members of a \fIreplica set\fP will load all indexes related to an operation into memory before applying operations from the oplog. You can modify this behavior so that the secondaries will only load the \fB_id\fP index. Specify -\fB_id_only\fP or \fBnone\fP to prevent the \fI\%mongod\fP from +\fB_id_only\fP or \fBnone\fP to prevent the \fBmongod\fP from loading \fIany\fP index into memory. .UNINDENT .SS Master\-Slave Replication @@ -737,14 +894,14 @@ replica sets are the preferred configuration for database replication. .INDENT 0.0 .TP .B \-\-master -Configures \fI\%mongod\fP to run as a replication -\fImaster\fP. +Configures \fBmongod\fP to run as a replication +\fImaster\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-slave -Configures \fI\%mongod\fP to run as a replication -\fIslave\fP. +Configures \fBmongod\fP to run as a replication +\fIslave\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -768,200 +925,256 @@ apply operations from the \fImaster\fP node. .INDENT 0.0 .TP .B \-\-autoresync -For use with the \fI\%--slave\fP option, the +For use with the \fI\%--slave\fP option. When set, \fI\%--autoresync\fP option allows this slave to automatically -resync if the local data is more than 10 seconds behind the -master. This option may be problematic if the \fIoplog\fP is too -small (controlled by the \fI\%--oplogSize\fP option.) If the -\fIoplog\fP not large enough to store the difference in changes -between the master\(aqs current state and the state of the slave, this -node will forcibly resync itself unnecessarily. When you set the If -the \fI\%--autoresync\fP option the slave will not attempt an -automatic resync more than once in a ten minute period. +resync if it is more than 10 seconds behind the master. This +setting may be problematic if the \fI\%--oplogSize\fP specifies +a too small oplog. +If the \fIoplog\fP is not large enough to store the difference in +changes between the master\(aqs current state and the state of the +slave, this instance will forcibly resync itself +unnecessarily. When you set the \fBautoresync\fP option to +\fBfalse\fP, the slave will not attempt an automatic resync more than +once in a ten minute period. .UNINDENT .SS Sharding Cluster Options .INDENT 0.0 .TP .B \-\-configsvr -Declares that this \fI\%mongod\fP instance serves as the +Declares that this \fBmongod\fP instance serves as the \fIconfig database\fP of a sharded cluster. When running with this option, clients will not be able to write data to any database -other than \fBconfig\fP and \fBadmin\fP. The default port for -\fI\%mongod\fP with this option is \fB27019\fP and -\fI\%mongod\fP writes all data files to the \fB/configdb\fP -sub\-directory of the \fI\%--dbpath\fP directory. +other than \fBconfig\fP and \fBadmin\fP\&. The default port for a +\fBmongod\fP with this option is \fB27019\fP and the default +\fI\-\-dbpath\fP directory is \fB/data/configdb\fP, unless +specified. +.sp +Changed in version 2.2: \fI\%--configsvr\fP also sets \fI\%--smallfiles\fP\&. + +.sp +Changed in version 2.4: \fI\%--configsvr\fP creates a local \fIoplog\fP\&. + +.sp +Do not use \fI\%--configsvr\fP with \fI\%--replSet\fP or +\fI\%--shardsvr\fP\&. Config servers cannot be a shard +server or part of a \fIreplica set\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-shardsvr -Configures this \fI\%mongod\fP instance as a shard in a +Configures this \fBmongod\fP instance as a shard in a partitioned cluster. The default port for these instances is -\fB27018\fP. The only effect of \fI\%--shardsvr\fP is to change +\fB27018\fP\&. The only effect of \fI\%--shardsvr\fP is to change the port number. .UNINDENT .INDENT 0.0 .TP -.B \-\-noMoveParanoia -Disables a "paranoid mode" for data writes for chunk migration -operation. See the -\fIchunk migration\fP -and \fBmoveChunk\fP command documentation for more information. +.B \-\-moveParanoia +New in version 2.4. + .sp -By default \fI\%mongod\fP will save copies of migrated chunks on -the "from" server during migrations as "paranoid mode." Setting -this option disables this paranoia. +During chunk migrations, \fI\%--moveParanoia\fP forces the +\fBmongod\fP instances to save all documents migrated from this +shard in the \fBmoveChunk\fP directory of the \fBdbpath\fP\&. MongoDB +does not delete data from this directory. +.sp +Prior to 2.4, \fI\%--moveParanoia\fP was the default behavior of +MongoDB. .UNINDENT .SS SSL Options -.IP "See" +.INDENT 0.0 +.INDENT 3.5 +.SS See .sp -\fB/administration/ssl\fP for full documentation of -MongoDB\(aqs support. -.RE +http://docs.mongodb.org/manual/tutorial/configure\-ssl for full +documentation of MongoDB\(aqs support. +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B \-\-sslOnNormalPorts New in version 2.2. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -Enables SSL for \fI\%mongod\fP. With \fI\%--sslOnNormalPorts\fP, -a \fI\%mongod\fP requires SSL encryption for all connections on the -default MongoDB port, or the port specified by \fI\%--port\fP. By +Enables SSL for \fBmongod\fP\&. With \fI\%--sslOnNormalPorts\fP, +a \fBmongod\fP requires SSL encryption for all connections on the +default MongoDB port, or the port specified by \fI\-\-port\fP\&. By default, \fI\%--sslOnNormalPorts\fP is disabled. .UNINDENT .INDENT 0.0 .TP .B \-\-sslPEMKeyFile <filename> New in version 2.2. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -Specifies the \fB.pem\fP file that contains both the SSL -certificate and key. Specify the file name of the \fB.pem\fP +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 When using \fI\%--sslOnNormalPorts\fP, you must specify -\fI\%--sslPEMKeyFile\fP. +\fI\%--sslPEMKeyFile\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-sslPEMKeyPassword <value> New in version 2.2. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp Specifies the password to de\-crypt the certificate\-key file (i.e. \fI\%--sslPEMKeyFile\fP). Only use \fI\%--sslPEMKeyPassword\fP if the certificate\-key file is -encrypted. In all cases, \fI\%mongod\fP will redact the password from +encrypted. In all cases, \fBmongod\fP will redact the password from all logging and reporting output. .sp Changed in version 2.4: \fI\%--sslPEMKeyPassword\fP is only needed when the private -key is encrypted. In earlier versions \fI\%mongod\fP would require +key is encrypted. In earlier versions \fBmongod\fP would require \fI\%--sslPEMKeyPassword\fP whenever using \fI\%--sslOnNormalPorts\fP, even when the private key was not encrypted. + .UNINDENT .INDENT 0.0 .TP .B \-\-sslCAFile <filename> New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .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 +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 .UNINDENT .INDENT 0.0 .TP .B \-\-sslCRLFile <filename> New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -Specifies the \fB.pem\fP file that contains the Certificate -Revocation List. Specify the file name of the \fB.pem\fP +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 .UNINDENT .INDENT 0.0 .TP .B \-\-sslWeakCertificateValidation New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp Disables the requirement for SSL certificate validation, that \fI\%--sslCAFile\fP enables. With -\fI\%--sslWeakCertificateValidation\fP, \fI\%mongod\fP will accept +\fI\%--sslWeakCertificateValidation\fP, \fBmongod\fP will accept connections if the client does not present a certificate when establishing the connection. .sp -If the client presents a certificate and \fI\%mongod\fP has -\fI\%--sslWeakCertificateValidation\fP enabled, \fI\%mongod\fP +If the client presents a certificate and \fBmongod\fP has +\fI\%--sslWeakCertificateValidation\fP enabled, \fBmongod\fP will validate the certificate using the root certificate chain specified by \fI\%--sslCAFile\fP, and reject clients with invalid certificates. .sp Use \fI\%--sslWeakCertificateValidation\fP if you have a mixed deployment that includes clients that do not or cannot present -certificates to \fI\%mongod\fP. +certificates to \fBmongod\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-sslFIPSMode New in version 2.4. -.IP Note + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 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 +for SSL. To use SSL you can either compile MongoDB with SSL support +or use MongoDB Enterprise\&. See http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information about SSL and MongoDB. -.RE +.UNINDENT +.UNINDENT .sp -When specified, \fI\%mongod\fP will use the FIPS mode of the +When specified, \fBmongod\fP will use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant -OpenSSL library to use \fI\%--sslFIPSMode\fP. +OpenSSL library to use \fI\%--sslFIPSMode\fP\&. .UNINDENT .SH USAGE .sp -In common usage, the invocation of \fI\%mongod\fP will resemble the +In common usage, the invocation of \fBmongod\fP will resemble the following in the context of an initialization or control script: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongod \-\-config /etc/mongodb.conf .ft P .fi +.UNINDENT +.UNINDENT .sp -See the "\fB/reference/configuration\-options\fP" for more information -on how to configure \fI\%mongod\fP using the configuration file. +See the http://docs.mongodb.org/manual/reference/configuration\-options for more information +on how to configure \fBmongod\fP using the configuration file. .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, 10gen, Inc. +2011-2013, MongoDB, Inc. .\" Generated by docutils manpage writer. . 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. . diff --git a/debian/mongoexport.1 b/debian/mongoexport.1 index d82825f2a7c..0883293dad1 100644 --- a/debian/mongoexport.1 +++ b/debian/mongoexport.1 @@ -1,4 +1,6 @@ -.TH "MONGOEXPORT" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOEXPORT" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongoexport \- MongoDB . @@ -28,23 +30,25 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongoexport\fP is a utility that produces a JSON or CSV export +\fBmongoexport\fP is a utility that produces a JSON or CSV export of data stored in a MongoDB instance. See the -"\fB/administration/import\-export\fP" document for a more in depth -usage overview, and the "\fBmongoimport\fP" document for more +http://docs.mongodb.org/manual/core/import\-export document for a more in depth +usage overview, and the \fBmongoimport\fP document for more information regarding the \fBmongoimport\fP utility, which provides the inverse "importing" capability. -.IP Note -Do not use \fBmongoimport\fP and \fI\%mongoexport\fP for +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Do not use \fBmongoimport\fP and \fBmongoexport\fP for full\-scale backups because they may not reliably capture data type information. Use \fBmongodump\fP and \fBmongorestore\fP as -described in "\fB/administration/backups\fP" for this kind of +described in http://docs.mongodb.org/manual/core/backups for this kind of functionality. -.RE +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -52,6 +56,10 @@ functionality. .UNINDENT .INDENT 0.0 .TP +.B mongoexport +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -60,26 +68,28 @@ 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.) +the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongoexport\fP utility. +Returns the version of the \fBmongoexport\fP utility. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port> Specifies a resolvable hostname for the \fBmongod\fP from which you -want to export data. By default \fI\%mongoexport\fP attempts to +want to export data. By default \fBmongoexport\fP attempts to connect to a MongoDB process ruining on the localhost port number -\fB27017\fP. +\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, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -87,37 +97,45 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .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\%mongoexport --host\fP command. +number using the \fImongoexport \-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongoexport\fP to connect +Enables IPv6 support that allows \fBmongoexport\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongoexport\fP, disable IPv6 +and processes, including \fBmongoexport\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 mongoexport. -.IP Note +instances in mongoexport\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongoexport 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, mongoexport does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongoexport\fP to connect to \fBmongod\fP +Allows \fBmongoexport\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -125,135 +143,205 @@ 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\%mongoexport --password\fP option to supply a password. +\fImongoexport \-\-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\%mongoexport\fP -will prompt for a password interactively. +If you specify a \fI\-\-username\fP and +do not pass an argument to \fI\-\-password\fP, +\fBmongoexport\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\%mongoexport\fP assumes that the database specified to the -\fI\%--db\fP argument holds the user\(aqs credentials, unless you -specify \fI\%--authenticationDatabase\fP. +By default, \fBmongoexport\fP assumes that the database specified to the +\fI\-\-db\fP argument 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 +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\%mongoexport\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongoexport\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 -\fB\-\-dbpath\fP option enables \fI\%mongoexport\fP to attach +\fB\-\-dbpath\fP option enables \fBmongoexport\fP to attach directly to local data files and insert the data without the -\fBmongod\fP. To run with \fB\-\-dbpath\fP, \fI\%mongoexport\fP +\fBmongod\fP\&. To run with \fB\-\-dbpath\fP, \fBmongoexport\fP needs to lock access to the data directory: as a result, no \fBmongod\fP can access the same path while the process runs. .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb -Use the \fI\%--directoryperdb\fP in conjunction with the +Use the \fI\-\-directoryperdb\fP in conjunction with the corresponding option to \fBmongod\fP, which allows -\fI\%mongoexport\fP to export data into MongoDB instances that +\fBmongoexport\fP to export data from MongoDB instances that have every database\(aqs files saved in discrete directories on the disk. This option is only relevant when specifying the -\fI\%--dbpath\fP option. +\fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-journal -Allows \fI\%mongoexport\fP operations to access the durability +Allows \fBmongoexport\fP operations to access 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. +\fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-db <db>, \-d <db> -Use the \fI\%--db\fP option to specify the name of the database +Use the \fI\-\-db\fP option to specify the name of the database that contains the collection you want to export. .UNINDENT .INDENT 0.0 .TP .B \-\-collection <collection>, \-c <collection> -Use the \fI\%--collection\fP option to specify the collection -that you want \fI\%mongoexport\fP to export. +Use the \fI\-\-collection\fP option to specify the collection +that you want \fBmongoexport\fP to export. .UNINDENT .INDENT 0.0 .TP .B \-\-fields <field1[,field2]>, \-f <field1[,field2]> -Specify a field or number fields to \fIinclude\fP in the export. All -other fields will be \fIexcluded\fP from the export. Comma separate a -list of fields to limit the fields exported. +Specify a field or fields to \fIinclude\fP in the export. Use a comma +separated list of fields to specify multiple fields. +.sp +For \fI\-\-csv\fP output formats, +\fBmongoexport\fP includes only the specified field(s), and the +specified field(s) can be a field within a sub\-document. +.sp +For \fIJSON\fP output formats, \fBmongoexport\fP includes +only the specified field(s) \fBand\fP the \fB_id\fP field, and if the +specified field(s) is a field within a sub\-document, the +\fBmongoexport\fP includes the sub\-document with all +its fields, not just the specified field within the document. .UNINDENT .INDENT 0.0 .TP .B \-\-fieldFile <file> -As an alternative to "\fI\%--fields\fP" -the \fI\%--fieldFile\fP option allows you to specify a file -(e.g. \fB<file>\(ga\fP) to hold a list of field names to specify a list -of fields to \fIinclude\fP in the export. All other fields will be -\fIexcluded\fP from the export. Place one field per line. +As an alternative to \fI\-\-fields\fP, the +\fI\-\-fieldFile\fP option allows you to +specify in a file the field or fields to \fIinclude\fP in the export and +is \fBonly valid\fP with the \fI\-\-csv\fP +option. The file must have only one field per line, and the line(s) +must end with the LF character (\fB0x0A\fP). +.sp +\fBmongoexport\fP includes only the specified field(s). The +specified field(s) can be a field within a sub\-document. .UNINDENT .INDENT 0.0 .TP -.B \-\-query <JSON> +.B \-\-query <JSON>, \-q <JSON> Provides a \fIJSON document\fP as a query that optionally limits the documents returned in the export. +.INDENT 7.0 +.INDENT 3.5 +.SH EXAMPLE +.sp +Given a collection named \fBrecords\fP in the database \fBtest\fP +with the following documents: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "_id" : ObjectId("51f0188846a64a1ed98fde7c"), "a" : 1 } +{ "_id" : ObjectId("520e61b0c6646578e3661b59"), "a" : 1, "b" : 2 } +{ "_id" : ObjectId("520e642bb7fa4ea22d6b1871"), "a" : 2, "b" : 3, "c" : 5 } +{ "_id" : ObjectId("520e6431b7fa4ea22d6b1872"), "a" : 3, "b" : 3, "c" : 6 } +{ "_id" : ObjectId("520e6445b7fa4ea22d6b1873"), "a" : 5, "b" : 6, "c" : 8 } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The following \fBmongoexport\fP uses the \fI\-q\fP +option to export only the documents with the field \fBa\fP greater +than or equal to (\fB$gte\fP) to \fB3\fP: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoexport \-d test \-c records \-q "{ a: { \e$gte: 3 } } }" \-\-out exportdir/myRecords.json +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The resulting file contains the following documents: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "_id" : { "$oid" : "520e6431b7fa4ea22d6b1872" }, "a" : 3, "b" : 3, "c" : 6 } +{ "_id" : { "$oid" : "520e6445b7fa4ea22d6b1873" }, "a" : 5, "b" : 6, "c" : 8 } +.ft P +.fi +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-csv Changes the export format to a comma separated values (CSV) -format. By default \fI\%mongoexport\fP writes data using one +format. By default \fBmongoexport\fP writes data using one \fIJSON\fP document for every MongoDB document. +.sp +If you specify \fI\%--csv\fP, then you must also use either +the \fI\-\-fields\fP or the \fI\-\-fieldFile\fP option to +declare the fields to export from the collection. .UNINDENT .INDENT 0.0 .TP .B \-\-jsonArray -Modifies the output of \fI\%mongoexport\fP to write the +Modifies the output of \fBmongoexport\fP to write the entire contents of the export as a single \fIJSON\fP array. By -default \fI\%mongoexport\fP writes data using one JSON document +default \fBmongoexport\fP writes data using one JSON document for every MongoDB document. .UNINDENT .INDENT 0.0 .TP .B \-\-slaveOk, \-k -Allows \fI\%mongoexport\fP to read data from secondary or slave -nodes when using \fI\%mongoexport\fP with a replica set. This +Allows \fBmongoexport\fP to read data from secondary or slave +nodes when using \fBmongoexport\fP with a replica set. This option is only available if connected to a \fBmongod\fP or \fBmongos\fP and is not available when used with the -"\fI\%mongoexport --dbpath\fP" option. +"\fImongoexport \-\-dbpath\fP" option. .sp This is the default behavior. .UNINDENT @@ -261,17 +349,18 @@ This is the default behavior. .TP .B \-\-out <file>, \-o <file> Specify a file to write the export to. If you do not specify a file -name, the \fI\%mongoexport\fP writes data to standard output +name, the \fBmongoexport\fP writes data to standard output (e.g. \fBstdout\fP). .UNINDENT .INDENT 0.0 .TP .B \-\-forceTableScan New in version 2.2. + .sp -Forces \fI\%mongoexport\fP to scan the data store directly: -typically, \fI\%mongoexport\fP saves entries as they appear in the -index of the \fB_id\fP field. Use \fI\%--forceTableScan\fP to skip +Forces \fBmongoexport\fP to scan the data store directly: +typically, \fBmongoexport\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: .INDENT 7.0 @@ -282,70 +371,96 @@ 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\%mongoexport\fP -does not use \fB$snapshot\fP. As a result, the export produced -by \fI\%mongoexport\fP can reflect the state of the database at +When you run with \fI\-\-forceTableScan\fP, \fBmongoexport\fP +does not use \fB$snapshot\fP\&. As a result, the export produced +by \fBmongoexport\fP can reflect the state of the database at many different points in time. -.IP Warning -Use \fI\%--forceTableScan\fP with extreme caution +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +Use \fI\-\-forceTableScan\fP with extreme caution and consideration. -.RE +.UNINDENT +.UNINDENT .UNINDENT .SH USAGE .sp -In the following example, \fI\%mongoexport\fP exports the +In the following example, \fBmongoexport\fP exports the collection \fBcontacts\fP from the \fBusers\fP database from the -\fBmongod\fP instance running on the localhost port -number \fB27017\fP. This command writes the export data in \fICSV\fP -format into a file located at \fB/opt/backups/contacts.csv\fP. +\fBmongod\fP instance running on the localhost port number +\fB27017\fP\&. This command writes the export data in \fICSV\fP format +into a file located at \fB/opt/backups/contacts.csv\fP\&. The +\fBfields.txt\fP file contains a line\-separated list of fields to +export. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C -mongoexport \-\-db users \-\-collection contacts \-\-csv \-\-out /opt/backups/contacts.csv +mongoexport \-\-db users \-\-collection contacts \-\-csv \-\-fieldFile fields.txt \-\-out /opt/backups/contacts.csv .ft P .fi +.UNINDENT +.UNINDENT .sp The next example creates an export of the collection \fBcontacts\fP from the MongoDB instance running on the localhost port number \fB27017\fP, with journaling explicitly enabled. This writes the export to the \fBcontacts.json\fP file in \fIJSON\fP format. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoexport \-\-db sales \-\-collection contacts \-\-out contacts.json \-\-journal .ft P .fi +.UNINDENT +.UNINDENT .sp The following example exports the collection \fBcontacts\fP from the \fBsales\fP database located in the MongoDB data files located at -\fB/srv/mongodb/\fP. This operation writes the export to standard output +\fB/srv/mongodb/\fP\&. This operation writes the export to standard output in \fIJSON\fP format. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoexport \-\-db sales \-\-collection contacts \-\-dbpath /srv/mongodb/ .ft P .fi -.IP Warning +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 The above example will only succeed if there is no \fBmongod\fP connected to the data files located in the \fB/srv/mongodb/\fP directory. -.RE +.UNINDENT +.UNINDENT .sp The final example exports the collection \fBcontacts\fP from the database \fBmarketing\fP . This data resides on the MongoDB instance located on the host \fBmongodb1.example.net\fP running on port \fB37017\fP, which requires the username \fBuser\fP and the password -\fBpass\fP. +\fBpass\fP\&. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoexport \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass \-\-collection contacts \-\-db marketing \-\-out mdb1\-examplenet.json .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. . diff --git a/debian/mongofiles.1 b/debian/mongofiles.1 index e6b40b1512d..95434b1e0ac 100644 --- a/debian/mongofiles.1 +++ b/debian/mongofiles.1 @@ -1,4 +1,6 @@ -.TH "MONGOFILES" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOFILES" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongofiles \- MongoDB . @@ -28,82 +30,56 @@ 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. -. .SH SYNOPSIS .sp -The \fI\%mongofiles\fP utility makes it possible to manipulate files +The \fBmongofiles\fP utility makes it possible to manipulate files stored in your MongoDB instance in \fIGridFS\fP objects from the command line. It is particularly useful as it provides an interface between objects stored in your file system and GridFS. .sp -All \fI\%mongofiles\fP commands take arguments in three groups: +All \fBmongofiles\fP commands have the following form: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongofiles <options> <commands> <filename> +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The components of the \fBmongofiles\fP command are: .INDENT 0.0 .IP 1. 3 -\fI\%Options\fP. You may use one or more of -these options to control the behavior of \fI\%mongofiles\fP. +\fI\%Options\fP\&. You may use one or more of +these options to control the behavior of \fBmongofiles\fP\&. .IP 2. 3 -\fI\%Commands\fP. Use one of these commands to -determine the action of \fI\%mongofiles\fP. +\fI\%Commands\fP\&. Use one of these commands to +determine the action of \fBmongofiles\fP\&. .IP 3. 3 -A file name representing either the name of a file on your system\(aqs -file system, a GridFS object. +A filename which is either: the name of a file on your local\(aqs file +system, or a GridFS object. .UNINDENT .sp -\fI\%mongofiles\fP, like \fBmongodump\fP, \fBmongoexport\fP, +\fBmongofiles\fP, like \fBmongodump\fP, \fBmongoexport\fP, \fBmongoimport\fP, and \fBmongorestore\fP, can access data stored in a MongoDB data directory without requiring a running \fBmongod\fP instance, if no other \fBmongod\fP is running. -.IP Note -For \fIreplica sets\fP, \fI\%mongofiles\fP can -only read from the set\(aqs \(aq\fIprimary\fP. -.RE -.SH COMMANDS -.INDENT 0.0 -.TP -.B mongofiles -.UNINDENT -.INDENT 0.0 -.TP -.B list <prefix> -Lists the files in the GridFS store. The characters specified after -\fBlist\fP (e.g. \fB<prefix>\fP) optionally limit the list of -returned items to files that begin with that string of characters. -.UNINDENT -.INDENT 0.0 -.TP -.B search <string> -Lists the files in the GridFS store with names that match any -portion of \fB<string>\fP. -.UNINDENT -.INDENT 0.0 -.TP -.B put <filename> -Copy the specified file from the local file system into GridFS -storage. .sp -Here, \fB<filename>\fP refers to the name the object will have in -GridFS, and \fI\%mongofiles\fP assumes that this reflects the name the -file has on the local file system. If the local filename is -different use the \fI\%mongofiles --local\fP option. -.UNINDENT +\fBIMPORTANT:\fP .INDENT 0.0 -.TP -.B get <filename> -Copy the specified file from GridFS storage to the local file -system. -.sp -Here, \fB<filename>\fP refers to the name the object will have in -GridFS, and \fI\%mongofiles\fP assumes that this reflects the name the -file has on the local file system. If the local filename is -different use the \fI\%mongofiles --local\fP option. +.INDENT 3.5 +For \fIreplica sets\fP, +\fBmongofiles\fP can only read from the set\(aqs +\(aq\fIprimary\fP\&. +.UNINDENT .UNINDENT +.SH OPTIONS .INDENT 0.0 .TP -.B delete <filename> -Delete the specified file from GridFS storage. +.B mongofiles .UNINDENT -.SH OPTIONS .INDENT 0.0 .TP .B \-\-help @@ -114,20 +90,20 @@ 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.) +the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongofiles\fP utility. +Returns the version of the \fBmongofiles\fP utility. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port> Specifies a resolvable hostname for the \fBmongod\fP that -holds your GridFS system. By default \fI\%mongofiles\fP attempts +holds your GridFS system. By default \fBmongofiles\fP attempts to connect to a MongoDB process ruining on the localhost port -number \fB27017\fP. +number \fB27017\fP\&. .sp Optionally, specify a port number to connect a MongoDB instance running on a port other than 27017. @@ -137,32 +113,38 @@ running on a port other than 27017. .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\%mongofiles --host\fP command. +number using the \fImongofiles \-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongofiles\fP to connect +Enables IPv6 support that allows \fBmongofiles\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongofiles\fP, disable IPv6 +and processes, including \fBmongofiles\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 mongofiles. -.IP Note +instances in mongofiles\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongofiles 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, mongofiles does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongofiles\fP to connect to \fBmongod\fP +Allows \fBmongofiles\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -170,82 +152,86 @@ 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\%mongofiles --password\fP option to supply a password. +\fImongofiles \-\-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\%mongofiles --username\fP option to +in conjunction with the \fImongofiles \-\-username\fP option to supply a username. .sp -If you specify a \fI\%--username\fP -without the \fI\%--password\fP option, \fI\%mongofiles\fP -will prompt for a password interactively. +If you specify a \fI\-\-username\fP and +do not pass an argument to \fI\-\-password\fP, +\fBmongofiles\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\%mongofiles\fP assumes that the database specified to the -\fI\%--db\fP argument holds the user\(aqs credentials, unless you -specify \fI\%--authenticationDatabase\fP. +By default, \fBmongofiles\fP assumes that the database specified to the +\fI\-\-db\fP argument 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 +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\%mongofiles\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongofiles\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\%mongofiles\fP to attach directly to +\fI\-\-dbpath\fP option enables \fBmongofiles\fP to attach directly to local data files interact with the GridFS data without the -\fBmongod\fP. To run with \fI\%--dbpath\fP, \fI\%mongofiles\fP needs to lock +\fBmongod\fP\&. To run with \fI\-\-dbpath\fP, \fBmongofiles\fP needs to lock access to the data directory: as a result, no \fBmongod\fP can access the same path while the process runs. .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb -Use the \fI\%--directoryperdb\fP in conjunction with the corresponding -option to \fBmongod\fP, which allows \fI\%mongofiles\fP when -running with the \fI\%--dbpath\fP option and MongoDB uses an +Use the \fI\-\-directoryperdb\fP in conjunction with the corresponding +option to \fBmongod\fP, which allows \fBmongofiles\fP when +running with the \fI\-\-dbpath\fP option and MongoDB uses an on\-disk format where every database has a distinct directory. This option is only relevant when specifying the -\fI\%--dbpath\fP option. +\fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-journal -Allows \fI\%mongofiles\fP operations to use the durability -\fIjournal\fP when running with \fI\%--dbpath\fP +Allows \fBmongofiles\fP operations to use the durability +\fIjournal\fP when running with \fI\-\-dbpath\fP to ensure that the database maintains a recoverable state. This -forces \fI\%mongofiles\fP to record all data on disk regularly. +forces \fBmongofiles\fP to record all data on disk regularly. .UNINDENT .INDENT 0.0 .TP .B \-\-db <db>, \-d <db> -Use the \fI\%--db\fP option to specify the MongoDB database that stores +Use the \fI\-\-db\fP option to specify the MongoDB database that stores or will store the GridFS files. .UNINDENT .INDENT 0.0 @@ -262,7 +248,7 @@ operations. .sp In the \fBmongofiles put\fP and \fBmongofiles get\fP commands the required \fB<filename>\fP modifier refers to the name -the object will have in GridFS. \fI\%mongofiles\fP assumes that +the object will have in GridFS. \fBmongofiles\fP assumes that this reflects the file\(aqs name on the local file system. This setting overrides this default. .UNINDENT @@ -270,7 +256,7 @@ system. This setting overrides this default. .TP .B \-\-type <MIME>, t <MIME> Provides the ability to specify a \fIMIME\fP type to describe the -file inserted into GridFS storage. \fI\%mongofiles\fP omits this +file inserted into GridFS storage. \fBmongofiles\fP omits this option in the default operation. .sp Use only with \fBmongofiles put\fP operations. @@ -285,21 +271,68 @@ adding an additional object with the same name. In the default operation, files will not be overwritten by a \fBmongofiles put\fP option. .UNINDENT -.SH USE +.SH COMMANDS +.INDENT 0.0 +.TP +.B list <prefix> +Lists the files in the GridFS store. The characters specified after +\fBlist\fP (e.g. \fB<prefix>\fP) optionally limit the list of +returned items to files that begin with that string of characters. +.UNINDENT +.INDENT 0.0 +.TP +.B search <string> +Lists the files in the GridFS store with names that match any +portion of \fB<string>\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B put <filename> +Copy the specified file from the local file system into GridFS +storage. +.sp +Here, \fB<filename>\fP refers to the name the object will have in +GridFS, and \fBmongofiles\fP assumes that this reflects the name the +file has on the local file system. If the local filename is +different use the \fImongofiles \-\-local\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B get <filename> +Copy the specified file from GridFS storage to the local file +system. +.sp +Here, \fB<filename>\fP refers to the name the object will have in +GridFS, and \fBmongofiles\fP assumes that this reflects the name the +file has on the local file system. If the local filename is +different use the \fImongofiles \-\-local\fP option. +.UNINDENT +.INDENT 0.0 +.TP +.B delete <filename> +Delete the specified file from GridFS storage. +.UNINDENT +.SH EXAMPLES .sp To return a list of all files in a \fIGridFS\fP collection in the \fBrecords\fP database, use the following invocation at the system shell: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records list .ft P .fi +.UNINDENT +.UNINDENT .sp -This \fI\%mongofiles\fP instance will connect to the +This \fBmongofiles\fP instance will connect to the \fBmongod\fP instance running on the \fB27017\fP localhost interface to specify the same operation on a different port or hostname, and issue a command that resembles one of the following: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -308,58 +341,80 @@ mongofiles \-\-hostname db1.example.net \-d records list mongofiles \-\-hostname db1.example.net \-\-port 37017 \-d records list .ft P .fi +.UNINDENT +.UNINDENT .sp Modify any of the following commands as needed if you\(aqre connecting the \fBmongod\fP instances on different ports or hosts. .sp To upload a file named \fB32\-corinth.lp\fP to the GridFS collection in the \fBrecords\fP database, you can use the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records put 32\-corinth.lp .ft P .fi +.UNINDENT +.UNINDENT .sp To delete the \fB32\-corinth.lp\fP file from this GridFS collection in the \fBrecords\fP database, you can use the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records delete 32\-corinth.lp .ft P .fi +.UNINDENT +.UNINDENT .sp To search for files in the GridFS collection in the \fBrecords\fP database that have the string \fBcorinth\fP in their names, you can use following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records search corinth .ft P .fi +.UNINDENT +.UNINDENT .sp To list all files in the GridFS collection in the \fBrecords\fP database that begin with the string \fB32\fP, you can use the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records list 32 .ft P .fi +.UNINDENT +.UNINDENT .sp To fetch the file from the GridFS collection in the \fBrecords\fP database named \fB32\-corinth.lp\fP, you can use the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongofiles \-d records get 32\-corinth.lp .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. . diff --git a/debian/mongoimport.1 b/debian/mongoimport.1 index 22313c05cc6..28afbb21649 100644 --- a/debian/mongoimport.1 +++ b/debian/mongoimport.1 @@ -1,4 +1,6 @@ -.TH "MONGOIMPORT" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOIMPORT" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongoimport \- MongoDB . @@ -28,24 +30,26 @@ 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. -. .SH SYNOPSIS .sp -The \fI\%mongoimport\fP tool provides a route to import content from a +The \fBmongoimport\fP tool provides a route to import content from a JSON, CSV, or TSV export created by \fBmongoexport\fP, or potentially, another third\-party export tool. See the -"\fB/administration/import\-export\fP" document for a more in depth -usage overview, and the "\fBmongoexport\fP" document for more +http://docs.mongodb.org/manual/core/import\-export document for a more in depth +usage overview, and the \fBmongoexport\fP document for more information regarding \fBmongoexport\fP, which provides the inverse "importing" capability. -.IP Note -Do not use \fI\%mongoimport\fP and \fBmongoexport\fP for +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Do not use \fBmongoimport\fP and \fBmongoexport\fP for full instance, production backups because they will not reliably capture data type information. Use \fBmongodump\fP and \fBmongorestore\fP as -described in "\fB/administration/backups\fP" for this kind of +described in http://docs.mongodb.org/manual/core/backups for this kind of functionality. -.RE +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -53,6 +57,10 @@ functionality. .UNINDENT .INDENT 0.0 .TP +.B mongoimport +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -61,35 +69,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.) +the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongoimport\fP program. +Returns the version of the \fBmongoimport\fP program. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port>, \-h Specifies a resolvable hostname for the \fBmongod\fP to which -you want to restore the database. By default \fI\%mongoimport\fP +you want to restore the database. By default \fBmongoimport\fP will attempt to connect to a MongoDB process ruining on the -localhost port numbered \fB27017\fP. +localhost port numbered \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 argument with a +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 and -port names. \fI\%mongoimport\fP will, given the seed of at least -one connected set member, connect to primary node of that set. This +port names. \fBmongoimport\fP will, given the seed of at least +one connected set member, connect to the \fIprimary\fP of that set. This option would resemble: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C \-\-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 +111,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\%mongoimport --host\fP command. +number using the \fImongoimport \-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongoimport\fP to connect +Enables IPv6 support that allows \fBmongoimport\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongoimport\fP, disable IPv6 +and processes, including \fBmongoimport\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 mongoimport. -.IP Note +instances in mongoimport\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongoimport 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, mongoimport does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongoimport\fP to connect to \fBmongod\fP +Allows \fBmongoimport\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -132,70 +150,74 @@ 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\%mongoimport --password\fP option to supply a password. +\fImongoimport \-\-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\%mongoimport --username\fP option to +in conjunction with the \fImongoimport \-\-username\fP option to supply a username. .sp -If you specify a \fI\%--username\fP -without the \fI\%--password\fP option, \fI\%mongoimport\fP -will prompt for a password interactively. +If you specify a \fI\-\-username\fP and +do not pass an argument to \fI\-\-password\fP, +\fBmongoimport\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 option. .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\%mongoimport\fP assumes that the database specified to the -\fI\%--db\fP argument holds the user\(aqs credentials, unless you -specify \fI\%--authenticationDatabase\fP. +By default, \fBmongoimport\fP assumes that the database specified to the +\fI\-\-db\fP argument 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 +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\%mongoimport\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongoimport\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\%mongoimport\fP to attach directly to local data files and -insert the data without the \fBmongod\fP. To run with -\fB\-\-dbpath\fP, \fI\%mongoimport\fP needs to lock access to the +\fI\-\-dbpath\fP option enables +\fBmongoimport\fP to attach directly to local data files and +insert the data without the \fBmongod\fP\&. To run with +\fB\-\-dbpath\fP, \fBmongoimport\fP needs to lock access to the data directory: as a result, no \fBmongod\fP can access the same path while the process runs. .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb -Use the \fI\%--directoryperdb\fP in conjunction with the +Use the \fI\-\-directoryperdb\fP in conjunction with the corresponding option to \fBmongod\fP, which allows -\fI\%mongoimport\fP to import data into MongoDB instances that +\fBmongoimport\fP to import data into MongoDB instances that have every database\(aqs files saved in discrete directories on the disk. This option is only relevant when specifying the -\fI\%--dbpath\fP option. +\fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP @@ -203,33 +225,24 @@ disk. This option is only relevant when specifying the Allows \fBmongoexport\fP write to the durability \fIjournal\fP to ensure that the data files will remain in a consistent state during the write process. This option is only -relevant when specifying the \fI\%--dbpath\fP option. +relevant when specifying the \fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-db <db>, \-d <db> -Use the \fI\%--db\fP option to specify a database for -\fI\%mongoimport\fP to restore data. If you do not specify a -\fB<db>\fP, \fI\%mongoimport\fP creates new databases that -correspond to the databases where data originated and data may be -overwritten. Use this option to restore data into a MongoDB -instance that already has data, or to restore only some data in the -specified backup. +Use the \fI\-\-db\fP option to specify a database for +\fBmongoimport\fP to import data. .UNINDENT .INDENT 0.0 .TP .B \-\-collection <collection>, \-c <collection> -Use the \fI\%--collection\fP option to specify a collection for -\fBmongorestore\fP to restore. If you do not specify a -\fB<collection>\fP, \fI\%mongoimport\fP imports all collections -created. Existing data may be overwritten. Use this option to -restore data into a MongoDB instance that already has data, or to -restore only some data in the specified imported data set. +Use the \fI\-\-collection\fP option to specify a collection for +\fBmongoimport\fP to import. .UNINDENT .INDENT 0.0 .TP -.B \-\-fields <field1<,filed2>>, \-f <field1[,filed2]> -Specify a comma seperatedlist of field names when importing +.B \-\-fields <field1<,field2>>, \-f <field1[,field2]> +Specify a comma separated list of field names when importing \fIcsv\fP or \fItsv\fP files that do not have field names in the first (i.e. header) line of the file. .UNINDENT @@ -237,7 +250,7 @@ the first (i.e. header) line of the file. .TP .B \-\-fieldFile <filename> As an alternative to \fI\%--fields\fP the \fI\%--fieldFile\fP -option allows you to specify a file (e.g. \fB<file>\(ga\fP) to that +option allows you to specify a file (e.g. \fB<file>\fP) to that holds a list of field names if your \fIcsv\fP or \fItsv\fP file does not include field names in the first (i.e. header) line of the file. Place one field per line. @@ -246,7 +259,7 @@ of the file. Place one field per line. .TP .B \-\-ignoreBlanks In \fIcsv\fP and \fItsv\fP exports, ignore empty fields. If not -specified, \fI\%mongoimport\fP creates fields without values in +specified, \fBmongoimport\fP creates fields without values in imported documents. .UNINDENT .INDENT 0.0 @@ -260,22 +273,22 @@ Declare the type of export format to import. The default format is .TP .B \-\-file <filename> Specify the location of a file containing the data to -import. \fI\%mongoimport\fP will read data from standard input +import. \fBmongoimport\fP will read data from standard input (e.g. "stdin.") if you do not specify a file. .UNINDENT .INDENT 0.0 .TP .B \-\-drop -Modifies the importation procedure so that the target instance -drops every collection before restoring the collection from the -dumped backup. +Modifies the import process so that the target instance +drops every collection before importing the collection from the +input. .UNINDENT .INDENT 0.0 .TP .B \-\-headerline -If using "\fI\%--type csv\fP" or -"\fI\%--type tsv\fP," use the first line as -field names. Otherwise, \fI\%mongoimport\fP will import the first +If using "\fI\-\-type csv\fP" or +"\fI\-\-type tsv\fP," use the first line as +field names. Otherwise, \fBmongoimport\fP will import the first line as a distinct document. .UNINDENT .INDENT 0.0 @@ -286,14 +299,14 @@ database if they match an imported object, while inserting all other objects. .sp If you do not specify a field or fields using the -\fI\%--upsertFields\fP \fI\%mongoimport\fP will upsert on the +\fI\%--upsertFields\fP \fBmongoimport\fP will upsert on the basis of the \fB_id\fP field. .UNINDENT .INDENT 0.0 .TP .B \-\-upsertFields <field1[,field2]> Specifies a list of fields for the query portion of the -\fIupsert\fP. Use this option if the \fB_id\fP fields in the +\fIupsert\fP\&. Use this option if the \fB_id\fP fields in the existing documents don\(aqt match the field in the document, but another field or field combination can uniquely identify documents as a basis for performing upsert operations. @@ -305,16 +318,18 @@ field or fields. .TP .B \-\-stopOnError New in version 2.2. + .sp -Forces \fI\%mongoimport\fP to halt the import operation at the +Forces \fBmongoimport\fP to halt the import operation at the first error rather than continuing the operation despite errors. .UNINDENT .INDENT 0.0 .TP .B \-\-jsonArray Changed in version 2.2: The limit on document size increased from 4MB to 16MB. + .sp -Accept import of data expressed with multiple MongoDB document +Accept import of data expressed with multiple MongoDB documents within a single \fIJSON\fP array. .sp Use in conjunction with \fImongoexport \-\-jsonArray\fP to @@ -323,57 +338,73 @@ imports of 16 MB or smaller. .UNINDENT .SH USAGE .sp -In this example, \fI\%mongoimport\fP imports the \fIcsv\fP +In this example, \fBmongoimport\fP imports the \fIcsv\fP formatted data in the \fB/opt/backups/contacts.csv\fP into the collection \fBcontacts\fP in the \fBusers\fP database on the MongoDB -instance running on the localhost port numbered \fB27017\fP. +instance running on the localhost port numbered \fB27017\fP\&. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoimport \-\-db users \-\-collection contacts \-\-type csv \-\-file /opt/backups/contacts.csv .ft P .fi +.UNINDENT +.UNINDENT .sp -In the following example, \fI\%mongoimport\fP imports the data in +In the following example, \fBmongoimport\fP imports the data in the \fIJSON\fP formatted file \fBcontacts.json\fP into the collection \fBcontacts\fP on the MongoDB instance running on the localhost port number 27017. Journaling is explicitly enabled. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C -mongoimport \-\-collection contacts \-\-file contacts.json \-\-journal +mongoimport \-\-collection contacts \-\-file contacts.json .ft P .fi +.UNINDENT +.UNINDENT .sp -In the next example, \fI\%mongoimport\fP takes data passed to it on +In the next example, \fBmongoimport\fP takes data passed to it on standard input (i.e. with a \fB|\fP pipe.) and imports it into the collection \fBcontacts\fP in the \fBsales\fP database is the -MongoDB datafiles located at \fB/srv/mongodb/\fP. if the import process -encounters an error, the \fI\%mongoimport\fP will halt because of -the \fI\%--stopOnError\fP option. +MongoDB datafiles located at \fB/srv/mongodb/\fP\&. if the import process +encounters an error, the \fBmongoimport\fP will halt because of +the \fI\-\-stopOnError\fP option. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoimport \-\-db sales \-\-collection contacts \-\-stopOnError \-\-dbpath /srv/mongodb/ .ft P .fi +.UNINDENT +.UNINDENT .sp -In the final example, \fI\%mongoimport\fP imports data from the +In the final example, \fBmongoimport\fP imports data from the file \fB/opt/backups/mdb1\-examplenet.json\fP into the collection \fBcontacts\fP within the database \fBmarketing\fP on a remote MongoDB -database. This \fI\%mongoimport\fP accesses the \fBmongod\fP +database. This \fBmongoimport\fP accesses the \fBmongod\fP instance running on the host \fBmongodb1.example.net\fP over port \fB37017\fP, which requires the username \fBuser\fP and the password -\fBpass\fP. +\fBpass\fP\&. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoimport \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass \-\-collection contacts \-\-db marketing \-\-file /opt/backups/mdb1\-examplenet.json .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. . diff --git a/debian/mongooplog.1 b/debian/mongooplog.1 index c6e2e27866e..f23ed638aa9 100644 --- a/debian/mongooplog.1 +++ b/debian/mongooplog.1 @@ -1,4 +1,6 @@ -.TH "MONGOOPLOG" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOOPLOG" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongooplog \- MongoDB . @@ -28,43 +30,53 @@ 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. -. .sp New in version 2.2. + .SH SYNOPSIS .sp -\fI\%mongooplog\fP is a simple tool that polls operations from +\fBmongooplog\fP is a simple tool that polls operations from the \fIreplication\fP \fIoplog\fP of a remote server, and applies them to the local server. This capability supports certain classes of real\-time migrations that require that the source server remain online and in operation throughout the migration process. .sp Typically this command will take the following form: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongooplog \-\-from mongodb0.example.net \-\-host mongodb1.example.net .ft P .fi +.UNINDENT +.UNINDENT .sp This command copies oplog entries from the \fBmongod\fP instance running on the host \fBmongodb0.example.net\fP and duplicates -operations to the host \fBmongodb1.example.net\fP. If you do not need -to keep the \fI\%--from\fP host running during +operations to the host \fBmongodb1.example.net\fP\&. If you do not need +to keep the \fI\-\-from\fP host running during the migration, consider using \fBmongodump\fP and \fBmongorestore\fP or another \fBbackup\fP operation, which may be better suited to your operation. -.IP Note -If the \fBmongod\fP instance specified by the \fI\%--from\fP +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +If the \fBmongod\fP instance specified by the \fI\-\-from\fP argument is running with \fBauthentication\fP, then -\fI\%mongooplog\fP will not be able to copy oplog entries. -.RE -.IP "See also" +\fBmongooplog\fP will not be able to copy oplog entries. +.UNINDENT +.UNINDENT .sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 \fBmongodump\fP, \fBmongorestore\fP, -"\fB/administration/backups\fP", "\fIOplog Internals Overview\fP", and "\fIReplica Set Oplog Sizing\fP". -.RE +http://docs.mongodb.org/manual/core/backups, http://docs.mongodb.org/manual/core/replica\-set\-oplog\&. +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -72,6 +84,10 @@ argument is running with \fBauthentication\fP, then .UNINDENT .INDENT 0.0 .TP +.B mongooplog +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -80,23 +96,23 @@ 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\%mongooplog\fP utility. +Returns the version of the \fBmongooplog\fP utility. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port>, \-h Specifies a resolvable hostname for the \fBmongod\fP instance -to which \fI\%mongooplog\fP will apply \fIoplog\fP operations -retrieved from the serve specified by the \fI\%--from\fP +to which \fBmongooplog\fP will apply \fIoplog\fP operations +retrieved from the serve specified by the \fI\-\-from\fP option. .sp -\fI\%mongooplog\fP assumes that all target \fBmongod\fP -instances are accessible by way of port \fB27017\fP. You may, +\fBmongooplog\fP assumes that all target \fBmongod\fP +instances are accessible by way of port \fB27017\fP\&. You may, optionally, declare an alternate port number as part of the hostname argument. .sp @@ -105,6 +121,8 @@ instance by specifying the host and port number directly. .sp To connect to a replica set, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -112,39 +130,47 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B \-\-port Specifies the port number of the \fBmongod\fP instance where -\fI\%mongooplog\fP will apply \fIoplog\fP entries. Only +\fBmongooplog\fP will apply \fIoplog\fP entries. Only specify this option if the MongoDB instance that you wish to connect to is not running on the standard port. (i.e. \fB27017\fP) -You may also specify a port number using the \fI\%--host\fP command. +You may also specify a port number using the \fI\-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongooplog\fP to connect +Enables IPv6 support that allows \fBmongooplog\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongooplog\fP, disable IPv6 +and processes, including \fBmongooplog\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 mongooplog. -.IP Note +instances in mongooplog\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongooplog 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, mongooplog does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongooplog\fP to connect to \fBmongod\fP +Allows \fBmongooplog\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -152,122 +178,109 @@ 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\%mongooplog\fP will -prompt for a password interactively. +If you specify a \fI\-\-username\fP and +do not pass an argument to \fI\-\-password\fP, +\fBmongooplog\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 option. .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\%mongooplog\fP assumes that the database specified to the +By default, \fBmongooplog\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\%mongooplog\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongooplog\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 a directory, containing MongoDB data files, to which -\fI\%mongooplog\fP will apply operations from the \fIoplog\fP -of the database specified with the \fI\%--from\fP -option. When used, the \fI\%--dbpath\fP option enables +\fBmongooplog\fP will apply operations from the \fIoplog\fP +of the database specified with the \fI\-\-from\fP +option. When used, the \fI\-\-dbpath\fP option enables \fBmongo\fP to attach directly to local data files and write data without a running \fBmongod\fP instance. To run with -\fI\%--dbpath\fP, \fI\%mongooplog\fP needs to restrict access +\fI\-\-dbpath\fP, \fBmongooplog\fP needs to restrict access to the data directory: as a result, no \fBmongod\fP can be access the same path while the process runs. .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb -Use the \fI\%--directoryperdb\fP in conjunction with the -corresponding option to \fBmongod\fP. This option allows -\fI\%mongooplog\fP to write to data files organized with each +Use the \fI\-\-directoryperdb\fP in conjunction with the +corresponding option to \fBmongod\fP\&. This option allows +\fBmongooplog\fP to write to data files organized with each database located in a distinct directory. This option is only -relevant when specifying the \fI\%--dbpath\fP option. +relevant when specifying the \fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-journal -Allows \fI\%mongooplog\fP operations to use the durability +Allows \fBmongooplog\fP operations to use the durability \fIjournal\fP to ensure that the data files will remain in a consistent state during the writing process. This -option is only relevant when specifying the \fI\%--dbpath\fP +option is only relevant when specifying the \fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP -.B \-\-fields [field1[,field2]], \-f [field1[,field2]] -Specify a field or number fields to constrain which data -\fI\%mongooplog\fP will migrate. All other fields will be -\fIexcluded\fP from the migration. Comma separate a list of fields to -limit the applied fields. -.UNINDENT -.INDENT 0.0 -.TP -.B \-\-fieldFile <file> -As an alternative to "\fI\%--fields\fP" the -\fI\%--fieldFile\fP option allows you to specify a file -(e.g. \fB<file>\fP) that holds a list of field names to \fIinclude\fP in -the migration. All other fields will be \fIexcluded\fP from the -migration. Place one field per line. -.UNINDENT -.INDENT 0.0 -.TP .B \-\-seconds <number>, \-s <number> -Specify a number of seconds of operations for \fI\%mongooplog\fP -to pull from the \fI\%remote host\fP. Unless +Specify a number of seconds of operations for \fBmongooplog\fP +to pull from the \fIremote host\fP\&. Unless specified the default value is \fB86400\fP seconds, or 24 hours. .UNINDENT .INDENT 0.0 .TP .B \-\-from <host[:port]> -Specify the host for \fI\%mongooplog\fP to retrieve \fIoplog\fP -operations from. \fI\%mongooplog\fP \fIrequires\fP this +Specify the host for \fBmongooplog\fP to retrieve \fIoplog\fP +operations from. \fBmongooplog\fP \fIrequires\fP this option. .sp -Unless you specify the \fI\%--host\fP option, -\fI\%mongooplog\fP will apply the operations collected with this +Unless you specify the \fI\-\-host\fP option, +\fBmongooplog\fP will apply the operations collected with this option to the oplog of the \fBmongod\fP instance running on -the localhost interface connected to port \fB27017\fP. +the localhost interface connected to port \fB27017\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-oplogns <namespace> -Specify a namespace in the \fI\%--from\fP +Specify a namespace in the \fI\-\-from\fP host where the oplog resides. The default value is \fBlocal.oplog.rs\fP, which is the where \fIreplica set\fP members store their operation log. However, if you\(aqve copied \fIoplog\fP @@ -275,72 +288,77 @@ entries into another database or collection, use this option to copy oplog entries stored in another location. .sp \fINamespaces\fP take the form of -\fB[database].[collection]\fP. +\fB[database].[collection]\fP\&. .UNINDENT .SS Usage .sp -Consider the following prototype \fI\%mongooplog\fP command: +Consider the following prototype \fBmongooplog\fP command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongooplog \-\-from mongodb0.example.net \-\-host mongodb1.example.net .ft P .fi +.UNINDENT +.UNINDENT .sp Here, entries from the \fIoplog\fP of the \fBmongod\fP running -on port \fB27017\fP. This only pull entries from the last 24 hours. -.sp -In the next command, the parameters limit this operation to only apply -operations to the database \fBpeople\fP in the collection \fBusage\fP on -the target host (i.e. \fBmongodb1.example.net\fP): +on port \fB27017\fP\&. This only pull entries from the last 24 hours. .sp -.nf -.ft C -mongooplog \-\-from mongodb0.example.net \-\-host mongodb1.example.net \-\-database people \-\-collection usage -.ft P -.fi -.sp -This operation only applies oplog entries from the last 24 hours. Use -the \fI\%--seconds\fP argument to capture a -greater or smaller amount of time. Consider the following example: +Use the \fI\-\-seconds\fP argument to capture +a greater or smaller amount of time. Consider the following example: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongooplog \-\-from mongodb0.example.net \-\-seconds 172800 .ft P .fi +.UNINDENT +.UNINDENT .sp -In this operation, \fI\%mongooplog\fP captures 2 full days of +In this operation, \fBmongooplog\fP captures 2 full days of operations. To migrate 12 hours of \fIoplog\fP entries, use the following form: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongooplog \-\-from mongodb0.example.net \-\-seconds 43200 .ft P .fi +.UNINDENT +.UNINDENT .sp -For the previous two examples, \fI\%mongooplog\fP migrates entries +For the previous two examples, \fBmongooplog\fP migrates entries to the \fBmongod\fP process running on the localhost interface -connected to the \fB27017\fP port. \fI\%mongooplog\fP can also +connected to the \fB27017\fP port. \fBmongooplog\fP can also operate directly on MongoDB\(aqs data files if no \fBmongod\fP is running on the \fItarget\fP host. Consider the following example: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongooplog \-\-from mongodb0.example.net \-\-dbpath /srv/mongodb \-\-journal .ft P .fi +.UNINDENT +.UNINDENT .sp -Here, \fI\%mongooplog\fP imports \fIoplog\fP operations from the -\fBmongod\fP host connected to port \fB27017\fP. This migrates +Here, \fBmongooplog\fP imports \fIoplog\fP operations from the +\fBmongod\fP host connected to port \fB27017\fP\&. This migrates operations to the MongoDB data files stored in the \fB/srv/mongodb\fP -directory. Additionally \fI\%mongooplog\fP will use the durability +directory. Additionally \fBmongooplog\fP will use the durability \fIjournal\fP to ensure that the data files remain in a consistent state. .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, 10gen, Inc. +2011-2013, MongoDB, Inc. .\" Generated by docutils manpage writer. . diff --git a/debian/mongoperf.1 b/debian/mongoperf.1 index 8404a263c7d..3fb4fcbff19 100644 --- a/debian/mongoperf.1 +++ b/debian/mongoperf.1 @@ -1,4 +1,6 @@ -.TH "MONGOPERF" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOPERF" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongoperf \- MongoDB . @@ -28,21 +30,22 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongoperf\fP is a utility to check disk I/O performance +\fBmongoperf\fP is a utility to check disk I/O performance independently of MongoDB. .sp It times tests of random disk I/O and presents the results. You can -use \fI\%mongoperf\fP for any case apart from MongoDB. The -\fI\%mmf\fP \fBtrue\fP mode is completely generic. In -that mode is it somewhat analogous to tools such as \fI\%bonnie++\fP (albeit mongoperf is +use \fBmongoperf\fP for any case apart from MongoDB. The +\fBmmf\fP \fBtrue\fP mode is completely generic. In +that mode it is somewhat analogous to tools such as \fI\%bonnie++\fP (albeit mongoperf is simpler). .sp -Specify options to \fI\%mongoperf\fP using a JavaScript document. -.IP "See also" +Specify options to \fBmongoperf\fP using a JavaScript document. +.sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%bonnie\fP @@ -53,7 +56,8 @@ Specify options to \fI\%mongoperf\fP using a JavaScript document. .IP \(bu 2 \fI\%Checking Disk Performance with the mongoperf Utility\fP .UNINDENT -.RE +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -61,27 +65,37 @@ Specify options to \fI\%mongoperf\fP using a JavaScript document. .UNINDENT .INDENT 0.0 .TP +.B mongoperf +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help -Displays the options to \fI\%mongoperf\fP. Specify options to -\fI\%mongoperf\fP with a JSON document described in the +Displays the options to \fBmongoperf\fP\&. Specify options to +\fBmongoperf\fP with a JSON document described in the \fI\%Configuration Fields\fP section. .UNINDENT .INDENT 0.0 .TP .B <jsonconfig> -\fI\%mongoperf\fP accepts configuration options in the form of a +\fBmongoperf\fP accepts configuration options in the form of a file that holds a \fIJSON\fP document. You must stream the -content of this file into \fI\%mongoperf\fP, as in the following +content of this file into \fBmongoperf\fP, as in the following operation: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C mongoperf < config .ft P .fi +.UNINDENT +.UNINDENT .sp In this example \fBconfig\fP is the name of a file that holds a JSON document that resembles the following example: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -97,6 +111,8 @@ document that resembles the following example: } .ft P .fi +.UNINDENT +.UNINDENT .sp See the \fI\%Configuration Fields\fP section for documentation of each of these fields. @@ -109,9 +125,9 @@ of these fields. .sp \fIDefault:\fP 1 .sp -Defines the number of threads \fI\%mongoperf\fP will use in the +Defines the number of threads \fBmongoperf\fP will use in the test. To saturate your system\(aqs storage system you will need -multiple threads. Consider setting \fI\%nThreads\fP to \fB16\fP. +multiple threads. Consider setting \fBnThreads\fP to \fB16\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -129,9 +145,9 @@ Test file size. .sp \fIDefault:\fP 0 .sp -\fI\%mongoperf\fP will pause for the number of specified -\fI\%sleepMicros\fP divided by the -\fI\%nThreads\fP between each operation. +\fBmongoperf\fP will pause for the number of specified +\fBsleepMicros\fP divided by the +\fBnThreads\fP between each operation. .UNINDENT .INDENT 0.0 .TP @@ -140,17 +156,17 @@ Test file size. .sp \fIDefault:\fP \fBfalse\fP .sp -Set \fI\%mmf\fP to \fBtrue\fP to use memory mapped +Set \fBmmf\fP to \fBtrue\fP to use memory mapped files for the tests. .sp Generally: .INDENT 7.0 .IP \(bu 2 -when \fI\%mmf\fP is \fBfalse\fP, \fI\%mongoperf\fP +when \fBmmf\fP is \fBfalse\fP, \fBmongoperf\fP tests direct, physical, I/O, without caching. Use a large file size to test heavy random I/O load and to avoid I/O coalescing. .IP \(bu 2 -when \fI\%mmf\fP is \fBtrue\fP, \fI\%mongoperf\fP +when \fBmmf\fP is \fBtrue\fP, \fBmongoperf\fP runs tests of the caching system, and can use normal file system cache. Use \fBmmf\fP in this mode to test file system cache behavior with memory mapped files. @@ -163,10 +179,10 @@ behavior with memory mapped files. .sp \fIDefault:\fP \fBfalse\fP .sp -Set \fI\%r\fP to \fBtrue\fP to perform reads as part of +Set \fBr\fP to \fBtrue\fP to perform reads as part of the tests. .sp -Either \fI\%r\fP or \fI\%w\fP must be \fBtrue\fP. +Either \fBr\fP or \fBw\fP must be \fBtrue\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -175,10 +191,22 @@ Either \fI\%r\fP or \fI\%w\fP must be \fBtrue\fP. .sp \fIDefault:\fP \fBfalse\fP .sp -Set \fI\%w\fP to \fBtrue\fP to perform writes as part of +Set \fBw\fP to \fBtrue\fP to perform writes as part of the tests. .sp -Either \fI\%r\fP or \fI\%w\fP must be \fBtrue\fP. +Either \fBr\fP or \fBw\fP must be \fBtrue\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B mongoperf.recSizeKB +New in version 2.4. + +.sp +\fIType:\fP Integer. +.sp +\fIDefault:\fP 4 kb +.sp +The size of each write operation. .UNINDENT .INDENT 0.0 .TP @@ -187,59 +215,71 @@ Either \fI\%r\fP or \fI\%w\fP must be \fBtrue\fP. .sp \fIDefault:\fP 0 .sp -Seconds between disk flushes. \fI\%syncDelay\fP is -similar to \fBsyncDelay\fP for \fBmongod\fP. +Seconds between disk flushes. \fBmongoperf.syncDelay\fP is +similar to \fI\-\-syncdelay\fP for \fBmongod\fP\&. .sp -The \fI\%syncDelay\fP controls how frequently -\fI\%mongoperf\fP performs an asynchronous disk flush the memory +The \fBsyncDelay\fP controls how frequently +\fBmongoperf\fP performs an asynchronous disk flush of the memory mapped file used for testing. By default, \fBmongod\fP -performs this operation every every 60 seconds. Use -\fI\%syncDelay\fP to test basic system performance of +performs this operation every 60 seconds. Use +\fBsyncDelay\fP to test basic system performance of this type of operation. .sp -Only use \fI\%syncDelay\fP in conjunction with -\fI\%mmf\fP set to \fBtrue\fP. +Only use \fBsyncDelay\fP in conjunction with +\fBmmf\fP set to \fBtrue\fP\&. .sp -The default value of \fB0\fP disables this +The default value of \fB0\fP disables this. .UNINDENT .SH USE +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongoperf < jsonconfigfile .ft P .fi +.UNINDENT +.UNINDENT .sp -Replace \fBjsonconfigfile\fP with the path to the \fI\%mongoperf\fP -configuration. You may also invoke \fI\%mongoperf\fP in the +Replace \fBjsonconfigfile\fP with the path to the \fBmongoperf\fP +configuration. You may also invoke \fBmongoperf\fP in the following form: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C echo "{nThreads:16,fileSizeMB:1000,r:true}" | ./mongoperf .ft P .fi +.UNINDENT +.UNINDENT .sp In this operation: .INDENT 0.0 .IP \(bu 2 -\fI\%mongoperf\fP tests direct physical random read io\(aqs, using +\fBmongoperf\fP tests direct physical random read io\(aqs, using 16 concurrent reader threads. .IP \(bu 2 -\fI\%mongoperf\fP uses a 1 gigabyte test file. +\fBmongoperf\fP uses a 1 gigabyte test file. .UNINDENT .sp Consider using \fBiostat\fP, as invoked in the following example to monitor I/O performance during the test. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C iostat \-xm 2 .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. . diff --git a/debian/mongorestore.1 b/debian/mongorestore.1 index 730bb32e55e..a28a3253dc8 100644 --- a/debian/mongorestore.1 +++ b/debian/mongorestore.1 @@ -1,4 +1,6 @@ -.TH "MONGORESTORE" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGORESTORE" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongorestore \- MongoDB . @@ -28,40 +30,48 @@ 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. -. .SH SYNOPSIS .sp -The \fI\%mongorestore\fP tool imports content from binary database -dump, created by \fBmongodump\fP into a specific -database. \fI\%mongorestore\fP can import content to an existing -database or create a new one. +The \fBmongorestore\fP program writes data from a binary database +dump created by \fBmongodump\fP to a MongoDB +instance. \fBmongorestore\fP can create a new database or add +data to an existing database. .sp -\fI\%mongorestore\fP only performs inserts into the existing -database, and does not perform updates or \fIupserts\fP. If -existing data with the same \fB_id\fP already exists on the target -database, \fI\%mongorestore\fP will \fInot\fP replace it. +\fBmongorestore\fP can write data to either \fImongod\fP or \fBmongos\fP +instances, in addition to writing directly to MongoDB data files +without an active \fBmongod\fP\&. .sp -\fI\%mongorestore\fP will recreate indexes from the dump +If you restore to an existing database, \fBmongorestore\fP will +only insert into the existing database, and does not perform updates +of any kind. If existing documents have the same value \fB_id\fP field +in the target database and collection, +\fBmongorestore\fP will \fInot\fP overwrite those documents. .sp -The behavior of \fI\%mongorestore\fP has the following properties: +Remember the following properties of \fBmongorestore\fP behavior: .INDENT 0.0 .IP \(bu 2 +\fBmongorestore\fP recreates indexes recorded by +\fBmongodump\fP\&. +.IP \(bu 2 all operations are inserts, not updates. .IP \(bu 2 -all inserts are "fire and forget," \fI\%mongorestore\fP does not -wait for a response from a \fBmongod\fP to ensure that the -MongoDB process has received or recorded the operation. +\fBmongorestore\fP does not wait for a response from a +\fBmongod\fP to ensure that the MongoDB process has received or +recorded the operation. .sp The \fBmongod\fP will record any errors to its log that occur -during a restore operation but \fI\%mongorestore\fP will not +during a restore operation, but \fBmongorestore\fP will not receive errors. .UNINDENT -.IP Note +.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 +earlier versions of \fBmongod\fP\&. +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -69,6 +79,10 @@ earlier versions of \fBmongod\fP. .UNINDENT .INDENT 0.0 .TP +.B mongorestore +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -77,26 +91,29 @@ 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.) +the option multiple times (e.g. \fB\-vvvvv\fP). .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongorestore\fP tool. +Returns the version of the \fBmongorestore\fP tool. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port> Specifies a resolvable hostname for the \fBmongod\fP to which you want to restore the database. By default -\fI\%mongorestore\fP will attempt to connect to a MongoDB -process running on the localhost port number \fB27017\fP. +\fBmongorestore\fP will attempt to connect to a MongoDB +process running on the localhost port number \fB27017\fP\&. For an +example of \fI\-\-host\fP, see \fIbackup\-restore\-dump\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, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -104,37 +121,46 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .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 command. +on the standard port (i.e. \fB27017\fP). You may also specify a port +number using the \fI\-\-host\fP command. For +an example of \fI\-\-port\fP, see \fIbackup\-restore\-dump\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongorestore\fP to connect +Enables IPv6 support that allows \fBmongorestore\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongorestore\fP, disable IPv6 +and processes, including \fBmongorestore\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 mongorestore. -.IP Note +instances in mongorestore\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongorestore 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, mongorestore does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongorestore\fP to connect to \fBmongod\fP +Allows \fBmongorestore\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -142,102 +168,110 @@ 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 -password. +\fI\-\-password\fP option to supply a +password. For an example of \fI\-\-username\fP, see +\fIbackup\-restore\-dump\fP\&. .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\%mongorestore --username\fP option to -supply a username. -.sp -If you specify a \fI\%--username\fP -without the \fI\%--password\fP option, \fI\%mongorestore\fP -will prompt for a password interactively. +in conjunction with the \fI\-\-username\fP option to +supply a username. For an example of \fI\-\-password\fP, see +\fIbackup\-restore\-dump\fP\&. +.sp +If you specify a \fI\-\-username\fP and do not pass an argument +to \fI\-\-password\fP, \fBmongorestore\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\%mongorestore\fP assumes that the database specified to the -\fI\%--db\fP argument holds the user\(aqs credentials, unless you -specify \fI\%--authenticationDatabase\fP. +By default, \fBmongorestore\fP assumes that the database specified to the +\fI\-\-db\fP argument 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 +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\%mongorestore\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongorestore\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\%mongorestore\fP to attach +\fI\-\-dbpath\fP option enables \fBmongorestore\fP to attach directly to local data files and insert the data without the -\fBmongod\fP. To run with \fI\%--dbpath\fP, -\fI\%mongorestore\fP needs to lock access to the data directory: +\fBmongod\fP\&. To run with \fI\-\-dbpath\fP, +\fBmongorestore\fP needs to lock access to the data directory: as a result, no \fBmongod\fP can access the same path while the -process runs. +process runs. For an example of \fI\-\-dbpath\fP, see +\fIbackup\-restore\-dbpath\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-directoryperdb -Use the \fI\%--directoryperdb\fP in conjunction with the +Use the \fI\-\-directoryperdb\fP in conjunction with the corresponding option to \fBmongod\fP, which allows -\fI\%mongorestore\fP to import data into MongoDB instances that +\fBmongorestore\fP to import data into MongoDB instances that have every database\(aqs files saved in discrete directories on the disk. This option is only relevant when specifying the -\fI\%--dbpath\fP option. +\fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-journal -Allows \fI\%mongorestore\fP write to the durability +Allows \fBmongorestore\fP write to the durability \fIjournal\fP to ensure that the data files will remain in a consistent state during the write process. This option is only -relevant when specifying the \fI\%--dbpath\fP option. +relevant when specifying the \fI\-\-dbpath\fP option. For an +example of \fI\-\-journal\fP, see \fIbackup\-restore\-dbpath\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-db <db>, \-d <db> -Use the \fI\%--db\fP option to specify a database for -\fI\%mongorestore\fP to restore data \fIinto\fP. If the database -doesn\(aqt exist, \fI\%mongorestore\fP will create the specified +Use the \fI\-\-db\fP option to specify a database for +\fBmongorestore\fP to restore data \fIinto\fP\&. If the database +doesn\(aqt exist, \fBmongorestore\fP will create the specified database. If you do not specify a \fB<db>\fP, -\fI\%mongorestore\fP creates new databases that correspond to +\fBmongorestore\fP creates new databases that correspond to the databases where data originated and data may be overwritten. Use this option to restore data into a MongoDB instance that already has data. .sp -\fI\%--db\fP does \fInot\fP control which \fIBSON\fP files -\fI\%mongorestore\fP restores. You must use the -\fI\%mongorestore\fP \fI\%path option\fP to limit that restored data. +\fI\-\-db\fP does \fInot\fP control which \fIBSON\fP files +\fBmongorestore\fP restores. You must use the +\fBmongorestore\fP \fI\%path option\fP to limit that restored data. .UNINDENT .INDENT 0.0 .TP .B \-\-collection <collection>, \-c <collection> -Use the \fI\%--collection\fP option to specify a collection for -\fI\%mongorestore\fP to restore. If you do not specify a -\fB<collection>\fP, \fI\%mongorestore\fP imports all collections +Use the \fI\-\-collection\fP option to specify a collection for +\fBmongorestore\fP to restore. If you do not specify a +\fB<collection>\fP, \fBmongorestore\fP imports all collections created. Existing data may be overwritten. Use this option to restore data into a MongoDB instance that already has data, or to restore only some data in the specified imported data set. @@ -245,21 +279,23 @@ restore only some data in the specified imported data set. .INDENT 0.0 .TP .B \-\-objcheck -Forces the \fI\%mongorestore\fP to validate all requests from +Forces the \fBmongorestore\fP to validate all requests from clients upon receipt to ensure that clients never insert invalid documents into the database. For objects with a high degree of -sub\-document nesting, \fI\%--objcheck\fP can have a small impact +sub\-document nesting, \fI\-\-objcheck\fP can have a small impact on performance. You can set \fI\%--noobjcheck\fP to disable object checking at run\-time. .sp -Changed in version 2.4: MongoDB enables \fI\%--objcheck\fP by default, to prevent any +Changed in version 2.4: MongoDB enables \fI\-\-objcheck\fP by default, to prevent any client from inserting malformed or invalid BSON into a MongoDB database. + .UNINDENT .INDENT 0.0 .TP .B \-\-noobjcheck New in version 2.4. + .sp Disables the default document validation that MongoDB performs on all incoming BSON documents. @@ -267,10 +303,11 @@ incoming BSON documents. .INDENT 0.0 .TP .B \-\-filter \(aq<JSON>\(aq -Limits the documents that \fI\%mongorestore\fP imports to only +Limits the documents that \fBmongorestore\fP imports to only those documents that match the JSON document specified as -\fB\(aq<JSON>\(aq\fP. Be sure to include the document in single quotes to -avoid interaction with your system\(aqs shell environment. +\fB\(aq<JSON>\(aq\fP\&. Be sure to include the document in single quotes to +avoid interaction with your system\(aqs shell environment. For an +example of \fI\%--filter\fP, see \fIbackup\-restore\-filter\fP\&. .UNINDENT .INDENT 0.0 .TP @@ -284,30 +321,33 @@ backup. .B \-\-oplogReplay Replays the \fIoplog\fP after restoring the dump to ensure that the current state of the database reflects the point\-in\-time backup captured with -the "\fImongodump \-\-oplog\fP" command. +the "\fImongodump \-\-oplog\fP" command. For an example of +\fI\%--oplogReplay\fP, see \fIbackup\-restore\-oplogreplay\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-keepIndexVersion -Prevents \fI\%mongorestore\fP from upgrading the index to the latest +Prevents \fBmongorestore\fP from upgrading the index to the latest version during the restoration process. .UNINDENT .INDENT 0.0 .TP .B \-\-w <number of replicas per write> New in version 2.2. + .sp Specifies the \fIwrite concern\fP for each write operation that -\fI\%mongorestore\fP writes to the target database. By default, -\fI\%mongorestore\fP does not wait for a response for -\fIwrite acknowledgment\fP. +\fBmongorestore\fP writes to the target database. By default, +\fBmongorestore\fP does not wait for a response for +\fIwrite acknowledgment\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-noOptionsRestore New in version 2.2. + .sp -Prevents \fI\%mongorestore\fP from setting the collection +Prevents \fBmongorestore\fP from setting the collection options, such as those specified by the \fBcollMod\fP \fIdatabase command\fP, on restored collections. .UNINDENT @@ -315,8 +355,9 @@ options, such as those specified by the \fBcollMod\fP .TP .B \-\-noIndexRestore New in version 2.2. + .sp -Prevents \fI\%mongorestore\fP from restoring and building +Prevents \fBmongorestore\fP from restoring and building indexes as specified in the corresponding \fBmongodump\fP output. .UNINDENT @@ -324,9 +365,10 @@ output. .TP .B \-\-oplogLimit <timestamp> New in version 2.2. + .sp -Prevents \fI\%mongorestore\fP from applying \fIoplog\fP entries newer -than the \fB<timestamp>\fP. Specify \fB<timestamp>\fP values in the +Prevents \fBmongorestore\fP from applying \fIoplog\fP entries newer +than the \fB<timestamp>\fP\&. Specify \fB<timestamp>\fP values in the form of \fB<time_t>:<ordinal>\fP, where \fB<time_t>\fP is the seconds since the UNIX epoch, and \fB<ordinal>\fP represents a counter of operations in the oplog that occurred in the specified second. @@ -337,59 +379,71 @@ You must use \fI\%--oplogLimit\fP in conjunction with the .INDENT 0.0 .TP .B <path> -The final argument of the \fI\%mongorestore\fP command is a +The final argument of the \fBmongorestore\fP command is a directory path. This argument specifies the location of the database dump from which to restore. .UNINDENT .SH USAGE .sp -See \fB/tutorial/backup\-databases\-with\-binary\-database\-dumps\fP -for a larger overview of \fI\%mongorestore\fP -usage. Also see the "\fBmongodump\fP" document for an overview of the +See http://docs.mongodb.org/manual/tutorial/backup\-databases\-with\-binary\-database\-dumps +for a larger overview of \fBmongorestore\fP +usage. Also see the \fBmongodump\fP document for an overview of the \fBmongodump\fP, which provides the related inverse functionality. .sp Consider the following example: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C -mongorestore \-\-collection people \-\-db accounts dump/accounts/ +mongorestore \-\-collection people \-\-db accounts dump/accounts/people.bson .ft P .fi +.UNINDENT +.UNINDENT .sp -Here, \fI\%mongorestore\fP reads the database dump in the \fBdump/\fP +Here, \fBmongorestore\fP reads the database dump in the \fBdump/\fP sub\-directory of the current directory, and restores \fIonly\fP the documents in the collection named \fBpeople\fP from the database named -\fBaccounts\fP. \fI\%mongorestore\fP restores data to the instance -running on the localhost interface on port \fB27017\fP. +\fBaccounts\fP\&. \fBmongorestore\fP restores data to the instance +running on the localhost interface on port \fB27017\fP\&. .sp -In the next example, \fI\%mongorestore\fP restores a backup of the +In the next example, \fBmongorestore\fP restores a backup of the database instance located in \fBdump\fP to a database instance stored in the \fB/srv/mongodb\fP on the local machine. This requires that there are no active \fBmongod\fP instances attached to \fB/srv/mongodb\fP data directory. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongorestore \-\-dbpath /srv/mongodb .ft P .fi +.UNINDENT +.UNINDENT .sp -In the final example, \fI\%mongorestore\fP restores a database -dump located at \fB/opt/backup/mongodump\-2011\-10\-24\fP, from a database +In the final example, \fBmongorestore\fP restores a database +dump located at \fB/opt/backup/mongodump\-2011\-10\-24\fP, to a database running on port \fB37017\fP on the host -\fBmongodb1.example.net\fP. \fI\%mongorestore\fP authenticates to -the this MongoDB instance using the username \fBuser\fP and the +\fBmongodb1.example.net\fP\&. The \fBmongorestore\fP command authenticates to +the MongoDB instance using the username \fBuser\fP and the password \fBpass\fP, as follows: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongorestore \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-password pass /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. . diff --git a/debian/mongos.1 b/debian/mongos.1 index 27c0bd768e8..a3c5e978aed 100644 --- a/debian/mongos.1 +++ b/debian/mongos.1 @@ -1,4 +1,6 @@ -.TH "MONGOS" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOS" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongos \- MongoDB Shard Utility . @@ -28,30 +30,36 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongos\fP for "MongoDB Shard," is a routing service for +\fBmongos\fP for "MongoDB Shard," is a routing service for MongoDB shard configurations that processes queries from the application layer, and determines the location of this data in the \fIsharded cluster\fP, in order to complete these operations. From the perspective of the application, a -\fI\%mongos\fP instance behaves identically to any other MongoDB +\fBmongos\fP instance behaves identically to any other MongoDB instance. -.IP Note +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 Changed in version 2.1. + .sp Some aggregation operations using the \fBaggregate\fP will -cause \fI\%mongos\fP instances to require more CPU resources +cause \fBmongos\fP instances to require more CPU resources than in previous versions. This modified performance profile may dictate alternate architecture decisions if you use the \fIaggregation framework\fP extensively in a sharded environment. -.RE -.IP "See also" +.UNINDENT +.UNINDENT .sp -\fB/sharding\fP and \fB/core/sharded\-clusters\fP. -.RE +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 +http://docs.mongodb.org/manual/sharding and http://docs.mongodb.org/manual/core/sharding\-introduction\&. +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -59,6 +67,10 @@ dictate alternate architecture decisions if you use the .UNINDENT .INDENT 0.0 .TP +.B mongos +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help, \-h Returns a basic help and usage text. .UNINDENT @@ -74,31 +86,40 @@ Specifies a configuration file, that you can use to specify runtime\-configurations. While the options are equivalent and accessible via the other command line arguments, the configuration file is the preferred method for runtime configuration of -mongod. See the "\fB/reference/configuration\-options\fP" document +mongod. See the http://docs.mongodb.org/manual/reference/configuration\-options document for more information about these options. .sp Not all configuration options for \fBmongod\fP make sense in -the context of \fI\%mongos\fP. +the context of \fBmongos\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +Ensure the configuration file uses ASCII +encoding. \fBmongod\fP does not support configuration files +with non\-ASCII encoding, including UTF\-8. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-verbose, \-v Increases the amount of internal reporting returned on standard -output or in the log file specified by \fI\%--logpath\fP. Use the +output or in the log file specified by \fI\%--logpath\fP\&. Use the \fB\-v\fP form to control the level of verbosity 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 \-\-quiet -Runs the \fI\%mongos\fP instance in a quiet mode that attempts to limit +Runs the \fBmongos\fP instance in a quiet mode that attempts to limit the amount of output. .UNINDENT .INDENT 0.0 .TP .B \-\-port <port> -Specifies a TCP port for the \fI\%mongos\fP to listen for client -connections. By default \fI\%mongos\fP listens for connections on +Specifies a TCP port for the \fBmongos\fP to listen for client +connections. By default \fBmongos\fP listens for connections on port 27017. .sp UNIX\-like systems require root access to access ports with numbers @@ -107,38 +128,42 @@ lower than 1024. .INDENT 0.0 .TP .B \-\-bind_ip <ip address> -The IP address that the \fI\%mongos\fP process will bind to and -listen for connections. By default \fI\%mongos\fP listens for -connections on the localhost (i.e. \fB127.0.0.1\fP address.) You may -attach \fI\%mongos\fP to any interface; however, if you attach -\fI\%mongos\fP to a publicly accessible interface you must -implement proper authentication or firewall restrictions to protect -the integrity of your database. +The IP address that the \fBmongos\fP process will bind to and +listen for connections. By default \fBmongos\fP listens for +connections all interfaces. You may attach \fBmongos\fP to any +interface; however, when attaching \fBmongos\fP to a publicly +accessible interface ensure that you have implemented proper +authentication and/or firewall restrictions to protect the +integrity of your database. .UNINDENT .INDENT 0.0 .TP .B \-\-maxConns <number> Specifies the maximum number of simultaneous connections that -\fI\%mongos\fP will accept. This setting will have no effect if +\fBmongos\fP will accept. This setting will have no effect if the value of this setting is higher than your operating system\(aqs configured maximum connection tracking threshold. .sp -This is particularly useful for \fI\%mongos\fP if you have a +This is particularly useful for \fBmongos\fP if you have a client that creates a number of collections but allows them to timeout rather than close the collections. When you set \fBmaxConns\fP, ensure the value is slightly higher than the size of the connection pool or the total number of connections to prevent erroneous connection spikes from propagating to the members -of a \fIshard\fP cluster. -.IP Note +of a \fIsharded cluster\fP\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 You cannot set \fBmaxConns\fP to a value higher -than \fI20000\fP. -.RE +than \fI20000\fP\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-objcheck -Forces the \fI\%mongos\fP to validate all requests from clients +Forces the \fBmongos\fP to validate all requests from clients upon receipt to ensure that invalid objects are never inserted into the database. This option has a performance impact, and is not enabled by default. @@ -149,7 +174,7 @@ enabled by default. Specify a path for the log file that will hold all diagnostic logging information. .sp -Unless specified, \fI\%mongos\fP will output all log information +Unless specified, \fBmongos\fP will output all log information to the standard output. Additionally, unless you also specify \fI\%--logappend\fP, the logfile will be overwritten when the process restarts. @@ -157,58 +182,105 @@ process restarts. .INDENT 0.0 .TP .B \-\-logappend -Specify to ensure that \fI\%mongos\fP appends additional logging +Specify to ensure that \fBmongos\fP appends additional logging data to the end of the logfile rather than overwriting the content of the log when the process restarts. .UNINDENT .INDENT 0.0 .TP +.B \-\-setParameter <options> +New in version 2.4. + +.sp +Specifies an option to configure on startup. Specify multiple +options with multiple \fI\%--setParameter\fP options. See +http://docs.mongodb.org/manual/reference/parameters for full documentation of these +parameters. The \fBsetParameter\fP database command provides +access to many of these parameters. \fI\%--setParameter\fP supports the +following options: +.INDENT 7.0 +.IP \(bu 2 +\fBenableLocalhostAuthBypass\fP +.IP \(bu 2 +\fBenableTestCommands\fP +.IP \(bu 2 +\fBlogLevel\fP +.IP \(bu 2 +\fBlogUserIds\fP +.IP \(bu 2 +\fBnotablescan\fP +.IP \(bu 2 +\fBquiet\fP +.IP \(bu 2 +\fBsupportCompatibilityFormPrivilegeDocuments\fP +.IP \(bu 2 +\fBsyncdelay\fP +.IP \(bu 2 +\fBtextSearchEnabled\fP +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B \-\-syslog New in version 2.1.0. + .sp Sends all logging output to the host\(aqs \fIsyslog\fP system rather -than to standard output or a log file as with \fI\%--logpath\fP. -.IP Warning -You cannot use \fI\%--syslog\fP with \fI\%--logpath\fP. -.RE +than to standard output or a log file as with \fI\%--logpath\fP\&. +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +You cannot use \fI\%--syslog\fP with \fI\%--logpath\fP\&. +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-pidfilepath <path> -Specify a file location to hold the "\fIPID\fP" or process ID of the -\fI\%mongos\fP process. Useful for tracking the \fI\%mongos\fP process in -combination with the \fI\%mongos --fork\fP option. +Specify a file location to hold the \fIPID\fP or process ID of the +\fBmongos\fP process. Useful for tracking the \fBmongos\fP process in +combination with the \fImongos \-\-fork\fP option. .sp Without a specified \fI\%--pidfilepath\fP option, -\fI\%mongos\fP creates no PID file. +\fBmongos\fP creates no PID file. .UNINDENT .INDENT 0.0 .TP .B \-\-keyFile <file> Specify the path to a key file to store authentication information. This option is only useful for the connection between -\fI\%mongos\fP instances and components of the \fIsharded cluster\fP. -.IP "See also" +\fBmongos\fP instances and components of the \fIsharded cluster\fP\&. .sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 \fIsharding\-security\fP -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-nounixsocket -Disables listening on the UNIX socket. Without this option -\fI\%mongos\fP creates a UNIX socket. +Disables listening on the UNIX socket. \fBmongos\fP always +listens on the UNIX socket, unless \fI\%--nounixsocket\fP is set, +\fI\%--bind_ip\fP is \fInot\fP set, or \fI\%--bind_ip\fP does \fInot\fP +specify \fB127.0.0.1\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-unixSocketPrefix <path> -Specifies a path for the UNIX socket. Unless specified, -\fI\%mongos\fP creates a socket in the \fB/tmp\fP path. +Specifies a path for the UNIX socket. Unless this option has a +value \fBmongos\fP creates a socket with \fB/tmp\fP as a prefix. +.sp +MongoDB will \fIalways\fP create and listen on a UNIX socket, unless +\fI\%--nounixsocket\fP is set, \fI\%--bind_ip\fP is \fInot\fP set, +or \fI\%--bind_ip\fP specifies \fB127.0.0.1\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-fork -Enables a \fIdaemon\fP mode for \fBmongod\fP which forces the +Enables a \fIdaemon\fP mode for \fBmongos\fP which forces the process to the background. This is the normal mode of operation, in production and production\-like environments, but may \fInot\fP be desirable for testing. @@ -217,43 +289,51 @@ desirable for testing. .TP .B \-\-configdb <config1>,<config2><:port>,<config3> Set this option to specify a configuration database -(i.e. \fIconfig database\fP) for the \fIsharded cluster\fP. You must +(i.e. \fIconfig database\fP) for the \fIsharded cluster\fP\&. You must specify either 1 configuration server or 3 configuration servers, in a comma separated list. -.IP Note -\fI\%mongos\fP instances read from the first \fIconfig +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +\fBmongos\fP instances read from the first \fIconfig server\fP in the list provided. All -\fI\%mongos\fP instances \fBmust\fP specify the hosts to the +\fBmongos\fP instances \fBmust\fP specify the hosts to the \fI\%--configdb\fP setting in the same order. .sp If your configuration databases reside in more that one data center, order the hosts in the \fI\%--configdb\fP argument so that the config database that is closest to the majority of your -\fI\%mongos\fP instances is first servers in the list. -.RE -.IP Warning +\fBmongos\fP instances is first servers in the list. +.UNINDENT +.UNINDENT +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 Never remove a config server from the \fI\%--configdb\fP parameter, even if the config server or servers are not available, or offline. -.RE +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-test This option is for internal testing use only, and runs unit tests -without starting a \fI\%mongos\fP instance. +without starting a \fBmongos\fP instance. .UNINDENT .INDENT 0.0 .TP .B \-\-upgrade This option updates the meta data format used by the -\fIconfig database\fP. +\fIconfig database\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-chunkSize <value> The value of the \fI\%--chunkSize\fP determines the size of each \fIchunk\fP, \fIin megabytes\fP, of data distributed around the -\fIsharded cluster\fP. The default value is 64 megabytes, which +\fIsharded cluster\fP\&. The default value is 64 megabytes, which is the ideal size for chunks in most deployments: larger chunk size can lead to uneven data distribution, smaller chunk size often leads to inefficient movement of chunks between nodes. However, in @@ -263,13 +343,13 @@ size. This option \fIonly\fP sets the chunk size when initializing the cluster for the first time. If you modify the run\-time option later, the new value will have no effect. See the -"\fIsharding\-balancing\-modify\-chunk\-size\fP" procedure if you +http://docs.mongodb.org/manual/tutorial/modify\-chunk\-size\-in\-sharded\-cluster procedure if you need to change the chunk size on an existing sharded cluster. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support to allow clients to connect to \fI\%mongos\fP +Enables IPv6 support to allow clients to connect to \fBmongos\fP using IPv6 networks. MongoDB disables IPv6 support by default in \fBmongod\fP and all utilities. .UNINDENT @@ -289,6 +369,7 @@ Disables the scripting engine. .TP .B \-\-nohttpinterface New in version 2.1.2. + .sp Disables the HTTP interface. .UNINDENT @@ -296,16 +377,17 @@ Disables the HTTP interface. .TP .B \-\-localThreshold New in version 2.2. + .sp -\fI\%--localThreshold\fP affects the logic that \fI\%mongos\fP +\fI\%--localThreshold\fP affects the logic that \fBmongos\fP uses when selecting \fIreplica set\fP members to pass read operations to from clients. Specify a value to \fI\%--localThreshold\fP in milliseconds. The default value is \fB15\fP, which corresponds to the default value in all of the client -\fBdrivers\fP. +\fBdrivers\fP\&. .sp -When \fI\%mongos\fP receives a request that permits reads to -\fIsecondary\fP members, the \fI\%mongos\fP will: +When \fBmongos\fP receives a request that permits reads to +\fIsecondary\fP members, the \fBmongos\fP will: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 @@ -317,10 +399,10 @@ time of 15 milliseconds of the nearest suitable member of the set. .sp If you specify a value for \fI\%--localThreshold\fP, -\fI\%mongos\fP will construct the list of replica members +\fBmongos\fP will construct the list of replica members that are within the latency allowed by this value. .IP \(bu 2 -The \fI\%mongos\fP will select a member to read from at +The \fBmongos\fP will select a member to read from at random from this list. .UNINDENT .UNINDENT @@ -329,72 +411,82 @@ random from this list. The ping time used for a set member compared by the \fI\%--localThreshold\fP setting is a moving average of recent ping times, calculated, at most, every 10 seconds. As a result, some queries -may reach members above the threshold until the \fI\%mongos\fP +may reach members above the threshold until the \fBmongos\fP recalculates the average. .sp See the \fIreplica\-set\-read\-preference\-behavior\-member\-selection\fP -section of the \fIread preference\fP +section of the \fBread preference\fP documentation for more information. .UNINDENT .INDENT 0.0 .TP .B \-\-noAutoSplit New in version 2.0.7. + .sp -\fI\%--noAutoSplit\fP prevents \fI\%mongos\fP from +\fI\%--noAutoSplit\fP prevents \fBmongos\fP from automatically inserting metadata splits in a \fIsharded -collection\fP. If set on all \fI\%mongos\fP, this will prevent +collection\fP\&. If set on all \fBmongos\fP, this will prevent MongoDB from creating new chunks as the data in a collection grows. .sp -Because any \fI\%mongos\fP in a cluster can create a split, +Because any \fBmongos\fP in a cluster can create a split, to totally disable splitting in a cluster you must -set \fI\%--noAutoSplit\fP on all \fI\%mongos\fP. -.IP Warning +set \fI\%--noAutoSplit\fP on all \fBmongos\fP\&. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 With \fI\%--noAutoSplit\fP enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution. -.RE +.UNINDENT +.UNINDENT .UNINDENT .SS SSL Options -.IP "See" +.INDENT 0.0 +.INDENT 3.5 +.SS See .sp -\fB/administration/ssl\fP for full documentation of -MongoDB\(aqs support. -.RE +http://docs.mongodb.org/manual/tutorial/configure\-ssl for full +documentation of MongoDB\(aqs support. +.UNINDENT +.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\%mongos\fP assumes that the database specified to the +By default, \fBmongos\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\%mongos\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongos\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 .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, 10gen, Inc. +2011-2013, MongoDB, Inc. .\" Generated by docutils manpage writer. . diff --git a/debian/mongosniff.1 b/debian/mongosniff.1 index 8b4ffd41d2a..71bb9211706 100644 --- a/debian/mongosniff.1 +++ b/debian/mongosniff.1 @@ -1,4 +1,6 @@ -.TH "MONGOSNIFF" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOSNIFF" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongosniff \- MongoDB . @@ -28,34 +30,40 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongosniff\fP provides a low\-level operation tracing/sniffing view -into database activity in real time. Think of \fI\%mongosniff\fP as a +\fBmongosniff\fP provides a low\-level operation tracing/sniffing view +into database activity in real time. Think of \fBmongosniff\fP as a MongoDB\-specific analogue of \fBtcpdump\fP for TCP/IP network -traffic. Typically, \fI\%mongosniff\fP is most frequently used in driver +traffic. Typically, \fBmongosniff\fP is most frequently used in driver development. -.IP Note -\fI\%mongosniff\fP requires \fBlibpcap\fP and is only available for +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBmongosniff\fP requires \fBlibpcap\fP and is only available for Unix\-like systems. Furthermore, the version distributed with the MongoDB binaries is dynamically linked against aversion 0.9 of -\fBlibpcap\fP. If your system has a different version of \fBlibpcap\fP, you -will need to compile \fI\%mongosniff\fP yourself or create a +\fBlibpcap\fP\&. If your system has a different version of \fBlibpcap\fP, you +will need to compile \fBmongosniff\fP yourself or create a symbolic link pointing to \fBlibpcap.so.0.9\fP to your local version -of \fBlibpcap\fP. Use an operation that resembles the following: +of \fBlibpcap\fP\&. Use an operation that resembles the following: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C ln \-s /usr/lib/libpcap.so.1.1.1 /usr/lib/libpcap.so.0.9 .ft P .fi +.UNINDENT +.UNINDENT .sp Change the path\(aqs and name of the shared library as needed. -.RE +.UNINDENT +.UNINDENT .sp -As an alternative to \fI\%mongosniff\fP, Wireshark, a popular +As an alternative to \fBmongosniff\fP, Wireshark, a popular network sniffing tool is capable of inspecting and parsing the MongoDB wire protocol. .SH OPTIONS @@ -65,6 +73,10 @@ wire protocol. .UNINDENT .INDENT 0.0 .TP +.B mongosniff +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -72,7 +84,7 @@ Returns a basic help and usage text. .TP .B \-\-forward <host><:port> Declares a host to forward all parsed requests that the -\fI\%mongosniff\fP intercepts to another \fBmongod\fP +\fBmongosniff\fP intercepts to another \fBmongod\fP instance and issue those operations on that database instance. .sp Specify the target host name and port in the \fB<host><:port>\fP @@ -80,6 +92,8 @@ format. .sp To connect to a replica set, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -87,12 +101,14 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .B \-\-source <NET [interface]>, <FILE [filename]>, <DIAGLOG [filename]> Specifies source material to inspect. Use \fB\-\-source NET [interface]\fP to inspect traffic from a network interface -(e.g. \fBeth0\fP or \fBlo\fP.) Use \fB\-\-source FILE [filename]\fP to +(e.g. \fBeth0\fP or \fBlo\fP\&.) Use \fB\-\-source FILE [filename]\fP to read captured packets in \fIpcap\fP format. .sp You may use the \fB\-\-source DIAGLOG [filename]\fP option to read @@ -105,14 +121,14 @@ option. Modifies the behavior to \fIonly\fP display invalid BSON objects and nothing else. Use this option for troubleshooting driver development. This option has some performance impact on the -performance of \fI\%mongosniff\fP. +performance of \fBmongosniff\fP\&. .UNINDENT .INDENT 0.0 .TP .B <port> Specifies alternate ports to sniff for traffic. By default, -\fI\%mongosniff\fP watches for MongoDB traffic on port 27017. Append -multiple port numbers to the end of \fI\%mongosniff\fP to monitor +\fBmongosniff\fP watches for MongoDB traffic on port 27017. Append +multiple port numbers to the end of \fBmongosniff\fP to monitor traffic on multiple ports. .UNINDENT .SH USAGE @@ -120,22 +136,30 @@ traffic on multiple ports. Use the following command to connect to a \fBmongod\fP or \fBmongos\fP running on port 27017 \fIand\fP 27018 on the localhost interface: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongosniff \-\-source NET lo 27017 27018 .ft P .fi +.UNINDENT +.UNINDENT .sp Use the following command to only log invalid \fIBSON\fP objects for the \fBmongod\fP or \fBmongos\fP running on the localhost interface and port 27018, for driver development and troubleshooting: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongosniff \-\-objcheck \-\-source NET lo 27018 .ft P .fi +.UNINDENT +.UNINDENT .SH BUILD MONGOSNIFF .sp To build \fBmongosniff\fP yourself, Linux users can use the following @@ -150,19 +174,25 @@ systems package management software. Dependencies include: .IP \(bu 2 \fBgit\fP \- to download the MongoDB source code. .IP \(bu 2 -\fBscons\fP and a C++ compiler \- to build \fI\%mongosniff\fP. +\fBscons\fP and a C++ compiler \- to build \fBmongosniff\fP\&. .UNINDENT .IP 2. 3 Download a copy of the MongoDB source code using \fBgit\fP: +.INDENT 3.0 +.INDENT 3.5 .sp .nf .ft C git clone git://github.com/mongodb/mongo.git .ft P .fi +.UNINDENT +.UNINDENT .IP 3. 3 Issue the following sequence of commands to change to the -\fBmongo/\fP directory and build \fI\%mongosniff\fP: +\fBmongo/\fP directory and build \fBmongosniff\fP: +.INDENT 3.0 +.INDENT 3.5 .sp .nf .ft C @@ -171,13 +201,19 @@ scons mongosniff .ft P .fi .UNINDENT -.IP Note +.UNINDENT +.UNINDENT +.sp +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 If you run \fBscons mongosniff\fP before installing \fBlibpcap\fP you -must run \fBscons clean\fP before you can build \fI\%mongosniff\fP. -.RE +must run \fBscons clean\fP before you can build \fBmongosniff\fP\&. +.UNINDENT +.UNINDENT .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, 10gen, Inc. +2011-2013, MongoDB, Inc. .\" Generated by docutils manpage writer. . diff --git a/debian/mongostat.1 b/debian/mongostat.1 index 61d99a23ce5..97f0c92337c 100644 --- a/debian/mongostat.1 +++ b/debian/mongostat.1 @@ -1,4 +1,6 @@ -.TH "MONGOSTAT" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOSTAT" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongostat \- MongoDB . @@ -28,40 +30,41 @@ 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. -. .SH SYNOPSIS .sp -The \fI\%mongostat\fP utility provides a quick overview of the +The \fBmongostat\fP utility provides a quick overview of the status of a currently running \fBmongod\fP or \fBmongos\fP -instance. \fI\%mongostat\fP is functionally similar to the +instance. \fBmongostat\fP is functionally similar to the UNIX/Linux file system utility \fBvmstat\fP, but provides data regarding \fBmongod\fP and \fBmongos\fP instances. -.IP "See also" .sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 For more information about monitoring MongoDB, see -\fB/administration/monitoring\fP. +http://docs.mongodb.org/manual/administration/monitoring\&. .sp For more background on various other MongoDB status outputs see: .INDENT 0.0 .IP \(bu 2 -\fB/reference/server\-status\fP +http://docs.mongodb.org/manual/reference/command/serverStatus .IP \(bu 2 -\fB/reference/replica\-status\fP +http://docs.mongodb.org/manual/reference/command/replSetGetStatus .IP \(bu 2 -\fB/reference/database\-statistics\fP +http://docs.mongodb.org/manual/reference/command/dbStats .IP \(bu 2 -\fB/reference/collection\-statistics\fP +http://docs.mongodb.org/manual/reference/command/collStats .UNINDENT .sp For an additional utility that provides MongoDB metrics see -"\fBmongotop\fP." -.RE +\fBmongotop\fP\&. +.UNINDENT +.UNINDENT .sp -\fI\%mongostat\fP connects to the \fBmongod\fP instance running +\fBmongostat\fP connects to the \fBmongod\fP instance running on the local host interface on TCP port \fB27017\fP; however, -\fI\%mongostat\fP can connect to any accessible remote \fBmongod\fP +\fBmongostat\fP can connect to any accessible remote \fBmongod\fP instance. .SH OPTIONS .INDENT 0.0 @@ -70,6 +73,10 @@ instance. .UNINDENT .INDENT 0.0 .TP +.B mongostat +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -78,25 +85,27 @@ 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.) +the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fI\%mongostat\fP utility. +Returns the version of the \fBmongostat\fP utility. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port> Specifies a resolvable hostname for the \fBmongod\fP from which you -want to export data. By default \fI\%mongostat\fP attempts to connect -to a MongoDB instance running on the localhost port number \fB27017\fP. +want to export data. By default \fBmongostat\fP attempts to connect +to a MongoDB instance running on the localhost 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, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -104,37 +113,45 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .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\%mongostat --host\fP command. +number using the \fImongostat \-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongostat\fP to connect +Enables IPv6 support that allows \fBmongostat\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongostat\fP, disable IPv6 +and processes, including \fBmongostat\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 mongostat. -.IP Note +instances in mongostat\&. + +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 SSL support in mongostat 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, mongostat does not support connections to \fBmongod\fP instances that require client certificate validation. -.RE +.UNINDENT +.UNINDENT .sp -Allows \fI\%mongostat\fP to connect to \fBmongod\fP +Allows \fBmongostat\fP to connect to \fBmongod\fP instance over an SSL connection. .UNINDENT .INDENT 0.0 @@ -142,48 +159,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\%mongostat --password\fP option to supply a password. +\fImongostat \-\-password\fP option to supply a password. +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +This user must have sufficient credentials to run +the \fBserverStatus\fP command, which is the +\fBclusterAdmin\fP role. See +http://docs.mongodb.org/manual/reference/user\-privileges and +http://docs.mongodb.org/manual/reference/privilege\-documents for more information. +.UNINDENT +.UNINDENT .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\%mongostat --username\fP option to +in conjunction with the \fImongostat \-\-username\fP option to supply a username. .sp -If you specify a \fI\%--username\fP -without the \fI\%--password\fP option, \fI\%mongostat\fP will -prompt for a password interactively. +If you specify a \fI\-\-username\fP, and do do not pass an +argument to \fI\-\-password\fP, \fBmongostat\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\%mongostat\fP assumes that the database specified to the +By default, \fBmongostat\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\%mongostat\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongostat\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 @@ -196,57 +228,57 @@ Disables the output of column or field names. .B \-\-rowcount <number>, \-n <number> Controls the number of rows to output. Use in conjunction with the \fBsleeptime\fP argument to control the duration of a -\fI\%mongostat\fP operation. +\fBmongostat\fP operation. .sp -Unless \fI\%--rowcount\fP is specified, \fI\%mongostat\fP +Unless \fI\%--rowcount\fP is specified, \fBmongostat\fP will return an infinite number -of rows (e.g. value of \fB0\fP.) +of rows (e.g. value of \fB0\fP\&.) .UNINDENT .INDENT 0.0 .TP .B \-\-http -Configures \fI\%mongostat\fP to collect data using the HTTP interface +Configures \fBmongostat\fP to collect data using the HTTP interface rather than a raw database connection. .UNINDENT .INDENT 0.0 .TP .B \-\-discover -With this option \fI\%mongostat\fP discovers and reports on +With this option \fBmongostat\fP discovers and reports on statistics from all members of a \fIreplica set\fP or -\fIsharded cluster\fP. When connected to any member of a replica +\fIsharded cluster\fP\&. When connected to any member of a replica set, \fI\%--discover\fP all non\-\fIhidden members\fP of the replica set. When connected to a \fBmongos\fP, -\fI\%mongostat\fP will return data from all \fIshards\fP in the cluster. If a replica set provides a shard in the -sharded cluster, \fI\%mongostat\fP will report on non\-hidden +\fBmongostat\fP will return data from all \fIshards\fP in the cluster. If a replica set provides a shard in the +sharded cluster, \fBmongostat\fP will report on non\-hidden members of that replica set. .sp -The \fI\%mongostat --host\fP option is not required but +The \fImongostat \-\-host\fP option is not required but potentially useful in this case. .UNINDENT .INDENT 0.0 .TP .B \-\-all -Configures \fI\%mongostat\fP to return all optional \fI\%fields\fP. +Configures \fBmongostat\fP to return all optional \fI\%fields\fP\&. .UNINDENT .INDENT 0.0 .TP .B <sleeptime> The final argument is the length of time, in seconds, that -\fI\%mongostat\fP waits in between calls. By default \fI\%mongostat\fP +\fBmongostat\fP waits in between calls. By default \fBmongostat\fP returns one call every second. .sp -\fI\%mongostat\fP returns values that reflect the operations +\fBmongostat\fP returns values that reflect the operations over a 1 second period. For values of \fB<sleeptime>\fP greater -than 1, \fI\%mongostat\fP averages data to reflect average +than 1, \fBmongostat\fP averages data to reflect average operations per second. .UNINDENT .SH FIELDS .sp -\fI\%mongostat\fP returns values that reflect the operations over a +\fBmongostat\fP returns values that reflect the operations over a 1 second period. When \fBmongostat <sleeptime>\fP has a value -greater than 1, \fI\%mongostat\fP averages the statistics to reflect +greater than 1, \fBmongostat\fP averages the statistics to reflect average operations per second. .sp -\fI\%mongostat\fP outputs the following fields: +\fBmongostat\fP outputs the following fields: .INDENT 0.0 .TP .B inserts @@ -278,7 +310,7 @@ The number of get more (i.e. cursor batch) operations per second. .TP .B command The number of commands per second. On \fIslave\fP and -\fIsecondary\fP systems, \fI\%mongostat\fP presents two values +\fIsecondary\fP systems, \fBmongostat\fP presents two values separated by a pipe character (e.g. \fB|\fP), in the form of \fBlocal|replicated\fP commands. .UNINDENT @@ -291,24 +323,25 @@ The number of \fIfsync\fP operations per second. .TP .B mapped The total amount of data mapped in megabytes. This is the total -data size at the time of the last \fI\%mongostat\fP call. +data size at the time of the last \fBmongostat\fP call. .UNINDENT .INDENT 0.0 .TP .B size The amount of (virtual) memory in megabytes used by the process at -the time of the last \fI\%mongostat\fP call. +the time of the last \fBmongostat\fP call. .UNINDENT .INDENT 0.0 .TP .B res The amount of (resident) memory in megabytes used by the process at -the time of the last \fI\%mongostat\fP call. +the time of the last \fBmongostat\fP call. .UNINDENT .INDENT 0.0 .TP .B faults Changed in version 2.1. + .sp The number of page faults per second. .sp @@ -323,15 +356,17 @@ The percent of time in a global write lock. Changed in version 2.2: The \fBlocked db\fP field replaces the \fBlocked %\fP field to more appropriate data regarding the database specific locks in version 2.2. + .UNINDENT .INDENT 0.0 .TP .B locked db New in version 2.2. + .sp The percent of time in the per\-database context\-specific -lock. \fI\%mongostat\fP will report the database that has spent -the most time since the last \fI\%mongostat\fP call with a write +lock. \fBmongostat\fP will report the database that has spent +the most time since the last \fBmongostat\fP call with a write lock. .sp This value represents the amount of time that the listed database @@ -372,14 +407,14 @@ The number of active clients performing write operations. .B netIn The amount of network traffic, in \fIbytes\fP, received by the MongoDB instance. .sp -This includes traffic from \fI\%mongostat\fP itself. +This includes traffic from \fBmongostat\fP itself. .UNINDENT .INDENT 0.0 .TP .B netOut The amount of network traffic, in \fIbytes\fP, sent by the MongoDB instance. .sp -This includes traffic from \fI\%mongostat\fP itself. +This includes traffic from \fBmongostat\fP itself. .UNINDENT .INDENT 0.0 .TP @@ -394,7 +429,7 @@ The name, if applicable, of the replica set. .INDENT 0.0 .TP .B repl -The replication status of the node. +The replication status of the member. .TS center; |l|l|. @@ -439,11 +474,13 @@ _ .UNINDENT .SH USAGE .sp -In the first example, \fI\%mongostat\fP will return data every -second for 20 seconds. \fI\%mongostat\fP collects data from the +In the first example, \fBmongostat\fP will return data every +second for 20 seconds. \fBmongostat\fP collects data from the \fBmongod\fP instance running on the localhost interface on port 27017. All of the following invocations produce identical behavior: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -453,12 +490,16 @@ mongostat \-n 20 1 mongostat \-n 20 .ft P .fi +.UNINDENT +.UNINDENT .sp -In the next example, \fI\%mongostat\fP returns data every 5 minutes -(or 300 seconds) for as long as the program runs. \fI\%mongostat\fP +In the next example, \fBmongostat\fP returns data every 5 minutes +(or 300 seconds) for as long as the program runs. \fBmongostat\fP collects data from the \fBmongod\fP instance running on the -localhost interface on port \fB27017\fP. Both of the following +localhost interface on port \fB27017\fP\&. Both of the following invocations produce identical behavior. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -467,12 +508,16 @@ mongostat \-n 0 300 mongostat 300 .ft P .fi +.UNINDENT +.UNINDENT .sp -In the following example, \fI\%mongostat\fP returns data every 5 -minutes for an hour (12 times.) \fI\%mongostat\fP collects data +In the following example, \fBmongostat\fP returns data every 5 +minutes for an hour (12 times.) \fBmongostat\fP collects data from the \fBmongod\fP instance running on the localhost interface on port 27017. Both of the following invocations produce identical behavior. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -480,22 +525,28 @@ mongostat \-\-rowcount 12 300 mongostat \-n 12 300 .ft P .fi +.UNINDENT +.UNINDENT .sp -In many cases, using the \fI\%--discover\fP +In many cases, using the \fI\-\-discover\fP will help provide a more complete snapshot of the state of an entire group of machines. If a \fBmongos\fP process connected to a \fIsharded cluster\fP is running on port \fB27017\fP of the local machine, you can use the following form to return statistics from all members of the cluster: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongostat \-\-discover .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. . diff --git a/debian/mongotop.1 b/debian/mongotop.1 index a949893193d..20208e67746 100644 --- a/debian/mongotop.1 +++ b/debian/mongotop.1 @@ -1,4 +1,6 @@ -.TH "MONGOTOP" "1" "March 14, 2013" "2.2.3" "mongodb-manual" +.\" Man page generated from reStructuredText. +. +.TH "MONGOTOP" "1" "October 03, 2013" "2.4" "mongodb-manual" .SH NAME mongotop \- MongoDB . @@ -28,35 +30,36 @@ 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. -. .SH SYNOPSIS .sp -\fI\%mongotop\fP provides a method to track the amount of time a -MongoDB instance spends reading and writing data. \fI\%mongotop\fP +\fBmongotop\fP provides a method to track the amount of time a +MongoDB instance spends reading and writing data. \fBmongotop\fP provides statistics on a per\-collection level. By default, -\fI\%mongotop\fP returns values every second. -.IP "See also" +\fBmongotop\fP returns values every second. .sp +\fBSEE ALSO:\fP +.INDENT 0.0 +.INDENT 3.5 For more information about monitoring MongoDB, see -\fB/administration/monitoring\fP. +http://docs.mongodb.org/manual/administration/monitoring\&. .sp For additional background on various other MongoDB status outputs see: .INDENT 0.0 .IP \(bu 2 -\fB/reference/server\-status\fP +http://docs.mongodb.org/manual/reference/command/serverStatus .IP \(bu 2 -\fB/reference/replica\-status\fP +http://docs.mongodb.org/manual/reference/command/replSetGetStatus .IP \(bu 2 -\fB/reference/database\-statistics\fP +http://docs.mongodb.org/manual/reference/command/dbStats .IP \(bu 2 -\fB/reference/collection\-statistics\fP +http://docs.mongodb.org/manual/reference/command/collStats .UNINDENT .sp For an additional utility that provides MongoDB metrics -see "\fBmongostat\fP." -.RE +see \fBmongostat\fP\&. +.UNINDENT +.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -64,6 +67,10 @@ see "\fBmongostat\fP." .UNINDENT .INDENT 0.0 .TP +.B mongotop +.UNINDENT +.INDENT 0.0 +.TP .B \-\-help Returns a basic help and usage text. .UNINDENT @@ -72,26 +79,28 @@ 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 -Print the version of the \fI\%mongotop\fP utility and exit. +Print the version of the \fBmongotop\fP utility and exit. .UNINDENT .INDENT 0.0 .TP .B \-\-host <hostname><:port> Specifies a resolvable hostname for the \fBmongod\fP from which you -want to export data. By default \fI\%mongotop\fP attempts to +want to export data. By default \fBmongotop\fP attempts to connect to a MongoDB process running on the localhost port number -\fB27017\fP. +\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, you can specify the replica set seed name, and a seed list of set members, in the following format: +.INDENT 7.0 +.INDENT 3.5 .sp .nf .ft C @@ -99,19 +108,21 @@ name, and a seed list of set members, in the following format: .ft P .fi .UNINDENT +.UNINDENT +.UNINDENT .INDENT 0.0 .TP .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\%mongotop --host\fP command. +number using the \fImongotop \-\-host\fP command. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fI\%mongotop\fP to connect +Enables IPv6 support that allows \fBmongotop\fP to connect to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fI\%mongotop\fP, disable IPv6 +and processes, including \fBmongotop\fP, disable IPv6 support by default. .UNINDENT .INDENT 0.0 @@ -119,96 +130,103 @@ support by default. .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\%mongotop\fP option to supply a +\fImongotop\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\%mongotop\fP will prompt -for a password interactively. +If you specify a \fI\-\-username\fP and do +not pass an argument to \fI\-\-password\fP, \fBmongotop\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\%mongotop\fP assumes that the database specified to the +By default, \fBmongotop\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\%mongotop\fP also includes support for \fBGSSAPI\fP to handle +challenge/response authentication mechanism. In MongoDB Enterprise, +\fBmongotop\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 \-\-locks New in version 2.2. + .sp -Toggles the mode of \fI\%mongotop\fP to report on use of -per\-database \fIlocks\fP. These data are useful for +Toggles the mode of \fBmongotop\fP to report on use of +per\-database \fIlocks\fP\&. These data are useful for measuring concurrent operations and lock percentage. .UNINDENT .INDENT 0.0 .TP .B <sleeptime> The final argument is the length of time, in seconds, that -\fI\%mongotop\fP waits in between calls. By default -\fI\%mongotop\fP returns data every second. +\fBmongotop\fP waits in between calls. By default +\fBmongotop\fP returns data every second. .UNINDENT .SH FIELDS .sp -\fI\%mongotop\fP returns time values specified in milliseconds +\fBmongotop\fP returns time values specified in milliseconds (ms.) .sp -\fI\%mongotop\fP only reports active namespaces or databases, +\fBmongotop\fP only reports active namespaces or databases, depending on the \fI\%--locks\fP option. If you don\(aqt see a database or collection, it has received no recent activity. You can issue a simple operation in the \fBmongo\fP shell to generate activity to -affect the output of \fI\%mongotop\fP. +affect the output of \fBmongotop\fP\&. .INDENT 0.0 .TP .B mongotop.ns Contains the database namespace, which combines the database name and collection. .sp -Changed in version 2.2: If you use the \fI\%--locks\fP, the \fI\%ns\fP field does not -appear in the \fI\%mongotop\fP output. +Changed in version 2.2: If you use the \fI\%--locks\fP, the \fBns\fP field does not +appear in the \fBmongotop\fP output. + .UNINDENT .INDENT 0.0 .TP .B mongotop.db New in version 2.2. + .sp -Contains the name of the database. The database named \fB.\fP refers +Contains the name of the database. The database named \fB\&.\fP refers to the global lock, rather than a specific database. .sp This field does not appear unless you have invoked -\fI\%mongotop\fP with the \fI\%--locks\fP option. +\fBmongotop\fP with the \fI\%--locks\fP option. .UNINDENT .INDENT 0.0 .TP @@ -235,23 +253,29 @@ Provides a time stamp for the returned data. .UNINDENT .SH USE .sp -By default \fI\%mongotop\fP connects to the MongoDB instance -running on the localhost port \fB27017\fP. However, \fI\%mongotop\fP can optionally +By default \fBmongotop\fP connects to the MongoDB instance +running on the localhost port \fB27017\fP\&. However, \fBmongotop\fP can optionally connect to remote \fBmongod\fP instances. See the \fI\%mongotop options\fP for more information. .sp -To force \fI\%mongotop\fP to return less frequently specify a number, in -seconds at the end of the command. In this example, \fI\%mongotop\fP will +To force \fBmongotop\fP to return less frequently specify a number, in +seconds at the end of the command. In this example, \fBmongotop\fP will return every 15 seconds. +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongotop 15 .ft P .fi +.UNINDENT +.UNINDENT .sp This command produces the following output: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -272,18 +296,26 @@ test.system.namespaces 0ms 0ms 0ms admin. 0ms 0ms 0ms .ft P .fi +.UNINDENT +.UNINDENT .sp -To return a \fI\%mongotop\fP report every 5 minutes, use the +To return a \fBmongotop\fP report every 5 minutes, use the following command: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C mongotop 300 .ft P .fi +.UNINDENT +.UNINDENT .sp -To report the use of per\-database locks, use \fI\%mongotop --locks\fP, +To report the use of per\-database locks, use \fImongotop \-\-locks\fP, which produces the following output: +.INDENT 0.0 +.INDENT 3.5 .sp .nf .ft C @@ -296,9 +328,11 @@ connected to: 127.0.0.1 . 0ms 0ms 0ms .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. . |