diff --git a/source/administration/replica-sets.txt b/source/administration/replica-sets.txt index 903633ec583..8db70382a2d 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -21,10 +21,13 @@ suggestions for administers of replica sets. The following tutorials provide task-oriented instructions for specific administrative tasks related to replica set operation. - - :doc:`/tutorial/deploy-replica-set` - - :doc:`/tutorial/expand-replica-set` + - :doc:`/tutorial/change-hostnames-in-a-replica-set` + - :doc:`/tutorial/change-oplog-size` - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + - :doc:`/tutorial/convert-secondary-into-arbiter` - :doc:`/tutorial/deploy-geographically-distributed-replica-set` + - :doc:`/tutorial/deploy-replica-set` + - :doc:`/tutorial/expand-replica-set` .. _replica-set-node-configurations: .. _replica-set-member-configurations: @@ -57,8 +60,8 @@ configurations. .. _replica-set-secondary-only-members: .. _replica-set-secondary-only-configuration: -Secondary-Only -~~~~~~~~~~~~~~ +Secondary-Only Members +~~~~~~~~~~~~~~~~~~~~~~ The secondary-only configuration prevents a :term:`secondary` member in a :term:`replica set` from ever becoming a :term:`primary` in a @@ -119,8 +122,8 @@ This sets the following: .. _replica-set-hidden-members: .. _replica-set-hidden-configuration: -Hidden -~~~~~~ +Hidden Members +~~~~~~~~~~~~~~ Hidden members are part of a replica set but cannot become primary and are invisible to client applications. *However,* @@ -164,8 +167,8 @@ other members in the set will not advertise the hidden member in the .. _replica-set-delayed-members: .. _replica-set-delayed-configuration: -Delayed -~~~~~~~ +Delayed Members +~~~~~~~~~~~~~~~ Delayed members copy and apply operations from the primary's :term:`oplog` with a specified delay. If a member has a delay of one hour, then @@ -220,12 +223,10 @@ queries in normal operations. ` window, the delayed member cannot successfully replicate operations. -.. see:: For more information about delayed members, see the - section on :ref:`Delayed Replication `. - Additionally consider the following resources: - :data:`members[n].slaveDelay`, :ref:`Replica Set Reconfiguration - `, :ref:`Oplog Sizing - `, and :doc:`/tutorial/change-oplog-size`. +.. seealso:: :data:`members[n].slaveDelay`, :ref:`Replica Set Reconfiguration + `, :ref:`replica-set-oplog-sizing`, + :ref:`replica-set-procedure-change-oplog-size` in this document, + and the :doc:`/tutorial/change-oplog-size` tutorial. .. index:: replica set members; arbiters .. _replica-set-arbiters: @@ -289,8 +290,8 @@ hostname and the port. .. _replica-set-non-voting-members: .. _replica-set-non-voting-configuration: -Non-Voting -~~~~~~~~~~ +Non-Voting Members +~~~~~~~~~~~~~~~~~~ You may choose to change the number of votes that each member has in :ref:`elections ` for :term:`primary`. In general, all @@ -492,30 +493,11 @@ of the member with the highest :data:`members[n].priority` setting. 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 -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: - -#. Restart the current :term:`primary` instance in the :term:`replica set` in - "standalone" mode, running on a different port. - -#. Save the last entry from the old (current) oplog and create a - backup of the oplog. - -#. Drop the existing oplog and create a new oplog of a different size. - -#. Insert the previously saved last entry from the old oplog into the - new oplog. - -#. Restart the server as a member of the replica set on its usual - port. +The following is an overview of the procedure for changing the size of the oplog: -#. Apply this procedure to any other member of the replica set that - *could become* primary. +.. include:: /includes/procedure-change-oplog-size.rst -.. seealso:: The :doc:`/tutorial/change-oplog-size` tutorial. +For a detailed procedure, see :doc:`/tutorial/change-oplog-size`. .. _replica-set-security: @@ -657,10 +639,11 @@ Possible causes of replication lag include: For more information see: - - the :ref:`Replication Write Concern ` section, - - the :ref:`replica-set-oplog` documentation, - - the :ref:`Oplog Sizing ` section, and - - the :doc:`/tutorial/change-oplog-size` tutorial. + - :ref:`replica-set-write-concern`. + - The :ref:`replica-set-oplog-sizing` topic in the :doc:`/core/replication` document. + - The :ref:`replica-set-oplog` topic in the :doc:`/core/replication-internals` document. + - The :ref:`replica-set-procedure-change-oplog-size` topic this document. + - The :doc:`/tutorial/change-oplog-size` tutorial. .. index:: pair: replica set; failover .. _replica-set-failover-administration: diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index b73c6802a0c..dcfe2beced4 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -18,7 +18,7 @@ troubleshooting and for further understanding MongoDB's behavior and approach. Oplog ----- -For an explanation of the oplog, see the :ref:`oplog ` +For an explanation of the oplog, see the :ref:`replica-set-oplog-sizing` topic in the :doc:`/core/replication` document. Under various exceptional diff --git a/source/core/replication.txt b/source/core/replication.txt index 296a2105eb5..92b4ba5bae0 100644 --- a/source/core/replication.txt +++ b/source/core/replication.txt @@ -279,7 +279,7 @@ on the :term:`primary` and then records the operations on the primary's oplog. The :term:`secondary` members then replicate this log and apply the operations to themselves in an asynchronous process. All replica set members contain a copy of the oplog, allowing them to maintain the -current state of the database. +current state of the database. The oplog is an :term:`idempotent` log. By default, the size of the oplog is as follows: @@ -297,16 +297,14 @@ By default, the size of the oplog is as follows: Before oplog creation, you can specify the size of your oplog with the :setting:`oplogSize` option. Once the oplog is created, you can only -change the size of the oplog by using the :ref:`oplog resizing procedure -`. - -.. QUESTION: SK, Can the next graph be rewritten? It's unclear to me. BG - -For example, if an oplog fits 24 hours of operations, then members can -stop copying entries from the oplog for 24 hours before they require -full resyncing *and* the disk will be full in 19 days. If this were -the case, you would have a very high-volume member. In many -circumstances, the default oplog can hold days of operations. +change the size of the oplog by using the :doc:`/tutorial/change-oplog-size` tutorial. + +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. This example describes a +very high-volume member. In many circumstances, the default oplog can +hold days of operations. The following factors affect how MongoDB uses space in the oplog: diff --git a/source/includes/procedure-change-oplog-size.rst b/source/includes/procedure-change-oplog-size.rst new file mode 100644 index 00000000000..529cc54ea2f --- /dev/null +++ b/source/includes/procedure-change-oplog-size.rst @@ -0,0 +1,20 @@ +1. Shut down the current :term:`primary` instance in the + :term:`replica set` and then restart it on a different port + and in "standalone" mode. + +#. Create a backup of the old (current) oplog. This is optional. + +#. Save the last entry from the old oplog. + +#. Drop the old oplog. + +#. Create a new oplog of a different size. + +#. Insert the previously saved last entry from the old oplog into the + new oplog. + +#. Restart the server as a member of the replica set on its usual + port. + +#. Apply this procedure to any other member of the replica set that + *could become* primary. \ No newline at end of file diff --git a/source/tutorial/change-oplog-size.txt b/source/tutorial/change-oplog-size.txt index f04ec3be624..303194d516a 100644 --- a/source/tutorial/change-oplog-size.txt +++ b/source/tutorial/change-oplog-size.txt @@ -4,211 +4,150 @@ Change the Size of the Oplog .. default-domain:: mongodb -The :term:`oplog`, which supports :term:`replication`, by creating an -:term:`idempotent` operation log that :term:`secondary` members can -use to reproduce all write operations is a :term:`capped -collection`. While the default sizing for the oplog is big enough to -support most usage patterns there are cases that require a differently -sized oplog. - -This guide describes the process for changing the size if the default -size is too big or too small for the needs of your deployment. - -Background ----------- - -Most :term:`replica set` deployments will never need to modify the -oplog size. In most cases the :ref:`default oplog size -` is an acceptable size. If an oplog of this -size fills up in an hour, for instance, the disk will be full in less -then a day (about 20 hours); if the oplog fills up in a day, the disk -will be full in less than a month (about 20 days.) - -Some usage patterns, however, indicate a different usage pattern. For -instance, large numbers of multi-updates, a significant portion of -delete operations, and in place updates can generate large numbers in -short periods of time. - -Because the :term:`oplog` is a :term:`capped collection` once you have -created an oplog, you cannot modify its size except by using the -procedure outlined in this document. - -.. seealso:: ":ref:`Introduction to Oplog Sizing - `." +The :term:`oplog` exists internally as a :term:`capped collection`, so +you cannot modify its size in the course of normal operations. In most +cases the :ref:`default oplog size ` is an +acceptable size; however, in some situations you may need a larger or +smaller oplog. For example, you might need to change the oplog size +if your applications perform large numbers of multi-updates or +deletes in short periods of time. + +This tutorial describes how to resize the oplog. For a detailed +explanation of oplog sizing, see the :ref:`replica-set-oplog-sizing` +topic in the :doc:`/core/replication` document. For details on the how +oplog size affects :term:`delayed members ` and affects +:term:`replication lag`, see the :ref:`replica-set-delayed-members` +topic and the :ref:`replica-set-replication-lag` topic in +:doc:`/administration/replica-sets`. Overview -------- -The procedure for changing the size of the oplog is as follows: - -1. Restart the current :term:`primary` instance in the 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. - -3. Drop the current 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. - -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`. +The following is an overview of the procedure for changing the size of +the oplog: +.. include:: /includes/procedure-change-oplog-size.rst Procedure --------- -For the purpose of example, this document describes the process of -re-sizing the oplog on a member of the :setting:`rs0 ` -running on :setting:`port` ``27017`` with a :setting:`data directory -` of ``/srv/mongodb``. - -Quarantine the Instance -~~~~~~~~~~~~~~~~~~~~~~~ - -Issue the following command from your system shell to shutdown the -node: - -.. code-block:: sh - - mongod --dbpath /srv/mongodb --shutdown - -If this node is the primary this will trigger a failover situation and -another node in the replica set will become primary. - -Then restart the instance running on a different port in standalone -(i.e. without :setting:`replSet` or :option:`--replSet `,) -using the following command and the system shell: - -.. code-block:: sh - - mongod --port 37017 --dbpath /srv/mongodb - -Before continuing, you may want to backup the existing oplog. This -step is entirely optional. +The examples in this procedure use the following configuration: -.. code-block:: sh +- The active :term:`replica set` is ``rs0``. - mongodump --db local --collection 'oplog.rs' --port 37017 +- The replica set is running on port is ``27017``. -Then, connect to the instance using the :program:`mongo` shell, with -the following command to begin the procedure: +- The replica set is running with a :setting:`data directory ` + of ``/srv/mongodb``. -.. code-block:: sh +1. Shut down the current :term:`primary` instance in the replica set and + then restart it in "standalone" mode running on a different port. + Note that shutting down the primary will trigger a failover situation + and another member in the replica set will become primary. - mongo --port 37017 + To shut down the current primary instance, use a command that + resembles the following: -Save the Last Oplog Entry -~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: sh -In the :program:`mongo` shell, you want to use the ``local`` database, -to interact with the oplog. Issue the following command: + mongod --dbpath /srv/mongodb --shutdown -.. code-block:: javascript + To restart the instance on a different port and in "standalone" mode + (i.e. without :setting:`replSet` or :option:`--replSet `), use a command that resembles the following: - use local + .. code-block:: sh -Then, use the following :method:`db.collection.save()` operation to save the last -entry in the oplog to a temporary collection: + mongod --port 37017 --dbpath /srv/mongodb -.. code-block:: javascript +#. Backup the existing oplog on the standalone instance. Use the + following sequence of commands: - db.temp.save( db.oplog.rs.find().sort( {$natural : -1} ).limit(1).next() ) + .. code-block:: sh -You can see this oplog entry in the ``temp`` collection by issuing -the following command: + mongodump --db local --collection 'oplog.rs' --port 37017 -.. code-block:: javascript + Connect to the instance using the :program:`mongo` shell: - db.temp.find() + .. code-block:: sh -Resize the Oplog -~~~~~~~~~~~~~~~~ + mongo --port 37017 -The following operations assume that you're using the ``local`` -database. Entering ``db`` into the shell will return the name of the -current database. If this does *not* return ``local``, the ``use -local`` command will switch the shell to the ``local`` database. +#. Save the last entry from the old (current) oplog. -Drop the Existing Oplog -``````````````````````` + a. In the :program:`mongo` shell, enter the following command to use the + ``local`` database to interact with the oplog: -Begin by dropping the existing ``oplog.rs`` collection in the -``local`` database. Use the following command: + .. code-block:: javascript -.. code-block:: javascript + use local - db.oplog.rs.drop() + #. Use the :method:`db.collection.save()` operation to save the last + entry in the oplog to a temporary collection: -This will return ``true`` on the shell. + .. code-block:: javascript -Create a New Oplog -`````````````````` + db.temp.save( db.oplog.rs.find().sort( {$natural : -1} ).limit(1).next() ) -Use the :dbcommand:`create` command to create the new oplog. + You can see this oplog entry in the ``temp`` collection by issuing + the following command: -.. code-block:: javascript + .. code-block:: javascript - db.runCommand( { create : "oplog.rs", capped : true, size : 2147483648 } ) + db.temp.find() -Specify the ``size`` argument in bytes. A value of ``2147483648`` -will create a new oplog that's 2 gigabytes. This command will return -the following status upon success: +#. Drop the old ``oplog.rs`` collection in the ``local`` database. Use + the following command: -.. code-block:: javascript + .. code-block:: javascript - { "ok" : 1 } + db.oplog.rs.drop() -Insert Saved Oplog Entry in New Oplog -````````````````````````````````````` + This will return ``true`` on the shell. -Issue the following command to save the last entry from the oplog into -the new oplog. +#. Use the :dbcommand:`create` command to create a new oplog of a + different size. Specify the ``size`` argument in bytes. A value of + ``2147483648`` will create a new oplog that's 2 gigabytes: -.. code-block:: javascript + .. code-block:: javascript - db.oplog.rs.save( db.temp.findOne() ) + db.runCommand( { create : "oplog.rs", capped : true, size : 2147483648 } ) -You can confirm that this entry is in the new oplog with the following -operation: + Upon success, this command returns the following status: -.. code-block:: javascript + .. code-block:: javascript - db.oplog.rs.find() + { "ok" : 1 } -Congratulations! You have resized the oplog of this instance. +#. Insert the previously saved last entry from the old oplog into the + new oplog: -Restart Instance -~~~~~~~~~~~~~~~~ + .. code-block:: javascript -Now that the resize operation is complete, issue the following command -sequence to shut down the node and restarted in replica set mode. + db.oplog.rs.save( db.temp.findOne() ) -.. code-block:: javascript + To confirm the entry is in the new oplog, issue the following command: - mongod --dbpath /srv/mongodb --shutdown - mongod --replSet rs0 --dbpath /srv/mongodb + .. code-block:: javascript -The replica member will recover and "catch up," and then will be -eligible for election to :term:`primary`. You can use the following -command on a :program:`mongo` shell connection to the *current* -:term:`primary`. + db.oplog.rs.find() -.. code-block:: javascript +#. Restart the server as a member of the replica set on its usual + port: - rs.stepDown() + .. code-block:: javascript -This will cause the primary to step down and force an election. If -this node's :ref:`priority ` is higher than -all other nodes in the set *and* it has successfully "caught up," then -it will likely become primary. + mongod --dbpath /srv/mongodb --shutdown + mongod --replSet rs0 --dbpath /srv/mongodb -Other Replica Set Members -~~~~~~~~~~~~~~~~~~~~~~~~~ + The replica member will recover and "catch up" and then will be + eligible for election to :term:`primary`. To step down the + "temporary" primary that took over when you initially shut down the + server, use the :method:`rs.stepDown()` method. This will force an + election for primary. If the server's :ref:`priority + ` is higher than all other members in the + set *and* if it has successfully "caught up," then it will likely + become primary. -You should repeat this procedure for any member of the replica set -that *could* become primary. +#. Repeat this procedure for any other member of the replica set that + *could* become primary.