From 438936bd606d8c32b755f61e58a4cd0cd985621c Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 22:33:31 -0400 Subject: [PATCH 01/15] added note regarding arbiter placement --- source/core/replication.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/core/replication.txt b/source/core/replication.txt index 73fd142ae1f..7a4e2dd5c9b 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -144,6 +144,10 @@ participate in :term:`elections `. arbiter on a system with another work load such as an application server or monitoring node. +.. note:: + It is not recommended that arbiter processes be run on a server that is + an active member (primary of secondary) of it's replica set. + .. index:: replica set members; non-voting .. _replica-set-non-voting-members: From dce2a6354cd6edc8964e9260df99bdd16f23779d Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 22:36:24 -0400 Subject: [PATCH 02/15] removing unnecessary comma --- source/administration/replication-architectures.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index 93e0259fbc6..e86c1b2420c 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -53,7 +53,7 @@ architectural conditions are true: - The set has an odd number of voting members. - Deploy a single :ref:`arbiter `, if you have + Deploy a single :ref:`arbiter ` if you have an even number of voting replica set members. - The set only has 7 voting members at any time. From bd4539d7e4e071e8b10d6ed4b7cc7c0b79eb3916 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 22:39:08 -0400 Subject: [PATCH 03/15] grammatical clarification --- source/administration/replication-architectures.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index e86c1b2420c..d3a67984599 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -56,7 +56,7 @@ architectural conditions are true: Deploy a single :ref:`arbiter ` if you have an even number of voting replica set members. -- The set only has 7 voting members at any time. +- The set only has at most 7 voting members at any time. - Every member with a :data:`priority ` greater than ``0`` can function as ``primary`` in a :term:`failover` From b4a783148a82de41399a1b76e1b48d79ca19843b Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 22:39:49 -0400 Subject: [PATCH 04/15] grammatical clarification --- source/administration/replication-architectures.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index d3a67984599..9990adfd9e9 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -63,7 +63,7 @@ architectural conditions are true: situation. If a member does not have this capability (i.e. resource constraints,) set its ``priority`` value to ``0``. -- A majority of the set's members exist in the main data center. +- The majority of the set's members exist in the main data center. .. seealso:: ":doc:`/tutorial/expand-replica-set`." From 245e8c9af5ef7050d39830826579684f6d8c7098 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 22:48:52 -0400 Subject: [PATCH 05/15] grammatical clarifications in Geo-Dist ReplSets --- source/administration/replication-architectures.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index 9990adfd9e9..8d8c02cee2a 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -90,16 +90,16 @@ In many circumstances, these deployments consist of the following: become primary (i.e. with a :data:`members[n].priority` value of ``0``.) -If any of the members fail, the replica set will still be able to -elect a primary node. If the connection between the data center fails, -the member or members in the second data center cannot become primary +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 primary data center fails, recovering from the database instance in the secondary facility requires manual intervention, but with proper :term:`write concern` there will be no data loss and -downtime is typically be minimal. +downtime will typically 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 From 74fb25069c676bcb32f406beb296449b26afd727 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Fri, 1 Jun 2012 23:34:05 -0400 Subject: [PATCH 06/15] fixes to the dev replset tutorial --- source/tutorial/deploy-replica-set.txt | 43 +++++++++++++++++--------- 1 file changed, 28 insertions(+), 15 deletions(-) diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index af96fe274cc..8640bdcb42b 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -17,22 +17,31 @@ Overview For most deployments, a simple 3 node replica set provides a sufficient redundancy to survive most network partitions and other -system failures. A replica set of this size provides sufficient -capacity to host many distributed read operations. While MongoDB's -replica set functionality provides a great deal of flexibility and -specific definable node behaviors or types, it's best to avoid this +system failures. A replica set of this also size provides sufficient +capacity to host many distributed read operations. + +.. Whoa, Whoa, Whoa... Is 10gen really recommending against redundancy? +.. As a SysAd, I personally disagree with this notion; what I typically +.. recommend is absolutely to implement a basic ReplSet in Prod, but not +.. get into Sharding unless you find that it's really necessary. + +While MongoDB's replica set functionality provides a great deal of flexibility +and specific definable node behaviors or types, it's best to avoid this additional complexity until your application requires the functionality. + + Requirements ------------ Three distinct systems, so that each system can run its own instance -of :program:`mongod`. For test systems you can run all three instances -of the :program:`mongod` process on a local system. e.g. a laptop) or -within a virtual instance. For production environments, you should -endeavor to maintain as much separation between the nodes: Deploy -replica set members on distinct hardware, and on systems that draw -power from different circuits, to the greatest extent possible. +of :program:`mongod`. For development systems you may run all three +instances of the :program:`mongod` process on a local system. (e.g. a +laptop) or within a virtual instance. For production environments, you +should endeavor to maintain as much separation between the nodes. For +instance: Deploy replica set members on distinct hardware, and on +systems that draw power from different circuits, to the greatest extent +possible. Procedure --------- @@ -75,9 +84,10 @@ following options for more information: :option:`--port `, option. You will also need to specify the :option:`--bind_ip ` option. -Log in with the :program:`mongo` shell to the first host. If you're -accessing this command remotely, modify the hostname. using the -following command: :: +Connect to the mongod instance with the :program:`mongo` shell to the +first host. If you're accessing this command remotely, replace +"localhost" with the approriate hostname. Open a new terminal session +and enter the following: :: mongo localhost:27017 @@ -104,8 +114,11 @@ replica set. rs.add("localhost:27019") Congratulations, after these commands return you will have a fully -functional replica set. You may have to wait several moments for the -new replica set to successfully elect a :term:`primary` node. +functional replica set. Within a couple moments the new replica set +should successfully elect a :term:`primary` node. + +At any time, you may check the status of your replica set with the +:func:`rs.status()` command. See the documentation of the following shell functions for more information: :func:`rs.initiate()`, :func:`rs.conf()`, From 185d3ae43567691b3be6b694db45156640f701dd Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 14:27:03 -0400 Subject: [PATCH 07/15] removed note regarding replset seed list, replacing with a TODO until I can test and fill out the docs --- source/tutorial/deploy-replica-set.txt | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index 8640bdcb42b..5357fc4186f 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -138,8 +138,8 @@ Production replica sets are very similar to the development or testing deployment described above, with the following differences: - Each member of the replica set will reside on it's own machine, and - the MongoDB processes will all bind to port ``27017``, or the - standard MongoDB port. + the MongoDB processes will all bind to port ``27017`` (the + standard MongoDB port.) - All runtime configuration will be specified in :doc:`configuration files ` rather than as @@ -176,17 +176,10 @@ current node. The DNS or host names need to point and resolve to this IP address. Configure network rules or a virtual private network (i.e. "VPN") to permit this access. -.. note:: - - The portion of the :setting:`replSet` following the ``/`` - provides a "seed list" of hosts that are known to be members of the - same replica set, which is used for fetching changed configurations - following restarts. It is acceptable to omit this section entirely, - and have the :setting:`replSet` option resemble: - - .. code-block:: cfg - - replSet = rs0 +.. TODO: file-based replset 'seed list' +.. The note that was here appeared to reference an example that has +.. changed. Currently there is very little info on seed lists +.. www.mongodb.org/display/DOCS/File+Based+Configuration Store this file on each system, located at ``/etc/mongodb.conf`` on the file system. See the documentation of the configuration options From 4dd3f4b678f77932f6158f5c04f6622ad1e0ab17 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 14:32:01 -0400 Subject: [PATCH 08/15] more positive phrasing regarding the replset primary election --- source/tutorial/deploy-replica-set.txt | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index 5357fc4186f..8691f52f939 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -181,14 +181,16 @@ IP address. Configure network rules or a virtual private network .. changed. Currently there is very little info on seed lists .. www.mongodb.org/display/DOCS/File+Based+Configuration -Store this file on each system, located at ``/etc/mongodb.conf`` on -the file system. See the documentation of the configuration options +See the documentation of the configuration options used above: :setting:`dbpath`, :setting:`port`, :setting:`replSet`, :setting:`bind_ip`, and :setting:`fork`. Also consider any additional :doc:`configuration options ` that your deployment may require. +Store this file on each system, located at ``/etc/mongodb.conf`` on +the file system. + On each system issue the following command to start the :program:`mongod` process: @@ -230,8 +232,8 @@ replica set. rs.add("mongodb2.example.net") Congratulations, after these commands return you will have a fully -functional replica set. You may have to wait several moments for the -new replica set to successfully elect a :term:`primary` node. +functional replica set. Within a couple moments the new replica set +should successfully elect a :term:`primary` node. .. seealso:: The documentation of the following shell functions for more information: From 9b67f6bb71d117a507533e86dc4231e5c750d652 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:15:41 -0400 Subject: [PATCH 09/15] mostly grammatical & formatting changes --- source/administration/replication-architectures.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/administration/replication-architectures.txt b/source/administration/replication-architectures.txt index 8d8c02cee2a..c4e2c8907ed 100644 --- a/source/administration/replication-architectures.txt +++ b/source/administration/replication-architectures.txt @@ -115,8 +115,8 @@ 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. Typically these members provide backups, support -reporting, or act as cold standbys in the clusters. There are three +become primary. Typical use-cases for these members include providing +backups, support reporting, or acting as cold standbys. There are three settings relevant for these kinds of nodes: - **Priority**: These members have :data:`members[n].priority` @@ -140,7 +140,7 @@ settings relevant for these kinds of nodes: .. note:: - *All* members of a replica set vote in elections *except* for + 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. @@ -155,7 +155,7 @@ 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. -If this node have journaling enabled, you can safely use standard +If this node has 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 From 130d37275ad04ef302852b9e8ebb501768838ee6 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:20:33 -0400 Subject: [PATCH 10/15] added seealso commands and improved order of tutorials in top section --- source/administration/replica-sets.txt | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b7a5c11e161..a18b15f2213 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -13,6 +13,7 @@ addition to general troubleshooting suggestions. .. seealso:: + - :func:`rs.status()` and :func:`db.isMaster()` - :ref:`Replica Set Reconfiguration Process ` - :func:`rs.conf()` and :func:`rs.reconfig()` - :doc:`/reference/replica-configuration` @@ -20,10 +21,11 @@ addition to general troubleshooting suggestions. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. - - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` - - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - :doc:`/tutorial/deploy-replica-set` - :doc:`/tutorial/expand-replica-set` + - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + - :doc:`/tutorial/deploy-geographically-distributed-replica-set` + Procedures ---------- From 6b7a28626dd8d179baa635b9550f592b1e29fd79 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:25:45 -0400 Subject: [PATCH 11/15] completed 'Adding Members' section. Minor fixes --- source/administration/replica-sets.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index a18b15f2213..66b8433ee20 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -46,7 +46,8 @@ From to time, you may need to add an additional member to an existing - copy the 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. + replica set after a short interval. By copying the data over + manually, replication is given a head-start. If the difference in the amount of time between the most recent operation and the most recent operation to the database exceeds the @@ -83,7 +84,7 @@ 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:27018``. See ":data:`host `," +``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 :func:`rs.add()`, you must From b958b093f62dac847c17f873b344de0e0c8c8f54 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:30:51 -0400 Subject: [PATCH 12/15] completed Removing and Replacing sections. Minor changes. --- source/administration/replica-sets.txt | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 66b8433ee20..148a7807b19 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -98,8 +98,8 @@ this case. Removing Members ~~~~~~~~~~~~~~~~ -Administrators can remove any member of a replica set at any time, for -a number of operational reasons. Use the :func:`rs.remove()` function +A member of a replica set may be removed at any time, for any number +of operational reasons. 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 @@ -127,9 +127,10 @@ directly. Replacing a Member ~~~~~~~~~~~~~~~~~~ -There are two methods for replacing a member of a replica set. First, -you may remove and then re-add a member using the following procedure -in the :program:`mongo` shell: +There are two methods for replacing a member of a replica set. + +First, you may remove and then re-add a member using the following +procedure in the :program:`mongo` shell: .. code-block:: javascript From 1611be4f07801b24705d0935976652dab6329fdc Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:39:10 -0400 Subject: [PATCH 13/15] completed Node Configuration with minor changes (typo) --- source/administration/replica-sets.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 148a7807b19..dc5f7311a42 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -312,7 +312,7 @@ primary. Member ``3`` has a priority of ``2`` and will become primary, if eligible, under most circumstances. Member ``2`` has a priority of ``1``, and will become primary if no node with a higher priority is eligible to be primary. Since all additional nodes in the set will -also have a prio1rity of ``1`` by default, member ``2`` and all +also have a priority of ``1`` by default, member ``2`` and all additional nodes will be equally likely to become primary if higher priority nodes are not accessible. Finally, member ``1`` has a priority of ``0.5``, which makes it less likely to become primary than From 1aecde0d15e360684766e58905dee43e2c68e0c0 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 16:53:58 -0400 Subject: [PATCH 14/15] completed 'Failover and Recovery'; small changes; added a TODO --- source/administration/replica-sets.txt | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index dc5f7311a42..31f03db628d 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -570,15 +570,15 @@ Possible causes of replication lag include: Failover and Recovery ~~~~~~~~~~~~~~~~~~~~~ -In most cases, failover occurs with out administrator intervention -seconds after the :term:`primary` steps down or becomes inaccessible -and ineligible to act as primary. If your MongoDB deployment does not -failover according to expectations, consider the following operational -errors: +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 +does not failover according to expectations, consider the following +operational errors: - No remaining member is able to form a majority. This can happen as a - result of network portions that render some members - inaccessible. Architect your deployment to ensure that a majority of + result of network partitions that render some members + inaccessible. Design your deployment to ensure that a majority of set members can elect a primary in the same facility as core application systems. @@ -599,6 +599,9 @@ 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`. +.. a *what*? TODO: Clarify what is meant by "program writes rolled +.. back data to a BSON" + You can prevent rollbacks prevented by ensuring safe writes by using the appropriate :term:`write concern`. From 172683a13a77ce08e93ff4164e9c617a6fb68783 Mon Sep 17 00:00:00 2001 From: H Waldo G Date: Sun, 3 Jun 2012 21:28:08 -0400 Subject: [PATCH 15/15] added comments regarding premature optimization and cleaned up examples in Requirements --- source/tutorial/deploy-replica-set.txt | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index 8691f52f939..e36d89a14fa 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -20,15 +20,13 @@ sufficient redundancy to survive most network partitions and other system failures. A replica set of this also size provides sufficient capacity to host many distributed read operations. -.. Whoa, Whoa, Whoa... Is 10gen really recommending against redundancy? -.. As a SysAd, I personally disagree with this notion; what I typically -.. recommend is absolutely to implement a basic ReplSet in Prod, but not -.. get into Sharding unless you find that it's really necessary. - While MongoDB's replica set functionality provides a great deal of flexibility and specific definable node behaviors or types, it's best to avoid this additional complexity until your application requires the functionality. - +Until your circumstances require it, It is strongly recommended that +you avoid using the additional configuration options (delayed nodes, +hidden nodes, voting options, etc) unless your circumstances warrant +the additional complexity. Avoid premature optimization. Requirements @@ -39,9 +37,10 @@ of :program:`mongod`. For development systems you may run all three instances of the :program:`mongod` process on a local system. (e.g. a laptop) or within a virtual instance. For production environments, you should endeavor to maintain as much separation between the nodes. For -instance: Deploy replica set members on distinct hardware, and on -systems that draw power from different circuits, to the greatest extent -possible. +example, when using VMs in Production, each node should live on +separate host servers, served by redundant power circuits, and with +redundant network paths. + Procedure --------- @@ -85,7 +84,7 @@ following options for more information: :option:`--port `, ` option. Connect to the mongod instance with the :program:`mongo` shell to the -first host. If you're accessing this command remotely, replace +first host. If you're running this command remotely, replace "localhost" with the approriate hostname. Open a new terminal session and enter the following: ::