DOCS-275 redirect master-slave documentation

draft/administration/replication-master-slave.txt

@@ -0,0 +1,392 @@
+============
+Master Slave
+============
+
+.. default-domain:: mongodb
+
+*Use only for versions prior to 1.6*
+
+.. important:: Use :doc:`replica sets </replication>` rather than the
+   :term:`master`-:term:`slave` configuration. Replica sets are a
+   functional superset of master-slave and are more robust. Master-slave
+   configuration preceded replica sets, which were introduced in MongoDB
+   version 1.6. This documentation is intended for users of MongoDB
+   versions prior to MongoDB 1.6.
+
+   To download a newer version of MongoDB, see `MongoDB Downloads <http://mongodb.org/downloads>`_.
+
+.. warning::
+
+   Master-slave configuration is a legacy configuration and should not
+   be used with MongoDB version 1.6 or higher. Instead use :doc:`replica
+   sets </replication>`, which provide automated failover and backups,
+   and which ensure high availability.
+
+Master Slave vs. Replica Sets
+-----------------------------
+
+In MongoDB 1.6+, :term:`replica sets <replica set>` replaced
+:term:`master`-:term:`slave` as the preferred configuration
+for :doc:`replication </replication>`.
+
+The following replica set configuration is equivalent to a two-node
+master-slave setup with hosts ``M`` (master) and ``S`` (slave):
+
+.. code-block:: javascript
+
+   cfg = {
+     _id : 'mysetname',
+     members : [
+       { _id : 0, host : 'M', priority : 1 },
+       { _id : 1, host : 'S', priority : 0, votes : 0 }
+     ]
+   };
+
+Configuration and Setup
+-----------------------
+
+*Use only for versions prior to 1.6*
+
+To configure an instance of :program:`mongod` to be a :term:`master`
+database in a master-:term:`slave` configuration, start two instances of
+the database, one in *master* mode, and the other in *slave* mode.
+
+.. note:: The following examples explicitly specify the location of
+   the data files on the command line. This is unnecessary if you are
+   running the master and slave on separate machines. But for readers
+   who are going try this setup on a single node, the examples specify
+   the data files in the interest of safety.
+
+.. code-block:: javascript
+
+   bin/mongod --master [--dbpath /data/masterdb/]
+
+As a result, the master server process will create a
+``local.oplog.$main`` collection. This is the "transaction log" that
+queues operations that will be applied at the slave.
+
+To configure an instance of :program:`mongod` to be a slave database in a
+master-slave configuration:
+
+.. code-block:: javascript
+
+   bin/mongod --slave --source <masterhostname>[:<port>] [--dbpath /data/slavedb/]
+
+Details of the source server are then stored in the slave's
+``local.sources`` collection. Instead of specifying the ``--source``
+parameter, you can add an object to ``local.sources`` that specifies
+information about the master server:
+
+.. code-block:: javascript
+
+   bin/mongo <slavehostname>/local
+   db.sources.find(); // confirms the collection is empty. then:
+   db.sources.insert( { host: <masterhostname> } );
+
+- ``host: masterhostname`` is the IP address or FQDN of the master
+  database machine. Append ``:port`` to the server hostname if you want
+  to run on a nonstandard port number.
+
+- ``only: databasename`` (optional) if specified, indicates that only
+  the specified database should replicate.
+
+A slave may become out of sync with a master if:
+
+- The slave falls far behind the data updates available from that
+  master.
+
+- The slave is terminated and then restarted some time later when
+  relevant updates are no longer available from the master.
+
+If a slave becomes out of sync, replication terminates. Operator
+intervention is required if replication is to be restarted. An operator
+can restart replication using the ``{resync:1}`` command. Alternatively,
+the :option:`--autoresync` option causes a slave to restart replication
+automatically (after ten second pause) if the slave becomes out of sync.
+If :option:`--autoresync` is specified, the slave does not attempt an
+automatic resync more than once in a ten minute period.
+
+The :option:`--oplogSize` option can be specified (along with
+``--master``) to configure the amount of disk space in megabytes that will
+be allocated for storing updates to be made available to slave nodes. If
+:option:`--oplogSize` is not specified, the amount of disk space for
+storing updates will be 5% of available disk space, with a minimum of
+1GB) for 64bit machines and 50MB for 32bit machines.
+
+Command-line Options
+--------------------
+
+*Use the master-slave configuration only for versions prior to 1.6*
+
+Master Command-line Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `--master`: The :term:`master` mode.
+
+- :option:`--oplogSize`: This takes an argument and specifies the size
+  limit in MB for the oplog.
+
+Slave Command-line Options
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `--slave`: The :term:`slave` mode.
+
+- `--source`: This takes an argument and specifies the master as
+  <server:port>.
+
+- `--only`: This takes an argument and specifies a single database to
+  replicate.
+
+- :data:`--slaveDelay <members[n].slaveDelay>`: This takes an argument
+  and specifies the delay (in seconds) to be used when applying master
+  ops to slave.
+
+- :option:`--autoresync`: Automatically resync if slave data is stale.
+
+--slavedelay
+~~~~~~~~~~~~
+
+Sometimes it is beneficial to have a :term:`slave` that is purposefully
+many hours behind, to prevent human error. In MongoDB 1.3.3+ you can
+specify this with the :data:`--slaveDelay <members[n].slaveDelay>`
+command line option. Specify the delay to be used (in seconds) when
+applying :term:`master` operations to the slave.
+
+Specify this option at the slave:
+
+.. code-block:: javascript
+
+   mongod --slave --source mymaster.foo.com --slavedelay 7200
+
+Diagnostics
+~~~~~~~~~~~
+
+To have MongoDB inspect the contents of local.oplog.$main on the
+:term:`master` and report status, issue the following command from the
+:program:`mongo` shell:
+
+.. code-block:: javascript
+
+   db.printReplicationInfo()
+
+To have MongoDB inspect the contents of ``local.sources`` on the
+:term:`slave` and report status, issue the following command from the
+:program:`mongo` shell:
+
+.. code-block:: javascript
+
+   db.printSlaveReplicationInfo()
+
+Alternately, in MongoDB 1.3.2+, you can issue the following command:
+
+.. code-block:: javascript
+
+   db._adminCommand( { serverStatus : 1 , repl : N } )
+
+``N`` is the level of diagnostic information and can have the following
+values:
+
+- 0 - none
+- 1 - local (doesn't have to connect to other server)
+- 2 - remote (has to check with the master)
+
+Security
+--------
+
+*Use the master-slave configuration only for versions prior to 1.6*
+
+When security is enabled, you must configure a user account for the
+local database that exists on both servers.
+
+The :term:`slave`-side of a replication connection first looks for a
+user repl in ``local.system.users``. If present, that user is used to
+authenticate against the local database on the source side of the
+connection. If repl user does not exist, the first user object in
+``local.system.users`` is tried.
+
+The ``local`` database works like the ``admin`` database: an account for
+local has access to the entire server.
+
+The following is an example security configuration when security is enabled:
+
+.. code-block:: javascript
+
+   $ mongo <slavehostname>/admin -u <existingadminusername> -p<adminpassword>
+   > use local
+   > db.addUser('repl', <replpassword>);
+   ^c
+   $ mongo <masterhostname>/admin -u <existingadminusername> -p<adminpassword>
+   > use local
+   > db.addUser('repl', <replpassword>);
+
+Administrative Tasks for Master-Slave Configurations
+----------------------------------------------------
+
+*Use the master-slave configuration only for versions prior to 1.6*
+
+Failing over to a Slave (Promotion)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To permanently fail over from a down :term:`master` (``A``) to a
+:term:`slave` (``B``):
+
+1. Shut down ``A``.
+
+2. Stop :program:`mongod` on ``B``.
+
+3. Back up or delete local.* datafiles on ``B``.
+
+4. Restart :program:`mongod` on ``B`` with the ``--master`` option.
+
+.. note:: This is a one time cutover. The "mirror" is broken. ``A``
+   cannot be brought back in sync with ``B`` without a full resync.
+
+Inverting Master and Slave
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you have a :term:`master` (``A``) and a :term:`slave` (``B``) and you
+would like to reverse their roles, follow this recommended sequence. The
+sequence assumes ``A`` is healthy, up-to-date and up.
+
+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 master and slave:
+
+1. Halt writes on ``A`` using the :term:`fsync` command.
+
+2. Make sure ``B`` is caught up.
+
+3. Shut down ``B``.
+
+4. Wipe local.* on ``B`` to remove old ``local.sources``.
+
+5. Start up ``B`` with the ``--master`` option.
+
+6. Do a write on ``B``, which primes the :term:`oplog` to provide a new
+   sync start point.
+
+7. Shut down ``B``. ``B`` will now have a new set of ``local.*`` files.
+
+8. Shut down ``A`` and replace ``A``'s ``local.*`` files with a copy of
+   ``B``'s new ``local.*`` files. Remember to compress the files before/while
+   copying them. They can be quite large.
+
+9. Start ``B`` with the ``--master`` option.
+
+10. Start ``A`` with all the usual slave options plus --:setting:`fastsync`.
+
+Creating a Slave from an Existing Master's Disk Image
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you can stop write operations to the :term:`master` for an indefinite
+period, you can copy the data files from the master to the new
+:term:`slave` and then start the slave with --:setting:`fastsync`.
+
+.. warning::
+
+   Be careful with :setting:`fastsync`. If the data is not perfectly in
+   sync, a discrepancy will exist forever.
+
+:setting:`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 :term:`slave's <slave>` data file snapshot
+without any special options. Note data snapshots should only be taken
+when a :program:`mongod` process is down or in ``fsync-and-lock`` state.
+
+Resyncing a Slave that is too Stale to Recover
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:term:`Slaves <slave>` asynchronously apply write operations from the
+:term:`master`. These operations are stored in the master's
+:term:`oplog`. The oplog is finite in length. If a slave is too far
+behind, a full resync will be necessary.
+
+To resync the
+slave, open the :program:`mongo` shell and point it at the slave:
+
+.. code-block::
+
+   mongo <slave_host_and_port>
+
+Then run the :dbcommand:`resync` command:
+
+.. code-block::
+
+   use admin
+   db.runCommand({resync: 1})
+
+This forces a full resync of all data (which will be very slow on a
+large database). The same effect can be achieved by stopping
+:program:`mongod` on the slave, delete all slave data files, and
+restarting it.
+
+Slave Chaining
+~~~~~~~~~~~~~~
+
+:term:`Slaves <slave>` cannot be "chained." They must all connect to the
+:term:`master` directly. If a slave is chained to another slave you may
+see the following in the logs:
+
+.. code-block:: text
+
+   assertion 13051 tailable cursor requested on non capped collection
+   ns:local.oplog.$main
+
+Correcting a Slave's Source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change a :term:`slave's <slave>` source, manually modify the slave's
+``local.sources`` collection.
+
+.. example::
+
+   For example, say you accidentally type the wrong host for the slave's
+   source:
+
+   .. code-block:: javascript
+
+      mongod --slave --source prod.mississippi
+
+   You can restart the slave without the --slave and --source arguments.
+
+   .. code-block:: javascript
+
+      mongod
+
+   Now start the shell and update the ``local.sources`` collection.
+
+   .. code-block:: javascript
+
+      use local
+
+      db.sources.update({host : "prod.mississippi"}, {$set : {host :
+      "prod.mississippi"}})
+
+   Restart the slave with the correct command line arguments or with no
+   ``--source`` argument. Once ``local.sources`` is set, no ``--source``
+   is necessary.
+
+   .. code-block:: javascript
+
+      ./mongod --slave --source prod.mississippi
+
+   or
+
+   .. code-block:: javascript
+
+      . /mongod --slave
+
+   The slave now points to the correct :term:`master`.