Master Slave Replication

Warning

Deprecated since version 3.6: MongoDB 3.6 deprecates the use of master-slave replication.

Master-slave replication has been deprecated for components of sharded clusters since MongoDB 3.2.

Important

Replica sets replace master-slave replication for most use cases. If possible, use replica sets rather than master-slave replication for all new production deployments. This documentation remains to support legacy deployments and for archival purposes only.

In addition to providing all the functionality of master-slave deployments, replica sets are also more robust for production use. Master-slave replication preceded replica sets and made it possible to have a large number of non-master (i.e. slave) nodes, as well as to restrict replicated operations to only a single database; however, master-slave replication provides less redundancy and does not automate failover. See Deploy Master-Slave Equivalent using Replica Sets for a replica set configuration that is equivalent to master-slave replication. If you wish to convert an existing master-slave deployment to a replica set, see Convert a Master-Slave Deployment to a Replica Set.

Fundamental Operations

Initial Deployment

To configure a master-slave deployment, start two mongod instances: one in master mode, and the other in slave mode.

To start a mongod instance in master mode, invoke mongod as follows:

mongod --master --dbpath /data/masterdb/

With the --master option, the mongod will create a local.oplog.$main collection, which the “operation log” that queues operations that the slaves will apply to replicate operations from the master. The --dbpath is optional.

To start a mongod instance in slave mode, invoke mongod as follows:

mongod --slave --source <masterhostname><:<port>> --dbpath /data/slavedb/

Specify the hostname and port of the master instance to the --source argument. The --dbpath is optional.

For slave instances, MongoDB stores data about the source server in the local.sources collection.

Configuration Options for Master-Slave Deployments

As an alternative to specifying the --source run-time option, can add a document to local.sources specifying the master instance, as in the following operation in the mongo shell:

use local
db.sources.find()
db.sources.insert( { host: <masterhostname> <,only: <databasename>> } );

In line 1, you switch context to the local database. In line 2, the find() operation should return no documents, to ensure that there are no documents in the sources collection. Finally, line 3 uses db.collection.insert() to insert the source document into the local.sources collection. The model of the local.sources document is as follows:

host

The host field specifies the master mongod instance, and holds a resolvable hostname, i.e. IP address, or a name from a host file, or preferably a fully qualified domain name.

You can append <:port> to the host name if the mongod is not running on the default 27017 port.

only

Optional. Specify a name of a database. When specified, MongoDB will only replicate the indicated database.

Operational Considerations for Replication with Master Slave Deployments

Master instances store operations in an oplog which is a capped collection. As a result, if a slave falls too far behind the state of the master, it cannot “catchup” and must re-sync from scratch. Slave may become out of sync with a master if:

  • The slave falls far behind the data updates available from that master.
  • The slave stops (i.e. shuts down) and restarts later after the master has overwritten the relevant operations from the master.

When slaves are out of sync, replication stops. Administrators must intervene manually to restart replication. Use the resync command. Alternatively, the --autoresync allows a slave to restart replication automatically, after ten second pause, when the slave falls out of sync with the master. With --autoresync specified, the slave will only attempt to re-sync once in a ten minute period.

To prevent these situations you should specify a larger oplog when you start the master instance, by adding the --oplogSize option when starting mongod. If you do not specify --oplogSize, mongod will allocate 5% of available disk space on start up to the oplog, with a minimum of 1 GB for 64-bit machines and 50 MB for 32-bit machines.

Run time Master-Slave Configuration

MongoDB provides a number of command line options for mongod instances in master-slave deployments. See the Master-Slave Replication Command Line Options for options.

Diagnostics

On a master instance, issue the following operation in the mongo shell to return replication status from the perspective of the master:

rs.printReplicationInfo()

New in version 2.6: rs.printReplicationInfo(). For previous versions, use db.printReplicationInfo().

On a slave instance, use the following operation in the mongo shell to return the replication status from the perspective of the slave:

rs.printSlaveReplicationInfo()

New in version 2.6: rs.printSlaveReplicationInfo(). For previous versions, use db.printSlaveReplicationInfo().

Use the serverStatus as in the following operation, to return status of the replication:

db.serverStatus( { repl: 1 } )

See server status repl fields for documentation of the relevant section of output.

Security

When running with authorization enabled, in master-slave deployments configure a keyFile so that slave mongod instances can authenticate and communicate with the master mongod instance.

To enable authentication and configure the keyFile add the following option to your configuration file:

keyFile = /srv/mongodb/keyfile

Note

You may chose to set these run-time configuration options using the --keyFile option on the command line.

Setting keyFile enables authentication and specifies a key file for the mongod instances to use when authenticating to each other. The content of the key file is arbitrary but must be the same on all members of the deployment can connect to each other.

The key file must be less one kilobyte in size and may only contain characters in the base64 set. The key file must not have group or “world” permissions on UNIX systems. Use the following command to use the OpenSSL package to generate “random” content for use in a key file:

openssl rand -base64 741
</