diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index f179b5fc4a7..56511289fc1 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -4,12 +4,11 @@ Replica Set Administration .. default-domain:: mongodb -:term:`Replica sets ` in MongoDB automate the vast -majority of the administrative complexity typically associated with -database replication and management. Nevertheless, some deployment and -long term administrative requirements that require administrator -intervention. This document provides an overview of these tasks as in -addition to general troubleshooting suggestions. +:term:`Replica sets ` automate the vast majority of the +administrative tasks associated with database replication and +management. However, administrators must perform some tasks manually. +This document gives an overview of those tasks. This document also +provides troubleshooting suggestions. .. seealso:: @@ -34,41 +33,43 @@ Procedures Adding Members ~~~~~~~~~~~~~~ -From time to time, you may need to add an additional member to an existing -:term:`replica set`. The data directory for the new member can: +Before adding a new member to an existing :term:`replica set`, do one of +the following to prepare the new member's :term:`data directory `: -- have no data. In this case, MongoDB must copy all data as part of - the replication process before the member can exit - ":term:`recovering`" status, and become a :term:`secondary` - member. This process can be time intensive, but does not require - administrator intervention. +- Make sure the new member's data directory *does not* contain data. The + new member will copy the data directory from an existing member. -- copy the :term:`data directory ` from an existing member. The new member - becomes a secondary, and will catch up to the current state of the - replica set after a short interval. Copying the data over manually, - shortens the amount of time it takes for the new member to become + If the new member is in ":term:`recovering`" status, it must exit + recovering status and become a :term:`secondary` member before MongoDB + can copy all data as part of the replication process. This process can + be time intensive but does not require administrator intervention. + +- Manually copy the data directory from an existing member. The new + member becomes a secondary member and will catch up to the current + state of the replica set after a short interval. Copying the data over + manually shortens the amount of time for the new member to become current. - If the difference in the amount of time between the most recent - operation and the most recent operation to the database exceeds the - length of the :term:`oplog` on the existing members, then the new - instance will have to completely re-synchronize. Ensure that you can - copy the data to the new system and begin replication within the - window allowed by the :term:`oplog`. + Ensure that you can copy the data directory to the new member and + begin replication within the window allowed by the oplog. If the + difference in the amount of time between the most recent operation and + the most recent operation to the database exceeds the length of the + :term:`oplog` on the existing members, then the new instance will have + to completely re-synchronize. - Use :func:`db.printReplicationInfo()` to check the current state of - replica set members with regards to the oplog. + Use :func:`db.printReplicationInfo()` to check the current state of + replica set members with regards to the oplog. -To add a member to an existing :term:`replica set`, deploy a new +To add a member to an existing replica set, deploy a new :program:`mongod` instance, specifying the name of the replica set -(i.e. "setname" or ``replSet``) on the command line with the +(i.e. :data:`setname `) on the command line with the :option:`--replSet ` option or in the configuration file with the :setting:`replSet`. Take note of the host name and port information for the new :program:`mongod` instance. -Then, log in to the current primary using the :program:`mongo` +Then log in to the current :term:`primary` using the :program:`mongo` shell. Issue the :func:`db.isMaster()` command when connected to *any* -member of the set to determine the current :term:`primary`. Issue the +member of the set to determine the current primary. Issue the following command to add the new member to the set: .. code-block:: javascript @@ -76,7 +77,7 @@ following command to add the new member to the set: rs.add("mongo2.example.net:27017") Alternately, specify an entire configuration document with some or all -of the fields in a :data:`members ` document, for +of the fields in a :data:`members ` document. For example: .. code-block:: javascript @@ -98,11 +99,11 @@ this case. Removing Members ~~~~~~~~~~~~~~~~ -You may remove a member of a replica at any time, if needed. Use the +You may remove a member of a replica at any time. Use the :func:`rs.remove()` function in the :program:`mongo` shell while connected to the current :term:`primary`. Issue the :func:`db.isMaster()` command when connected to *any* member of the -set to determine the current :term:`primary`. Use a command in either +set to determine the current primary. Use a command in either of the following forms to remove the member: .. code-block:: javascript @@ -112,15 +113,14 @@ of the following forms to remove the member: This operation disconnects the shell briefly and forces a re-connection as the :term:`replica set` renegotiates which member -will be :term:`primary`. The shell will display an error even if this +will be primary. The shell displays an error even if this command succeeds. You can re-add a removed member to a replica set at any time using the -:ref:`procedure for adding replica set members -`. Additionally, consider -using the :ref:`replica set reconfiguration procedure +:ref:`procedure for adding replica set members `. +Additionally, consider using the :ref:`replica set reconfiguration procedure ` to change the -:data:`members[n].host` value to rename a host in a replica set +:data:`members[n].host` value to rename a member in a replica set directly. .. _replica-set-admin-procedure-replace-member: @@ -128,7 +128,7 @@ directly. Replacing a Member ~~~~~~~~~~~~~~~~~~ -There are two processes for replacing a member of a replica set: +There are two processes for replacing a member of a :term:`replica set`: #. Remove and then re-add a member using the following procedure in the :program:`mongo` shell: @@ -140,12 +140,12 @@ There are two processes for replacing a member of a replica set: .. note:: - Because the set member tracks its own replica set member ``_id`` + The set member tracks its own replica set member ``_id``, which can cause conflicts when trying to re-add a previous member. To resolve this issue, you can either restart the - :program:`mongod` process on the host that you're re-adding, or - make sure that you specify an ``_id`` in the :func:`rs.add()` + :program:`mongod` process on the member that you're re-adding, or + you can make sure that you specify an ``_id`` in the :func:`rs.add()` document. #. Use :func:`rs.reconfig()` to change the value of the @@ -161,22 +161,22 @@ There are two processes for replacing a member of a replica set: The second method may be useful if you have an existing configuration and only want to change the hostname of a member rather than - completely remove all configuration related to the existing/previous + completely remove all configurations related to the existing/previous set member. The :data:`members[n]._id` field does not change as a result of this operation. .. warning:: Any replica set configuration change can trigger the current - :term:`primary` to step down forcing an :term:`election`. This + :term:`primary` to step down, forcing an :term:`election`. This causes the current shell session to produce an error even when the - operation succeeds. Clients connected to this replica set will also + operation succeeds. Also, clients connected to this replica set will disconnect. .. _replica-set-node-priority-configuration: -Adjusting a Member's Priority -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Adjusting Priority +~~~~~~~~~~~~~~~~~~~~ To change the value of the :data:`members[n].priority` value in the replica set configuration, use the following sequence of commands in @@ -190,33 +190,33 @@ the :program:`mongo` shell: cfg.members[2].priority = 2 rs.reconfig(cfg) -The first operation sets the local variable ``cfg`` to the contents -of the current replica set configuration using the :func:`rs.conf()`, -which is a :term:`document`. The next three operations change the +The first operation uses :func:`rs.conf()` to set the local variable +``cfg`` to the contents of the current replica set configuration, which +is a :term:`document`. The next three operations change the :data:`members[n].priority` value in the ``cfg`` document for :data:`members[n]._id` of ``0``, ``1``, or ``2``. The final operation calls :func:`rs.reconfig()` with the argument of ``cfg`` to initialize the new configuration. -If a node has :data:`members[n].priority` set to ``0``, it is -ineligible to become primary, and will not seek -elections. :ref:`Hidden ` and -:ref:`delayed ` members and -:ref:`arbiters ` have priority set to -``0``. Unless configured, all nodes have a :data:`members[n].priority` -setting equal to ``1``. +If a member has :data:`members[n].priority` set to ``0``, it is +ineligible to become :term:`primary` and will not seek +elections. :ref:`Hidden members `, +:ref:`delayed members `, and +:ref:`arbiters ` all have :data:`members[n].priority` +set to ``0``. -.. note:: +Unless configured otherwise, all members have a :data:`members[n].priority` +set to ``1``. - The value of :data:`members[n].priority` can be any floating point - (i.e. decimal) number between ``0`` and ``1000``, and priorities - are only used to determine the preference in election. The priority - value is only used in with other instances. With the exception of - nodes with a priority of ``0``, the absolute value of the - :data:`members[n].priority` value is irrelevant. +The value of :data:`members[n].priority` can be any floating point +(i.e. decimal) number between ``0`` and ``1000``. Priorities +are only used to determine the preference in election. The priority +value is used only in relation to other members. With the exception of +members with a priority of ``0``, the absolute value of the +:data:`members[n].priority` value is irrelevant. Replica sets will preferentially elect and maintain the primary status -of the node with the highest :data:`members[n].priority` setting. +of the member with the highest :data:`members[n].priority` setting. .. warning:: @@ -234,8 +234,8 @@ of the node with the highest :data:`members[n].priority` setting. .. _replica-set-procedure-change-oplog-size: -Changing the Oplog Size -~~~~~~~~~~~~~~~~~~~~~~~ +Changing Oplog Size +~~~~~~~~~~~~~~~~~~~ The :term:`oplog` exists internally as a :term:`capped collection`, so you cannot modify its size in the course of normal operations. In most @@ -243,45 +243,45 @@ cases the :ref:`default oplog size ` is an acceptable size; however, in some situations you may need a larger or smaller oplog. To resize the oplog, follow these steps: -1. Restart the current :term:`primary` instance in the replica set in +1. Restart the current :term:`primary` instance in the :term:`replica set` in "standalone" mode, running on a different port. -2. Save the last entry from the old (current) oplog, and create a - backup of the old (current) oplog. +2. Save the last entry from the old (current) oplog and create a + backup of the oplog. -3. Drop the current oplog, and create a new oplog of a different size. +3. Drop the old oplog and create a new oplog of a different size. 4. Insert the previously saved last entry from the old oplog into the - new (current) oplog. + new oplog. 5. Restart the server as a member of the replica set on its usual port. 6. Apply this procedure to any other member of the replica set that - *could become* :term:`primary`. + *could become* primary. .. seealso:: The ":doc:`/tutorial/change-oplog-size`" tutorial. .. _replica-set-node-configurations: -Node Configurations -------------------- +Member Configurations +--------------------- -All replica sets have a single :term:`primary` node and one or more -:term:`secondary` nodes. Replica sets sets allow you to configure -secondary nodes in a variety of ways. This section describes these -configurations and also describes the arbiter node type. +All :term:`replica set's` 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 nodes, but only 7 nodes can have + 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 nodes. + for configuration information regarding non-voting members. .. warning:: The :func:`rs.reconfig()` shell command can force the current - primary to step down and causes an election. When the primary node + 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. @@ -291,9 +291,9 @@ configurations and also describes the arbiter node type. Secondary-Only ~~~~~~~~~~~~~~ -Given 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 node priorities: +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 @@ -306,24 +306,24 @@ operations in the :program:`mongo` shell to modify node priorities: This operation sets the following: -- Member ``0`` to a priority of ``0`` so that it can never become primary. +- 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 + become primary than other members but doesn't prohibit the possibility. -- Member ``2`` to a priority of ``1``, which is the default value, and - will become primary if no member with a higher priority is eligible - to be primary. +- 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`` has a priority of ``2`` and will become primary, if +- 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 members, add an + If your replica set has an even number of members, add an :ref:`arbiter ` to ensure that - nodes will be able to quickly obtain a majority of votes in an + members can quickly obtain a majority of votes in an :ref:`election ` for primary. .. seealso:: ":data:`members[n].priority`" and ":ref:`Replica Set @@ -344,9 +344,9 @@ operations in the :program:`mongo` shell: cfg.members[0].hidden = true rs.reconfig(cfg) -After re-configuring the set, the node with the ``_id`` of ``0``, -has a priority of ``0`` so that it cannot become master, while the -other nodes in the set will not advertise the hidden node in the +After re-configuring the set, the member with the ``_id`` of ``0`` +has a priority of ``0`` so that it cannot become master. The +other members in the set will not advertise the hidden member in the :dbcommand:`isMaster` or :func:`db.isMaster()` output. .. note:: @@ -354,7 +354,7 @@ other nodes in the set will not advertise the hidden node in the You must send the :func:`rs.reconfig()` command to a set member that *can* become :term:`primary`. In the above example, if you issue the :func:`rs.reconfig()` operation to the member with the ``_id`` - of ``0``, the operation will fail. + of ``0``, the operation fails. .. seealso:: ":ref:`Replica Set Read Preference `." ":data:`members[n].hidden`," ":data:`members[n].priority`," @@ -365,7 +365,7 @@ other nodes in the set will not advertise the hidden node in the Delayed ~~~~~~~ -To configure a replica set member with a one hour delay, use the +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 @@ -376,20 +376,20 @@ following sequence of operations in the :program:`mongo` shell: rs.reconfig(cfg) After the replica set reconfigures, the set member with the ``_id`` of -``0``, will have a priority of ``0`` so that it cannot become primary and -will delay replication and its :term:`oplog` by 3600 seconds or 1 -hour. Setting :data:`slaveDelay ` to a -non-zero value will also set :data:`hidden ` to -``true`` for this replica set so that it will not receive application +``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 - :term:`oplog`. If the oplog is shorter than the :data:`slaveDelay - ` window the delayed member will not be able - to successfully replicate operations. + 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 `." @@ -409,16 +409,16 @@ Use the following command to start an arbiter: mongod --replSet [setname] -Replace ``[setname]`` with the name of the replica set that the +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 primary* node, issue the following command: +to the *current* :term:`primary`, issue the following command: .. code-block:: javascript rs.addArb("[hostname]:[port]") -Replace the ``[hostname]:[port]`` string with the name of the -hostname and port of the arbiter that you wish to add to the set. +Replace the ``[hostname]:[port]`` string with the arbiter's +hostname and the port. .. seealso:: ":setting:`replSet`," ":option:`--replSet `, and ":func:`rs.addArb()`." @@ -428,7 +428,7 @@ hostname and port of the arbiter that you wish to add to the set. Non-Voting ~~~~~~~~~~ -To disable a node's ability to vote in :ref:`elections +To disable a member's ability to vote in :ref:`elections ` use the following command sequence in the :program:`mongo` shell. @@ -440,20 +440,20 @@ To disable a node's ability to vote in :ref:`elections cfg.members[5].votes = 0 rs.reconfig(cfg) -This sequence sets gives ``0`` votes to set members with the ``_id`` +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 nodes, you can add -three additional voting nodes to your set. Place voting nodes so that -your designated primary node or nodes can reach a majority of votes in +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 use, when possible all nodes 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 nodes are more + 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 @@ -464,12 +464,12 @@ the event of a network partition. Security -------- -In most cases, the most effective ways to control access and secure +In most cases, the most effective ways to control access and to secure the connection between members of a :term:`replica set` depend on -network level access control. Use your environment's firewall and -network routing to ensure that *only* traffic from clients and other -replica set members can reach your :program:`mongod` instances. Use -virtual private networks (VPNs) if needed to ensure secure connections +network-level access control. Use your environment's firewall and +network routing to ensure that traffic *only* from clients and other +replica set members can reach your :program:`mongod` instances. If needed, +use virtual private networks (VPNs) to ensure secure connections over wide area networks (WANs.) Additionally, MongoDB provides an authentication mechanism for @@ -479,8 +479,8 @@ shared key file that serves as a shared password. .. versionadded:: 1.8 for replica sets (1.9.1 for sharded replica sets) added support for authentication. -To enable authentication using a key file for the :term:`replica set`, -add the following option to your configuration file. +To enable authentication using a key file for the replica set, +add the following option to your configuration file: .. code-block:: cfg @@ -493,13 +493,13 @@ add the following option to your configuration file. options on the command line. Setting :setting:`keyFile` enables authentication and specifies a key -file for the replica set member use to when authenticating to each -other. The content of the key file is arbitrary, but must be the same -on all members of the :term:`replica set` and :program:`mongos` +file for the replica set members 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 replica set and on all :program:`mongos` instances that connect to the set. -The keyfile must be less one kilobyte in size and may only contain -characters in the base64 set and file must not have group or "world" +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: @@ -529,10 +529,10 @@ Replication Lag Replication lag is a delay between an operation on the :term:`primary` and the application of that operation from :term:`oplog` to the -:term:`secondary`. Such lag can be a significant issue, and can -seriously affect MongoDB replica set deployments. Excessive -replication lag makes "lagged" members ineligible to become -:term:`primary` quickly and increases the possibility that distributed +:term:`secondary`. Such lag can be a significant issue and can +seriously affect MongoDB :term:`replica set` deployments. Excessive +replication lag makes "lagged" members ineligible to quickly become +primary and increases the possibility that distributed read operations will be inconsistent. Identify replication lag by checking the values of @@ -544,42 +544,42 @@ Possible causes of replication lag include: - **Network Latency.** - Check the network routes between the members of your set, to ensure + Check the network routes between the members of your set to ensure that there is no packet loss or network routing issue. - Use tools including :command:`ping` to test latency between set - members and :command:`traceroute` to expose the routing of packets + Use tools including ``ping`` to test latency between set + members and ``traceroute`` to expose the routing of packets network endpoints. - **Disk Throughput.** - If the file system and disk device on the :term:`secondary` is - unable to flush data to disk as quickly as the :term:`primary`, then - the secondary will have difficulty keeping state. Disk related + If the file system and disk device on the secondary is + unable to flush data to disk as quickly as the primary, then + the secondary will have difficulty keeping state. Disk-related issues are incredibly prevalent on multi-tenant systems, including vitalized instances, and can be transient if the system accesses - disk devices are over an IP network (as is the case with Amazon's + disk devices over an IP network (as is the case with Amazon's EBS system.) - Use system-level tools to assess disk status including - :command:`iostat` or :command:`vmstat`. + Use system-level tools to assess disk status, including + ``iostat`` or ``vmstat``. - **Concurrency.** - In some cases, long running operations on the primary can block - replication on :term:`secondaries `. You can use + In some cases, long-running operations on the primary can block + replication on secondaries. You can use :term:`write concern` to prevent write operations from returning - unless replication can keep up with the write load. + if replication cannot keep up with the write load. Use the :term:`database profiler` to see if there are slow queries - or long running operations that correspond to the incidences of lag. + or long-running operations that correspond to the incidences of lag. Failover and Recovery ~~~~~~~~~~~~~~~~~~~~~ In most cases, failover occurs without administrator intervention -seconds after the :term:`primary` steps down, becomes inaccessible, -or otherwise ineligible to act as primary. If your MongoDB deployment +seconds after the :term:`primary` either steps down, becomes inaccessible, +or becomes otherwise ineligible to act as primary. If your MongoDB deployment does not failover according to expectations, consider the following operational errors: @@ -589,8 +589,8 @@ operational errors: set members can elect a primary in the same facility as core application systems. -- No member is eligible to become :term:`primary`. Members must have a - :data:`members[n].priority` setting greater than ``0``, have state +- No member is eligible to become primary. Members must have a + :data:`members[n].priority` setting greater than ``0``, have a state that is less than ten seconds behind the last operation to the :term:`replica set`, and generally be *more* up to date than the voting members. @@ -605,9 +605,9 @@ down. When the former primary begins replicating again it performs a were never replicated to the set so that the data set is in a consistent state. The :program:`mongod` program writes rolled back data to a :term:`BSON` file that you can view using -:program:`bsondump` apply manually using :program:`mongorestore`. +:program:`bsondump`, applied manually using :program:`mongorestore`. -You can prevent rollbacks prevented by ensuring safe writes by using +You can prevent rollbacks by ensuring safe writes by using the appropriate :term:`write concern`. .. seealso:: ":ref:`Replica Set Elections `" diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index 208ec773304..c358890735c 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -4,166 +4,170 @@ Replication Architectures .. default-domain:: mongodb -There is no single :term:`replica set` architecture that is compatible -or ideal for every deployment or environment. Indeed the flexibility -of replica sets may be its greatest strength. This document outlines -and describes the most prevalent deployment patterns for replica set -administrators. +There is no single :term:`replica set` architecture that is ideal for +every deployment or environment. Indeed the flexibility of replica sets +might be their greatest strength. This document describes the most +commonly used deployment patterns for replica sets. The descriptions +are necessarily not mutually exclusive and in some cases can be combined. -.. seealso:: ":doc:`/administration/replica-sets`" and - ":doc:`/reference/replica-configuration`." +.. seealso:: :doc:`/administration/replica-sets` and + :doc:`/reference/replica-configuration` -Three Member Sets +Three-Member Sets ------------------ -The minimum *recommend* architecture for a :term:`replica set` -consists of: +The minimum *recommended* architecture for a replica set consists of -- One :term:`primary ` for the set. +- One :term:`primary ` -- Two :term:`secondary members `, which can become the - primary at any time. +- Two :term:`secondary ` members, either of which can become + the primary at any time. -This makes :ref:`failover ` possible, and -ensures that there are two independent copies of the entire data set -at all times. Even if one member is inaccessible, the set will still -be able to elect another member as :term:`primary`, and continue -replication until the first member can recover. + This makes :ref:`failover ` possible and ensures + there exists two full, independent copies of the data set at all + times. If the primary fails, the replica set elects another member as + primary and continues replication until the primary recovers. .. note:: - The minimum *supported* configuration for replica sets includes one - :term:`primary` node, one :term:`secondary` node, and one - :ref:`arbiter `. The arbiter, requires fewer - resources, and lowers the total cost of the replica set, - at the cost of a great deal of redundancy and operational - flexibility. + While not *recommended*, the minimum *supported* configuration for + replica sets includes one :term:`primary`, one :term:`secondary`, and + one :ref:`arbiter `. The arbiter requires fewer + resources and lowers costs but sacrifices operational flexibility and + redundancy. -.. seealso:: ":doc:`/tutorial/deploy-replica-set`." +.. seealso:: :doc:`/tutorial/deploy-replica-set`. -Sets with More Than Three Members ---------------------------------- +Sets with Four or More Members +------------------------------ -Add additional members to a replica set to increase redundancy or to -provide additional resources for distributing secondary read -operations. +To increase redundancy or to provide additional resources for +distributing secondary read operations, you can add additional members +to a replica set. -In general, when deploying larger replica sets, ensure the following -architectural conditions are true: +When adding additional members, ensure the following architectural +conditions are true: - The set has an odd number of voting members. - Deploy a single :ref:`arbiter ` if you have - an even number of voting replica set members. + If you have an *even* number of voting members, deploy an :ref:`arbiter + ` to create an odd number. -- The set has only 7 voting members at any time. +- The set has no more than 7 voting members at a time. -- Every member with a :data:`priority ` greater - than ``0`` can function as ``primary`` in a :term:`failover` - situation. If a member does not have this capability (i.e. resource - constraints,) set its ``priority`` value to ``0``. +- Members that cannot function as primaries in a :term:`failover` + have their :data:`priority ` values set to ``0``. + + If a member cannot function as a primary, for example because of + resource constraints, a :data:`priority ` value + of ``0`` prevents it from being a primary. Any member with a + ``priority`` value greater than ``0`` is available to be a primary. - A majority of the set's members operate in the main data center. -.. seealso:: ":doc:`/tutorial/expand-replica-set`." +.. seealso:: :doc:`/tutorial/expand-replica-set`. .. _replica-set-geographical-distribution: Geographically Distributed Sets ------------------------------- -If you have infrastructure in more than one facility, you may want to -consider keeping one member of the replica set in a secondary -facility. Typically this member should have the :data:`priority -` :ref:`set ` -to ``0`` to prevent the node from ever becoming primary. +A geographically distributed replica set provides data recovery should +the primary data center fail. + +A geographically distributed set includes at least one member in a +secondary data center. The member has its the :data:`priority +` :ref:`set ` to +``0`` to prevent the member from ever becoming primary. In many circumstances, these deployments consist of the following: -- One :term:`primary ` set member in the first (i.e. primary) - data center. +- One :term:`primary ` in the first (i.e., primary) data + center. + +- One :term:`secondary ` member in the primary data center. + This member can become the primary member at any time. -- One :term:`secondary member ` in the first data center that - can become primary at any time. +- One secondary member in a secondary data center. This member is + ineligible to become primary. Its :data:`members[n].priority` value is + set to ``0``. -- One secondary node in another data center, that is ineligible to - become primary (i.e. with a :data:`members[n].priority` value of - ``0``.) +If the primary member should fail, the replica set elects a new primary +from the primary data center. -If the primary node should fail, the replica set will be able to elect a -new primary node as normal. If the connection between the data center -fails, any members in the second data center cannot become primary -independently, and the nodes in the primary data center will continue -to function. +If the *connection* between the primary and secondary data centers fails, +the member in the secondary center cannot independently become the +primary. -If the primary data center fails, recovering from the database -instance in the secondary facility requires manual intervention. With -proper :term:`write concern` there will be no data loss and downtime -can be minimal. +If the primary data center fails, you can manually recover the data set +from the secondary data center. With proper :term:`write concern` there +will be no data loss and downtime can be minimal. -For deployments that maintain three members the primary data center, -adding a node in a second data center will create an even number of -nodes, which may result in ties during elections for -:term:`primary`. In this situation deploy an :ref:`arbiter -` in your primary data center to ensure that a -primary is always electable. +When you add a secondary data center, make sure to keep an odd number of +members overall to prevent ties during elections for primary. This can +be done by deploying an :ref:`arbiter ` in your +primary data center. For example, if you have three members in the +primary data center and add a member in a secondary center, you create +an even number. To create an odd number and prevent ties, deploy an +:ref:`arbiter ` in your primary data center. -.. seealso:: ":doc:`/tutorial/deploy-geographically-distributed-replica-set`" +.. seealso:: + :doc:`/tutorial/deploy-geographically-distributed-replica-set` Hidden and Non-Voting Members ----------------------------- -In some cases it may be useful to maintain a member of the set that -has an always up-to-date copy of the entire data set, but that cannot -become primary. Often these members provide backups, support reporting -operations, or act as cold standbys. There are three settings relevant -for these kinds of nodes: +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. +You might create such a member to provide backups, to support reporting +operations, or to act as a cold standby. Such members fall into one or +more of the following categories: -- **Priority**: These members have :data:`members[n].priority` - settings so that they either cannot become :term:`primary`, or are - *very* unlikely to become primary. In all other respects - lower-priority nodes are identical any other replica set - member. (:ref:`see also `.) +- **Low-Priority**: These members have :data:`members[n].priority` + settings such that they are either unable to become :term:`primary` or + *very* unlikely to become primary. In all other respects these + low-priority members are identical to other replica set member. (See: + :ref:`replica-set-secondary-only-members`.) -- **Hidden**: These members cannot become primary *and* the set - excludes them from the output of :func:`db.isMaster()` or the - database command :dbcommand:`isMaster`, which prevents clients and - drivers from using these nodes for secondary reads. (:ref:`see also - `.) +- **Hidden**: These members cannot become primary *and* the set excludes + them from the output of :func:`db.isMaster()` and from the output of + the database command :dbcommand:`isMaster`. Excluding hidden members + from such outputs prevents clients and drivers from using hidden + members for secondary reads. (See: :ref:`replica-set-hidden-members`.) - **Voting**: This changes the number of votes that a member of the - replica set has in elections. In general, use priority to - control the outcome of elections, as weighting votes introduces - operational complexities and risks. Only modify the - number of votes when you need to have more than 7 members in a - replica set. (:ref:`see also `.) + replica set has in elections. In general, use priority to control the + outcome of elections, as weighting votes introduces operational + complexities and risks. Only modify the number of votes when you need + to have more than 7 members in a replica set. (See: + :ref:`replica-set-non-voting-members`.) .. note:: All members of a replica set vote in elections *except* for - :ref:`non-voting ` - members. Priority, hidden, or delayed status does not affect a - member's ability to vote in an election. + :ref:`non-voting ` members. Priority, + hidden, or delayed status does not affect a member's ability to vote + in an election. Backups ~~~~~~~ -For some deployments, keeping a replica set member for dedicated -backup purposes is operationally advantageous. Ensure this system is -close, from a networking perspective, to the primary node or likely -primary, and that the :term:`replication lag` is minimal or -non-existent. You may wish to create a dedicated :ref:`hidden node -` for the purpose of creating backups. +For some deployments, keeping a replica set member for dedicated backup +purposes is operationally advantageous. Ensure this member is close, +from a networking perspective, to the primary or likely primary. Ensure +that the :term:`replication lag` is minimal or non-existent. To create a +dedicated :ref:`hidden member ` for the +purpose of creating backups. -If this member runs with journaling enabled, you can safely use -standard :ref:`block level backup methods ` to -create a backup of this node. Otherwise, if your underlying system -does not support snapshots, you can connect :program:`mongodump` to -create a backup directly from the secondary node. In these cases, use -the :option:`--oplog ` option to ensure a -consistent point-in-time dump of the database state. +If this member runs with journaling enabled, you can safely use standard +:ref:`block level backup methods ` to create a +backup of this member. Otherwise, if your underlying system does not +support snapshots, you can connect :program:`mongodump` to create a +backup directly from the secondary member. In these cases, use the +:option:`--oplog ` option to ensure a consistent +point-in-time dump of the database state. -.. seealso:: ":doc:`/administration/backups`." +.. seealso:: :doc:`/administration/backups`. .. _replica-set-delayed-replication: @@ -171,32 +175,32 @@ Delayed Replication ~~~~~~~~~~~~~~~~~~~ :term:`Delayed members ` are special :program:`mongod` -instances in a :term:`replica set` that function other replica set -:term:`secondary` members in most cases, with the following -operational differences: they are not eligible for election to -primary, do not receive secondary queries. Delayed members *do* vote -in :term:`elections ` for primary. - -Delayed nodes apply operations from the :term:`oplog` on a delay to -provide running "historical" snapshot of the data set, or a rolling -backup. Typically these members provide protection against human -error, such as unintentionally deleted databases and collections or -failed application upgrades or migrations. - -See ":ref:`Replica Set Delayed Nodes `" for +instances in a :term:`replica set` that function the same way as +:term:`secondary` members with the following operational differences: +they are not eligible for election to primary and do not receive +secondary queries. Delayed members *do* vote in :term:`elections +` for primary. + +Delayed members apply operations from the :term:`oplog` on a delay to +provide a running "historical" snapshot of the data set, or a rolling +backup. Typically these members provide protection against human error, +such as unintentionally deleted databases and collections or failed +application upgrades or migrations. + +See :ref:`Replica Set Delayed Nodes ` for more information about configuring delayed replica set members. Reporting ~~~~~~~~~ -Typically :term:`hidden nodes ` provide a substrate for +Typically :term:`hidden members ` provide a substrate for reporting purposes, because the replica set segregates these instances from the cluster. Since no secondary reads reach hidden members, they -receive no traffic beyond what replication requires. While hidden -nodes are not electable as primary, they are still able to *vote* in -elections for primary. If your operational parameters requires this -kind of reporting functionality, see ":ref:`Hidden Replica Set Nodes -`" and :data:`members[n].hidden` for more +receive no traffic beyond what replication requires. While hidden members +are not electable as primary, they are still able to *vote* in elections +for primary. If your operational parameters requires this kind of +reporting functionality, see :ref:`Hidden Replica Set Nodes +` and :data:`members[n].hidden` for more information regarding this functionality. Cold Standbys @@ -204,58 +208,56 @@ Cold Standbys For some sets, it may not be possible to initialize a new members in a reasonable amount of time. In these situations, it may be useful to -maintain a secondary with an up to date copy for the purpose of -replacing another node in the replica set. In most cases, these nodes -can be ordinary members of the replica set, but in large sets, with -varied hardware availability, or given some patterns of +maintain a secondary member with an up-to-date copy for the purpose of +replacing another member in the replica set. In most cases, these +members can be ordinary members of the replica set, but in large sets, +with varied hardware availability, or given some patterns of :ref:`geographical distribution `, -you may want to use a node with a different :term:`priority`, +you may want to use a member with a different :term:`priority`, :term:`hidden `, or voting status. Cold standbys may be valuable when your :term:`primary` and "hot standby" :term:`secondaries ` members have a different -hardware specification or connect via a different network than the -main set. In these cases, deploy nodes with :term:`priority` equal to -``0`` to ensure that they will never become primary. These nodes will -vote in elections for primary, but will never be eligible for election -to primary. Consider likely failover scenarios, such as inter-site -network partitions, and ensure there will be members eligible for -election as primary *and* a quorum of voting members in the main -facility. +hardware specification or connect via a different network than the main +set. In these cases, deploy members with :term:`priority` equal to ``0`` +to ensure that they will never become primary. These members will vote in +elections for primary but will never be eligible for election to +primary. Consider likely failover scenarios, such as inter-site network +partitions, and ensure there will be members eligible for election as +primary *and* a quorum of voting members in the main facility. .. note:: - If your set already has ``7`` nodes, set the - :data:`members[n].votes` value to ``0`` for these nodes, so that + If your set already has ``7`` members, set the + :data:`members[n].votes` value to ``0`` for these members, so that they won't vote in elections. -.. seealso:: ":ref:`Secondary Only - `," and ":ref:`Hidden Nodes - `. +.. seealso:: :ref:`Secondary Only `, + and :ref:`Hidden Nodes `. .. _replica-set-arbiter-nodes: Arbiter Nodes ------------- -Always deploy an :term:`arbiter` to ensure that a replica set will -have a sufficient number of members to elect a :term:`primary`. While -having replica sets with 2 nodes is not recommended for production -environments, in these circumstances, and *any replica set with an -even number of members*, deploy an arbiter. +Always deploy an :term:`arbiter` to ensure that a replica set will have +a sufficient number of members to elect a :term:`primary`. While having +replica sets with 2 members is not recommended for production +environments, in these circumstances, and *any replica set with an even +number of members*, deploy an arbiter. -To add an arbiter, while connected to the *current primary* node in -the :program:`mongo` shell, issue the following command: +To add an arbiter, while connected to the *current primary* in the +:program:`mongo` shell, issue the following command: .. code-block:: javascript rs.addArb("[hostname]:[port]") Because arbiters do not hold a copy of the data, they have minimal -resource requirements and do not require dedicated hardware. Do not -add an arbiter to a set if you have an odd number of voting nodes that -hold data, to prevent tied :term:`elections `. +resource requirements and do not require dedicated hardware. Do not add +an arbiter to a set if you have an odd number of voting members that hold +data, to prevent tied :term:`elections `. -.. seealso:: ":ref:`Arbiter Nodes `," - ":setting:`replSet`," ":option:`mongod --replSet`, and - ":func:`rs.addArb()`." +.. seealso:: :ref:`Arbiter Nodes `, + :setting:`replSet`, :option:`mongod --replSet`, and + :func:`rs.addArb()`. \ No newline at end of file diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index e2844715495..5c0d48f82aa 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -7,11 +7,10 @@ Replication Internals Synopsis -------- -This document provides a more in-depth explanation of the internals -and operation of replica set features. This material is not necessary -for normal operation or application development, but may be -useful for troubleshooting, helpful understanding MongoDB's behavior, -or interesting for learning about MongoDB's approach. +This document provides a more in-depth explanation of the internals and +operation of :term:`replica set` features. This material is not necessary for +normal operation or application development but may be useful for +troubleshooting and for further understanding MongoDB's behavior and approach. .. index:: replica set; oplog .. _replica-set-oplog: @@ -21,19 +20,17 @@ Oplog Replication itself works by way of a special :term:`capped collection` called the :term:`oplog`. This collection keeps a rolling record of -all operations applied to the primary node. Secondary nodes then +all operations applied to the :term:`primary`. Secondary members then replicate this log by applying the operations to themselves in an -asynchronous process. Under normal operation, secondary nodes will +asynchronous process. Under normal operation, :term:`secondary` members reflect writes within one second of the primary. However, various -exceptional situations may cause secondaries lag behind further. See +exceptional situations may cause secondaries to lag behind further. See :term:`replication lag` for details. -Also consider :ref:`oplog sizing ` for more -information about the oplog. +All members send heartbeats (pings) to all other members in the set and can +import operations to the local oplog from any other member in the set. -All members send heartbeats to all other members, and can import -operations to into its oplog from any other member in the -set. +For more information about the oplog, see :ref:`oplog sizing `. .. 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. @@ -47,65 +44,64 @@ MongoDB uses :term:`single-master replication` to ensure that the database remains consistent. However, clients may modify the :ref:`read preferences ` on a per-connection basis in order to distribute read operations to the -secondary members of a replica set. Read-heavy deployments may achieve -greater query volumes by distributing reads to secondary nodes. But +:term:`secondary` members of a :term:`replica set`. Read-heavy deployments may achieve +greater query volumes by distributing reads to secondary members. But keep in mind that replication is asynchronous; therefore, reads from secondaries may not always reflect the latest writes to the -primary. See the ":ref:`consistency `" -section for more about ":ref:`read preference -`" and ":ref:`write concern -`." +:term:`primary`. See the :ref:`consistency ` +section for more about :ref:`read preference +` and :ref:`write concern +`. .. note:: - Use :func:`db.getReplicationInfo()` from a secondary node - and the ":doc:`replication status ` - output to asses the current state of replication, and determine if + Use :func:`db.getReplicationInfo()` from a secondary member + and the :doc:`replication status ` + output to asses the current state of replication and determine if there is any unintended replication delay. -In the default configuration, all have nodes an equal chance of -becoming primary; however, it's possible to set "priorities" that +In the default configuration, all members have an equal chance of +becoming primary; however, it's possible to set :data:`priority ` values that weight the election. In some architectures, there may be operational reasons for increasing the likelihood of a specific replica set member -becoming primary. For instance, a node located in a remote data -center should become primary . See: ":ref:`node -priority `" for more background on this +becoming primary. For instance, a member located in a remote data +center should *not* become primary. See: :ref:`node +priority ` for more background on this concept. -Replica sets can also include nodes with four special -configurations which affect membership behavior in a replica -set. Consider the following node types: +Replica sets can also include members with the following four special +configurations that affect membership behavior: -- :ref:`Secondary-only ` members - have their "priority" set to 0 and thus not eligible for election as - primary nodes. +- :ref:`Secondary-only ` members have + their :data:`priority ` values set to ``0`` and thus + are not eligible for election as primaries. - :ref:`Hidden ` members do not appear in the - output of :func:`db.isMaster()`. This setting prevents clients - from discovering, and thus potentially queries, the node in question. + output of :func:`db.isMaster()`. This prevents clients + from discovering and potentially querying the member in question. - :ref:`Delayed ` members lag a fixed period - of time behind the the primary node. These nodes are typically used + of time behind the primary. These members are typically used for disaster recovery scenarios. For example, if an administrator mistakenly truncates a collection, and you discover the mistake within - the lag window, then you can manually fail over to the delayed node. + the lag window, then you can manually fail over to the delayed member. - :ref:`Arbiters ` exist solely to participate in elections. They do not replicate data from the primary. In almost every case, replica sets simplify the process of -administering database replication; however, replica sets still have a +administering database replication. However, replica sets still have a unique set of administrative requirements and concerns. Choosing the right :doc:`system architecture ` for your data set is crucial. Administrators of replica sets also have unique :ref:`monitoring -`, and :ref:`security ` +` and :ref:`security ` concerns. The :ref:`replica set functions ` in the :program:`mongo` shell, provide the tools necessary for replica set administration. In particular use the :func:`rs.conf()` to return a :term:`document` that holds the :doc:`replica set configuration -`, and :func:`rs.reconfig()` to +` and use :func:`rs.reconfig()` to modify the configuration of an existing replica set. .. index:: replica set; elections @@ -118,30 +114,30 @@ Elections When you initialize a :term:`replica set` for the first time, or when any failover occurs, an election takes place to decide which member should become :term:`primary`. A primary is the only member in the replica -set that can accept write operations including :func:`insert() +set that can accept write operations, including :func:`insert() `, :func:`update() `, and :func:`remove() `. Elections are the process replica set members use to -select the primary in a set. Elections follow after one of two events: -a primary that "steps down" or a :term:`secondary` that -loses contact with a :term:`primary` member. All members have one vote +select the primary in a set. Two types of events can trigger an election: +a primary steps down or a :term:`secondary` member +loses contact with a primary. All members have one vote in an election, and any :program:`mongod` can veto an election. A -single veto will invalidate the election. +single veto invalidates the election. An existing primary will step down in response to the -:dbcommand:`replSetStepDown` command, or if it sees that one of +:dbcommand:`replSetStepDown` command or if it sees that one of the current secondaries is eligible for election *and* has a higher priority. A secondary will call for an election if it cannot -establish a connection to a primary member. A primary will also step -down when they cannot contact a majority of the members of the replica -set. When the current primary member steps down, it closes all open client +establish a connection to a primary. A primary will also step +down when it cannot contact a majority of the members of the replica +set. When the current primary steps down, it closes all open client connections to prevent clients from unknowingly writing data to a non-primary member. In an election, every member, including :ref:`hidden ` members, :ref:`arbiters -`, and even recovering members get a single +`, and even recovering members, get a single vote. Members will give votes to every eligible member that calls an election. @@ -150,24 +146,24 @@ conditions: - If the member seeking an election is not a member of the voter's set. -- If the member seeking an election is not up to date with the most +- If the member seeking an election is not up-to_date with the most recent operation accessible in the replica set. - If the member seeking an election has a lower priority than another member in the set that is also eligible for election. -- If the current :term:`primary` member has more recent operations +- If the current primary member has more recent operations (i.e. a higher "optime") than the member seeking election, from the perspective of the voting member. - The current primary will also veto an election if it has the same or more recent operations (i.e. a "higher or equal optime") than the - node seeking election. + member seeking election. .. note:: - Any member of a replica set *can* veto an election, even if they - are :ref:`non-voting members `. + Any member of a replica set *can* veto an election, even if the + member is a :ref:`non-voting member `. The first member to receive votes from a majority of members in a set becomes the next primary until the next election. Be @@ -177,61 +173,58 @@ aware of the following conditions and possible situations: seconds. If a heartbeat does not return for more than 10 seconds, the other members mark the delinquent member as inaccessible. -- Replica set members only compare priorities with other members of +- Replica set members compare priorities only with other members of the set. The absolute value of priorities does not have any impact on the outcome of replica set elections. .. note:: - The only exception is that members with a priority of ``0`` - cannot become :term:`primary` and will not seek election. See + The only exception is that members with :data:`priority ` values of ``0`` + cannot become primary and will not seek election. See :ref:`replica-set-node-priority-configuration` for more information. -- Replica set members cannot become primary *unless* they have the - highest "optime" of any visible members in the set. +- A replica set member cannot become primary *unless* it has the + highest "optime" of any visible member in the set. - If the member of the set with the highest priority is within 10 - seconds of the latest oplog entry, then the set will *not* elect a - :term:`primary` until the member with the highest priority catches up + seconds of the latest :term:`oplog` entry, then the set will *not* elect a + primary until the member with the highest priority catches up to the latest operation. -.. seealso:: ":ref:`Non-voting members in a replica - set`", - ":ref:`replica-set-node-priority-configuration`", and - ":data:`replica configuration ` +.. seealso:: :ref:`Non-voting members in a replica + set`, + :ref:`replica-set-node-priority-configuration`, and + :data:`replica configuration ` Syncing ------- -Replica set members sync, or copy :term:`oplog` entries, from the -:term:`primary` or another :term:`secondary` member of the set in -order to remain up to date with the current state of the set. +In order to remain up-to-date with the current state of the :term:`replica set`, +set members sync, or copy, :term:`oplog` entries from other members. -When a new member joins a set, or an existing member restarts, the new -member waits to receive heartbeats from other members. Then, by -default, a new member will sync from the *the closest* member of the -set that is either: the primary or another secondary with more recent -oplog entries. This prevents two secondaries from syncing from each -other. +When a new member joins a set or when an existing member restarts, the +member waits to receive heartbeats from other members. By +default, the member syncs from the *the closest* member of the +set that is either the primary or another secondary with more recent +oplog entries. This prevents two secondaries from syncing from each other. In version 2.0, secondaries only change sync targets if the connection between secondaries drops or produces an error. For example: -#. If you have two secondary members in one data center, a primary in - a second facility, *and* you start all three instances at roughly +#. If you have two secondary members in one data center and a primary in + a second facility, and if you start all three instances at roughly the same time (i.e. with no existing data sets or oplog,) both secondaries will likely sync from the primary, as neither secondary has more recent oplog entries. - If you restart one of the secondaries, when it rejoins the set it - will likely begin syncing from the other secondary. + If you restart one of the secondaries, then when it rejoins the set it + will likely begin syncing from the other secondary, because of proximity. -#. If, you have a primary in one facility, and a secondary in an - alternate facility, and you add another secondary to the alternate - facility, the new secondary will likely sync from the older - secondary because this member is closer and has more recent oplog - entries. +#. If you have a primary in one facility and a secondary in an + alternate facility, and if you add another secondary to the alternate + facility, the new secondary will likely sync from the existing + secondary because it is closer than the primary. diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index b3c2308f797..8116eb01c98 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -18,7 +18,7 @@ configuration. Note that default values are not explicitly displayed. Configuration Variables ----------------------- -.. data:: rs.conf._id: +.. data:: rs.conf._id **Type**: string