diff --git a/source/administration/journaling.txt b/source/administration/journaling.txt index 0bc570296d2..af47364f078 100644 --- a/source/administration/journaling.txt +++ b/source/administration/journaling.txt @@ -4,24 +4,23 @@ Journaling .. default-domain:: mongodb -MongoDB uses *write ahead logging* or :term:`journaling ` to +MongoDB uses *write ahead logging* to an on-disk :term:`journal` to guarantee :doc:`write operation ` durability -by way of a an on disk journal. Before applying a change to the data -files, MongoDB writes this operation to the journal. Then, if MongoDB -terminates or encounters an error unexpectedly before it can write the -data to disk, MongoDB can re-apply the write operation and maintain a -consistent state. - -Journaling ensures that :program:`mongodb` is crash resilient. *Without* -a journal, if :program:`mongodb` exits unexpectedly, you must assume -your data is in an inconsistent state and must either run +and to provide crash resiliency. Before applying a change to the data +files, MongoDB writes the change operation to the journal. If MongoDB +should terminate or encounter an error before it can write the changes +from the journal to the data files, MongoDB can re-apply the write +operation and maintain a consistent state. + +*Without* a journal, if :program:`mongod` exits unexpectedly, you must assume +your data is in an inconsistent state, and you must run either :doc:`repair ` -or preferably :ref:`resync ` from a +or, preferably, :ref:`resync ` from a clean member of the replica set. -When journaling is enabled, if :program:`mongodb` stops unexpectedly, +With journaling enabled, if :program:`mongod` stops unexpectedly, the program can recover everything written to the journal, and the -data is in a consistent state. By default, the greatest extent of lost +data remains in a consistent state. By default, the greatest extent of lost writes, i.e., those not made to the journal, is no more than the last 100 milliseconds. diff --git a/source/administration/monitoring.txt b/source/administration/monitoring.txt index 2c8a8a1597b..a25d0d56306 100644 --- a/source/administration/monitoring.txt +++ b/source/administration/monitoring.txt @@ -483,8 +483,8 @@ however, as replication lag grows, two significant problems emerge: integrity of your data set. - Second, if the replication lag exceeds the length of the operation - log (:term:`oplog`) then the secondary will have to resync all data - from the :term:`primary` and rebuild all indexes. In normal + log (:term:`oplog`) then MongoDB will have to perform an initial sync on the secondary, copying all data + from the :term:`primary` and rebuilding all indexes. In normal circumstances this is uncommon given the typical size of the oplog, but it's an issue to be aware of. diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index b31f4576e1e..2d1592c677c 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -370,7 +370,7 @@ the following to prepare the new member's :term:`data directory `: 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 resynchronize, as described in + to perform an initial sync, which completely resynchronizes the data, as described in :ref:`replica-set-resync-stale-member`. Use :method:`db.printReplicationInfo()` to check the current state of @@ -575,13 +575,13 @@ Resyncing a Member of a Replica Set When a secondary's replication process falls behind so far that :term:`primary` overwrites oplog entries that the secondary has not yet replicated, that secondary cannot catch up and becomes "stale." -When that occurs, you must resync the member by removing its data and -replacing it with up-to-date data. +When that occurs, you must completely resynchronize the member by removing its data and +performing an initial sync. To do so, use one of the following approaches: - Restart the :program:`mongod` with an empty data directory and let - MongoDB's normal replication syncing feature restore the data. This + MongoDB's normal initial syncing feature restore the data. This is the more simple option, but may take longer to replace the data. See :ref:`replica-set-auto-resync-stale-member`. @@ -598,9 +598,9 @@ To do so, use one of the following approaches: Automatically Resync a Stale Member ``````````````````````````````````` -This procedure relies on MongoDB's regular process for syncing a new +This procedure relies on MongoDB's regular process for initially syncing a new member to restore the data on the stale member. For an overview of how -MongoDB syncs :term:`replica sets `, see the +MongoDB initially syncs :term:`replica sets `, see the :ref:`replica-set-syncing` section. To resync the stale member: @@ -624,7 +624,7 @@ To resync the stale member: mongod --dbpath /data/db/ --replSet rsProduction - At this point, the :program:`mongod` will resync. This process may + At this point, the :program:`mongod` will perform an initial sync. This process may take a long time, depending on the size of the database and speed of the network. Remember that this operation may have an impact on the working set and/or traffic to existing primary other members of diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 94d986e314c..7acf3dfeeb5 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -255,14 +255,20 @@ and a majority of servers in one data center and one server in another. Syncing ------- -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. +In order to remain up-to-date with the current state of the +:term:`replica set`, set members :term:`sync`, or copy, :term:`oplog` +entries from other members. Members sync data at two different points: -When a new member joins a set or 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. +- "Initial sync" occurs when MongoDB creates new databases on a new or + restored member, populating the member with the replica set's + data. When a new or restored member joins or rejoins a set, 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. + +- "Replication" occurs continually after initial sync and keeps the + member updated with changes to the replica set's data. In version 2.0, secondaries only change sync targets if the connection between secondaries drops or produces an error. @@ -282,5 +288,3 @@ For example: 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. - -.. seealso:: :ref:`replica-set-resync-stale-member` diff --git a/source/core/replication.txt b/source/core/replication.txt index cfa03552983..09db69081c5 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -245,9 +245,8 @@ that might create rollbacks. [replica set sync] replSet syncThread: 13410 replSet too much data to roll back In these situations you will need to manually intervene to either - save data manually, or resync from a "current" member of the set by - deleting the content of the existing:setting:`dbpath` directory to - resume normal operation. + save data manually or to perform an initial sync from a "current" member of the set by + deleting the content of the existing :setting:`dbpath` directory. For more information on failover, see: @@ -344,8 +343,8 @@ the first time, you can only change the size of the oplog by using the In most cases, the default oplog size is sufficient. For example, if an oplog that is 5% of free disk space fills up in 24 hours of operations, then -secondaries can stop copying entries from the oplog for 24 hours before -they require full resyncing. However, most replica sets have much +secondaries can stop copying entries from the oplog for up to 24 hours +without becoming stale. However, most replica sets have much lower operation volumes, and their oplogs can hold a much larger number of operations. diff --git a/source/reference/command/replSetSyncFrom.txt b/source/reference/command/replSetSyncFrom.txt index 66fa7542e9b..2fe21cf1d44 100644 --- a/source/reference/command/replSetSyncFrom.txt +++ b/source/reference/command/replSetSyncFrom.txt @@ -8,16 +8,18 @@ replSetSyncFrom .. versionadded:: 2.2 - :option host: Specifies the name and port number of the set member - that you want *this* member to sync from. Use + :option host: Specifies the name and port number of the replica set member + that this member replicates from. Use the ``[hostname]:[port]`` form. :dbcommand:`replSetSyncFrom` allows you to explicitly configure which host the current :program:`mongod` will poll :term:`oplog` entries from. This operation may be useful for testing different - patterns and in situations where a set member is not syncing from - the host you want. The member to sync from must be a valid - source for data in the set; a member of a replica set cannot sync from: + patterns and in situations where a set member is not replicating from + the host you want. The member to replicate from must be a valid + source for data in the set. + + A member cannot replicate from: - itself. - an arbiter, because arbiters do not hold data. @@ -26,9 +28,9 @@ replSetSyncFrom - a :program:`mongod` instance that is not a member of the same replica set. - If you attempt to sync from a member that is more than 10 seconds + If you attempt to replicate from a member that is more than 10 seconds behind the current member, :program:`mongod` will return and log a - warning, but *will* sync from such members. + warning, but it still *will* replicate from the member that is behind. The command has the following prototype form: @@ -52,6 +54,8 @@ replSetSyncFrom .. note:: + .. TODO this next para has a sentence that is missing a noun or verb or some such + :dbcommand:`replSetSyncFrom` provides a temporary override of default behavior. When you restart the :program:`mongod` instance, if the connection that the :program:`mongod` uses to diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index b855a6a6fce..eff9189d79a 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -643,9 +643,9 @@ Replication Options *Default:* false In the context of :term:`replica set` replication, set this option - to ``true`` if you have seeded this replica with a snapshot of the + to ``true`` if you have seeded this member with a snapshot of the :term:`dbpath` of another member of the set. Otherwise the - :program:`mongod` will attempt to perform a full sync. + :program:`mongod` will attempt to perform an initial sync, as though the member were a new member. .. warning:: diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 4f46f374aab..c69b727c1ce 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -591,18 +591,18 @@ Glossary eventual consistency A property of a distributed system allowing changes to the system to propagate gradually. In a database system, this means - that readable nodes are not required to reflect the latest + that readable members are not required to reflect the latest writes at all times. In MongoDB, reads to a primary have - :term:`strict consistency`; reads to secondary nodes have + :term:`strict consistency`; reads to secondaries have :term:`eventual consistency`. strict consistency - A property of a distributed system requiring that all nodes + A property of a distributed system requiring that all members always reflect the latest changes to the system. In a database system, this means that any system that can provide data must reflect the latest writes at all times. In MongoDB, reads to a primary have :term:`strict consistency`; reads to secondary - nodes have :term:`eventual consistency`. + members have :term:`eventual consistency`. write concern Specifies whether a write operation has succeeded. Write concern @@ -617,16 +617,16 @@ Glossary priority In the context of :term:`replica sets `, priority - is a configurable value that helps determine which nodes in + is a configurable value that helps determine which members in a replica set are most likely to become :term:`primary`. - .. seealso:: :ref:`Replica Set Node Priority + .. seealso:: :ref:`Replica Set Member Priority ` election In the context of :term:`replica sets `, an election is the process by which members of a replica set select - primary nodes on startup and in the event of failures. + primaries on startup and in the event of failures. .. seealso:: :ref:`Replica Set Elections ` and :term:`priority`. @@ -653,17 +653,17 @@ Glossary arbiter A member of a :term:`replica set` that exists solely to vote - in :term:`elections `. Arbiter nodes do not replicate data. + in :term:`elections `. Arbiters do not replicate data. - .. seealso:: :ref:`Delayed Nodes ` + .. seealso:: :ref:`Delayed Members ` read preference A setting on the MongoDB :doc:`drivers ` that determines how the clients direct read operations. Read preference affects all replica sets including - shards. By default, drivers direct all reads to :term:`primary` - nodes for :term:`strict consistency`. However, you may also - direct reads to secondary nodes for :term:`eventually consistent + shards. By default, drivers direct all reads to :term:`primaries ` + for :term:`strict consistency`. However, you may also + direct reads to secondaries for :term:`eventually consistent ` reads. .. seealso:: :ref:`Read Preference ` @@ -671,7 +671,7 @@ Glossary replication lag The length of time between the last operation in the primary's :term:`oplog` last operation applied to a particular - :term:`secondary` or :term:`slave` node. In general, you want + :term:`secondary` or :term:`slave`. In general, you want to keep replication lag as small as possible. .. seealso:: :ref:`Replication Lag ` @@ -689,14 +689,14 @@ Glossary level between the application layer and the database server. failover - The process that allows one of the :term:`secondary` nodes in a + The process that allows one of the :term:`secondary` members in a :term:`replica set` to become :term:`primary` in the event of a failure. .. seealso:: :ref:`Replica Set Failover `. data-center awareness - A property that allows clients to address nodes in a system to + A property that allows clients to address members in a system to based upon their location. :term:`Replica sets ` implement data-center @@ -714,8 +714,8 @@ Glossary recovering A :term:`replica set` member status indicating that a member - is synchronizing or re-synchronizing its data - from the primary node. Recovering nodes are unavailable for reads. + is not ready to begin normal activities of a secondary or primary. + Recovering members are unavailable for reads. control script A script used by a UNIX-like operating system to start, stop, @@ -911,3 +911,19 @@ Glossary dot notation .. include:: /includes/fact-dot-notation.rst + + sync + The :term:`replica set` operation that replicates data from the + :term:`primary` to the other members of the set that hold data. + Replica sets synchronize data at two different points: + + - "Initial sync" occurs when MongoDB creates new databases on a + new or restored :term:`replica set` member, populating the the + member with the replica set's data. + + - "Replication" occurs continually after initial sync and keeps + the member updated with changes to the replica set's data. + + initial sync + The :term:`replica set` operation that replicates data from an + existing replica set member to a new or restored replica set member. diff --git a/source/reference/local-database.txt b/source/reference/local-database.txt index eefade813b2..c11485ae4dc 100644 --- a/source/reference/local-database.txt +++ b/source/reference/local-database.txt @@ -50,7 +50,7 @@ Collections on Replica Set Members .. data:: local.replset.minvalid - This contains an object used internally by replica sets to track sync + This contains an object used internally by replica sets to track replication status. .. data:: local.slaves diff --git a/source/reference/method/rs.syncFrom.txt b/source/reference/method/rs.syncFrom.txt index da0618e49c0..3c5643d9f9d 100644 --- a/source/reference/method/rs.syncFrom.txt +++ b/source/reference/method/rs.syncFrom.txt @@ -11,6 +11,6 @@ rs.syncFrom() Provides a wrapper around the :dbcommand:`replSetSyncFrom`, which allows administrators to configure the member of a replica set that the current member will pull data from. Specify the name of the - member you want to sync from in the form of ``[hostname]:[port]``. + member you want to replicate from in the form of ``[hostname]:[port]``. See :dbcommand:`replSetSyncFrom` for more details. diff --git a/source/reference/mongod.txt b/source/reference/mongod.txt index 102437834e4..1a61044d904 100644 --- a/source/reference/mongod.txt +++ b/source/reference/mongod.txt @@ -487,9 +487,10 @@ Replication Options .. option:: --fastsync In the context of :term:`replica set` replication, set this option - if you have seeded this replica with a snapshot of the + if you have seeded this member with a snapshot of the :term:`dbpath` of another member of the set. Otherwise the - :program:`mongod` will attempt to perform a full sync. + :program:`mongod` will attempt to perform an initial sync, + as though the member were a new member. .. warning:: diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 3ec7b168d58..11c377418bc 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -109,8 +109,8 @@ Configuration Variables of the :data:`members[n].buildIndexes` field after adding the member to the set. - Furthermore, other secondaries cannot synchronize off of replica - set members where :data:`members[n].buildIndexes` is false. + Other secondaries cannot replicate from + a members where :data:`members[n].buildIndexes` is false. .. data:: members[n].hidden diff --git a/source/release-notes/replica-set-features.txt b/source/release-notes/replica-set-features.txt index 9641f425390..a3ea1469b92 100644 --- a/source/release-notes/replica-set-features.txt +++ b/source/release-notes/replica-set-features.txt @@ -28,7 +28,7 @@ Replica Set Features and Version Compatibility - 1.8.0 * - Replication from Nearest Server (by ping Time) - 2.0 - * - :dbcommand:`replSetSyncFrom` support for syncing from specific + * - :dbcommand:`replSetSyncFrom` support for replicating from specific members. - 2.2 diff --git a/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt b/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt index 3bd7ac86be4..0ace08dac11 100644 --- a/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt +++ b/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt @@ -142,8 +142,8 @@ Reconfigure by "Breaking the Mirror" This option selects a surviving :term:`replica set` member to be the new :term:`primary` and to "seed" a new replica set. In the following -procedure, the new primary is ``db0.example.net``. All other members will resync -from this member. +procedure, the new primary is ``db0.example.net``. MongoDB copies the +data from ``db0.example.net`` to all the other members. 1. Stop the surviving :program:`mongod` instances. To ensure a clean shutdown, use an existing :term:`control script` or an invocation that resembles the @@ -185,4 +185,5 @@ from this member. rs.add("db1.example.net:27017") - These members will resync and copy all data from ``db0.example.net``. + MongoDB peforms an initial sync on the added members by copying all + data from ``db0.example.net`` to the added members. diff --git a/source/tutorial/recover-data-following-unexpected-shutdown.txt b/source/tutorial/recover-data-following-unexpected-shutdown.txt index 634fb2d6fa7..55f524a27fa 100644 --- a/source/tutorial/recover-data-following-unexpected-shutdown.txt +++ b/source/tutorial/recover-data-following-unexpected-shutdown.txt @@ -20,7 +20,7 @@ If you are *not* running as part of a :term:`replica set` **and** do data that may be in an inconsistent state. If you are running as part of a replica set, you should *always* restore from a backup or restart the :program:`mongod` instance with an empty :setting:`dbpath` and -allow MongoDB to resync the data. +allow MongoDB to perform an initial sync to restore the data. .. seealso:: The :doc:`/administration` documents, including :ref:`Replica Set Syncing `, and the @@ -49,7 +49,7 @@ When you are aware of a :program:`mongod` instance running without journaling that stops unexpectedly **and** you're not running with replication, you should always run the repair operation before starting MongoDB again. If you're using replication, then restore from -a backup and allow replication to :ref:`synchronize ` your data. +a backup and allow replication to perform an initial :ref:`sync ` to restore data. If the ``mongod.lock`` file in the data directory specified by :setting:`dbpath`, ``/data/db`` by default, is *not* a zero-byte file, @@ -80,7 +80,7 @@ Overview Do not use this procedure to recover a member of a :term:`replica set`. Instead you should either restore from a :doc:`backup ` - or resync from an intact member of the set, as described in :ref:`replica-set-resync-stale-member`. + or perform an initial sync using data from an intact member of the set, as described in :ref:`replica-set-resync-stale-member`. There are two processes to repair data files that result from an unexpected shutdown: @@ -184,5 +184,5 @@ situations. If you are not running with journaling, and your database shuts down unexpectedly for *any* reason, you should always proceed *as if* your database is in an inconsistent and likely corrupt state. If at all possible restore -from :doc:`backup ` or if running as a :term:`replica -set` resync from an intact member of the set, as described in :ref:`replica-set-resync-stale-member`. +from :doc:`backup ` or, if running as a :term:`replica +set`, restore by performing an initial sync using data from an intact member of the set, as described in :ref:`replica-set-resync-stale-member`.