DOCS-6859, DOCS-6949: pull out WiredTiger upgrade procedure

config/sphinx_local.yaml

@@ -12,37 +12,38 @@ theme:
   jira: 'DOCS'
   sitename: 'MongoDB Docs'
   nav_excluded:
+    - /administration/production-checklist
     - /aggregation
+    - /applications/geospatial-indexes
+    - /contributors/getting-started
+    - /core/authorization
+    - /core/journaling
     - /core/map-reduce
-    - /core/replica-set-members
     - /core/replica-set-architectures
     - /core/replica-set-high-availability
-    - /applications/geospatial-indexes
+    - /core/replica-set-members
     - /core/sharded-cluster-components
-    - /security
-    - /core/authentication
-    - /core/authorization
+    - /core/wiredtiger
     - /installation
-    - /reference/security
-    - /reference/indexes
-    - /reference/replication
-    - /reference/sharding
+    - /products/bi-connector
     - /reference/command
+    - /reference/indexes
     - /reference/method
-    - /reference/operator/query
-    - /reference/operator/update
     - /reference/operator/aggregation
+    - /reference/operator/query
     - /reference/operator/query-modifier
+    - /reference/operator/update
+    - /reference/replication
+    - /reference/security
+    - /reference/sharding
     - /release-notes/2.4
     - /release-notes/2.6
     - /release-notes/2.8
     - /release-notes/3.0
     - /release-notes/3.2
+    - /security
     - /storage
-    - /administration/production-checklist
-    - /contributors/getting-started
-    - /core/journaling
-    - /products/bi-connector
+    - /tutorial/change-sharded-cluster-wiredtiger
 sidebars:
   '**':
     - 'pagenav.html'

source/core/wiredtiger.txt

@@ -136,3 +136,12 @@ The WiredTiger journal is also compressed by default. For information
 on journal compression, see :ref:`storage-wiredtiger-journal`.
 
 .. seealso:: `<http://wiredtiger.com>`_
+
+.. class:: hidden
+
+   .. toctree::
+      :titlesonly:
+
+      /tutorial/change-standalone-wiredtiger.txt
+      /tutorial/change-replica-set-wiredtiger.txt
+      /tutorial/change-sharded-cluster-wiredtiger.txt

source/includes/fact-config-server-storage-engine-mix.rst

@@ -0,0 +1,5 @@
+You may safely **continue** to use :ref:`MMAPv1 <storage-mmapv1>` for
+the :term:`config servers <config server>` even if the shards of the
+sharded cluster is using the WiredTiger storage engine. If you do choose
+to update the config servers to use WiredTiger, you must update **all
+three**.

source/includes/fact-storage-engine-configuration-file-setting.rst

@@ -1,3 +1,3 @@
 You can also specify the options in a :doc:`configuration file
 </reference/configuration-options>`. To specify the storage engine, use
-the new :setting:`storage.engine` setting.
+the :setting:`storage.engine` setting.

source/includes/fact-wiredtiger-minimum-version.rst

@@ -0,0 +1,6 @@
+You must be using MongoDB version 3.0 or greater in order to use the
+WiredTiger storage engine. If upgrading from an earlier version of
+MongoDB, see the guides on :doc:`Upgrading to MongoDB 3.0
+</release-notes/3.0-upgrade>` or :doc:`Upgrading to MongoDB 3.2
+</release-notes/3.2-upgrade>` before proceeding with changing your
+storage engine.

source/includes/steps-change-config-server-wiredtiger.yaml

@@ -0,0 +1,211 @@
+title: "Disable the balancer."
+ref: change-wt-config-svr-disable-balancer
+content: |
+  Turn off the :ref:`balancer <sharding-balancing-internals>` in the
+  sharded cluster, as described in
+  :ref:`sharding-balancing-disable-temporarily`. 
+action:
+  language: sh
+  code: |
+    sh.disableBalancer()
+---
+title: "Shut down the **third** config server."
+ref: change-wt-config-svr-shutdown-3
+content: |
+  Use the :program:`mongo` shell to shut down the third config server.
+
+  The third config server is the last one listed in the
+  :program:`mongos` :setting:`~sharding.configDB` setting.
+action: |
+  language: sh
+  code: |
+    db.shutdownServer()
+---
+title: "Export the data of the **second** config server with ``mongodump``."
+ref: change-wt-config-svr-export-2
+pre: |
+  The second config server is the second server listed in the
+  :program:`mongos` setting :setting:`~sharding.configDB`.
+action:
+  language: sh
+  code: |
+    mongodump --out <exportDataDestination>
+post: |
+  Specify additional options as appropriate, such as username and
+  password if running with authorization enabled. See
+  :program:`mongodump` for available options.
+---
+title: "For the **second** config server, create a data directory for the new ``mongod`` running with WiredTiger."
+ref: change-wt-config-svr-create-dir-2
+content: |
+  Create a data directory for the new :program:`mongod` instance that
+  will run with the WiredTiger storage engine. ``mongod`` must have read
+  and write permissions for this directory.
+
+  ``mongod`` with WiredTiger will not start with data files created with
+  a different storage engine.
+---
+title: "Start the **second** config server ``mongod`` with WiredTiger."
+ref: change-wt-config-svr-restart-w-wiredtiger-2
+pre: |
+  Start :program:`mongod` as a config server, specifying ``wiredTiger``
+  as the :option:`--storageEngine` and the newly created data directory
+  for WiredTiger as the :option:`--dbpath`. Specify additional options
+  as appropriate.
+action:
+  language: sh
+  code: |
+     mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
+post: |
+
+  .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+---
+title: "Upload the exported data using ``mongorestore`` to the **second** config server."
+ref: change-wt-config-svr-upload-data-2
+action:
+  language: sh
+  code: |
+    mongorestore <exportDataDestination>
+post: |
+   Specify additional options as appropriate. See
+   :program:`mongorestore` for available options.
+---
+title: "Shut down the **second** config server."
+ref: change-wt-config-svr-shutdown-2
+pre: |
+  When the :program:`mongorestore` procedure of the previous step is
+  complete, use the :program:`mongo` shell to shut down the second
+  config server. This is necessary to maintain only two active config
+  servers at once and keep the sharded cluster's metadata read-only.
+action:
+  language: sh
+  code: |
+    db.shutdownServer()
+---
+title: "Restart the **third** config server."
+ref: change-wt-config-svr-restart-3
+pre: |
+  Simply restart the third config server with its original startup
+  options. **Do not** change it to use the WiredTiger storage engine
+  yet, as that will be done in a later step.
+action:
+  language: sh
+  code: |
+    mongod --configsvr
+---
+title: "Export the data of the **third** config server with ``mongodump``."
+ref: change-wt-config-svr-export-3
+action:
+  language: sh
+  code: |
+    mongodump --out <exportDataDestination>
+post: |
+  Specify additional options as appropriate, such as username and
+  password if running with authorization enabled. See
+  :program:`mongodump` for available options.
+---
+title: "For the **third** config server, create a data directory for the new ``mongod`` running with WiredTiger."
+ref: change-wt-config-svr-create-dir-3
+content: |
+  Create a data directory for the new :program:`mongod` instance that
+  will run with the WiredTiger storage engine. ``mongod`` must have read
+  and write permissions for this directory.
+
+  ``mongod`` with WiredTiger will not start with data files created with
+  a different storage engine.
+---
+title: "Start the **third** config server with WiredTiger."
+ref: change-wt-config-svr-restart-w-wiredtiger-3
+pre: |
+  Start :program:`mongod` as a config server, specifying ``wiredTiger``
+  as the :option:`--storageEngine` and the newly created data directory
+  for WiredTiger as the :option:`--dbpath`. Specify additional options
+  as appropriate.
+action:
+  language: sh
+  code: |
+     mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
+post: |
+  .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+---
+title: "Upload the exported data using ``mongorestore`` to the **third** config server."
+ref: change-wt-config-svr-upload-data-3
+action:
+  language: sh
+  code: |
+    mongorestore <exportDataDestination>
+post: |
+   Specify additional options as appropriate. See
+   :program:`mongorestore` for available options
+---
+title: "Export data of the **first** config server with ``mongodump``."
+ref: change-wt-config-svr-export-1
+action:
+  language: sh
+  code: |
+    mongodump --out <exportDataDestination>
+post: |
+  Specify additional options as appropriate, such as username and
+  password if running with authorization enabled. See
+  :program:`mongodump` for available options.
+---
+title: "For the **first** config server, create a data directory for the new ``mongod`` running with WiredTiger."
+ref: change-wt-config-svr-create-dir-1
+content: |
+  Create a data directory for the new :program:`mongod` instance that
+  will run with the WiredTiger storage engine. ``mongod`` must have read
+  and write permissions for this directory.
+
+  ``mongod`` with WiredTiger will not start with data files created with
+  a different storage engine.
+---
+title: "Start the **first** config server with WiredTiger."
+ref: change-wt-config-svr-restart-w-wiredtiger-1
+pre: |
+  Start :program:`mongod` as a config server, specifying ``wiredTiger``
+  as the :option:`--storageEngine` and the newly created data directory
+  for WiredTiger as the :option:`--dbpath`. Specify additional options
+  as appropriate.
+action:
+  language: sh
+  code: |
+     mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
+post: |
+  .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+---
+title: "Upload the exported data using ``mongorestore`` to the **first** config server."
+ref: change-wt-config-svr-upload-data-1
+action:
+  language: sh
+  code: |
+    mongorestore <exportDataDestination>
+post: |
+   Specify additional options as appropriate. See
+   :program:`mongorestore` for available options
+---
+title: "Enable writes to the sharded cluster's metadata."
+ref: change-wt-config-svr-start-2
+pre: |
+  Restart the **second** config server with the same options as in step
+  5. Remember to specify WiredTiger as the :option:`--storageEngine` and
+  the newly created WiredTiger data directory as the :option:`--dbpath`.
+action:
+  language: sh
+  code: |
+     mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --configsvr
+post: |
+   .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+
+   Once all three config servers are up, the sharded cluster's metadata
+   is available for writes.
+---
+title: "Re-enable the balancer."
+ref: change-wt-config-svr-reenable-balancer
+pre: |
+  Once all three config servers are up and running with WiredTiger,
+  :ref:`re-enable the balancer <sharding-balancing-enable>`.
+action:
+  language: sh
+  code: |
+    sh.startBalancer()
+...

source/includes/steps-change-replica-set-wiredtiger.yaml

@@ -0,0 +1,48 @@
+title: "Shut down the secondary member."
+ref: change-wt-repl-sync-shutdown-secondary
+pre: |
+  In the :program:`mongo` shell, shut down the secondary :program:`mongod`
+  instance you wish to upgrade.
+action:
+  language: sh
+  code: |
+    db.shutdownServer()
+---
+title: "Prepare a data directory for the new ``mongod`` running with WiredTiger."
+ref: change-wt-repl-sync-wiredtiger-dir
+pre: |
+  Prepare a data directory for the new :program:`mongod` instance that
+  will run with the WiredTiger storage engine. ``mongod`` must have read
+  and write permissions for this directory. You can either delete the
+  contents of the stopped secondary member's current data directory or
+  create a new directory entirely.
+
+  ``mongod`` with WiredTiger will not start with data files created with
+  a different storage engine.
+---
+title: "Start ``mongod`` with WiredTiger."
+ref: change-wt-repl-sync-start-mongod-w-wiredtiger
+pre: |
+  Start :program:`mongod`, specifying ``wiredTiger`` as the
+  :option:`--storageEngine` and the prepared data directory for
+  WiredTiger as the :option:`--dbpath`. Specify additional options as
+  appropriate for this replica set member.
+action:
+  language: sh
+  code: |
+    mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath> --replSet <replSetName>
+post: |
+  Since no data exists in the ``--dbpath``, the ``mongod`` will perform an
+  :doc:`initial sync </tutorial/resync-replica-set-member>`. The length of the
+  initial sync process depends on the size of the database and network
+  connection between members of the replica set.
+
+  .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+---
+title: "Repeat the procedure for other replica set secondaries you wish to upgrade."
+ref: change-wt-repl-sync-repeat
+pre: |
+  Perform this procedure again for the rest of the :term:`secondary
+  members <secondary>` of the replica set you wish to use the WiredTiger
+  storage engine.
+...

source/includes/steps-change-standalone-wiredtiger.yaml

@@ -0,0 +1,50 @@
+title: "Start the ``mongod`` you wish to change to WiredTiger."
+ref: change-wt-standalone-start
+content: |
+  If :program:`mongod` is already running, you can skip this step.
+---
+title: "Export data using ``mongodump``."
+ref: change-wt-standalone-export-data
+action:
+  language: sh
+  code: |
+    mongodump --out <exportDataDestination>
+post: |
+  Specify additional options as appropriate, such as username and
+  password if running with authorization enabled. See
+  :program:`mongodump` for available options.
+---
+title: "Create a data directory for the new ``mongod`` running with WiredTiger."
+ref: change-wt-standalone-create-wiredtiger-dir
+content: |
+  Create a data directory for the new :program:`mongod` instance that
+  will run with the WiredTiger storage engine. ``mongod`` must have read
+  and write permissions for this directory.
+
+  ``mongod`` with WiredTiger will not start with data files created with
+  a different storage engine.
+---
+title: "Start ``mongod`` with WiredTiger."
+ref: change-wt-standalone-start-mongod-w-wiredtiger
+pre: |
+  Start :program:`mongod`, specifying ``wiredTiger`` as the
+  :option:`--storageEngine` and the newly created data directory for
+  WiredTiger as the :option:`--dbpath`. Specify additional options as
+  appropriate.
+action:
+  language: sh
+  code: |
+     mongod --storageEngine wiredTiger --dbpath <newWiredTigerDBPath>
+post: |
+  .. include:: /includes/fact-storage-engine-configuration-file-setting.rst
+---
+title: "Upload the exported data using ``mongorestore``."
+ref: change-wt-standalone-upload-data
+action:
+  language: sh
+  code: |
+    mongorestore <exportDataDestination>
+post: |
+   Specify additional options as appropriate. See
+   :program:`mongorestore` for available options.
+...