From b141d633797e9802da09754bf648cb8c561f55e9 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Sep 2012 17:11:59 -0400 Subject: [PATCH 1/3] DOCS-493 consolidate member configuration info --- source/administration/replica-sets.txt | 528 +++++++++++------- .../replication-architectures.txt | 4 +- source/applications/replication.txt | 4 +- source/core/replication.txt | 292 +++------- 4 files changed, 407 insertions(+), 421 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b117ef740f3..7a4cf497b18 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -26,6 +26,305 @@ suggestions for administers of replica sets. - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` - :doc:`/tutorial/deploy-geographically-distributed-replica-set` +.. _replica-set-node-configurations: +.. _replica-set-member-configurations: + +Member Configurations +--------------------- + +All :term:`replica sets ` have a single :term:`primary` and one or more +:term:`secondaries `. Replica sets allow you to configure +secondary members in a variety of ways. This section describes these +configurations. + +.. note:: + + A replica set can have up to 12 members, but only 7 members can have + votes. For configuration information regarding non-voting members, see + :ref:`replica-set-non-voting-members`. + +.. warning:: + + The :method:`rs.reconfig()` shell command can force the current + primary to step down, which causes an election. When the primary + steps down, the :program:`mongod` closes all client + connections. While, this typically takes 10-20 seconds, attempt to + make these changes during scheduled maintenance periods. + +.. index:: replica set members; secondary only +.. _replica-set-secondary-only-members: +.. _replica-set-secondary-only-configuration: + +Secondary-Only +~~~~~~~~~~~~~~ + +"Secondary-only" mode prevents a :term:`secondary` member in a +:term:`replica set` from ever becoming a :term:`primary` in a +:term:`failover`. You can set secondary-only mode for any secondary. + +For example, you may want to configure all members of a replica sets +located outside of the main data centers as "secondary-only" to prevent +these members from ever becoming primary. + +To configure a member as secondary-only, set its +:data:`members[n].priority` value to ``0``. Any member with a +:data:`members[n].priority` equal to ``0`` will never seek election and +cannot become primary in any situation. For more information on priority +levels, see :ref:`replica-set-node-priority`. + +As an example of modifying member priorities, assume a four-member +replica set with member ``_id`` values of: ``0``, ``1``, ``2``, and +``3``. Use the following sequence of operations in the :program:`mongo` +shell to modify member priorities: + +.. code-block:: javascript + + cfg = rs.conf() + cfg.members[0].priority = 0 + cfg.members[1].priority = 0.5 + cfg.members[2].priority = 1 + cfg.members[3].priority = 2 + rs.reconfig(cfg) + +This sets the following: + +- Member ``0`` to a priority of ``0`` so that it can never become :term:`primary`. + +- Member ``1`` to a priority of ``0.5``, which makes it less likely to + become primary than other members but doesn't prohibit the + possibility. + +- Member ``2`` to a priority of ``1``, which is the default value. + Member ``2`` becomes primary if no member with a *higher* priority is + eligible. + +- Member ``3`` to a priority of ``2``. Member ``3`` becomes primary, if + eligible, under most circumstances. + +.. note:: + + If your replica set has an even number of members, add an + :ref:`arbiter ` to ensure that + members can quickly obtain a majority of votes in an + :ref:`election ` for primary. + +.. seealso:: :data:`members[n].priority` and :ref:`Replica Set + Reconfiguration `. + +.. index:: replica set members; hidden +.. _replica-set-hidden-members: +.. _replica-set-hidden-configuration: + +Hidden +~~~~~~ + +Hidden members are part of a replica set but cannot become +primary and are invisible to client applications. *However,* +hidden members **do** vote in :ref:`elections `. + +Hidden members are ideal for instances that will have significantly +different usage patterns than the other members and require separation +from normal traffic. Typically, hidden members provide reporting, +dedicated backups, and dedicated read-only testing and integration +support. + +Hidden members have :data:`members[n].priority` set +``0`` and have :data:`members[n].hidden` set to ``true``. + +To configure a :term:`hidden member`, use the following sequence of +operations in the :program:`mongo` shell: + +.. code-block:: javascript + + cfg = rs.conf() + cfg.members[0].priority = 0 + cfg.members[0].hidden = true + rs.reconfig(cfg) + +After re-configuring the set, the member with the ``_id`` of ``0`` +has a priority of ``0`` so that it cannot become primary. The +other members in the set will not advertise the hidden member in the +:dbcommand:`isMaster` or :method:`db.isMaster()` output. + +.. note:: + + You must send the :method:`rs.reconfig()` command to a set member + that *can* become :term:`primary`. In the above example, if you issue + the :method:`rs.reconfig()` operation to the member with the ``_id`` + of ``0``, the operation fails. + +.. seealso:: :ref:`Replica Set Read Preference ` + and :ref:`Replica Set Reconfiguration ` + +.. index:: replica set members; delayed +.. _replica-set-delayed-members: +.. _replica-set-delayed-configuration: + +Delayed +~~~~~~~ + +Delayed members copy and apply operations from the primary's :term:`oplog` with +a specified delay. If a member has a slave delay of one hour, then it +the latest entry in this member's oplog will not be more recent than +one hour old, and the state of data for the member will reflect the state of the +set an hour earlier. + +.. example:: If the current time is 09:52 and the secondary is a + delayed by an hour, no operation will be more recent than 08:52. + +Delayed members may help recover from various kinds of human error. Such +errors may include inadvertently deleted databases or botched +application upgrades. Consider the following factors when determining +the amount of slave delay to apply: + +- Ensure that the length of the delay is equal to or greater than your + maintenance window. + +- The size of the oplog is sufficient to capture *more than* the + number of operations that typically occur in that period of + time. See the section on :ref:`oplog sizing + ` for more information. + +Delayed members must have a :term:`priority` set to ``0`` to prevent +them from becoming primary in their replica sets. Also these members +should be :ref:`hidden ` to prevent your +application from seeing or querying this member. + +To configure a :term:`replica set` member with a one hour delay, use the +following sequence of operations in the :program:`mongo` shell: + +.. code-block:: javascript + + cfg = rs.conf() + cfg.members[0].priority = 0 + cfg.members[0].slaveDelay = 3600 + rs.reconfig(cfg) + +After the replica set reconfigures, the set member with the ``_id`` of +``0`` has a priority of ``0`` and cannot become :term:`primary`. The :data:`slaveDelay ` value +delays both replication and the member's :term:`oplog` by 3600 seconds (1 +hour). Setting :data:`slaveDelay ` to a +non-zero value also sets :data:`hidden ` to +``true`` for this replica set so that it does not receive application +queries in normal operations. + +.. warning:: + + The length of the secondary :data:`slaveDelay + ` must fit within the window of the + oplog. If the oplog is shorter than the :data:`slaveDelay + ` window, the delayed member cannot + successfully replicate operations. + +.. related:: For more information about delayed members, see the + section on :ref:`Delayed Replication `. + Additionally consider the following resources: + :data:`members[n].slaveDelay`, :ref:`Replica Set Reconfiguration + `, :ref:`Oplog Sizing + `, and :doc:`/tutorial/change-oplog-size`. + +.. index:: replica set members; arbiters +.. _replica-set-arbiters: +.. _replica-set-arbiter-configuration: + +Arbiters +~~~~~~~~ + +Arbiters are special :program:`mongod` instances that do not hold a +copy of the data and thus cannot become primary. Arbiters exist solely +participate in :term:`elections `. + +.. note:: + + Because of their minimal system requirements, you may safely deploy an + arbiter on a system with another workload such as an application + server or monitoring member. + +.. warning:: + + Do not run arbiter processes on a system that is an active + :term:`primary` or :term:`secondary` of its replica set. + +Arbiters never receive the contents of any collection but do have the +following interactions with the rest of the replica set: + +- Credential exchanges, which are used to authenticate the arbiter with + the replica set. All MongoDB processes within a replica set use + keyfiles. These exchanges are encrypted. + +- Only the authentication step is encrypted. Replica set configuration + data and voting are not encrypted. + +If your MongoDB deployment uses SSL, then all communications between +arbiters and the other members of the replica set are secure. See the +documentation for :doc:`/administration/ssl` for more information. Run +all arbiters on secure networks, as with all MongoDB components. + +To start an arbiter, use the following command: + +.. code-block:: sh + + mongod --replSet [setname] + +Replace ``[setname]`` with the name of the :term:`replica set` that the +arbiter will join. Then in the :program:`mongo` shell, while connected +to the *current* :term:`primary`, issue the following command: + +.. code-block:: javascript + + rs.addArb("[hostname]:[port]") + +Replace the ``[hostname]:[port]`` string with the arbiter's +hostname and the port. + +.. seealso:: :setting:`replSet`, :option:`--replSet `, + and :method:`rs.addArb()`. + +.. index:: replica set members; non-voting +.. _replica-set-non-voting-members: +.. _replica-set-non-voting-configuration: + +Non-Voting +~~~~~~~~~~ + +You may choose to change the number of votes that each member has in +:term:`elections ` for :term:`primary`. In general, all +members should have only 1 vote to prevent intermittent ties, deadlock, +or the wrong members from becoming :term:`primary`. Use :ref:`replica +set priorities ` to control which members +are more likely to become primary. + +To disable a member's ability to vote in :ref:`elections +` use the following command sequence in the +:program:`mongo` shell. + +.. code-block:: javascript + + cfg = rs.conf() + cfg.members[3].votes = 0 + cfg.members[4].votes = 0 + cfg.members[5].votes = 0 + rs.reconfig(cfg) + +This sequence gives ``0`` votes to set members with the ``_id`` +values of ``3``, ``4``, and ``5``. This setting allows the set to +elect these members as :term:`primary` but does not allow them to +vote in elections. If you have three non-voting members, you can add +three additional voting members to your set. Place voting members so that +your designated primary or primaries can reach a majority of votes in +the event of a network partition. + +.. note:: + + In general and when possible, all members should have only 1 vote. This + prevents intermittent ties, deadlocks, or the wrong members from + becoming primary. Use :ref:`Replica Set Priorities + ` to control which members are more + likely to become primary. + +.. seealso:: :data:`members[n].votes` and :ref:`Replica Set + Reconfiguration `. + Procedures ---------- @@ -40,7 +339,7 @@ the following to prepare the new member's :term:`data directory `: - Make sure the new member's data directory *does not* contain data. The new member will copy the data directory from an existing member. - If the new member is in a ":term:`recovering`" state, it must exit + If the new member is in a :term:`recovering` state, it must exit become a :term:`secondary` before MongoDB can copy all data as part of the replication process. This process takes time but does not require administrator intervention. @@ -86,9 +385,9 @@ example: rs.add({_id: 1, host: "mongo2.example.net:27017", priority: 0, hidden: true}) This configures a :term:`hidden member` that is accessible at -``mongo2.example.net:27017``. See ":data:`host `," -":data:`priority `," and ":data:`hidden -`" for more information about these settings. When +``mongo2.example.net:27017``. See :data:`host `, +:data:`priority `, and :data:`hidden +` for more information about these settings. When you specify a full configuration object with :method:`rs.add()`, you must declare the ``_id`` field, which is not automatically populated in this case. @@ -228,8 +527,8 @@ of the member with the highest :data:`members[n].priority` setting. Perform routine replica set reconfiguration during scheduled maintenance windows. -.. seealso:: The ":ref:`Replica Reconfiguration Usage - `" example revolves around +.. seealso:: The :ref:`Replica Reconfiguration Usage + ` example revolves around changing the priorities of the :data:`members` of a replica set. .. _replica-set-procedure-change-oplog-size: @@ -260,205 +559,7 @@ smaller oplog. To resize the oplog, follow these steps: #. Apply this procedure to any other member of the replica set that *could become* primary. -.. seealso:: The ":doc:`/tutorial/change-oplog-size`" tutorial. - -.. _replica-set-node-configurations: -.. _replica-set-member-configurations: - -Member Configurations ---------------------- - -All :term:`replica sets ` have a single :term:`primary` and one or more -:term:`secondaries `. Replica sets sets allow you to configure -secondary members in a variety of ways. This section describes these -configurations. - -.. note:: - - A replica set can have up to 12 members, but only 7 members can have - votes. See ":ref:`non-voting members `" - for configuration information regarding non-voting members. - -.. warning:: - - The :method:`rs.reconfig()` shell command can force the current - primary to step down, which causes an election. When the primary - steps down, the :program:`mongod` closes all client - connections. While, this typically takes 10-20 seconds, attempt to - make these changes during scheduled maintenance periods. - -.. _replica-set-secondary-only-configuration: - -Secondary-Only -~~~~~~~~~~~~~~ - -Given a four-member :term:`replica set`, with member ``_id`` values of: -``0``, ``1``, ``2``, and ``3``, use the following sequence of -operations in the :program:`mongo` shell to modify member priorities: - -.. code-block:: javascript - - cfg = rs.conf() - cfg.members[0].priority = 0 - cfg.members[1].priority = 0.5 - cfg.members[2].priority = 1 - cfg.members[3].priority = 2 - rs.reconfig(cfg) - -This operation sets the following: - -- Member ``0`` to a priority of ``0`` so that it can never become :term:`primary`. - -- Member ``1`` to a priority of ``0.5``, which makes it less likely to - become primary than other members but doesn't prohibit the - possibility. - -- Member ``2`` to a priority of ``1``, which is the default value. - Member ``2`` becomes primary if no member with a *higher* priority is - eligible. - -- Member ``3`` to a priority of ``2``. Member ``3`` becomes primary, if - eligible, under most circumstances. - -.. note:: - - If your replica set has an even number of members, add an - :ref:`arbiter ` to ensure that - members can quickly obtain a majority of votes in an - :ref:`election ` for primary. - -.. seealso:: ":data:`members[n].priority`" and ":ref:`Replica Set - Reconfiguration `." - -.. _replica-set-hidden-configuration: - -Hidden -~~~~~~ - -To configure a :term:`hidden member`, use the following sequence of -operations in the :program:`mongo` shell: - -.. code-block:: javascript - - cfg = rs.conf() - cfg.members[0].priority = 0 - cfg.members[0].hidden = true - rs.reconfig(cfg) - -After re-configuring the set, the member with the ``_id`` of ``0`` -has a priority of ``0`` so that it cannot become primary. The -other members in the set will not advertise the hidden member in the -:dbcommand:`isMaster` or :method:`db.isMaster()` output. - -.. note:: - - You must send the :method:`rs.reconfig()` command to a set member - that *can* become :term:`primary`. In the above example, if you issue - the :method:`rs.reconfig()` operation to the member with the ``_id`` - of ``0``, the operation fails. - -.. seealso:: ":ref:`Replica Set Read Preference `." - ":data:`members[n].hidden`," ":data:`members[n].priority`," - and ":ref:`Replica Set Reconfiguration `." - -.. _replica-set-delayed-configuration: - -Delayed -~~~~~~~ - -To configure a :term:`replica set` member with a one hour delay, use the -following sequence of operations in the :program:`mongo` shell: - -.. code-block:: javascript - - cfg = rs.conf() - cfg.members[0].priority = 0 - cfg.members[0].slaveDelay = 3600 - rs.reconfig(cfg) - -After the replica set reconfigures, the set member with the ``_id`` of -``0`` has a priority of ``0`` and cannot become :term:`primary`. The :data:`slaveDelay ` value -delays both replication and the member's :term:`oplog` by 3600 seconds (1 -hour). Setting :data:`slaveDelay ` to a -non-zero value also sets :data:`hidden ` to -``true`` for this replica set so that it does not receive application -queries in normal operations. - -.. warning:: - - The length of the secondary :data:`slaveDelay - ` must fit within the window of the - oplog. If the oplog is shorter than the :data:`slaveDelay - ` window, the delayed member cannot - successfully replicate operations. - -.. related:: For more information about delayed members, see the - section on ":ref:`Delayed Replication `." - Additionally consider the following resources: - ":data:`members[n].slaveDelay`," ":ref:`Replica Set Reconfiguration - `," ":ref:`Oplog Sizing - `," and ":doc:`/tutorial/change-oplog-size`." - -.. _replica-set-arbiter-configuration: - -Arbiters -~~~~~~~~ - -Use the following command to start an arbiter: - -.. code-block:: sh - - mongod --replSet [setname] - -Replace ``[setname]`` with the name of the :term:`replica set` that the -arbiter will join. Then in the :program:`mongo` shell, while connected -to the *current* :term:`primary`, issue the following command: - -.. code-block:: javascript - - rs.addArb("[hostname]:[port]") - -Replace the ``[hostname]:[port]`` string with the arbiter's -hostname and the port. - -.. seealso:: ":setting:`replSet`," ":option:`--replSet `, - and ":method:`rs.addArb()`." - -.. _replica-set-non-voting-configuration: - -Non-Voting -~~~~~~~~~~ - -To disable a member's ability to vote in :ref:`elections -` use the following command sequence in the -:program:`mongo` shell. - -.. code-block:: javascript - - cfg = rs.conf() - cfg.members[3].votes = 0 - cfg.members[4].votes = 0 - cfg.members[5].votes = 0 - rs.reconfig(cfg) - -This sequence gives ``0`` votes to set members with the ``_id`` -values of ``3``, ``4``, and ``5``. This setting allows the set to -elect these members as :term:`primary` but does not allow them to -vote in elections. If you have three non-voting members, you can add -three additional voting members to your set. Place voting members so that -your designated primary or primaries can reach a majority of votes in -the event of a network partition. - -.. note:: - - In general and when possible, all members should have only 1 vote. This - prevents intermittent ties, deadlocks, or the wrong members from - becoming primary. Use ":ref:`Replica Set Priorities - `" to control which members are more - likely to become primary. - -.. seealso:: ":data:`members[n].votes`" and ":ref:`Replica Set - Reconfiguration `." +.. seealso:: The :doc:`/tutorial/change-oplog-size` tutorial. .. _replica-set-security: @@ -520,7 +621,7 @@ response strategies for any of these symptoms, the following sections provide good places to start a troubleshooting investigation with :term:`replica sets `. -.. seealso:: ":doc:`/administration/monitoring`." +.. seealso:: :doc:`/administration/monitoring`. .. _replica-set-replication-lag: @@ -605,9 +706,22 @@ Possible causes of replication lag include: - the :ref:`Oplog Sizing ` section, and - the :doc:`/tutorial/change-oplog-size` tutorial. +.. index:: pair: replica set; failover +.. _replica-set-failover: +.. _failover: + Failover and Recovery ~~~~~~~~~~~~~~~~~~~~~ +Replica sets feature automated failover. If the :term:`primary` +goes offline or becomes unresponsive and a majority of the original +set members can still connect to each other, the set will elect a new +primary. + +While :term:`failover` is automatic, :term:`replica set` +administrators should still understand exactly how this process +works. This section below describe failover in detail. + In most cases, failover occurs without administrator intervention seconds after the :term:`primary` either steps down, becomes inaccessible, or becomes otherwise ineligible to act as primary. If your MongoDB deployment @@ -641,4 +755,4 @@ data to a :term:`BSON` file that you can view using You can prevent rollbacks by ensuring safe writes by using the appropriate :term:`write concern`. -.. seealso:: ":ref:`Replica Set Elections `" +.. seealso:: :ref:`Replica Set Elections ` diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index 769a5035eae..f7a5cfedfff 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -115,8 +115,8 @@ an even number. To create an odd number and prevent ties, deploy an .. seealso:: :doc:`/tutorial/deploy-geographically-distributed-replica-set` -Hidden and Non-Voting Members ------------------------------ +Non-Production Members +---------------------- In some cases it may be useful to maintain a member that has an always up-to-date copy of the entire data set but that cannot become primary. diff --git a/source/applications/replication.txt b/source/applications/replication.txt index 599a652b489..214c6cc7915 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -41,7 +41,7 @@ command's return or acknowledgment: inaccessible or insertion errors caused by :ref:`duplicate key errors `. -- "``j``" or "journal" option. +- ``j`` or "journal" option. Confirms the above, and that the :program:`mongod` instance has written the data to the on-disk journal. This ensures that the data @@ -541,7 +541,7 @@ For any operation that targets a member *other* than the Once the application selects a member of the set to use for read operations, the driver continues to use this connection for read preference until the application specifies a new read preference or -something interrupts the connection. See ":ref:`replica-set-read-preference-behavior-requests`" +something interrupts the connection. See :ref:`replica-set-read-preference-behavior-requests` for more information. .. [#acceptable-secondary-latency] Applications can configure the diff --git a/source/core/replication.txt b/source/core/replication.txt index dc0de856f91..0d46c191ac7 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -7,9 +7,9 @@ Replication Fundamentals A MongoDB :term:`replica set` is a cluster of :program:`mongod` instances that replicate amongst one another and ensure automated failover. Most replica sets consists of two or more :program:`mongod` instances with at most one -of these designated as the primary node and the rest as secondary -nodes. Clients direct all writes to the primary node, while -the secondary nodes replicate from the primary asynchronously. +of these designated as the primary and the rest as secondary +members. Clients direct all writes to the primary, while +the secondary members replicate from the primary asynchronously. Database replication with MongoDB adds redundancy, helps to ensure high availability, simplifies certain administrative tasks @@ -19,20 +19,24 @@ deployments use replication. If you're familiar with other database systems, you may think about replica sets as a more sophisticated form of traditional master-slave replication. [#master-slave]_ In master-slave replication, a -":term:`master`" node accepts writes while one or more ":term:`slave`" +:term:`master` node accepts writes while one or more :term:`slave` nodes replicate those write operations and thus maintain data sets -identical to the master. In MongoDB terms, the node that accepts write -operations is the "**primary**", and the replicating nodes are the -"**secondaries**". +identical to the master. In MongoDB terms, the member that accepts write +operations is the **primary**, and the replicating members are the +**secondaries**. MongoDB's replica sets provide automated failover. If a -:term:`primary` node fails, the remaining members will automatically -try to elect a new primary node. +:term:`primary` fails, the remaining members will automatically +try to elect a new primary. -.. seealso:: ":ref:`Replica Set Implementation Details - `" and the ":doc:`/replication`" index for - a list of all documents in this manual that contain information - related to the operation and use of MongoDB's replica sets. +A replica set can have up to 12 members, but only 7 members can have +votes. For information regarding non-voting members, see +:ref:`non-voting members ` + +.. seealso:: :ref:`Replica Set Implementation Details + ` and the :doc:`/replication` index for a + list of all documents in this manual that contain information related + to the operation and use of MongoDB's replica sets. .. [#master-slave] MongoDB also provides conventional master/slave replication. Master/slave replication operates by way of the same @@ -47,168 +51,36 @@ try to elect a new primary node. Member Configurations --------------------- -All replica sets at most use a single :term:`primary` member and one or -more :term:`secondary` members. Replica sets allow you to configure -secondary members in a variety of ways. This section describes uses and -functions of all the replica set member configurations. - -.. seealso:: ":ref:`Replica Set Node Configurations - `" for instruction on replica set - member configuration. - -.. note:: - - A replica set can have up to 12 nodes, but only 7 nodes can have - votes. See ":ref:`non-voting nodes `" - for information regarding non-voting nodes. - -.. index:: replica set members; secondary only -.. _replica-set-secondary-only-members: - -Secondary-Only -~~~~~~~~~~~~~~ - -You can set "secondary-only" mode for any :term:`replica set` -:term:`secondary` member to prevent the member from becoming a -:term:`primary` in a :term:`failover`. To set this configuration for a -member of the set see :ref:`secondary-only configuration `. - -Any node with a :data:`members[n].priority` value equal to ``0`` will -never seek election and cannot become primary in any situation. Many -users configure all members of their replica sets located -outside of the main data centers as "secondary-only" to prevent these -members from ever becoming primary. - -.. seealso:: ":ref:`Configuring Secondary-Only Members - `" for a procedure that you can - use to place a member in "secondary-only" mode. See :ref:`replica - set priorities `" for more information - on member priorities in general. - -.. index:: replica set members; hidden -.. _replica-set-hidden-members: - -Hidden -~~~~~~ - -Hidden members are part of a replica set, but are unable to become -primary (i.e. have :ref:`priority ` set to -a value of ``0``, ) and invisible to client applications. *However,* -hidden members **do** vote in :ref:`elections -`. - -Hidden members are ideal for instances that will have significantly -different usage patterns than the other nodes and require separation -from normal traffic. Typically, hidden members provide reporting, -dedicated backups, and dedicated read-only testing and integration -support. - -.. see:: The section on :ref:`configuring hidden members - ` for the procedure to implement - this configuration. - -.. index:: replica set members; delayed -.. _replica-set-delayed-members: - -Delayed -~~~~~~~ - -Delayed members copy and apply operations from the primary's :term:`oplog` with -a specified delay. If a member has a slave delay of one hour, then it -the latest entry in this member's oplog will not be more recent than -one hour old, and the state of data for the member will reflect the state of the -set an hour earlier. - -.. example:: If the current time is 09:52 and the secondary is a - delayed by an hour, no operation will be more recent than 08:52. - -Delayed members may help recover from -various kinds of human error. Such errors may include inadvertently -deleted databases or botched application upgrades. Consider the -following factors when determining the amount of slave delay to -apply: - -- Ensure that the length of the delay is equal to or greater than your - maintenance window. - -- The size of the oplog is sufficient to capture *more than* the - number of operations that typically occur in that period of - time. See the section on :ref:`oplog sizing - ` for more information. - -Delayed members must have a :term:`priority` set to ``0`` to prevent -them from becoming primary in their replica sets. Also these members -should be :ref:`hidden ` to prevent your -application from seeing or querying this member. - -.. see:: The section on :ref:`configuring a delayed member - ` for the procedure to implement this - configuration. - -.. index:: replica set members; arbiters -.. _replica-set-arbiters: - -Arbiters -~~~~~~~~ - -Arbiters are special :program:`mongod` instances that do not hold a -copy of the data and thus cannot become primary. Arbiters exist solely -participate in :term:`elections `. +All replica sets at most use a single :term:`primary` and one or more +:term:`secondary` members. You can configure secondary members in a +variety of ways, as listed here. For details, see +:ref:`replica-set-member-configurations` in the +:doc:`/administration/replica-sets` document. -.. note:: +You can configure a member as any of the following: - Because of their minimal system requirements, you may safely deploy an - arbiter on a system with another workload such as an application - server or monitoring node. - -.. warning:: +- Secondary-Only --- This member cannot become primary. See + :ref:`replica-set-secondary-only-members`. - Do not run arbiter processes on a system that is an active - :term:`primary` or :term:`secondary` of its replica set. +- Hidden --- This member is invisible to client applications. See + :ref:`replica-set-hidden-members`. -Arbiters never receive the contents of any collection but do have the -following interactions with the rest of the replica set: +- Delayed --- This member applies operations from the primary's :term:`oplog` with + a specified delay. See :ref:`replica-set-delayed-members`. -- Credential exchanges, which are used to authenticate the arbiter with - the replica set. All MongoDB processes within a replica set use - keyfiles. These exchanges are encrypted. +- Arbiters --- This member does not hold data and exists solely to + participate in :term:`elections `. See :ref:`replica-set-arbiters`. -- Only the authentication step is encrypted. Replica set configuration - data and voting are not encrypted. - -If your MongoDB deployment uses SSL, then all communications between -arbiters and the other members of the replica set are secure. See the -documentation for :doc:`/administration/ssl` for more information. Run -all arbiters on secure networks, as with all MongoDB components. - -.. index:: replica set members; non-voting -.. _replica-set-non-voting-members: - -Non-Voting -~~~~~~~~~~ - -You may choose to change the number of votes that each member has in -:term:`elections ` for :term:`primary`. In general, all -members should have only 1 vote to prevent intermittent ties, deadlock, -or the wrong nodes from becoming :term:`primary`. Use ":ref:`replica -set priorities `" to control which members -are more likely to become primary. - -.. index:: pair: replica set; failover -.. _replica-set-failover: -.. _failover: +- Non-Voting --- This member cannot vote in elections. See + :ref:`replica-set-non-voting-members`. Failover -------- -Replica sets feature automated failover. If the :term:`primary` node +Replica sets feature automated failover. If the :term:`primary` goes offline or becomes unresponsive and a majority of the original set members can still connect to each other, the set will elect a new -primary. - -While :term:`failover` is automatic, :term:`replica set` -administrators should still understand exactly how this process -works. This section below describe failover in detail. +primary. For details, see :ref:`replica-set-failover` .. index:: replica set; elections .. index:: failover; elections @@ -221,18 +93,18 @@ When any failover occurs, an election takes place to decide which member should become primary. Elections provide a mechanism for the members of a :term:`replica set` -to autonomously select a new :term:`primary` node without +to autonomously select a new :term:`primary` without administrator intervention. The election allows replica sets to recover from failover situations very quickly and robustly. -Whenever the primary node becomes unreachable, the secondary nodes -trigger an :ref:`election `. The first node to +Whenever the primary becomes unreachable, the secondary members +trigger an :ref:`election `. The first member to receive votes from a majority of the set will become primary. The most important feature of replica set elections is that a majority of the -original number of nodes in the replica set must be present for +original number of members in the replica set must be present for election to succeed. If you have a three-member replica set, the set can -elect a primary when two or three nodes can connect to each other. If -two nodes in the replica go offline, then the remaining node will +elect a primary when two or three members can connect to each other. If +two members in the replica go offline, then the remaining member will remain a secondary. .. note:: @@ -243,28 +115,28 @@ remain a secondary. view of the :term:`replica set` and helps prevent :term:`rollbacks `. -.. seealso:: ":ref:`Replica Set Election Internals `" +.. seealso:: :ref:`Replica Set Election Internals ` .. index:: replica set; priority .. _replica-set-node-priority: -Node Priority -~~~~~~~~~~~~~ +Member Priority +~~~~~~~~~~~~~~~ -In a replica set, every node has a "priority," that helps determine +In a replica set, every member has a "priority," that helps determine eligibility for :ref:`election ` to -:term:`primary`. By default, all nodes have a priority of ``1``, -unless you modify the :data:`members[n].priority` value. All nodes +:term:`primary`. By default, all members have a priority of ``1``, +unless you modify the :data:`members[n].priority` value. All members have a single vote in :ref:`elections `. .. warning:: Always configure the :data:`members[n].priority` value to control - which nodes will become primary. Do not configure + which members will become primary. Do not configure :data:`members[n].votes` except to permit more than 7 secondary - nodes. + members. -.. seealso:: ":ref:`Node Priority Configuration `" +.. seealso:: :ref:`Member Priority Configuration ` .. index:: pair: replica set; consistency .. _replica-set-consistency: @@ -272,23 +144,23 @@ have a single vote in :ref:`elections `. Consistency ----------- -In MongoDB, all read operations issued to the primary node of a +In MongoDB, all read operations issued to the primary of a replica set are :term:`consistent `, with the last write operation. If clients configure the :term:`read preference` to permit allow secondary reads, -read operations cannot return from :term:`secondary` nodes that have not +read operations cannot return from :term:`secondary` members that have not replicated more recent updates or operations. In these situations the query results may reflect a previous state. -This behavior is sometimes characterized as ":term:`eventual -consistency`" because the secondary node's state will *eventually* +This behavior is sometimes characterized as :term:`eventual +consistency` because the secondary member's state will *eventually* reflect the primary's state and MongoDB cannot guarantee :term:`strict -consistency` for read operations from secondary nodes. +consistency` for read operations from secondary members. There is no way to guarantee consistency for reads from *secondary -nodes,* except by configuring the :term:`client` and :term:`driver` to -ensure that write operations succeed on all nodes before completing +members,* except by configuring the :term:`client` and :term:`driver` to +ensure that write operations succeed on all members before completing successfully. This section provides an overview of the concepts that underpin @@ -304,11 +176,11 @@ have access to consistent data. Rollbacks ~~~~~~~~~ -In some :term:`failover` situations :term:`primary` nodes will have +In some :term:`failover` situations :term:`primaries ` will have accepted write operations that have *not* replicated to the :term:`secondaries ` after a failover occurs. This case is rare and typically occurs as a result of a network partition with -replication lag. When this node (the former primary) rejoins the +replication lag. When this member (the former primary) rejoins the :term:`replica set` and attempts to continue replication as a secondary the former primary must revert these operations or "roll back" these operations to maintain database consistency across the @@ -319,13 +191,13 @@ database's :setting:`dbpath` directory. Use :doc:`bsondump ` to read the contents of these rollback files and then manually apply the changes to the new primary. There is no way for MongoDB to appropriately and fairly handle rollback situations -without manual intervention. Even after the node completes the +without manual intervention. Even after the member completes the rollback and returns to secondary status, administrators will need to apply or decide to ignore the rollback data. The best strategy for avoiding all rollbacks is to ensure :ref:`write propagation ` to all or some of the -nodes in the set. Using +members in the set. Using these kinds of policies prevents situations that might create rollbacks. @@ -368,9 +240,9 @@ working with replica sets: :term:`Read preference` and :term:`write concern` have particular :ref:`consistency ` implications. -.. seealso:: ":doc:`/applications/replication`," - ":ref:`replica-set-write-concern`," and - ":ref:`replica-set-read-preference`." +.. seealso:: :doc:`/applications/replication`, + :ref:`replica-set-write-concern`, and + :ref:`replica-set-read-preference`. Administration and Operations ----------------------------- @@ -380,8 +252,8 @@ administrators of replica set deployments. .. seealso:: - - ":doc:`/administration/replica-sets`" - - ":doc:`/administration/replication-architectures`" + - :doc:`/administration/replica-sets` + - :doc:`/administration/replication-architectures` .. index:: replica set; oplog .. _replica-set-oplog-sizing: @@ -418,7 +290,7 @@ oplog will be as follows: Once created, you cannot change the size of the oplog without using the :ref:`oplog resizing procedure ` - outlined in the ":doc:`/tutorial/change-oplog-size`" guide. + outlined in the :doc:`/tutorial/change-oplog-size` guide. For example, if an oplog fits 24 hours of operations, then members can stop copying entries from the oplog for 24 hours before they require @@ -459,33 +331,33 @@ Without replication, a standalone MongoDB instance represents a single point of failure and any disruption of the MongoDB system will render the database unusable and potentially unrecoverable. Replication increase the reliability of the database instance, and replica sets -are capable of distributing reads to :term:`secondary` nodes depending +are capable of distributing reads to :term:`secondary` members depending on :term:`read preference`. For database work loads dominated by read operations, (i.e. "read heavy") replica sets can greatly increase the capability of the database system. -The minimum requirements for a replica set include two nodes with +The minimum requirements for a replica set include two members with data, for a :term:`primary` and a :term:`secondary`, and an :ref:`arbiters `. In most circumstances, however, you will want -to deploy three data nodes. +to deploy three data members. For those deployments that rely heavily on distributing reads to -secondary instances, add additional nodes to the set as load +secondary instances, add additional members to the set as load increases. As your deployment grows, consider adding or moving replica set members to secondary data centers or to geographically distinct locations for additional redundancy. While many architectures -are possible, always ensure that the quorum of nodes required to elect +are possible, always ensure that the quorum of members required to elect a primary remains in your main facility. Depending on your operational requirements, you may consider adding -nodes configured for a specific purpose including, a :term:`delayed +members configured for a specific purpose including, a :term:`delayed member` to help provide protection against human errors and change -control, a :term:`hidden member` to provide an isolated node for +control, a :term:`hidden member` to provide an isolated member for reporting and monitoring, and/or a :ref:`secondary only member ` for dedicated backups. The process of establishing a new replica set member can be resource -intensive on existing nodes. As a result, deploy new members to +intensive on existing members. As a result, deploy new members to existing replica sets significantly before current demand saturates the existing members. @@ -522,9 +394,9 @@ that: - If you use MongoDB's authentication system to limit access to your infrastructure, ensure that you configure a - :setting:`keyFile` on all nodes to permit authentication. + :setting:`keyFile` on all members to permit authentication. -.. seealso:: ":ref:`Replica Set Security `" +.. seealso:: :ref:`Replica Set Security ` .. _replica-set-deployment-overview: .. _replica-set-architecture: @@ -552,13 +424,13 @@ Consider the following factors when developing an architecture for your replica set: - Ensure that the members of the replica set will always be able to - elect a primary node. Run an odd number of nodes or run an arbiter + elect a primary. Run an odd number of members or run an arbiter on one of your application servers if you have an even number of members. -- With geographically distributed nodes, be aware of where the - "quorum" of nodes will be in case of likely network partitions, - attempt to ensure that the set can elect a primary among the nodes in +- With geographically distributed members, be aware of where the + "quorum" of members will be in case of likely network partitions, + attempt to ensure that the set can elect a primary among the members in the primary data center. - Consider including a :ref:`hidden ` @@ -571,5 +443,5 @@ your replica set: ` to prevent it from becoming :term:`primary`. -.. seealso:: ":doc:`/administration/replication-architectures`" for +.. seealso:: :doc:`/administration/replication-architectures` for more information regarding replica set architectures. From ca022db0dac18e8fcef533b995d24d8120461976 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Sep 2012 17:38:49 -0400 Subject: [PATCH 2/3] DOCS-493 removed em dashes --- source/core/replication.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/core/replication.txt b/source/core/replication.txt index 0d46c191ac7..560687537c1 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -21,7 +21,7 @@ replica sets as a more sophisticated form of traditional master-slave replication. [#master-slave]_ In master-slave replication, a :term:`master` node accepts writes while one or more :term:`slave` nodes replicate those write operations and thus maintain data sets -identical to the master. In MongoDB terms, the member that accepts write +identical to the master. In MongoDB deployments, the member that accepts write operations is the **primary**, and the replicating members are the **secondaries**. @@ -59,19 +59,19 @@ variety of ways, as listed here. For details, see You can configure a member as any of the following: -- Secondary-Only --- This member cannot become primary. See +- **Secondary-Only**: These members cannot become primary. See :ref:`replica-set-secondary-only-members`. -- Hidden --- This member is invisible to client applications. See +- **Hidden**: These members are invisible to client applications. See :ref:`replica-set-hidden-members`. -- Delayed --- This member applies operations from the primary's :term:`oplog` with +- **Delayed**: These members apply operations from the primary's :term:`oplog` with a specified delay. See :ref:`replica-set-delayed-members`. -- Arbiters --- This member does not hold data and exists solely to +- **Arbiters**: These members do not hold data and exist solely to participate in :term:`elections `. See :ref:`replica-set-arbiters`. -- Non-Voting --- This member cannot vote in elections. See +- **Non-Voting**: These members cannot vote in elections. See :ref:`replica-set-non-voting-members`. Failover From b510ec0dc49b34f1ba3e803809262e6dc1f7488b Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 5 Sep 2012 17:48:15 -0400 Subject: [PATCH 3/3] DOCS-493: edits --- source/core/replication-internals.txt | 7 +++-- source/core/replication.txt | 5 ++-- source/replication.txt | 40 ++++++++++----------------- 3 files changed, 21 insertions(+), 31 deletions(-) diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 1398e365a20..2d016c65ea6 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -37,10 +37,11 @@ operations require idempotency: - post-rollback catch-up - sharding chunk migrations - .. TODO Verify that "sharding chunk migrations" (above) requires - idempotency. The wiki was unclear on the subject. +.. seealso:: The :ref:`replica-set-oplog-sizing` topic in + :doc:`/core/replication`. -For more information about the oplog, see :ref:`oplog sizing `. +.. TODO Verify that "sharding chunk migrations" (above) requires + idempotency. The wiki was unclear on the subject. .. In 2.0, replicas would import entries from the member lowest .. "ping," This wasn't true in 1.8 and will likely change in 2.2. diff --git a/source/core/replication.txt b/source/core/replication.txt index 560687537c1..ab1449b8881 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -21,9 +21,8 @@ replica sets as a more sophisticated form of traditional master-slave replication. [#master-slave]_ In master-slave replication, a :term:`master` node accepts writes while one or more :term:`slave` nodes replicate those write operations and thus maintain data sets -identical to the master. In MongoDB deployments, the member that accepts write -operations is the **primary**, and the replicating members are the -**secondaries**. +identical to the master. For MongoDB deployments, the member that accepts write +operations is the **primary**, and the replicating members are **secondaries**. MongoDB's replica sets provide automated failover. If a :term:`primary` fails, the remaining members will automatically diff --git a/source/replication.txt b/source/replication.txt index 29a0cdac775..402b4893a9c 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -2,33 +2,23 @@ Replication =========== -MongoDB supports database replication using a cluster of servers -known as a replica set. A replica set provides master-slave-style -replication with automated failover. +Database replication ensures redundancy, backup, and automatic failover. +Replication occurs through groups of servers known as replica sets. -If you're just getting started with replication in MongoDB, check out -the :doc:`core replication docs ` and the docs on -:doc:`using replica sets in the application development -`. +This page lists the documents, tutorials, and reference pages that describe replica sets. -There's also a very good `video introduction`_ to replica sets in -MongoDB. - -Before deploying a replica set to production, you should be familiar -with the :doc:`suggested replication architectures -`. The :doc:`replica set -administration ` document covers basic -administrative tasks such as adding and removing nodes. - -Finally, administrators and other advanced users will want to read up -on :doc:`replication internals ` and -consider the :ref:`replication reference material ` - -.. _`video introduction`: http://www.10gen.com/presentations/mongosv-2011/a-mongodb-replication-primer-replica-sets-in-practice +For an overview, see :doc:`/core/replication`. To work with members, see +:doc:`administration/replica-sets`. To configure deployment +architecture, see :doc:`administration/replication-architectures`. To +modify read and write operations, see :doc:`applications/replication`. +For common procedures, see the :ref:`tutorials list +`. Documentation ------------- +The following is the expanded outline of the main documentation: + .. toctree:: :maxdepth: 2 @@ -38,6 +28,8 @@ Documentation applications/replication core/replication-internals +.. _replica-set-tutorials-list: + Tutorials --------- @@ -59,13 +51,11 @@ operations in detail. Reference --------- -Finally, consider the replication reference material. The first is a -reference to the replica set configuration object and process: +The following describes the replica set configuration object: - :doc:`/reference/replica-configuration` -The next two documents describe the output of the replication status -commands: +The following describe status commands: - :doc:`/reference/replica-status` - :doc:`/reference/replication-info`