diff options
Diffstat (limited to 'debian/mongorestore.1')
| -rw-r--r-- | debian/mongorestore.1 | 940 |
1 files changed, 748 insertions, 192 deletions
diff --git a/debian/mongorestore.1 b/debian/mongorestore.1 index 7d891f15021..d3180931a7e 100644 --- a/debian/mongorestore.1 +++ b/debian/mongorestore.1 @@ -1,6 +1,6 @@ .\" Man page generated from reStructuredText. . -.TH "MONGORESTORE" "1" "January 30, 2015" "3.0" "mongodb-manual" +.TH "MONGORESTORE" "1" "Jun 21, 2018" "4.0" "mongodb-manual" .SH NAME mongorestore \- MongoDB Data Restoration Tool . @@ -30,72 +30,104 @@ 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 .. +.SS On this page +.INDENT 0.0 +.IP \(bu 2 +\fI\%Synopsis\fP +.IP \(bu 2 +\fI\%Behavior\fP +.IP \(bu 2 +\fI\%Required Access\fP +.IP \(bu 2 +\fI\%Options\fP +.IP \(bu 2 +\fI\%Examples\fP +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.IP "Mac OSX Sierra and Go 1.6 Incompatibility" +.sp +Users running on Mac OSX Sierra require the 3.2.10 or newer version +of mongorestore\&. +.UNINDENT +.UNINDENT .SH SYNOPSIS .sp -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. +The \fI\%mongorestore\fP program loads data from either a binary +database dump created by \fBmongodump\fP or the standard input +(starting in version 3.0.0) into a \fBmongod\fP or +\fBmongos\fP instance. +.sp +Run \fI\%mongorestore\fP from the system command line, not the \fBmongo\fP shell. .sp -\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\&. +For an overview of \fI\%mongorestore\fP usage, see +/tutorial/backup\-and\-restore\-tools\&. .SH BEHAVIOR +.SS Insert Only .sp -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. +\fI\%mongorestore\fP can create a new database or add data to an +existing database. However, \fI\%mongorestore\fP performs inserts +only and does not perform updates. That is, if restoring documents to +an existing database and collection and existing documents have the +same value \fB_id\fP field as the to\-be\-restored documents, +\fI\%mongorestore\fP will \fInot\fP overwrite those documents. +.SS Rebuild Indexes .sp -Remember the following properties of \fBmongorestore\fP behavior: -.INDENT 0.0 -.IP \(bu 2 -\fBmongorestore\fP recreates indexes recorded by +\fI\%mongorestore\fP recreates indexes recorded by \fBmongodump\fP\&. -.IP \(bu 2 -all operations are inserts, not updates. -.IP \(bu 2 -\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 \fBmongorestore\fP will not -receive errors. +\fBNOTE:\fP +.INDENT 0.0 +.INDENT 3.5 +Starting in MongoDB 2.6, creating indexes will error if an +index key in an existing document exceeds the limit\&. See +2.6\-index\-key\-length\-incompatibility for more information and +solution. +.sp +If you have an existing data set that violates this limit but want +to resolve the index issue after restoring the data, you can disable +the default index key length validation on the target database by +setting the \fBmongod\fP instance’s +\fBfailIndexKeyTooLong\fP parameter to false. +.UNINDENT .UNINDENT +.SS Version Compatibility .sp The data format used by \fBmongodump\fP from version 2.2 or later is \fIincompatible\fP with earlier versions of \fBmongod\fP\&. Do not use recent versions of \fBmongodump\fP to back up older data stores. +.SS Exclude \fBsystem.profile\fP Collection +.sp +\fI\%mongorestore\fP does not restore the \fBsystem.profile\fP collection data. +.SH REQUIRED ACCESS +.sp +To restore data to a MongoDB deployment that has access control enabled, the \fBrestore\fP role provides +access to restore any database if the backup data does not include +\fBsystem.profile\fP collection data. +.sp +If the backup data includes \fBsystem.profile\fP collection data and the target database +does not contain the \fBsystem.profile\fP +collection, \fI\%mongorestore\fP attempts to create the collection +even though the program does not actually restore \fBsystem.profile\fP +documents. As such, the user requires additional privileges to perform +\fBcreateCollection\fP and \fBconvertToCapped\fP +actions on the \fBsystem.profile\fP +collection for a database. +.sp +As of MongoDB 3.2.11, you can run \fI\%mongorestore\fP with +\fI\%\-\-oplogReplay\fP if you have the +\fBrestore\fP role. To replay the oplog on versions of MongoDB +3.2.10 and earlier, you must create a +user\-defined role that has +\fBanyAction\fP on resource\-anyresource and grant only +to users who must run \fI\%mongorestore\fP with +\fI\%\-\-oplogReplay\fP\&. +.SH OPTIONS .sp -New in version 3.0.0: \fBmongorestore\fP also accepts input via standard input. - -.SH REQUIRED ACCESS TO RESTORE USER DATA -.sp -Changed in version 2.6. +Changed in version 3.0.0: \fI\%mongorestore\fP removed the \fB\-\-filter\fP, \fB\-\-dbpath\fP, and the +\fB\-\-noobjcheck\fP options. -.sp -To restore users and \fIuser\-defined roles\fP on a -given database, you must have access to the \fBadmin\fP database. MongoDB -stores the user data and role definitions for all databases in the -\fBadmin\fP database. -.sp -Specifically, to restore users to a given database, you must have the -\fBinsert\fP \fIaction\fP on the \fBadmin\fP -database\(aqs \fBadmin.system.users\fP collection. The \fBrestore\fP -role provides this privilege. -.sp -To restore user\-defined roles to a database, you must have the -\fBinsert\fP action on the \fBadmin\fP database\(aqs -\fBadmin.system.roles\fP collection. The \fBrestore\fP role -provides this privilege. -.SH OPTIONS -.INDENT 0.0 -.TP -.B mongorestore -.UNINDENT .INDENT 0.0 .TP .B mongorestore @@ -115,13 +147,13 @@ including the option multiple times, (e.g. \fB\-vvvvv\fP\&.) .INDENT 0.0 .TP .B \-\-quiet -Runs the \fBmongorestore\fP in a quiet mode that attempts to limit the amount +Runs \fBmongorestore\fP in a quiet mode that attempts to limit the amount of output. .sp This option suppresses: .INDENT 7.0 .IP \(bu 2 -output from \fIdatabase commands\fP +output from database commands .IP \(bu 2 replication activity .IP \(bu 2 @@ -137,6 +169,60 @@ Returns the \fBmongorestore\fP release number. .UNINDENT .INDENT 0.0 .TP +.B \-\-uri <connectionString> +New in version 3.4.6. + +.sp +Specify a resolvable URI +connection string for the \fBmongod\fP to which to +connect. +.sp +The following is the standard +URI connection scheme: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For detailed explanations of the components of this string, refer to +the +Connection String URI Format +documentation. +.sp +\fBIMPORTANT:\fP +.INDENT 7.0 +.INDENT 3.5 +The following \fI\%mongorestore\fP options are incompatible with the +\fB\-\-uri\fP option. Instead, specify these options as part of your +\fB\-\-uri\fP connection string when applicable: +.INDENT 0.0 +.IP \(bu 2 +\fB\-\-host\fP +.IP \(bu 2 +\fB\-\-port\fP +.IP \(bu 2 +\fB\-\-db\fP +.IP \(bu 2 +\fB\-\-username\fP +.IP \(bu 2 +\fB\-\-password\fP (when specifying the password as part of the +URI connection string) +.IP \(bu 2 +\fB\-\-authenticationDatabase\fP +.IP \(bu 2 +\fB\-\-authenticationMechanism\fP +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B \-\-host <hostname><:port>, \-h <hostname><:port> \fIDefault\fP: localhost:27017 .sp @@ -176,22 +262,16 @@ client connections. .UNINDENT .INDENT 0.0 .TP -.B \-\-ipv6 -Enables IPv6 support and allows the \fBmongorestore\fP to connect to the -MongoDB instance using an IPv6 network. All MongoDB programs and -processes disable IPv6 support by default. -.UNINDENT -.INDENT 0.0 -.TP .B \-\-ssl New in version 2.6. .sp Enables connection to a \fBmongod\fP or \fBmongos\fP that has -SSL support enabled. +TLS/SSL support enabled. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -203,23 +283,32 @@ Specifies the \fB\&.pem\fP file that contains the root certificate chain from the Certificate Authority. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +Starting in version 3.4, if \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP is not +specified and you are not using x.509 authentication, the +system\-wide CA certificate store will be used when connecting to an +TLS/SSL\-enabled server. +.sp +If using x.509 authentication, \fB\-\-sslCAFile\fP or \fBssl.CAFile\fP +must be specified. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 -If the \fBmongo\fP shell or any other tool that connects to -\fBmongos\fP or \fBmongod\fP is run without -\fI\-\-sslCAFile\fP, it will not attempt to validate -server certificates. This results in vulnerability to expired -\fBmongod\fP and \fBmongos\fP certificates as well as to foreign -processes posing as valid \fBmongod\fP or \fBmongos\fP -instances. Ensure that you \fIalways\fP specify the CA file against which -server certificates should be validated in cases where intrusion is a -possibility. +\fBVersion 3.2 and earlier:\fP For TLS/SSL connections (\fB\-\-ssl\fP) to +\fBmongod\fP and \fBmongos\fP, if the \fBmongorestore\fP runs without the +\fI\%\-\-sslCAFile\fP, \fBmongorestore\fP will not attempt +to validate the server certificates. This creates a vulnerability +to expired \fBmongod\fP and \fBmongos\fP certificates as +well as to foreign processes posing as valid \fBmongod\fP or +\fBmongos\fP instances. Ensure that you \fIalways\fP specify the +CA file to validate the server certificates in cases where +intrusion is a possibility. .UNINDENT .UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -227,17 +316,18 @@ possibility. New in version 2.6. .sp -Specifies the \fB\&.pem\fP file that contains both the SSL certificate +Specifies the \fB\&.pem\fP file that contains both the TLS/SSL certificate and key. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp -This option is required when using the \fI\-\-ssl\fP option to connect +This option is required when using the \fI\%\-\-ssl\fP option to connect to a \fBmongod\fP or \fBmongos\fP that has \fBCAFile\fP enabled \fIwithout\fP \fBallowConnectionsWithoutCertificates\fP\&. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -246,16 +336,17 @@ New in version 2.6. .sp Specifies the password to de\-crypt the certificate\-key file (i.e. -\fI\-\-sslPEMKeyFile\fP). Use the \fI\-\-sslPEMKeyPassword\fP option only if the +\fI\%\-\-sslPEMKeyFile\fP). Use the \fI\%\-\-sslPEMKeyPassword\fP option only if the certificate\-key file is encrypted. In all cases, the \fBmongorestore\fP will redact the password from all logging and reporting output. .sp If the private key in the PEM file is encrypted and you do not specify -the \fI\-\-sslPEMKeyPassword\fP option, the \fBmongorestore\fP will prompt for a passphrase. See -\fIssl\-certificate\-password\fP\&. +the \fI\%\-\-sslPEMKeyPassword\fP option, the \fBmongorestore\fP will prompt for a passphrase. See +ssl\-certificate\-password\&. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -267,8 +358,9 @@ Specifies the \fB\&.pem\fP file that contains the Certificate Revocation List. Specify the file name of the \fB\&.pem\fP file using relative or absolute paths. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -281,8 +373,36 @@ the use of invalid certificates. When using the \fBallowInvalidCertificates\fP setting, MongoDB logs as a warning the use of the invalid certificate. .sp -The default distribution of MongoDB does not contain support for SSL. -For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tutorial/configure\-ssl\&. +Starting in MongoDB 4.0, if you specify +\fB\-\-sslAllowInvalidCertificates\fP or \fBssl.allowInvalidCertificates: +true\fP when using x.509 authentication, an invalid certificate is +only sufficient to establish a TLS/SSL connection but is +\fIinsufficient\fP for authentication. +.sp +\fBWARNING:\fP +.INDENT 7.0 +.INDENT 3.5 +For TLS/SSL connections to \fBmongod\fP and +\fBmongos\fP, avoid using +\fB\-\-sslAllowInvalidCertificates\fP if possible and only use +\fB\-\-sslAllowInvalidCertificates\fP on systems where intrusion is +not possible. +.sp +If the \fBmongo\fP shell (and other +mongodb\-tools\-support\-ssl) runs with the +\fB\-\-sslAllowInvalidCertificates\fP option, the +\fBmongo\fP shell (and other +mongodb\-tools\-support\-ssl) will not attempt to validate +the server certificates. This creates a vulnerability to expired +\fBmongod\fP and \fBmongos\fP certificates as +well as to foreign processes posing as valid +\fBmongod\fP or \fBmongos\fP instances. +.UNINDENT +.UNINDENT +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -290,9 +410,13 @@ For more information on MongoDB and SSL, see http://docs.mongodb.org/manual/tuto New in version 3.0. .sp -Disables the validation of the hostnames in SSL certificates. Allows -\fBmongorestore\fP to connect to MongoDB instances if the hostname their +Disables the validation of the hostnames in TLS/SSL certificates. Allows +\fBmongorestore\fP to connect to MongoDB instances even if the hostname in their certificates do not match the specified hostname. +.sp +For more information about TLS/SSL and MongoDB, see +/tutorial/configure\-ssl and +/tutorial/configure\-ssl\-clients . .UNINDENT .INDENT 0.0 .TP @@ -302,14 +426,14 @@ New in version 2.6. .sp Directs the \fBmongorestore\fP to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use -the \fI\-\-sslFIPSMode\fP option. +the \fI\%\-\-sslFIPSMode\fP option. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 -FIPS Compatible SSL is +FIPS\-compatible TLS/SSL is available only in \fI\%MongoDB Enterprise\fP\&. See -http://docs.mongodb.org/manual/tutorial/configure\-fips for more information. +/tutorial/configure\-fips for more information. .UNINDENT .UNINDENT .UNINDENT @@ -327,31 +451,36 @@ Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the \fB\-\-username\fP and \fB\-\-authenticationDatabase\fP options. .sp -If you do not specify an argument for \fI\-\-password\fP, \fBmongorestore\fP will -prompt interactively for a password on the console. +Changed in version 3.0.0: If you do not specify an argument for \fI\%\-\-password\fP, \fBmongorestore\fP returns +an error. + +.sp +Changed in version 3.0.2: If you wish \fBmongorestore\fP to prompt the user +for the password, pass the \fI\%\-\-username\fP option without +\fI\%\-\-password\fP or specify an empty string as the \fI\%\-\-password\fP value, +as in \fB\-\-password ""\fP . + .UNINDENT .INDENT 0.0 .TP .B \-\-authenticationDatabase <dbname> -New in version 2.4. - -.sp -Specifies the database that holds the user\(aqs credentials. +Specifies the database in which the user is created. +See user\-authentication\-database\&. .UNINDENT .INDENT 0.0 .TP .B \-\-authenticationMechanism <name> -\fIDefault\fP: MONGODB\-CR -.sp -New in version 2.4. - -.sp -Changed in version 2.6: Added support for the \fBPLAIN\fP and \fBMONGODB\-X509\fP authentication -mechanisms. - +\fIDefault\fP: SCRAM\-SHA\-1 .sp Specifies the authentication mechanism the \fBmongorestore\fP instance uses to authenticate to the \fBmongod\fP or \fBmongos\fP\&. +.sp +Changed in version 4.0: MongoDB removes support for the deprecated MongoDB +Challenge\-Response (\fBMONGODB\-CR\fP) authentication mechanism. +.sp +MongoDB adds support for SCRAM mechanism using the SHA\-256 hash +function (\fBSCRAM\-SHA\-256\fP). + .TS center; |l|l|. @@ -363,33 +492,47 @@ Description T} _ T{ -MONGODB\-CR +SCRAM\-SHA\-1 T} T{ -MongoDB challenge/response authentication. +\fI\%RFC 5802\fP standard +Salted Challenge Response Authentication Mechanism using the SHA\-1 +hash function. T} _ T{ -MONGODB\-X509 +SCRAM\-SHA\-256 T} T{ -MongoDB SSL certificate authentication. +\fI\%RFC 7677\fP standard +Salted Challenge Response Authentication Mechanism using the SHA\-256 +hash function. +.sp +Requires featureCompatibilityVersion set to \fB4.0\fP\&. +.sp +New in version 4.0. T} _ T{ -PLAIN +MONGODB\-X509 T} T{ -External authentication using LDAP. You can also use \fBPLAIN\fP -for authenticating in\-database users. \fBPLAIN\fP transmits -passwords in plain text. This mechanism is available only in -\fI\%MongoDB Enterprise\fP\&. +MongoDB TLS/SSL certificate authentication. T} _ T{ -GSSAPI +GSSAPI (Kerberos) T} T{ External authentication using Kerberos. This mechanism is available only in \fI\%MongoDB Enterprise\fP\&. T} _ +T{ +PLAIN (LDAP SASL) +T} T{ +External authentication using LDAP. You can also use \fBPLAIN\fP +for authenticating in\-database users. \fBPLAIN\fP transmits +passwords in plain text. This mechanism is available only in +\fI\%MongoDB Enterprise\fP\&. +T} +_ .TE .UNINDENT .INDENT 0.0 @@ -398,7 +541,7 @@ _ New in version 2.6. .sp -Specify the name of the service using \fBGSSAPI/Kerberos\fP\&. Only required if the service does not use the +Specify the name of the service using GSSAPI/Kerberos\&. Only required if the service does not use the default name of \fBmongodb\fP\&. .sp This option is available only in MongoDB Enterprise. @@ -409,7 +552,7 @@ This option is available only in MongoDB Enterprise. New in version 2.6. .sp -Specify the hostname of a service using \fBGSSAPI/Kerberos\fP\&. \fIOnly\fP required if the hostname of a machine does +Specify the hostname of a service using GSSAPI/Kerberos\&. \fIOnly\fP required if the hostname of a machine does not match the hostname resolved by DNS. .sp This option is available only in MongoDB Enterprise. @@ -424,7 +567,7 @@ 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\%\-\-db\fP does \fInot\fP control which BSON files \fBmongorestore\fP restores. You must use the \fBmongorestore\fP \fI\%path option\fP to limit that restored data. @@ -440,56 +583,217 @@ name. .UNINDENT .INDENT 0.0 .TP -.B \-\-objcheck -Forces \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 on performance. You can set -\fI\%\-\-noobjcheck\fP to disable object checking at run\-time. +.B \-\-nsExclude <namespace pattern> +New in version 3.4. + .sp -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. +Excludes the specified namespaces from the +restore operation. +.sp +\fI\%\-\-nsExclude\fP accepts a \fInamespace pattern\fP as its argument. The namespace +pattern permits \fI\%\-\-nsExclude\fP to refer to any namespace that matches the +specified pattern. \fI\%mongorestore\fP matches the smallest valid occurence +of the namespace pattern. +.sp +Use asterisks (\fB*\fP) as wild cards. Escape all literal asterisks +and backslashes with a backslash. \fI\%Restore Collections Using Wild Cards\fP +provides an example of using asterisks as wild cards. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-nsInclude <namespace pattern> +New in version 3.4. + +.sp +Includes only the specified namespaces in the +restore operation. +By enabling you to specify multiple collections to restore, +\fI\%\-\-nsInclude\fP offers a superset of the functionality of the +\fI\%\-\-collection\fP option. +.sp +\fI\%\-\-nsInclude\fP accepts a \fInamespace pattern\fP as its argument. The namespace +pattern permits \fI\%\-\-nsInclude\fP to refer to any namespace that matches the +specified pattern. \fI\%mongorestore\fP matches the smallest valid occurence +of the namespace pattern. +.sp +Use asterisks (\fB*\fP) as wild cards. Escape all literal asterisks +and backslashes with a backslash. \fI\%Restore Collections Using Wild Cards\fP +provides an example of using asterisks as wild cards. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-nsFrom <namespace pattern> +New in version 3.4. +.sp +Use with \fI\%\-\-nsTo\fP to rename a namespace during the +restore operation. \fI\%\-\-nsFrom\fP specifies the collection in the +dump file, while \fI\%\-\-nsTo\fP specifies the name that should be +used in the restored database. +.sp +\fI\%\-\-nsFrom\fP accepts a \fInamespace pattern\fP as its argument. The namespace +pattern permits \fI\%\-\-nsFrom\fP to refer to any namespace that matches the +specified pattern. \fI\%mongorestore\fP matches the smallest valid occurence +of the namespace pattern. +.sp +For simple replacements, use asterisks (\fB*\fP) as wild cards. +Escape all literal asterisks and backslashes with a backslash. +Replacements correspond linearly to matches: each asterisk in +\fB\-\-nsFrom\fP must correspond to an asterisk in \fB\-\-nsTo\fP, and the +first asterisk in \fB\-\-nsFrom\fP matches the first asterisk in \fBnsTo\fP\&. +.sp +For more complex replacements, use dollar signs to delimit a “wild +card” variable to use in the replacement. +\fI\%Change Collections’ Namespaces during Restore\fP provides an example of complex +replacements with dollar sign\-delimited wild cards. +.sp +Unlike replacements with asterisks, replacements with dollar +sign\-delimited wild cards do \fBnot\fP need to be linear. .UNINDENT .INDENT 0.0 .TP -.B \-\-noobjcheck -New in version 2.4. +.B \-\-nsTo <namespace pattern> +New in version 3.4. .sp -Disables the default document validation that MongoDB performs on all -incoming BSON documents. +Use with \fI\%\-\-nsFrom\fP to rename a namespace during the +restore operation. \fI\%\-\-nsTo\fP specifies the new collection +name to use in the restored database, while +\fI\%\-\-nsFrom\fP specifies the name in the dump file. +.sp +\fI\%\-\-nsTo\fP accepts a \fInamespace pattern\fP as its argument. The namespace +pattern permits \fI\%\-\-nsTo\fP to refer to any namespace that matches the +specified pattern. \fI\%mongorestore\fP matches the smallest valid occurence +of the namespace pattern. +.sp +For simple replacements, use asterisks (\fB*\fP) as wild cards. +Escape all literal asterisks and backslashes with a backslash. +Replacements correspond linearly to matches: each asterisk in +\fB\-\-nsFrom\fP must correspond to an asterisk in \fB\-\-nsTo\fP, and the +first asterisk in \fB\-\-nsFrom\fP matches the first asterisk in \fBnsTo\fP\&. +.sp +For more complex replacements, use dollar signs to delimit a “wild +card” variable to use in the replacement. +\fI\%Change Collections’ Namespaces during Restore\fP provides an example of complex +replacements with dollar sign\-delimited wild cards. +.sp +Unlike replacements with asterisks, replacements with dollar +sign\-delimited wild cards do \fBnot\fP need to be linear. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-objcheck +Forces \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 on performance. .UNINDENT .INDENT 0.0 .TP .B \-\-drop -Modifies the restoration procedure to drop every collection from the -target database before restoring the collection from the dumped backup. +Before restoring the collections from the dumped backup, drops the +collections from the target database. \fI\%\-\-drop\fP does not drop +collections that are not in the backup. +.sp +When the restore includes the \fBadmin\fP database, \fBmongorestore\fP with +\fI\%\-\-drop\fP removes all user credentials and replaces them with the +users defined in the dump file. Therefore, in systems with +\fBauthorization\fP enabled, \fBmongorestore\fP must be able +to authenticate to an existing user \fIand\fP to a user defined in the +dump file. If \fBmongorestore\fP can’t authenticate to a user defined in the +dump file, the restoration process will fail, leaving an empty +database. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dryRun +New in version 3.4. + .sp -With \fI\%\-\-drop\fP specified, \fBmongorestore\fP removes all user -credentials and replaces them with users defined in the dump -file. Therefore, in systems with \fBauthorization\fP -enabled, \fBmongorestore\fP must be able to authenticate to an existing -user \fIand\fP to a user defined in the dump file. If \fBmongorestore\fP can\(aqt -authenticate to a user defined in the dump file, the restoration -process will fail, leaving an empty database. +Runs \fBmongorestore\fP without actually importing any data, returning the +\fBmongorestore\fP summary information. Use with \fB\-\-verbose\fP to produce +more detailed summary information. .UNINDENT .INDENT 0.0 .TP .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. For an example of -\fI\%\-\-oplogReplay\fP, see \fIbackup\-restore\-oplogreplay\fP\&. +After restoring the database dump, replays the oplog entries +from a bson file. +When used in conjunction with \fBmongodump \-\-oplog\fP, +\fB~bin.mongorestore \-\-oplogReplay\fP +restores the database to the point\-in\-time backup captured with the +\fBmongodump \-\-oplog\fP command. +.sp +\fBmongorestore\fP searches for any valid source for the bson file +in the following locations: +.INDENT 7.0 +.IP \(bu 2 +The top level of the dump directory, as in the case of a dump created +with \fBmongodump \-\-oplog\fP\&. +.IP \(bu 2 +The path specified by \fI\%\-\-oplogFile\fP\&. +.IP \(bu 2 +\fB<dump\-directory>/local/oplog.rs.bson\fP, as in the case of a dump +of the \fBoplog.rs\fP collection in the \fBlocal\fP database +on a \fBmongod\fP that is a member of a replica set. +.UNINDENT +.sp +If there is an \fBoplog.bson\fP file at the top level of the dump +directory \fBand\fP a path specified by \fI\%\-\-oplogFile\fP, +\fBmongorestore\fP returns an error. +.sp +If there is an \fBoplog.bson\fP file at the top level of the dump directory, +\fBmongorestore\fP restores that file as the oplog. If there are also bson +files in the \fBdump/local\fP directory, \fBmongorestore\fP restores them like +normal collections. +.sp +If you specify an oplog file using \fI\%\-\-oplogFile\fP, +\fBmongorestore\fP restores that file as the oplog. If there are also bson +files in the \fBdump/local\fP directory, \fBmongorestore\fP restores them like +normal collections. +.sp +For an example of \fI\%\-\-oplogReplay\fP, see backup\-restore\-oplogreplay\&. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +When using \fI\%mongorestore\fP with \fI\%\-\-oplogReplay\fP to restore +a replica set, you must +restore a full dump of a replica set member created +using \fB~bin.mongodump \-\-oplog\fP\&. +\fI\%mongorestore\fP with \fI\%\-\-oplogReplay\fP fails if you use any of +the following options to limit the data be restored: +.INDENT 0.0 +.IP \(bu 2 +\fI\%\-\-db\fP +.IP \(bu 2 +\fI\%\-\-collection\fP +.IP \(bu 2 +\fI\%\-\-nsInclude\fP +.IP \(bu 2 +\fI\%\-\-nsExclude\fP +.UNINDENT +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +\fI\%mongorestore Required Access\fP +.UNINDENT +.UNINDENT +.sp +\fBSEE ALSO:\fP +.INDENT 7.0 +.INDENT 3.5 +\fBmongodump \-\-oplog\fP +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-oplogLimit <timestamp> -New in version 2.2. - -.sp -Prevents \fBmongorestore\fP from applying \fIoplog\fP entries +Prevents \fBmongorestore\fP from applying oplog entries with timestamp newer than or equal to \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 @@ -501,6 +805,19 @@ You must use \fI\%\-\-oplogLimit\fP in conjunction with the .UNINDENT .INDENT 0.0 .TP +.B \-\-oplogFile <path> +New in version 3.4. + +.sp +Specifies the path to the oplog file containing oplog data for the +restore. Use with \fI\%\-\-oplogReplay\fP\&. +.sp +If you specify \fI\%\-\-oplogFile\fP and there is an \fBoplog.bson\fP +file at the top level of the dump directory, \fBmongorestore\fP returns an +error. +.UNINDENT +.INDENT 0.0 +.TP .B \-\-keepIndexVersion Prevents \fBmongorestore\fP from upgrading the index to the latest version during the restoration process. @@ -508,49 +825,32 @@ version during the restoration process. .INDENT 0.0 .TP .B \-\-noIndexRestore -New in version 2.2. - -.sp Prevents \fBmongorestore\fP from restoring and building indexes as specified in the corresponding \fBmongodump\fP output. .UNINDENT .INDENT 0.0 .TP .B \-\-noOptionsRestore -New in version 2.2. - -.sp Prevents \fBmongorestore\fP from setting the collection options, -such as those specified by the \fBcollMod\fP \fIdatabase -command\fP, on restored collections. +such as those specified by the \fBcollMod\fP database +command, on restored collections. .UNINDENT .INDENT 0.0 .TP .B \-\-restoreDbUsersAndRoles Restore user and role definitions for the given database. See -http://docs.mongodb.org/manual/reference/system\-roles\-collection and -http://docs.mongodb.org/manual/reference/system\-users\-collection for more information. -.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 -\fBmongorestore\fP writes to the target database. By default, -\fBmongorestore\fP does not wait for a response for \fIwrite -acknowledgment\fP\&. +/reference/system\-roles\-collection and +/reference/system\-users\-collection for more information. .UNINDENT .INDENT 0.0 .TP .B \-\-writeConcern <document> \fIDefault\fP: majority .sp -Specifies the \fIwrite concern\fP for each write operation that \fBmongorestore\fP +Specifies the write concern for each write operation that \fBmongorestore\fP writes to the target database. .sp -Specify the write concern as a document with \fIw options\fP\&. +Specify the write concern as a document with w options\&. .UNINDENT .INDENT 0.0 .TP @@ -568,6 +868,57 @@ perform the insertions in an arbitrary order. .sp Number of collections \fBmongorestore\fP should restore in parallel. +.sp +If you specify \fB\-j\fP when restoring a \fIsingle\fP collection, \fB\-j\fP +maps to the \fI\%\-\-numInsertionWorkersPerCollection\fP option rather than +\fI\%\-\-numParallelCollections\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-numInsertionWorkersPerCollection int +\fIDefault\fP: 1 +.sp +New in version 3.0.0. + +.sp +Specifies the number of insertion workers to run concurrently per collection. +.sp +For large imports, increasing the number of insertion workers +may increase the speed of the import. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-stopOnError +New in version 3.0. + +.sp +Forces \fBmongorestore\fP to halt the restore when it encounters an +error. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-bypassDocumentValidation +Enables \fBmongorestore\fP to bypass document validation +during the operation. This lets you insert documents that do not +meet the validation requirements. +.sp +New in version 3.2.1. + +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-gzip +New in version 3.2. + +.sp +Restores from compressed files or data stream created by +\fB~bin.mongodump \-\-archive\fP +.sp +To restore from a dump directory that contains compressed files, run +\fI\%mongorestore\fP with the new \fB\-\-gzip\fP option. +.sp +To restore from a compressed archive file, run \fI\%mongorestore\fP with +the \fB\-\-gzip\fP option in conjunction with the \fB\-\-archive\fP option. .UNINDENT .INDENT 0.0 .TP @@ -575,19 +926,51 @@ in parallel. 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. +.sp +You cannot specify both the \fB<path>\fP argument and the \fB\-\-dir\fP +option, which also specifies the dump directory, to \fBmongorestore\fP\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-archive <=file|null> +New in version 3.2. + +.sp +Restores from an archive file or from the standard input (\fBstdin\fP). +.sp +To restore from an archive file, run \fBmongorestore\fP with the \fB\-\-archive\fP +option and the archive filename. +.sp +To restore from the standard input, run \fBmongorestore\fP with the +\fB\-\-archive\fP option but \fIomit\fP the filename. +.sp +\fBNOTE:\fP +.INDENT 7.0 +.INDENT 3.5 +.INDENT 0.0 +.IP \(bu 2 +You cannot use the \fB\-\-archive\fP option with the \fB\-\-dir\fP option. +.IP \(bu 2 +\fBmongorestore\fP still supports the positional \fB\-\fP parameter to +restore a \fIsingle\fP collection from the standard input. +.UNINDENT +.UNINDENT +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-dir string Specifies the dump directory. +.INDENT 7.0 +.IP \(bu 2 +You cannot specify both the \fB\-\-dir\fP option and the \fB<path>\fP +argument, which also specifies the dump directory, to \fBmongorestore\fP\&. +.IP \(bu 2 +You cannot use the \fB\-\-archive\fP option with the \fB\-\-dir\fP option. .UNINDENT -.SH USE -.sp -See http://docs.mongodb.org/manual/tutorial/backup\-with\-mongodump -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. +.UNINDENT +.SH EXAMPLES +.SS Restore a Collection .sp Consider the following example: .INDENT 0.0 @@ -595,43 +978,216 @@ Consider the following example: .sp .nf .ft C -mongorestore \-\-collection people \-\-db accounts dump/accounts/people.bson +mongorestore \-\-collection people \-\-db accounts dump/ .ft P .fi .UNINDENT .UNINDENT .sp -Here, \fBmongorestore\fP reads the database dump in the \fBdump/\fP +Here, \fI\%mongorestore\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\&. \fBmongorestore\fP restores data to the instance +\fBaccounts\fP\&. \fI\%mongorestore\fP restores data to the instance running on the localhost interface on port \fB27017\fP\&. .sp -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\&. The \fBmongorestore\fP command authenticates to -the MongoDB instance using the username \fBuser\fP and the -password \fBpass\fP, as follows: +New in version 3.4. + +.sp +You may alternatively use \fI\%\-\-nsInclude\fP to specify the canonical name of the collection that you +wish to restore rather than \fI\%\-\-collection\fP\&. \fI\%\-\-nsInclude\fP +enables you to specify the namespace of one or more collections +that you wish to include in the restore operation. The following +example restores the \fBpeople\fP collection from the \fBaccounts\fP +database in the \fBdump/\fP sub\-directory of the current directory: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongorestore \-\-nsInclude accounts.people dump/ +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Restore Collections Using Wild Cards +.sp +New in version 3.4. + +.sp +\fI\%\-\-nsInclude\fP and +\fI\%\-\-nsExclude\fP support specifying the +namespaces you wish to include or exclude from a +restore operation using asterisks as \fIwild cards\fP\&. +.sp +The following example restores the documents in the \fBdump/\fP +sub\-directory of the current directory that match the specified +namespace pattern. The \fI\%\-\-nsInclude\fP +statement specifies to only restore documents in the \fBtransactions\fP +database while \fI\%\-\-nsExclude\fP +instructs \fI\%mongorestore\fP to exclude collections whose +names end with \fB_dev\fP\&. \fI\%mongorestore\fP restores data to +the \fBmongod\fP instance running on the localhost interface +on port \fB27017\fP\&. .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 +mongorestore \-\-nsInclude \(aqtransactions.*\(aq \-\-nsExclude \(aqtransactions.*_dev\(aq dump/ .ft P .fi .UNINDENT .UNINDENT +.SS Change Collections’ Namespaces during Restore .sp -You can also \fIpipe\fP data directly into to \fBmongorestore\fP +New in version 3.4. + +.sp +MongoDB 3.4 added the \fI\%\-\-nsFrom\fP and +\fI\%\-\-nsTo\fP options, which enable you to +change the namespace of a collection that you are restoring. +\fI\%\-\-nsFrom\fP and \fI\%\-\-nsTo\fP support using asterisks as wild cards \fIand\fP +support using dollar signs to delimit “wild card” variables to use in +the replacement. +.sp +Consider a database \fBdata\fP that you have exported to a \fBdump/\fP +directory using \fBmongodump\fP\&. The \fBdata\fP database +contains the following collections: +.INDENT 0.0 +.IP \(bu 2 +\fBsales_customer1\fP +.IP \(bu 2 +\fBsales_customer2\fP +.IP \(bu 2 +\fBsales_customer3\fP +.IP \(bu 2 +\fBusers_customer1\fP +.IP \(bu 2 +\fBusers_customer2\fP +.IP \(bu 2 +\fBusers_customer3\fP +.UNINDENT +.sp +Using \fI\%\-\-nsFrom\fP and \fI\%\-\-nsTo\fP, you can restore the data into different +namespaces. The following operation +.INDENT 0.0 +.IP \(bu 2 +restores the \fBsales_<customerName>\fP collections in the \fBdata\fP +database to \fBsales\fP collections in the \fB<customerName>\fP database, +and +.IP \(bu 2 +restores the \fBusers_<customerName>\fP collections to \fBusers\fP +collections in the \fB<customerName>\fP database. +.UNINDENT +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongorestore \-\-nsInclude \(aqdata.*\(aq \-\-nsFrom \(aqdata.$prefix$_$customer$\(aq \-\-nsTo \(aq$customer$.$prefix$\(aq +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Restore with Access Control +.sp +In the following example, \fI\%mongorestore\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\&. The \fI\%mongorestore\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 +.SS Restore a Collection from Standard Input +.sp +You can also \fIpipe\fP data directly into to \fI\%mongorestore\fP through standard input, as in the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C -zcat /opt/backup/mongodump\-2014\-12\-03/accounts.people.bson.gz | mongorestore \-\-collection people \-\-db accounts +zcat /opt/backup/mongodump\-2014\-12\-03/accounts.people.bson.gz | mongorestore \-\-collection people \-\-db accounts \- +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Restore a Database from an Archive File +.sp +New in version 3.2. + +.sp +To restore from an archive file, run \fBrestore\fP with the new +\fB\-\-archive\fP option and the archive filename. For example, the +following operation restores the \fBtest\fP database from the file +\fBtest.20150715.archive\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongorestore \-\-archive=test.20150715.archive \-\-db test +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Restore a Database from Standard Input +.sp +New in version 3.2. + +.sp +To restore from the standard input, run \fI\%mongorestore\fP +with the \fBarchive\fP option but \fIomit\fP the filename. For example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongodump \-\-archive \-\-db test \-\-port 27017 | mongorestore \-\-archive \-\-port 27018 +.ft P +.fi +.UNINDENT +.UNINDENT +.SS Restore from Compressed Data +.sp +New in version 3.2: With the \fB\-\-gzip\fP option, \fI\%mongorestore\fP can restore from +compressed files or data stream created by \fBmongodump\fP\&. + +.sp +To restore from a dump directory that contains compressed files, run +\fI\%mongorestore\fP with the new \fB\-\-gzip\fP option. For +example, the following operation restores the \fBtest\fP database from +the compressed files located in the default \fBdump\fP directory: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongorestore \-\-gzip \-\-db test +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To restore from a compressed archive file, run \fI\%mongorestore\fP +with the \fB\-\-gzip\fP option in conjunction with the new \fB\-\-archive\fP +option. For example, the following operation restores the \fBtest\fP +database from the archive file \fBtest.20150715.gz\fP\&. +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongorestore \-\-gzip \-\-archive=test.20150715.gz \-\-db test .ft P .fi .UNINDENT @@ -639,6 +1195,6 @@ zcat /opt/backup/mongodump\-2014\-12\-03/accounts.people.bson.gz | mongorestore .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2015 +2008-2018 .\" Generated by docutils manpage writer. . |