DOCS-256 fsync wiki migration

source/reference/commands.txt

@@ -1347,44 +1347,77 @@ Administration
 
 .. dbcommand:: fsync
 
-   :dbcommand:`fsync` is an *administrative command* that forces the
-   :program:`mongod` process to flush all pending writes to the data
-   files. :program:`mongod` is always writing data to disk, and
-   guarantees that it will write all data to disk within the
-   :setting:`syncdelay` interval, which is 60 seconds by default. You
-   do not need to run :dbcommand:`fsync` in the course of normal
-   operations. The primary use of :dbcommand:`fsync` is to flush and
-   lock the database for backups.
+   The :dbcommand:`fsync` command forces the :program:`mongod` process
+   to flush all pending writes to the storage layer. :program:`mongod`
+   is always writing data to the storage layer within the
+   :setting:`syncdelay` interval, which is 60 seconds by default.
 
-   The :dbcommand:`fsync` operation blocks all other write operations
-   for a while it runs. To toggle a write-lock using
-   :dbcommand:`fsync`, add a lock argument, as follows:
+   .. code-block:: javascript
+
+      { fsync: 1 }
+
+   The :dbcommand:`fsync` operation is synchronous by default, to run
+   :dbcommand:`fsync` asynchronously, the command is:
+
+   .. code-block:: javascript
+
+      { fsync: 1, async: true }
+
+   Database backups can be performed using :dbcommand:`fsync` with the
+   ``lock`` operator, know as fsync lock. This will flush all data to
+   the data storage layer and block all write operations until the
+   database is unlocked. To set fsync lock for a database, use the
+   following command:
 
    .. code-block:: javascript
 
       { fsync: 1, lock: true }
 
-   This will sync the data files and lock the database against writes. Later,
-   you must run the following query to unlock the database:
+   .. note::
+
+      Read operations are allowed on a database that is fsync locked
+      until the next write operation, which will cause read operations
+      to be blocked. The database will then be locked until it is
+      unlocked.
+
+   To check on the current state of the fsync lock, use
+   :func:`db.currentOp()`.
+
+   To unlock the database, make a request for an unlock using the
+   following command:
 
    .. code-block:: javascript
 
       db.getSiblingDB("admin").$cmd.sys.unlock.findOne();
 
-   In the shell, you may use the following helpers to simplify
-   the process:
+   .. versionadded:: 1.9.0
+      The :func:`db.fsyncLock()` and :func:`db.fsyncUnlock()`
+      helpers in the shell.
+
+   In the shell, you may use the following shell helpers to simplify the
+   :dbcommand:`fsync` lock and unlock process:
 
    .. code-block:: javascript
 
       db.fsyncLock();
       db.fsyncUnlock();
 
-   .. versionadded:: 1.9.0
-      The :func:`db.fsyncLock()` and :func:`db.fsyncUnlock()`
-      helpers in the shell.
+   .. note::
+
+      :dbcommand:`fsync` lock is only possible on individual shards of
+      a shard cluster, not on the entire shard cluster. To backup an
+      entire shard cluster, please read: :ref:`Shard cluster
+      considerations for backups
+      <backups-with-sharding-and-replication>`
+
+   .. note::
+
+      With :term:`journaling <journal>` enabled, there are :ref:`other
+      methods<backup-with-journaling>` to create a backup.
 
    .. include:: /includes/note-disable-profiling-fsynclock.rst
 
+
 .. dbcommand:: dropDatabase
 
    The :dbcommand:`dropDatabase` command drops a database, deleting

source/reference/configuration-options.txt

@@ -510,11 +510,11 @@ Settings
 
    *Default:* 60
 
-   This setting controls the maximum number of seconds between disk
-   syncs. While :program:`mongod` is always writing data to disk, this
-   setting controls the maximum guaranteed interval between a
-   successful write operation and the next time the database flushes
-   data to disk.
+   This setting controls the maximum number of seconds between flushes
+   of pending writes to disk. While :program:`mongod` is always
+   writing data to disk, this setting controls the maximum guaranteed
+   interval between a successful write operation and the next time the
+   database flushes data to disk.
 
    In many cases, the actual interval between write operations and
    disk flushes is much shorter than the value