- Reference >
- MongoDB Package Components >
mongodump
mongodump
¶
On this page
Synopsis¶
mongodump
is a utility for creating a binary export of the
contents of a database. Consider using this utility as part of an
effective backup strategy. Use
mongodump
in conjunction with mongorestore
to
restore databases.
mongodump
can read data from either mongod
or mongos
instances, in addition to reading directly from MongoDB data files
without an active mongod
.
Behavior¶
mongodump
does not dump the content of the local
database.
The data format used by mongodump
from version 2.2 or
later is incompatible with earlier versions of mongod
.
Do not use recent versions of mongodump
to back up older
data stores.
When running mongodump
against a mongos
instance
where the sharded cluster consists of replica sets, the read preference of the operation will prefer reads
from secondary members of the set.
Changed in version 2.2: When used in combination with fsync
or
db.fsyncLock()
, mongod
will block
reads, including those from mongodump
, when
queued write operation waits behind the fsync
lock. Do not use mongodump
with
db.fsyncLock()
.
mongodump
overwrites output files if they exist in the
backup data folder. Before running the mongodump
command
multiple times, either ensure that you no longer need the files in the
output folder (the default is the dump/
folder) or rename the
folders or files.
Required Access¶
Backup Collections¶
To backup all the databases in a cluster via mongodump
, you
should have the backup
role. The backup
role provides
all the needed privileges for backing up all database. The role confers no
additional access, in keeping with the policy of least privilege.
To backup a given database, you must have read
access on the database.
Several roles provide this access, including the backup
role.
To backup the system.profile
collection in a database, you must have
read
access on certain system collections in the database. Several roles
provide this access, including the clusterAdmin
and
dbAdmin
roles.
Backup Users¶
Changed in version 2.6.
To backup users and user-defined roles for a
given database, you must have access to the admin
database. MongoDB
stores the user data and role definitions for all databases in the
admin
database.
Specifically, to backup a given database’s users, you must have the
find
action on the admin
database’s admin.system.users
collection. The backup
and userAdminAnyDatabase
roles both provide this privilege.
To backup the user-defined roles on a database, you must have the
find
action on the admin
database’s
admin.system.roles
collection. Both the backup
and
userAdminAnyDatabase
roles provide this privilege.
Options¶
-
mongodump
¶
-
--help
¶
Returns information on the options and use of mongodump.
-
--verbose
,
-v
¶
Increases the amount of internal reporting returned on standard output or in log files. Increase the verbosity with the
-v
form by including the option multiple times, (e.g.-vvvvv
.)
-
--quiet
¶
Runs the mongodump in a quiet mode that attempts to limit the amount of output.
This option suppresses:
- output from database commands
- replication activity
- connection accepted events
- connection closed events
-
--version
¶
Returns the mongodump release number.
-
--host
<hostname><:port>
,
-h
<hostname><:port>
¶ Default: localhost:27017
Specifies a resolvable hostname for the
mongod
to which to connect. By default, the mongodump attempts to connect to a MongoDB instance running on the localhost on port number27017
.To connect to a replica set, specify the
replica set name
and a seed list of set members. Use the following form:You can always connect directly to a single MongoDB instance by specifying the host and port number directly.
-
--port
<port>
¶ Default: 27017
Specifies the TCP port on which the MongoDB instance listens for client connections.
-
--ipv6
¶
Enables IPv6 support and allows the mongodump to connect to the MongoDB instance using an IPv6 network. All MongoDB programs and processes disable IPv6 support by default.
-
--ssl
¶
New in version 2.6.
Enables connection to a
mongod
ormongos
that has TLS/SSL support enabled.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslCAFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains the root certificate chain from the Certificate Authority. Specify the file name of the.pem
file using relative or absolute paths.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
Warning
If the
mongo
shell or any other tool that connects tomongos
ormongod
is run without--sslCAFile
, it will not attempt to validate server certificates. This results in vulnerability to expiredmongod
andmongos
certificates as well as to foreign processes posing as validmongod
ormongos
instances. Ensure that you always specify the CA file against which server certificates should be validated in cases where intrusion is a possibility.
-
--sslPEMKeyFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains both the TLS/SSL certificate and key. Specify the file name of the.pem
file using relative or absolute paths.This option is required when using the
--ssl
option to connect to amongod
ormongos
that hasCAFile
enabled withoutweakCertificateValidation
.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslPEMKeyPassword
<value>
¶ New in version 2.6.
Specifies the password to de-crypt the certificate-key file (i.e.
--sslPEMKeyFile
). Use the--sslPEMKeyPassword
option only if the certificate-key file is encrypted. In all cases, the mongodump will redact the password from all logging and reporting output.If the private key in the PEM file is encrypted and you do not specify the
--sslPEMKeyPassword
option, the mongodump will prompt for a passphrase. See SSL Certificate Passphrase.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslCRLFile
<filename>
¶ New in version 2.6.
Specifies the
.pem
file that contains the Certificate Revocation List. Specify the file name of the.pem
file using relative or absolute paths.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslAllowInvalidCertificates
¶
New in version 2.6.
Bypasses the validation checks for server certificates and allows the use of invalid certificates. When using the
allowInvalidCertificates
setting, MongoDB logs as a warning the use of the invalid certificate.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--sslFIPSMode
¶
New in version 2.6.
Directs the mongodump to use the FIPS mode of the installed OpenSSL library. Your system must have a FIPS compliant OpenSSL library to use the
--sslFIPSMode
option.The default distribution of MongoDB does not contain support for TLS/SSL. For more information on MongoDB and TLS/SSL, see Configure mongod and mongos for TLS/SSL.
-
--username
<username>
,
-u
<username>
¶ Specifies a username with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--password
and--authenticationDatabase
options.
-
--password
<password>
,
-p
<password>
¶ Specifies a password with which to authenticate to a MongoDB database that uses authentication. Use in conjunction with the
--username
and--authenticationDatabase
options.If you do not specify an argument for
--password
, mongodump will prompt interactively for a password on the console.
-
--authenticationDatabase
<dbname>
¶ If you do not specify an authentication database, mongodump assumes that the database specified to export holds the user’s credentials.
-
--authenticationMechanism
<name>
¶ Default: MONGODB-CR
New in version 2.4.
Changed in version 2.6: Added support for the
PLAIN
andMONGODB-X509
authentication mechanisms.Specifies the authentication mechanism the mongodump instance uses to authenticate to the
mongod
ormongos
.Value Description MONGODB-CR MongoDB challenge/response authentication. MONGODB-X509 MongoDB TLS/SSL certificate authentication. PLAIN External authentication using LDAP. You can also use PLAIN
for authenticating in-database users.PLAIN
transmits passwords in plain text. This mechanism is available only in MongoDB Enterprise.GSSAPI External authentication using Kerberos. This mechanism is available only in MongoDB Enterprise.
-
--gssapiServiceName
¶
New in version 2.6.
Specify the name of the service using GSSAPI/Kerberos. Only required if the service does not use the default name of
mongodb
.This option is available only in MongoDB Enterprise.
-
--gssapiHostName
¶
New in version 2.6.
Specify the hostname of a service using GSSAPI/Kerberos. Only required if the hostname of a machine does not match the hostname resolved by DNS.
This option is available only in MongoDB Enterprise.
-
--dbpath
<path>
¶ Specifies the directory of the MongoDB data files. The
--dbpath
option lets the mongodump attach directly to the local data files without going through a runningmongod
. When run with--dbpath
, the mongodump locks access to the data files. Nomongod
can access the files while the mongodump process runs.
-
--directoryperdb
¶
When used in conjunction with the corresponding option in
mongod
, allows the mongodump 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--dbpath
option.
-
--journal
¶
Enables the durability journal to ensure data files remain valid and recoverable. This option applies only when you specify the . The mongodump enables journaling by default on 64-bit builds of versions after 2.0.
-
--db
<database>
,
-d
<database>
¶ Specifies a database to backup. If you do not specify a database,
mongodump
copies all databases in this instance into the dump files.
-
--collection
<collection>
,
-c
<collection>
¶ Specifies a collection to backup. If you do not specify a collection, this option copies all collections in the specified database or instance to the dump files.
-
--out
<path>
,
-o
<path>
¶ Specifies the directory where
mongodump
will write BSON files for the dumped databases. By default,mongodump
saves output files in a directory nameddump
in the current working directory.To send the database dump to standard output, specify “
-
” instead of a path. Write to standard output if you want process the output before saving it, such as to usegzip
to compress the dump. When writing standard output,mongodump
does not write the metadata that writes in a<dbname>.metadata.json
file when writing to files directly.
-
--query
<json>
,
-q
<json>
¶ Provides a JSON document as a query that optionally limits the documents included in the output of
mongodump
.
-
--oplog
¶
Creates a file named
oplog.bson
as part of themongodump
output. Theoplog.bson
file, located in the top level of the output directory, contains oplog entries that occur during themongodump
operation. This file provides an effective point-in-time snapshot of the state of amongod
instance. To restore to a specific point-in-time backup, use the output created with this option in conjunction withmongorestore --oplogReplay
.Without
--oplog
, 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.--oplog
has no effect when runningmongodump
against amongos
instance to dump the entire contents of a sharded cluster. However, you can use--oplog
to dump individual shards.--oplog
only works against nodes that maintain an oplog. This includes all members of a replica set, as well as master nodes in master/slave replication deployments.--oplog
does not dump the oplog collection.
-
--repair
¶
Runs a repair option in addition to dumping the database.
--repair
operates directly on the database files. As such, you must use the--dbpath
option when using--repair
. The repair option attempts to repair a database that may be in an invalid state as a result of an improper shutdown ormongod
crash.The
--repair
option uses aggressive data-recovery algorithms that may produce a large amount of duplication.
-
--forceTableScan
¶
Forces
mongodump
to scan the data store directly: typically,mongodump
saves entries as they appear in the index of the_id
field. If you specify a query--query
, mongodump will use the most appropriate index to support that query.Use
--forceTableScan
to skip the index and scan the data directly. Typically there are two cases where this behavior is preferable to the default:- If you have key sizes over 800 bytes that would not be present in the
_id
index. - Your database uses a custom
_id
field.
When you run with
--forceTableScan
,mongodump
does not use$snapshot
. As a result, the dump produced bymongodump
can reflect the state of the database at many different points in time.Important
Use
--forceTableScan
with extreme caution and consideration.- If you have key sizes over 800 bytes that would not be present in the
-
--dumpDbUsersAndRoles
¶
Includes user and role definitions in the database’s dump directory when performing
mongodump
on a specific database. This option applies only when you specify a database in the--db
option. MongoDB always includes user and role definitions whenmongodump
applies to an entire instance and not just a specific database.
Use¶
See the Back Up and Restore with MongoDB Tools
for a larger overview of mongodump
usage. Also see the
mongorestore document for an overview of the
mongorestore
, which provides the related inverse
functionality.
The following command creates a dump file that contains only the
collection named collection
in the database named test
. In
this case the database is running on the local interface on port
27017
:
In the next example, mongodump
creates a backup of the
database instance stored in the /srv/mongodb
directory on the
local machine. This requires that no mongod
instance is
using the /srv/mongodb
directory.
In the final example, mongodump
creates a database dump
located at /opt/backup/mongodump-2011-10-24
, from a database
running on port 37017
on the host mongodb1.example.net
and
authenticating using the username user
and the password
pass
, as follows: