Data recovery 1862

source/includes/steps-recover-data-files.yaml

@@ -0,0 +1,101 @@
+ref: run-mongodump
+stepnum: 1
+title: Run :program:`mongodump` for each database to recover.
+action:
+   - pre: |
+        If the database used the :option:`--directoryperdb` option, run the
+        following command from the system shell prompt:
+     language: sh
+     code: |
+        mongodump --journal --dbpath /data/db --directoryperdb --repair -d users -o /data/recovery > /data/recovery/users.log
+   - pre: |
+        Otherwise omit the :option:`--directoryperdb` option:
+     language: sh
+     code: |
+        mongodump --journal --dbpath /data/db --repair -d users -o /data/recovery > /data/recovery/users.log
+---
+ref: verify
+stepnum: 2
+title: Verify the new files contain recovered documents.
+pre: |
+   Examine ``/data/recovery/users.log`` to determine how many documents
+   :program:`mongodump` recovered.
+---
+ref: create-new-mongodb-node
+stepnum: 3
+title: Create a new MongoDB node.
+pre: |
+    Use :program:`mongorestore` to create a new data directory. For
+    example, the following command restores data to the new data directory
+    ``/data/db2``.
+action:
+   language: sh
+   code: |
+      mongorestore --dbpath /data/db2 /data/recovery
+---
+ref: test
+stepnum: 4
+title: Test the data files on a standalone ``mongod``.
+action:
+   - pre: |
+        Start the :program:`mongod` with with a ``dbpath`` pointing to the
+        recovered data. For example:
+     language: sh
+     code: |
+        mongod --dbpath /data/recovery/
+   - pre: |
+        If the repair has removed data, the number of documents in the
+        collection will be lower than it had been previously. From the
+        :program:`mongo` shell, verify the number of documents in each collection:
+     language: javascript
+     code: |
+        use users
+        db.collection.count()
+post: |
+   Perform other application-specific tests in a staging environment as
+   needed. If the data files are correct, delete or archive the
+   ``/data/recovery`` directory and *do not proceed with any further
+   recovery efforts*.
+---
+ref: repair
+stepnum: 5
+title: Repair the data.
+pre: |
+   If :program:`mongodump` failed to recover the data files, use
+   :program:`mongod` with the :option:`--repair <mongod --repair>` and
+   :option:`--repairpath <mongod --repairpath>` options to create a new
+   data directory with a repaired set of data files. Specify a new
+   directory to receive the repaired data files:
+action:
+   language: sh
+   code: |
+      mongod --dbpath /data/db --repair --repairpath /data/recovery
+post: |
+   When the :option:`--repair <mongod --repair>` operation completes
+   successfully, the newly-repaired data files are in the new directory.
+
+   .. warning::
+
+      :option:`--repair <mongod --repair>` removes the invalid parts of
+      data files. You can lose data as part of the recovery process.
+      Under some circumstances, :option:`--repair <mongod --repair>`
+      may remove the majority of data in the data file. Without the
+      :option:`--repairpath <mongod --repairpath>` option, the new
+      data files permanently overwrite the old.
+---
+ref: test-data-files
+stepnum: 6
+title: Test the data files.
+pre: |
+   Test the data files using the procedure outlined above.
+---
+ref: use-files-normally
+stepnum: 7
+title: Use the recovered files normally.
+pre: |
+   Start :program:`mongod` with :setting:`dbpath` pointing to the new directory:
+action:
+   language: sh
+   code: |
+      mongod --dbpath <newpath>
+...

source/includes/toc-administration-backup-and-recovery.yaml

@@ -20,7 +20,16 @@ description: |
   Detailed procedures and considerations for backing up sharded
   clusters and single shards.
 ---
-file: /tutorial/recover-data-following-unexpected-shutdown
+file: /tutorial/maintain-valid-data-files
+description: |
+  Ensure valid data through journaling and replica sets.
+---
+file: /tutorial/detect-invalid-data-files
+description: |
+  Recover data from MongoDB data files that were not properly closed
+  or have an invalid state.
+---
+file: /tutorial/recover-data
 description: |
   Recover data from MongoDB data files that were not properly closed
   or have an invalid state.

source/includes/toc-spec-administration-tutorials-landing.yaml

@@ -18,7 +18,7 @@ files:
     level: 2
   - file: /administration/backup-sharded-clusters
     level: 2
-  - file: /tutorial/recover-data-following-unexpected-shutdown
+  - file: /tutorial/detect-invalid-data-files
     level: 2
   - text: "Continue reading from :doc:`/administration/backup` for additional tutorials of MongoDB backup and recovery procedures."
     level: 2

source/tutorial.txt

@@ -57,7 +57,7 @@ Replica Sets
 - :doc:`/tutorial/configure-replica-set-tag-sets`
 - :doc:`/tutorial/manage-chained-replication`
 - :doc:`/tutorial/reconfigure-replica-set-with-unavailable-members`
-- :doc:`/tutorial/recover-data-following-unexpected-shutdown`
+- :doc:`/tutorial/detect-invalid-data-files`
 - :doc:`/tutorial/troubleshoot-replica-sets`
 
 Sharding
@@ -85,7 +85,8 @@ Basic Operations
 ~~~~~~~~~~~~~~~~
 
 - :doc:`/tutorial/use-database-commands`
-- :doc:`/tutorial/recover-data-following-unexpected-shutdown`
+- :doc:`/tutorial/detect-invalid-data-files`
+- :doc:`/tutorial/copy-databases-between-instances`
 - :doc:`/tutorial/expire-data`
 - :doc:`/tutorial/manage-the-database-profiler`
 - :doc:`/tutorial/rotate-log-files`
@@ -103,7 +104,6 @@ Security
 - :doc:`/tutorial/add-user-administrator`
 - :doc:`/tutorial/add-user-to-database`
 - :doc:`/tutorial/define-roles`
-- :doc:`/tutorial/change-user-privileges`
 - :doc:`/tutorial/view-roles`
 - :doc:`/tutorial/generate-key-file`
 - :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication`

source/tutorial/detect-invalid-data-files.txt

@@ -0,0 +1,100 @@
+==========================
+Detect Invalid Data Files
+==========================
+
+.. default-domain:: mongodb
+
+.. contents::
+   :backlinks: none
+   :local:
+
+Overview
+--------
+
+If you have an interruption, such as a power failure, you must assume your
+data files are in an invalid state. This section describes how to check
+whether a :program:`mongod` instance shut down cleanly and how to test
+data integrity.
+
+To recover data that has been corrupted, see
+:doc:`/tutorial/recover-data`.
+
+.. note:: The best way to avoid data loss and ensure the most robust
+   deployments is to follow the recommendations in
+   :doc:`maintain-valid-data-files`.
+
+Procedures
+----------
+
+Detect an Unclean Shutdown
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To detect whether a :program:`mongod` instance shutdown cleanly, look for
+the following indicators:
+
+- a ``mongod.lock`` non-zero-length file in the data directory.
+
+- the following line in the :program:`mongod` log output:
+
+  .. code-block:: none
+
+     Unclean shutdown detected.
+
+These indicate an unclean shutdown, in which case you must assume data
+files are invalid.
+
+Test Data Integrity
+~~~~~~~~~~~~~~~~~~~
+
+This procedure applies only if the :program:`mongod` instance runs with
+:term:`journaling <journal>` enabled. To test data integrity, use either
+the :method:`db.collection.validate()` method or :dbcommand:`validate`
+command.
+
+For example, to test the integrity of the ``people`` collection, use the
+following command from the :program:`mongo` shell:
+
+.. code-block:: javascript
+
+   db.test.validate(true)
+
+A portion of the output shows that the ``test`` collection is valid:
+
+.. code-block:: javascript
+
+   {
+   ...
+
+     "valid" : true,
+     "errors" : [ ],
+     "ok" : 1
+   }
+
+If the collection is invalid, the output of
+:method:`db.collection.validate()` shows that as well:
+
+.. code-block:: javascript
+
+   {
+   ...
+      "valid" : false,
+      "errors" : [
+         "invalid bson object detected (see logs for more info)",
+         "exception during validate"
+      ],
+      "advice" : "ns corrupt, requires repair",
+      "ok" : 1
+   }
+
+Related Documents
+-----------------
+
+- :doc:`maintain-valid-data-files`
+
+- :doc:`/tutorial/recover-data`
+
+- :doc:`/tutorial/manage-journaling`
+
+- :doc:`/core/backups`
+
+- :doc:`/administration/backup`

source/tutorial/maintain-valid-data-files.txt

@@ -0,0 +1,66 @@
+=========================
+Maintain Valid Data Files
+=========================
+
+.. default-domain:: mongodb
+
+.. contents::
+   :backlinks: none
+   :local:
+
+Overview
+--------
+
+MongoDB provides features to protect your data in the event of hardware
+failure, power failure, network failure, or other unforeseen events that
+affect data. Use the features described here to ensure that data is
+routinely copied to multiple servers and that damaged servers recover
+quickly.
+
+Enable Journaling
+-----------------
+
+Always use :ref:`durability journaling <setting-journal>`. The journal
+stores recent data changes, with the primary aim of recovering from
+database invalidity. By default, MongoDB updates its journal ten
+times per second. In the worst case, with journaling enabled,
+``1/10`` of a second of data may be lost.
+
+If a :program:`mongod` instance without journaling shuts down
+unexpectedly for *any* reason, always assume that your database is
+in an invalid state.
+
+For 64-bit builds of :program:`mongod`, MongoDB enables journaling by
+default. For more information see :doc:`/core/journaling` and
+:doc:`/tutorial/manage-journaling`.
+
+Run All Deployments as Replica Sets
+-----------------------------------
+
+Certain recovery options are much simpler if the :program:`mongod`
+instance runs as a member of a replica set. The primary goal of
+replica sets in MongoDB is to ensure availability and prevent data loss. In
+the event of database invalidity, recovery may be as simple as syncing
+from a fellow replica set member.
+
+For more information see :doc:`/core/replication`.
+
+Shut Down Cleanly
+-----------------
+
+A clean shutdown means that all ongoing MongoDB operations are
+complete and :program:`mongod` has flushed and closed all data files.
+An unclean shutdown, however, can leave the database in an invalid state.
+To ensure a clean shutdown, use one of the shutdown procedures
+described in :doc:`/tutorial/manage-mongodb-processes`.
+
+Related Documents
+-----------------
+
+- :doc:`detect-invalid-data-files`
+
+- :doc:`/tutorial/recover-data`
+
+- :doc:`/core/backups`
+
+- :doc:`/administration/backup`