Navigation

This version of the documentation is archived and no longer supported.

Replication >
Replication Concepts >
Master Slave Replication

Master Slave Replication¶

On this page

Fundamental Operations
Run time Master-Slave Configuration
Security
Ongoing Administration and Operation of Master-Slave Deployments

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 mastermongod 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 1GB for 64bit machines and 50MB for 32bit machines.

Run time Master-Slave Configuration¶

MongoDB provides a number of run time configuration options for mongod instances in master-slave deployments. You can specify these options in configuration files or on the command-line. See documentation of the following:

For master nodes:
- master
- slave
For slave nodes:
- source
- only
- slaveDelay

Also consider the Master-Slave Replication Command Line Options for related options.

Diagnostics¶

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

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:

db.printSlaveReplicationInfo()

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

db.serverStatus()

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

Security¶

When running with auth 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

See also

Security for more information about security in MongoDB

Ongoing Administration and Operation of Master-Slave Deployments¶

Deploy Master-Slave Equivalent using Replica Sets¶

If you want a replication configuration that resembles master-slave replication, using replica sets replica sets, consider the following replica configuration document. In this deployment hosts <master> and <slave> [1] provide replication that is roughly equivalent to a two-instance master-slave deployment:

{
  _id : 'setName',
  members : [
    { _id : 0, host : "<master>", priority : 1 },
    { _id : 1, host : "<slave>", priority : 0, votes : 0 }
  ]
}

See Replica Set Configuration for more information about replica set configurations.

[1]	In replica set configurations, the `host` field must hold a resolvable hostname.

Convert a Master-Slave Deployment to a Replica Set¶

To convert a master-slave deployment to a replica set, restart the current master as a one-member replica set. Then remove the data directors from previous secondaries and add them as new secondaries to the new replica set.

To confirm that the current instance is master, run:

db.isMaster()

This should return a document that resembles the following:

{
        "ismaster" : true,
        "maxBsonObjectSize" : 16777216,
        "maxMessageSizeBytes" : 48000000,
        "localTime" : ISODate("2013-07-08T20:15:13.664Z"),
        "ok" : 1
}

Shut down the mongod processes on the master and all slave(s), using the following command while connected to each instance:
copy
```
db.adminCommand({shutdown : 1, force : true})
```
Back up your /data/db directories, in case you need to revert to the master-slave deployment.
Start the former master with the --replSet option, as in the following:
copy
```
mongod --replSet <setname>
```
Connect to the mongod with the mongo shell, and initiate the replica set with the following command:
copy
```
rs.initiate()
```
When the command returns, you will have successfully deployed a one-member replica set. You can check the status of your replica set at any time by running the following command:
copy
```
rs.status()
```

You can now follow the convert a standalone to a replica set tutorial to deploy your replica set, picking up from the Expand the Replica Set section.

Failing over to a Slave (Promotion)¶

To permanently failover from a unavailable or damaged master (A in the following example) to a slave (B):

Shut down A.
Stop mongod on B.
Back up and move all data files that begin with local on B from the dbpath.

Warning

Removing local.* is irrevocable and cannot be undone. Perform this step with extreme caution.
Restart mongod on B with the --master option.

Note

This is a one time operation, and is not reversible. A cannot become a slave of B until it completes a full resync.

Inverting Master and Slave¶

If you have a master (A) and a slave (B) and you would like to reverse their roles, follow this procedure. The procedure assumes A is healthy, up-to-date and available.

If A is not healthy but the hardware is okay (power outage, server crash, etc.), skip steps 1 and 2 and in step 8 replace all of A’s files with B’s files in step 8.

If A is not healthy and the hardware is not okay, replace A with a new machine. Also follow the instructions in the previous paragraph.

To invert the master and slave in a deployment:

Halt writes on A using the fsync command.
Make sure B is up to date with the state of A.
Shut down B.
Back up and move all data files that begin with local on B from the dbpath to remove the existing local.sources data.

Warning

Removing local.* is irrevocable and cannot be undone. Perform this step with extreme caution.
Start B with the --master option.
Do a write on B, which primes the oplog to provide a new sync start point.
Shut down B. B will now have a new set of data files that start with local.
Shut down A and replace all files in the dbpath of A that start with local with a copy of the files in the dbpath of B that begin with local.

Considering compressing the local files from B while you copy them, as they may be quite large.
Start B with the --master option.
Start A with all the usual slave options, but include fastsync.

Creating a Slave from an Existing Master’s Disk Image¶

If you can stop write operations to the master for an indefinite period, you can copy the data files from the master to the new slave and then start the slave with --fastsync.

Warning

Be careful with --fastsync. If the data on both instances is not identical, a discrepancy will exist forever.

fastsync is a way to start a slave by starting with an existing master disk image/backup. This option declares that the administrator guarantees the image is correct and completely up-to-date with that of the master. If you have a full and complete copy of data from a master you can use this option to avoid a full synchronization upon starting the slave.

Creating a Slave from an Existing Slave’s Disk Image¶

You can just copy the other slave’s data file snapshot without any special options. Only take data snapshots when a mongod process is down or locked using db.fsyncLock().

Resyncing a Slave that is too Stale to Recover¶

Slaves asynchronously apply write operations from the master that the slaves poll from the master’s oplog. The oplog is finite in length, and if a slave is too far behind, a full resync will be necessary. To resync the slave, connect to a slave using the mongo and issue the resync command:

use admin
db.runCommand( { resync: 1 } )

This forces a full resync of all data (which will be very slow on a large database). You can achieve the same effect by stopping mongod on the slave, deleting the entire content of the dbpath on the slave, and restarting the mongod.

Slave Chaining¶

Slaves cannot be “chained.” They must all connect to the master directly.

If a slave attempts “slave from” another slave you will see the following line in the mongod long of the shell:

assertion 13051 tailable cursor requested on non capped collection ns:local.oplog.$main

Correcting a Slave’s Source¶

To change a slave’s source, manually modify the slave’s local.sources collection.

Example

Consider the following: If you accidentally set an incorrect hostname for the slave’s source, as in the following example:

mongod --slave --source prod.mississippi

You can correct this, by restarting the slave without the --slave and --source arguments:

mongod

Connect to this mongod instance using the mongo shell and update the local.sources collection, with the following operation sequence:

use local

db.sources.update( { host : "prod.mississippi" },
                   { $set : { host : "prod.mississippi.example.net" } } )

Restart the slave with the correct command line arguments or with no --source option. After configuring local.sources the first time, the --source will have no subsequent effect. Therefore, both of the following invocations are correct:

mongod --slave --source prod.mississippi.example.net

or

mongod --slave

The slave now polls data from the correct master.

← Replica Set Data Synchronization Replica Set Tutorials →