1MONGODUMP(1) mongodb-manual MONGODUMP(1)
2
6 mongodump - MongoDB Data Dump Utility
7
9 mongodump is a utility for creating a binary export of the contents of
10 a database. Consider using this utility as part of an effective backup
11 strategy. Use mongodump in conjunction with mongorestore to restore
12 databases.
13 mongodump can read data from either mongod or mongos instances, in
15 addition to reading directly from MongoDB data files without an active
16 mongod.
17 SEE ALSO:
19 mongorestore, http://docs.mongodb.org/manual/tuto‐
20 rial/backup-sharded-cluster-with-database-dumps and http://docs.mon‐
21 godb.org/manual/core/backups.
22
24 mongodump does not dump the content of the local database.
25 The data format used by mongodump from version 2.2 or later is incom‐
27 patible with earlier versions of mongod. Do not use recent versions of
28 mongodump to back up older data stores.
29 When running mongodump against a mongos instance where the sharded
31 cluster consists of replica sets, the read preference of the operation
32 will prefer reads from secondary members of the set.
33 Changed in version 2.2: When used in combination with fsync or db.fsyn‐
35 cLock(), mongod will block reads, including those from mongodump, when
36 queued write operation waits behind the fsync lock. Do not use mongo‐
37 dump with db.fsyncLock().
38 mongodump overwrites output files if they exist in the backup data
41 folder. Before running the mongodump command multiple times, either
42 ensure that you no longer need the files in the output folder (the
43 default is the dump/ folder) or rename the folders or files.
44
46 Backup Collections
47 To backup all the databases in a cluster via mongodump, you should have
48 the backup role. The backup role provides the required privileges for
49 backing up all databases. The role confers no additional access, in
50 keeping with the policy of least privilege.
51 To backup a given database, you must have read access on the database.
53 Several roles provide this access, including the backup role.
54 To backup the system.profile collection, which is created when you
56 activate database profiling, you must have additional read access on
57 this collection. Several roles provide this access, including the clus‐
58 terAdmin and dbAdmin roles.
59 Backup Users
61 Changed in version 2.6.
62 To backup users and user-defined roles for a given database, you must
65 have access to the admin database. MongoDB stores the user data and
66 role definitions for all databases in the admin database.
67 Specifically, to backup a given database's users, you must have the
69 find action on the admin database's admin.system.users collection. The
70 backup and userAdminAnyDatabase roles both provide this privilege.
71 To backup the user-defined roles on a database, you must have the find
73 action on the admin database's admin.system.roles collection. Both the
74 backup and userAdminAnyDatabase roles provide this privilege.
75
77 Changed in version 3.0.0: mongodump removed the --dbpath as well as
78 related --directoryperdb and --journal options. You must use mongodump
79 while connected to a mongod instance.
80 mongodump
83 mongodump
85 --help Returns information on the options and use of mongodump.
87 --verbose, -v
89 Increases the amount of internal reporting returned on standard
90 output or in log files. Increase the verbosity with the -v form
91 by including the option multiple times, (e.g. -vvvvv.)
92 --quiet
94 Runs the mongodump in a quiet mode that attempts to limit the
95 amount of output.
96 This option suppresses:
98 · output from database commands
100 · replication activity
102 · connection accepted events
104 · connection closed events
106 --version
108 Returns the mongodump release number.
109 --host <hostname><:port>, -h <hostname><:port>
111 Default: localhost:27017
112 Specifies a resolvable hostname for the mongod to which to con‐
114 nect. By default, the mongodump attempts to connect to a MongoDB
115 instance running on the localhost on port number 27017.
116 To connect to a replica set, specify the replSetName and a seed
118 list of set members, as in the following:
119 <replSetName>/<hostname1><:port>,<hostname2><:port>,<...>
121 You can always connect directly to a single MongoDB instance by
123 specifying the host and port number directly.
124 Changed in version 3.0.0: If you use IPv6 and use the
126 <address>:<port> format, you must enclose the portion of an
127 address and port combination in brackets (e.g. [<address>]).
128 --port <port>
131 Default: 27017
132 Specifies the TCP port on which the MongoDB instance listens for
134 client connections.
135 --ipv6 Enables IPv6 support and allows the mongodump to connect to the
137 MongoDB instance using an IPv6 network. All MongoDB programs and
138 processes disable IPv6 support by default.
139 --ssl New in version 2.6.
141 Enables connection to a mongod or mongos that has SSL support
144 enabled.
145 The default distribution of MongoDB does not contain support for
147 SSL. For more information on MongoDB and SSL, see
148 http://docs.mongodb.org/manual/tutorial/configure-ssl.
149 --sslCAFile <filename>
151 New in version 2.6.
152 Specifies the .pem file that contains the root certificate chain
155 from the Certificate Authority. Specify the file name of the
156 .pem file using relative or absolute paths.
157 The default distribution of MongoDB does not contain support for
159 SSL. For more information on MongoDB and SSL, see
160 http://docs.mongodb.org/manual/tutorial/configure-ssl.
161 WARNING:
163 If the mongo shell or any other tool that connects to mongos
164 or mongod is run without --sslCAFile, it will not attempt to
165 validate server certificates. This results in vulnerability
166 to expired mongod and mongos certificates as well as to for‐
167 eign processes posing as valid mongod or mongos instances.
168 Ensure that you always specify the CA file against which
169 server certificates should be validated in cases where intru‐
170 sion is a possibility.
171 --sslPEMKeyFile <filename>
173 New in version 2.6.
174 Specifies the .pem file that contains both the SSL certificate
177 and key. Specify the file name of the .pem file using relative
178 or absolute paths.
179 This option is required when using the --ssl option to connect
181 to a mongod or mongos that has CAFile enabled without allowCon‐
182 nectionsWithoutCertificates.
183 The default distribution of MongoDB does not contain support for
185 SSL. For more information on MongoDB and SSL, see
186 http://docs.mongodb.org/manual/tutorial/configure-ssl.
187 --sslPEMKeyPassword <value>
189 New in version 2.6.
190 Specifies the password to de-crypt the certificate-key file
193 (i.e. --sslPEMKeyFile). Use the --sslPEMKeyPassword option only
194 if the certificate-key file is encrypted. In all cases, the mon‐
195 godump will redact the password from all logging and reporting
196 output.
197 If the private key in the PEM file is encrypted and you do not
199 specify the --sslPEMKeyPassword option, the mongodump will
200 prompt for a passphrase. See ssl-certificate-password.
201 The default distribution of MongoDB does not contain support for
203 SSL. For more information on MongoDB and SSL, see
204 http://docs.mongodb.org/manual/tutorial/configure-ssl.
205 --sslCRLFile <filename>
207 New in version 2.6.
208 Specifies the .pem file that contains the Certificate Revocation
211 List. Specify the file name of the .pem file using relative or
212 absolute paths.
213 The default distribution of MongoDB does not contain support for
215 SSL. For more information on MongoDB and SSL, see
216 http://docs.mongodb.org/manual/tutorial/configure-ssl.
217 --sslAllowInvalidCertificates
219 New in version 2.6.
220 Bypasses the validation checks for server certificates and
223 allows the use of invalid certificates. When using the allowIn‐
224 validCertificates setting, MongoDB logs as a warning the use of
225 the invalid certificate.
226 The default distribution of MongoDB does not contain support for
228 SSL. For more information on MongoDB and SSL, see
229 http://docs.mongodb.org/manual/tutorial/configure-ssl.
230 --sslAllowInvalidHostnames
232 New in version 3.0.
233 Disables the validation of the hostnames in SSL certificates.
236 Allows mongodump to connect to MongoDB instances if the hostname
237 their certificates do not match the specified hostname.
238 --sslFIPSMode
240 New in version 2.6.
241 Directs the mongodump to use the FIPS mode of the installed
244 OpenSSL library. Your system must have a FIPS compliant OpenSSL
245 library to use the --sslFIPSMode option.
246 NOTE:
248 FIPS Compatible SSL is available only in MongoDB Enterprise.
249 See http://docs.mongodb.org/manual/tutorial/configure-fips
250 for more information.
251 --username <username>, -u <username>
253 Specifies a username with which to authenticate to a MongoDB
254 database that uses authentication. Use in conjunction with the
255 --password and --authenticationDatabase options.
256 --password <password>, -p <password>
258 Specifies a password with which to authenticate to a MongoDB
259 database that uses authentication. Use in conjunction with the
260 --username and --authenticationDatabase options.
261 If you do not specify an argument for --password, mongodump will
263 prompt interactively for a password on the console.
264 --authenticationDatabase <dbname>
266 If you do not specify an authentication database, mongodump
267 assumes that the database specified to export holds the user's
268 credentials.
269 --authenticationMechanism <name>
271 Default: MONGODB-CR
272 New in version 2.4.
274 Changed in version 2.6: Added support for the PLAIN and MON‐
277 GODB-X509 authentication mechanisms.
278 Specifies the authentication mechanism the mongodump instance
281 uses to authenticate to the mongod or mongos.
282 ┌─────────────┬────────────────────────────┐
284 │Value │ Description │
285 ├─────────────┼────────────────────────────┤
286 │MONGODB-CR │ MongoDB challenge/response │
287 │ │ authentication. │
288 ├─────────────┼────────────────────────────┤
289 │MONGODB-X509 │ MongoDB SSL certificate │
290 │ │ authentication. │
291 ├─────────────┼────────────────────────────┤
292 │PLAIN │ External authentication │
293 │ │ using LDAP. You can also │
294 │ │ use PLAIN for authenticat‐ │
295 │ │ ing in-database users. │
296 │ │ PLAIN transmits passwords │
297 │ │ in plain text. This mecha‐ │
298 │ │ nism is available only in │
299 │ │ MongoDB Enterprise. │
300 ├─────────────┼────────────────────────────┤
301 │GSSAPI │ External authentication │
302 │ │ using Kerberos. This mech‐ │
303 │ │ anism is available only in │
304 │ │ MongoDB Enterprise. │
305 └─────────────┴────────────────────────────┘
306 --gssapiServiceName
308 New in version 2.6.
309 Specify the name of the service using GSSAPI/Kerberos. Only
312 required if the service does not use the default name of mon‐
313 godb.
314 This option is available only in MongoDB Enterprise.
316 --gssapiHostName
318 New in version 2.6.
319 Specify the hostname of a service using GSSAPI/Kerberos. Only
322 required if the hostname of a machine does not match the host‐
323 name resolved by DNS.
324 This option is available only in MongoDB Enterprise.
326 --db <database>, -d <database>
328 Specifies a database to backup. If you do not specify a data‐
329 base, mongodump copies all databases in this instance into the
330 dump files.
331 --collection <collection>, -c <collection>
333 Specifies a collection to backup. If you do not specify a col‐
334 lection, this option copies all collections in the specified
335 database or instance to the dump files.
336 --query <json>, -q <json>
338 Provides a JSON document as a query that optionally limits the
339 documents included in the output of mongodump.
340 --forceTableScan
342 Forces mongodump to scan the data store directly: typically,
343 mongodump saves entries as they appear in the index of the _id
344 field. If you specify a query --query, mongodump will use the
345 most appropriate index to support that query.
346 Use --forceTableScan to skip the index and scan the data
348 directly. Typically there are two cases where this behavior is
349 preferable to the default:
350 1. If you have key sizes over 800 bytes that would not be
352 present in the _id index.
353 2. Your database uses a custom _id field.
355 When you run with --forceTableScan, mongodump does not use
357 $snapshot. As a result, the dump produced by mongodump can
358 reflect the state of the database at many different points in
359 time.
360 IMPORTANT:
362 Use --forceTableScan with extreme caution and consideration.
363 --out <path>, -o <path>
365 Specifies the directory where mongodump will write BSON files
366 for the dumped databases. By default, mongodump saves output
367 files in a directory named dump in the current working direc‐
368 tory.
369 To send the database dump to standard output, specify "-"
371 instead of a path. Write to standard output if you want process
372 the output before saving it, such as to use gzip to compress the
373 dump. When writing standard output, mongodump does not write the
374 metadata that writes in a <dbname>.metadata.json file when writ‐
375 ing to files directly.
376 --repair
378 Runs a repair option in addition to dumping the database. The
379 repair option changes the behavior of mongodump to only write
380 valid data and exclude data that may be in an invalid state as a
381 result of an improper shutdown or mongod crash.
382 The --repair option uses aggressive data-recovery algorithms
384 that may produce a large amount of duplication.
385 --repair is only available for use with mongod instances using
387 the mmapv1 storage engine. You cannot run --repair with mongos
388 or with mongod instances that use the wiredTiger storage engine.
389 To repair data in a mongod instance using wiredTiger use mongod
390 --repair.
391 --oplog
393 Ensures that mongodump creates a dump of the database that
394 includes a partial oplog containing operations from the duration
395 of the mongodump operation. This oplog produces an effective
396 point-in-time snapshot of the state of a mongod instance. To
397 restore to a specific point-in-time backup, use the output cre‐
398 ated with this option in conjunction with mongorestore --oplo‐
399 gReplay.
400 Without --oplog, if there are write operations during the dump
402 operation, the dump will not reflect a single moment in time.
403 Changes made to the database during the update process can
404 affect the output of the backup.
405 --oplog has no effect when running mongodump against a mongos
407 instance to dump the entire contents of a sharded cluster. How‐
408 ever, you can use --oplog to dump individual shards.
409 --oplog only works against nodes that maintain an oplog. This
411 includes all members of a replica set, as well as master nodes
412 in master/slave replication deployments.
413 --oplog does not dump the oplog collection.
415 --dumpDbUsersAndRoles
417 Includes user and role definitions when performing mongodump on
418 a specific database. This option applies only when you specify a
419 database in the --db option. MongoDB always includes user and
420 role definitions when mongodump applies to an entire instance
421 and not just a specific database.
422 --excludeCollection array of strings
424 New in version 3.0.0.
425 Specifies collections to exclude from the output of mongodump
428 output.
429 --excludeCollectionsWithPrefix array of strings
431 New in version 3.0.0.
432 Excludes all collections from the output of mongodump with a
435 specified prefix.
436
438 See the http://docs.mongodb.org/manual/tutorial/backup-with-mongodump
439 for a larger overview of mongodump usage. Also see the mongorestore
440 document for an overview of the mongorestore, which provides the
441 related inverse functionality.
442 The following command creates a dump file that contains only the col‐
444 lection named collection in the database named test. In this case the
445 database is running on the local interface on port 27017:
446 mongodump --db test --collection collection
448 In the next example, mongodump creates a database dump located at
450 /opt/backup/mongodump-2011-10-24, from a database running on port 37017
451 on the host mongodb1.example.net and authenticating using the username
452 user and the password pass, as follows:
453 mongodump --host mongodb1.example.net --port 37017 --username user --password pass --out /opt/backup/mongodump-2011-10-24
455
457 MongoDB Documentation Project
458
460 2011-2015
4613.0 January 30, 2015 MONGODUMP(1)