diff options
author | Ernie Hershey <ernie.hershey@10gen.com> | 2014-02-28 11:16:26 -0500 |
---|---|---|
committer | Ernie Hershey <ernie.hershey@10gen.com> | 2014-03-19 09:52:12 -0400 |
commit | 3b0a2b212f6003b4aaa9d8e1c0d8cb841cd2496f (patch) | |
tree | 900952421e1e87f95f662170c6ef4e8878c27496 /debian/mongoimport.1 | |
parent | dcae4f6f020b0ee94a28ecb47577ad30fe11ddae (diff) | |
download | mongo-3b0a2b212f6003b4aaa9d8e1c0d8cb841cd2496f.tar.gz |
SERVER-11045 Update man pages from the MongoDB Manual
This is a direct copy of generated man page content from
the MongoDB Manual.
Diffstat (limited to 'debian/mongoimport.1')
-rw-r--r-- | debian/mongoimport.1 | 379 |
1 files changed, 246 insertions, 133 deletions
diff --git a/debian/mongoimport.1 b/debian/mongoimport.1 index 28afbb21649..95e9e6f80da 100644 --- a/debian/mongoimport.1 +++ b/debian/mongoimport.1 @@ -1,8 +1,8 @@ .\" Man page generated from reStructuredText. . -.TH "MONGOIMPORT" "1" "October 03, 2013" "2.4" "mongodb-manual" +.TH "MONGOIMPORT" "1" "March 18, 2014" "2.6" "mongodb-manual" .SH NAME -mongoimport \- MongoDB +mongoimport \- MongoDB Import Utility . .nr rst2man-indent-level 0 . @@ -38,18 +38,14 @@ potentially, another third\-party export tool. See the 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. +provides the inverse "exporting" capability. +.SH CONSIDERATIONS .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 http://docs.mongodb.org/manual/core/backups for this kind of functionality. -.UNINDENT -.UNINDENT .SH OPTIONS .INDENT 0.0 .TP @@ -61,43 +57,52 @@ functionality. .UNINDENT .INDENT 0.0 .TP -.B \-\-help -Returns a basic help and usage text. +.B \-\-help, \-h +Returns information on \fBmongoimport\fP options and usage. .UNINDENT .INDENT 0.0 .TP .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\&.) +Increases the amount of internal reporting returned on standard output +or in log files. Increase the verbosity with the \fB\-v\fP form by +including the option multiple times, (e.g. \fB\-vvvvv\fP\&.) +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-quiet +Runs \fBmongoimport\fP 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 +.IP \(bu 2 +replication activity +.IP \(bu 2 +connection accepted events +.IP \(bu 2 +connection closed events +.UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-version -Returns the version of the \fBmongoimport\fP program. +Returns the \fBmongoimport\fP release number. .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 \fBmongoimport\fP -will attempt to connect to a MongoDB process ruining on the -localhost port numbered \fB27017\fP\&. -.sp -Optionally, specify a port number to connect a MongoDB instance -running on a port other than \fB27017\fP\&. -.sp -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. \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: +Specifies a resolvable hostname for the \fBmongod\fP to which to +connect. By default \fBmongoimport\fP attempts to connect to a MongoDB instance +running on the localhost on port number \fB27017\fP\&. +.sp +To connect to a replica set, specify the replica set seed name and the +seed list of set members. Use the following format: .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 +<replica_set_name>/<hostname1><:port>,<hostname2:<port>,... .ft P .fi .UNINDENT @@ -109,187 +114,245 @@ specifying the host and port number directly. .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 \fImongoimport \-\-host\fP command. +Specifies the port number when the MongoDB instance is not running on the +standard port of \fB27017\fP\&. You may also specify the port number +using the \fB\-\-host\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-ipv6 -Enables IPv6 support that allows \fBmongoimport\fP to connect -to the MongoDB instance using an IPv6 network. All MongoDB programs -and processes, including \fBmongoimport\fP, disable IPv6 -support by default. +Enables IPv6 support, which allows \fBmongoimport\fP to connect to the MongoDB +instance using an IPv6 network. All MongoDB programs 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\&. +New in version 2.6. .sp -\fBNOTE:\fP -.INDENT 7.0 -.INDENT 3.5 -SSL support in mongoimport is not compiled into the default -distribution of MongoDB. See -http://docs.mongodb.org/manual/tutorial/configure\-ssl for more information on SSL -and MongoDB. +Enables connection to a \fBmongod\fP or \fBmongos\fP that has +SSL support enabled. .sp -Additionally, mongoimport does not support connections to -\fBmongod\fP instances that require client certificate -validation. +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\&. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslCAFile <filename> +New in version 2.6. + +.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 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\&. .UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslPEMKeyFile <filename> +New in version 2.6. + +.sp +Specifies the \fB\&.pem\fP file that contains both the SSL certificate +and key. Specify the file name of the \fB\&.pem\fP file using relative +or absolute paths. .sp -Allows \fBmongoimport\fP to connect to \fBmongod\fP -instance over an SSL connection. +This option is required when using the \fI\-\-ssl\fP option to connect +to a \fBmongod\fP or \fBmongos\fP that has +\fBsslCAFile\fP enabled \fIwithout\fP +\fBsslWeakCertificateValidation\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\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-username <username>, \-u <username> -Specifies a username to authenticate to the MongoDB instance, if your -database requires authentication. Use in conjunction with the -\fImongoimport \-\-password\fP option to supply a password. +.B \-\-sslPEMKeyPassword <value> +New in version 2.6. + +.sp +Specifies the password to de\-crypt the certificate\-key file (i.e. +\fI\-\-sslPEMKeyFile\fP). Use \fI\-\-sslPEMKeyPassword\fP only if +the certificate\-key file is encrypted. In all cases, \fBmongoimport\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 +\fI\-\-sslPEMKeyPassword\fP, \fBmongoimport\fP will prompt for a passphrase. +See \fIssl\-certificate\-password\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\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-password <password>, \-p <password> -Specifies a password to authenticate to the MongoDB instance. Use -in conjunction with the \fImongoimport \-\-username\fP option to -supply a username. +.B \-\-sslCRLFile <filename> +New in version 2.6. + +.sp +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 -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. +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\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-authenticationDatabase <dbname> -New in version 2.4. +.B \-\-sslAllowInvalidCertificates +New in version 2.6. .sp -Specifies the database that holds the user\(aqs (e.g -\fI\-\-username\fP) credentials. +Bypasses the validation checks for server certificates and allows +the use of invalid certificates. When using the +\fBsslAllowInvalidCertificates\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\&. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-sslFIPSMode +New in version 2.6. + .sp -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\&. +Directs \fBmongoimport\fP to use the FIPS mode of the installed OpenSSL +library. Your system must +have a FIPS compliant OpenSSL library to use \fI\-\-sslFIPSMode\fP\&. .sp -See \fBuserSource\fP, -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. +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\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-authenticationMechanism <name> +.B \-\-username <username>, \-u +Specifies a username with which to authenticate to a MongoDB database +that uses authentication. Use in conjunction with the \fB\-\-password\fP and +\fB\-\-authenticationDatabase\fP options. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-password <password>, \-p +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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-authenticationDatabase <dbname> 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 MongoDB Enterprise, -\fBmongoimport\fP also includes support for \fBGSSAPI\fP to handle -Kerberos authentication. +Specifies the database that holds the user\(aqs credentials. +If you do not specify an authentication database, \fBmongoimport\fP assumes +that the database specified as the argument to the \fI\-\-db\fP option +holds the user\(aqs credentials. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-authenticationMechanism <name> +New in version 2.4. + .sp -See http://docs.mongodb.org/manual/tutorial/control\-access\-to\-mongodb\-with\-kerberos\-authentication +Specifies the authentication mechanism. By default, the authentication +mechanism is \fBMONGODB\-CR\fP, which is the MongoDB challenge/response +authentication mechanism. In MongoDB Enterprise, \fBmongoimport\fP also includes +support for \fBGSSAPI\fP to handle Kerberos authentication. 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 -\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. +\fI\-\-dbpath\fP option enables \fBmongoimport\fP to attach directly to local data +files without a running \fBmongod\fP\&. When run with \fI\-\-dbpath\fP, +\fBmongoimport\fP locks access to the data directory. 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 -\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 +When used in conjunction with the corresponding option in +\fBmongod\fP, allows \fBmongoimport\fP to access data from MongoDB +instances that use an on\-disk format where every database has a distinct +directory. This option is only relevant when specifying the \fI\-\-dbpath\fP option. .UNINDENT .INDENT 0.0 .TP .B \-\-journal -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 +Allows \fBmongoimport\fP operations to use the durability \fIjournal\fP to +ensure data files remain valid and recoverable. This option is only 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 -\fBmongoimport\fP to import data. +.B \-\-db <database>, \-d +Specifies the name of the database on which to run \fBmongoimport\fP\&. .UNINDENT .INDENT 0.0 .TP -.B \-\-collection <collection>, \-c <collection> -Use the \fI\-\-collection\fP option to specify a collection for -\fBmongoimport\fP to import. +.B \-\-collection <collection>, \-c +Specifies the collection to import. +.sp +New in version 2.6: If you do not specify \fI\-\-collection\fP, +\fBmongoimport\fP takes the collection name from the input +filename. MongoDB omits the extension of the file from the +collection name, if the input file has an extension. + .UNINDENT .INDENT 0.0 .TP -.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. +.B \-\-fields <field1[,field2]>, \-f +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 .INDENT 0.0 .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>\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. +As an alternative to \fI\%\-\-fields\fP, the \fI\%\-\-fieldFile\fP +option allows you to specify a file that holds a list of field names if +your \fIcsv\fP or \fItsv\fP file does not include field names in the +first line of the file (i.e. header). Place one field per line. .UNINDENT .INDENT 0.0 .TP .B \-\-ignoreBlanks -In \fIcsv\fP and \fItsv\fP exports, ignore empty fields. If not +Ignores empty fields in \fIcsv\fP and \fItsv\fP exports. If not specified, \fBmongoimport\fP creates fields without values in imported documents. .UNINDENT .INDENT 0.0 .TP .B \-\-type <json|csv|tsv> -Declare the type of export format to import. The default format is -\fIJSON\fP, but it\(aqs possible to import \fIcsv\fP and -\fItsv\fP files. +Specifies the file type to import. The default format is \fIJSON\fP, +but it\(aqs possible to import \fIcsv\fP and \fItsv\fP files. .UNINDENT .INDENT 0.0 .TP .B \-\-file <filename> -Specify the location of a file containing the data to -import. \fBmongoimport\fP will read data from standard input -(e.g. "stdin.") if you do not specify a file. +Specifies the location and name of a file containing the data to import. +If you do not specify a file, \fBmongoimport\fP reads data from +standard input (e.g. "stdin"). .UNINDENT .INDENT 0.0 .TP .B \-\-drop -Modifies the import process so that the target instance -drops every collection before importing the collection from the -input. +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, \fBmongoimport\fP will import the first -line as a distinct document. +If using \fI\-\-type csv\fP or \fI\-\-type +tsv\fP, uses the first line as field names. +Otherwise, \fBmongoimport\fP will import the first line as a +distinct document. .UNINDENT .INDENT 0.0 .TP @@ -299,7 +362,7 @@ 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 \fBmongoimport\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 @@ -326,17 +389,14 @@ first error rather than continuing the operation despite errors. .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 documents +Accepts the import of data expressed with multiple MongoDB documents within a single \fIJSON\fP array. .sp -Use in conjunction with \fImongoexport \-\-jsonArray\fP to +Used in conjunction with \fImongoexport \-\-jsonArray\fP to import data written as a single \fIJSON\fP array. Limited to imports of 16 MB or smaller. .UNINDENT -.SH USAGE +.SH USE .sp In this example, \fBmongoimport\fP imports the \fIcsv\fP formatted data in the \fB/opt/backups/contacts.csv\fP into the @@ -353,10 +413,25 @@ mongoimport \-\-db users \-\-collection contacts \-\-type csv \-\-file /opt/back .UNINDENT .UNINDENT .sp +Since \fBmongoimport\fP uses the input file name (minus the +extension) as the collection name if \fB\-c\fP or \fB\-\-collection\fP is +unspecified, the following example is equivalent to the previous +example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +mongoimport \-\-db users \-\-type csv \-\-file /opt/backups/contacts.csv +.ft P +.fi +.UNINDENT +.UNINDENT +.sp 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. +number 27017. .INDENT 0.0 .INDENT 3.5 .sp @@ -370,7 +445,6 @@ mongoimport \-\-collection contacts \-\-file contacts.json .sp 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 \fBmongoimport\fP will halt because of the \fI\-\-stopOnError\fP option. @@ -402,9 +476,48 @@ mongoimport \-\-host mongodb1.example.net \-\-port 37017 \-\-username user \-\-p .fi .UNINDENT .UNINDENT +.SH TYPE FIDELITY +.sp +\fBWARNING:\fP +.INDENT 0.0 +.INDENT 3.5 +\fBmongoimport\fP and \fBmongoexport\fP do not reliably +preserve all rich \fIBSON\fP data types because \fIJSON\fP can +only represent a subset of the types supported by BSON. As a result, +data exported or imported with these tools may lose some measure of +fidelity. See http://docs.mongodb.org/manual/reference/mongodb\-extended\-json for more +information. +.UNINDENT +.UNINDENT +.sp +JSON can only represent a subset of the types supported by BSON. To +preserve type information, \fBmongoimport\fP accepts \fBstrict +mode representation\fP for certain +types. +.sp +For example, to preserve type information for BSON types +\fBdata_date\fP and \fBdata_numberlong\fP during +\fBmongoimport\fP, the data should be in strict mode +representation, as in the following: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +{ "_id" : 1, "volume" : { "$numberLong" : "2980000" }, "date" : { "$date" : "2014\-03\-13T13:47:42.483\-0400" } } +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +For the \fBdata_numberlong\fP type, \fBmongoimport\fP +converts into a float during the import. +.sp +See http://docs.mongodb.org/manual/reference/mongodb\-extended\-json for a complete list of +these types and the representations used. .SH AUTHOR MongoDB Documentation Project .SH COPYRIGHT -2011-2013, MongoDB, Inc. +2011-2014, MongoDB, Inc. .\" Generated by docutils manpage writer. . |