DOCS-9265, DOCS-5976: fsyncLock/Unlock and lock counts

Author: kay-kim

source/includes/apiargs-dbcommand-fsync-field.yaml

@@ -21,7 +21,11 @@ type: boolean
 ---
 arg_name: field
 description: |
-  Locks :binary:`~bin.mongod` instance and blocks all write operations.
+  
+  Takes a lock on the :binary:`~bin.mongod` instance and blocks all
+  write operations. Each :dbcommand:`fsync` with ``lock`` operation
+  takes a lock. 
+
 interface: dbcommand
 name: lock
 operation: fsync

source/includes/ref-toc-command-administration.yaml

@@ -66,6 +66,10 @@ name: ":dbcommand:`fsync`"
 file: /reference/command/fsync
 description: "Flushes pending writes to the storage layer and locks the database to allow backups."
 ---
+name: ":dbcommand:`fsyncUnlock`"
+file: /reference/command/fsyncUnlock
+description: "Unlocks one fsync lock."
+---
 name: ":dbcommand:`getParameter`"
 file: /reference/command/getParameter
 description: "Retrieves configuration options."

source/includes/steps-backup-sharded-cluster-with-snapshots.yaml

@@ -45,10 +45,7 @@ action:
     language: javascript
     code: |
       db.fsyncLock()
-    post: |
-      When calling :method:`db.fsyncLock()`, ensure that the connection
-      is kept open to allow a subsequent call to
-      :method:`db.fsyncUnlock()`.
+
   - heading: Lock config server replica set secondary.
     pre: |
       If locking a secondary of the CSRS, confirm that the member has
@@ -98,9 +95,6 @@ action:
     language: javascript
     code: |
        db.fsyncLock()
-    post: |
-      When calling :method:`db.fsyncLock()`, ensure that the connection is
-      kept open to allow a subsequent call to :method:`db.fsyncUnlock()`.
 ---
 title: Back up one of the config servers.
 stepnum: 3
@@ -136,8 +130,7 @@ pre: |
   unlock them.
 
   To unlock the replica set members, use :method:`db.fsyncUnlock()`
-  method in the :binary:`~bin.mongo` shell. For each locked member, use the
-  same :binary:`~bin.mongo` shell used to lock the instance.
+  method in the :binary:`~bin.mongo` shell.
 action: 
   language: javascript
   code: |

source/includes/steps-backup-sharded-clusters-dumps.yaml

@@ -39,10 +39,7 @@ action:
     language: javascript
     code: |
       db.fsyncLock()
-    post: |
-      When calling :method:`db.fsyncLock()`, ensure that the connection
-      is kept open to allow a subsequent call to
-      :method:`db.fsyncUnlock()`.
+
   - heading: Lock config server replica set secondary.
     pre: |
       If locking a secondary of the CSRS, confirm that the member has
@@ -92,9 +89,7 @@ action:
     language: javascript
     code: |
        db.fsyncLock()
-    post: |
-      When calling :method:`db.fsyncLock()`, ensure that the connection is
-      kept open to allow a subsequent call to :method:`db.fsyncUnlock()`.
+
 ---
 title: Backup one config server.
 stepnum: 3
@@ -116,7 +111,7 @@ action:
       If your deployment uses CSRS config servers, unlock the config server
       node before proceeding to the next step.
       To unlock the CSRS member, use :method:`db.fsyncUnlock()` method in
-      the :binary:`~bin.mongo` shell used to lock the instance.
+      the :binary:`~bin.mongo` shell.
     language: javascript
     code: |
       db.fsyncUnlock()
@@ -139,8 +134,7 @@ stepnum: 5
 ref: restart-replica-set-members
 pre: |
   To unlock the replica set members, use :method:`db.fsyncUnlock()`
-  method in the :binary:`~bin.mongo` shell. For each locked member, use the
-  same :binary:`~bin.mongo` shell used to lock the instance.
+  method in the :binary:`~bin.mongo` shell.
 action: 
   language: javascript
   code: |

source/reference/command/fsync.txt

@@ -10,6 +10,10 @@ fsync
    :depth: 1
    :class: singlecol
 
+.. meta::
+   :description: fsync, fsynclock, fsync lock, lock
+   :keywords: fsync, fsynclock, fsync lock, lock
+  
 Definition
 ----------
 
@@ -24,6 +28,7 @@ Definition
    layer and then writes the data to disk within the :setting:`~storage.syncPeriodSecs`
    interval, which is 60 seconds by default. Run :dbcommand:`fsync` when
    you want to flush writes to disk ahead of that interval.
+   
 
    The :dbcommand:`fsync` command has the following syntax:
 
@@ -35,6 +40,15 @@ Definition
 
    .. include:: /includes/apiargs/dbcommand-fsync-field.rst
 
+   To run the :dbcommand:`fsync` command, use the
+   :method:`db.adminCommand()` method:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { fsync: 1, ... } )
+   
+   
+
 Considerations
 --------------
 
@@ -59,28 +73,30 @@ If your :binary:`~bin.mongod` has :term:`journaling <journal>` enabled,
 please use :ref:`file system or volume/block level snapshot tool <backup-with-journaling>` to create a
 backup of the data set and the journal together as a single unit.
 
-Impact on Read Operations
-~~~~~~~~~~~~~~~~~~~~~~~~~
 
-After :dbcommand:`fsync` with the ``lock`` option runs on a
-:binary:`~bin.mongod`, all write operations will block until a subsequent
-unlock. Read operations *may* also block. As a result, :dbcommand:`fsync`
-with lock is not a reliable mechanism for making a :binary:`~bin.mongod`
-instance operate in a read-only mode.
+``fsync`` with ``lock: true``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. important::
+.. versionchanged:: 3.4
+
+   The ``{ fsync: 1, lock: true }`` command now returns a ``lockCount``
+   in the return document.
 
-   Blocked read operations prevent verification of authentication.
-   Such reads are necessary to establish new connections
-   to a :binary:`~bin.mongod` that enforces authorization checks.
+After ``{ fsync: 1, lock: true }`` runs on a :binary:`~bin.mongod`, all
+write operations will block.
 
-.. warning::
 
-   When calling :dbcommand:`fsync` with the ``lock`` option, ensure that
-   the connection remains open to allow a subsequent call to
-   :method:`db.fsyncUnlock()`.
+.. note::
+
+   The ``{ fsync: 1, lock: true }`` operation maintain a lock count.
+   Each ``{ fsync: 1, lock: true }`` operation increments the lock
+   count.
 
-   Closing the connection may make it difficult to release the lock.
+   To unlock a :binary:`~bin.mongod` instance for writes, the lock count
+   must be zero. That is, for a given number of ``{ fsync: 1, lock:
+   true }`` operation, you must issue a corresponding number of unlock
+   operations in order to unlock the instance for writes. To unlock,
+   see :method:`db.fsyncUnlock()`.
 
 Examples
 --------
@@ -94,7 +110,7 @@ The :dbcommand:`fsync` operation is synchronous by default. To run
 
 .. code-block:: javascript
 
-   { fsync: 1, async: true }
+   db.adminCommand( { fsync: 1, async: true } )
 
 The operation returns immediately. To view the status of the
 :dbcommand:`fsync` operation, check the output of
@@ -116,12 +132,33 @@ To lock the database, use the ``lock`` field set to ``true``:
 
 .. code-block:: javascript
 
-   { fsync: 1, lock: true }
+   db.adminCommand( { fsync: 1, lock: true } )
+
+The operation returns a document that includes the status of the
+operation and the ``lockCount``:
+
+.. code-block:: javascript
+
+   {
+      "info" : "now locked against writes, use db.fsyncUnlock() to unlock",
+      "lockCount" : NumberLong(1),
+      "seeAlso" : "http://dochub.mongodb.org/core/fsynccommand",
+      "ok" : 1
+   }
 
 You may continue to perform read operations on a :binary:`~bin.mongod` instance that has a
 :dbcommand:`fsync` lock. However, after the first write operation all
 subsequent read operations wait until you unlock the :binary:`~bin.mongod` instance.
 
+.. important::
+
+   The ``{ fsync: 1, lock: true }`` operation maintain a lock count.
+
+   To unlock a :binary:`~bin.mongod` instance for writes, the lock count
+   must be zero. That is, for a given number of ``{ fsync: 1, lock:
+   true }`` operation, you must issue a corresponding number of unlock
+   operations in order to unlock the instance for writes.
+
 Unlock ``mongod`` Instance
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -131,6 +168,8 @@ To unlock the :binary:`~bin.mongod`, use :method:`db.fsyncUnlock()`:
 
    db.fsyncUnlock();
 
+Repeat the :method:`db.fsyncUnlock()` to reduce the lock count to zero
+to unlock the instance for writes.
 
 Check Lock Status
 ~~~~~~~~~~~~~~~~~

source/reference/command/fsyncUnlock.txt

@@ -0,0 +1,100 @@
+===========
+fsyncUnlock
+===========
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. meta::
+   :description: fsync, fsyncUnlock, fsync unlock, unlock
+   :keywords: fsync, fsyncUnlock, fsync unlock, unlock
+
+Definition
+----------
+
+.. dbcommand:: fsyncUnlock
+
+   Reduces the lock taken by :dbcommand:`fsync` (with the lock option)
+   on a :binary:`~bin.mongod` instance by 1.
+
+   .. important::
+
+      The :dbcommand:`fsync` lock and :dbcommand:`fsyncUnlock`
+      operations maintain a lock count. Each :dbcommand:`fsync` lock
+      opeartion increments the lock count, and :dbcommand:`fsyncUnlock`
+      decrements the lock count.
+
+      To unlock a :binary:`~bin.mongod` instance for writes, the lock count
+      must be zero. That is, for a given number of :dbcommand:`fsync`
+      lock operations, you must issue a corresponding number of
+      :dbcommand:`fsyncUnlock` operations to unlock the instance for
+      writes.
+
+   :dbcommand:`fsyncUnlock` is an administrative operation. Typically
+   you will use :dbcommand:`fsyncUnlock` following a database
+   :doc:`backup operation </core/backups>`.
+
+   To run the :dbcommand:`fsyncUnlock` command, use the
+   :method:`db.adminCommand()` method:
+
+   .. code-block:: javascript
+
+      db.adminCommand( { fsyncUnlock: 1 } )
+
+   The operation returns a document with the following fields:
+
+   .. list-table::
+   
+      * - ``info``
+        - information on the status of the operation
+
+      * - ``lockCount``
+        - The number of locks remaining on the instance after the operation.
+
+          .. versionadded:: 3.4
+
+      * - ``ok``
+        - The status code.
+
+   .. tip::
+
+      The :binary:`~bin.mongo` shell provides the helper method
+      :method:`db.fsyncUnlock()`.
+
+Examples
+--------
+
+Consider a situation where :method:`db.fsyncLock()` has been issued two
+times. The following :dbcommand:`fsyncUnlock` operation reduces the
+locks taken by :method:`db.fsyncLock()` by 1:
+
+.. code-block:: javascript
+
+   db.adminCommand( { fsyncUnlock: 1 } )
+
+The operation returns the following document:
+
+.. code-block:: javascript
+
+   { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(1), "ok" : 1 }
+
+As the ``lockCount`` is greater than 0, the :binary:`~bin.mongod` instance
+is locked against writes. To unlock the instance for writes, run the
+unlock operation again:
+
+.. code-block:: javascript
+
+   db.adminCommand( { fsyncUnlock: 1 } )
+
+The operation returns the following document:
+
+.. code-block:: javascript
+
+   { "info" : "fsyncUnlock completed", "lockCount" : NumberLong(0), "ok" : 1 }
+
+The :binary:`~bin.mongod` instance is unlocked for writes.