- Replication >
- Master Slave Replication
Master Slave Replication¶
On this page
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.
Replica sets provide functional super-set of master-slave and are more robust for production use. Master-slave replication preceded replica and makes it possible have a large number of non-master (i.e. slave) and to only replicate operations for 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.
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:
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:
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:
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 ahost
file, or preferably a fully qualified domain name.You can append
<:port>
to the host name if themongod
is not running on the default27017
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:
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:
On a slave instance, use the following operation in the
mongo
shell to return the replication status from the
perspective of the slave:
Use the serverStatus
as in the following operation, to
return status of the replication:
See server status repl fields for documentation of the relevant section of output.
Security¶
When running with auth
enabled, in
master-slave deployments, you must create a user
account for the local database on both mongod
instances. Log in, and authenticate to the admin
database on the
slave instance, and then create the repl
user on the local
database, with the following operation:
Once created, repeat the operation on the master instance.
The slave instance first looks for a user named repl
in the
local.system.users
collection. If
present, the slave uses this user account to authenticate to the
local
database in the master
instance. If the repl
user
does not exist, the slave instance attempts to authenticate using the
first user document in the local.system.users
collection.
The local
database works like the admin
database: an account for
local has access to the entire server.
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:
See Replica Set Configuration for more information about replica set configurations.
[1] | In replica set configurations, the
host field must hold a resolvable
hostname. |
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
onB
.Back up and move all data files that begin with
local
onB
from thedbpath
.Warning
Removing
local.*
is irrevocable and cannot be undone. Perform this step with extreme caution.
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 ofA
.Shut down
B
.Back up and move all data files that begin with
local
onB
from thedbpath
to remove the existinglocal.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 withlocal
.Shut down
A
and replace all files in thedbpath
ofA
that start withlocal
with a copy of the files in thedbpath
ofB
that begin withlocal
.Considering compressing the
local
files fromB
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 includefastsync
.
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 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:
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:
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:
You can correct this, by restarting the slave without the
--slave
and
--source
arguments:
Connect to this mongod
instance using the
mongo
shell and update the local.sources
collection, with the following operation sequence:
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:
or
The slave now polls data from the correct master.