DOCSP-3449: Compact Oplog after Reducing Size

source/reference/command/compact.txt

@@ -108,6 +108,71 @@ to 100 bytes on the collection named by ``<collection>``:
 
    db.runCommand ( { compact: '<collection>', paddingBytes: 100 } )
 
+.. _compact-authentication:
+
+``compact`` Required Privileges
+-------------------------------
+
+For clusters enforcing :ref:`authentication <authentication>`,
+you must authenticate as a user with the :authrole:`compact` privilege
+action on the target collection. The :authrole:`dbAdmin` role provides 
+the required privileges for running :dbcommand:`compact` against
+non-system collections. 
+
+For :ref:`system collections <metadata-system-collections>`, create a 
+custom role that grants the :authrole:`compact` action on the system 
+collection. You can then grant that role to a new or existing user and 
+authenticate as that user to perform the :dbcommand:`compact` command. 
+For example, the following operations create a custom role that grants 
+the :authrole:`compact` action against specified database and
+collection:
+
+.. code-block:: javascript
+
+   use admin
+   db.createRole(
+      {
+         role: "myCustomCompactRole",
+         privileges: [
+            {
+               resource: { "db" : "<database>" , "collection" : "<collection>" },
+               actions: [ "compact" ]
+            }
+         ],
+         roles: []
+      }
+   )
+
+For more information on configuring the ``resource`` document, see 
+:ref:`resource-document`.
+
+To add the :authrole:`dbAdmin` or the custom role to an existing
+user, use :method:`db.grantRoleToUser` or :method:`db.updateUser()`.
+The following operation grants the custom ``compact`` role to the 
+``myCompactUser`` on the ``admin`` database:
+
+.. code-block:: javascript
+
+   use admin
+   db.grantRoleToUser("myCompactUser", [ "dbAdmin" | "myCustomCompactRole" ] )
+
+To add the :authrole:`dbAdmin` or the custom role to a new user,
+specify the role to the ``roles`` array of the
+:method:`db.createUser()` method when creating the user.
+
+.. code-block:: javascript
+
+   use admin
+   db.createUser(
+     { 
+        user: "myCompactUser",
+        pwd: "myCompactUserPassword"
+        roles: [
+          { role: "dbAdmin", db: "<database>" } | "myCustomCompactRole"
+        ]
+      }
+   )
+
 Behavior
 --------
 

source/reference/command/replSetResizeOplog.txt

@@ -52,6 +52,14 @@ other member in the replica set. You must run
 :dbcommand:`replSetResizeOplog` on each replica set member in your
 cluster to change the oplog size for all members.
 
+Reducing the oplog size does *not* reclaim that disk space
+automatically. You must run :dbcommand:`compact` against the
+``oplog.rs`` collection in the ``local`` database. ``compact``
+blocks all operations on the database it runs against.
+Running ``compact`` against ``oplog.rs`` therefore prevents oplog 
+synchronization. For a procedure on resizing the oplog and compacting
+``oplog.rs``, see :doc:`/tutorial/change-oplog-size`.
+
 Example
 --------
 

source/tutorial/change-oplog-size.txt

@@ -10,18 +10,11 @@ Change the Size of the Oplog
    :depth: 1
    :class: singlecol
 
-.. versionadded:: 3.6
-
 This procedure changes the size of the oplog [#oplog]_ on each member of a
 replica set using the :dbcommand:`replSetResizeOplog` command, starting
 with the :term:`secondary` members before proceeding to the
-:term:`primary`.
-
-.. important::
-
-   You can only run :dbcommand:`replSetResizeOplog` on
-   replica set members running with the
-   :ref:`WiredTiger storage engine <storage-wiredtiger>`.
+:term:`primary`. The :dbcommand:`replSetResizeOplog` command only
+supports the :ref:`storage-wiredtiger` storage engine.
 
 Perform these steps on each :term:`secondary` replica set member
 *first*. Once you have changed the oplog size for all secondary
@@ -76,3 +69,48 @@ member to 16 gigabytes, or 16000 megabytes.
 .. [#oplog]
 
    .. include:: /includes/fact-oplog-size.rst
+
+.. compact-oplog-rs:
+
+D. (Optional) Compact ``oplog.rs`` to reclaim disk space
+--------------------------------------------------------
+
+Reducing the size of the oplog does *not* automatically reclaim
+the disk space allocated to the original oplog size. You must run
+:dbcommand:`compact` against the ``oplog.rs`` collection in the
+``local`` database to reclaim disk space. There are no benefits to 
+running ``compact`` on the ``oplog.rs`` collection after increasing the 
+oplog size.
+
+.. important::
+
+   The replica set member cannot replicate oplog entries while the 
+   ``compact`` operation is ongoing. While ``compact`` runs, the 
+   member may fall so far behind the primary that it cannot resume 
+   replication. The likelihood of a member becoming "stale" during
+   the ``compact`` procedure increases with cluster write throughput,
+   and may be further exacerbated by the reduced oplog size.
+
+   Consider scheduling a maintenance window during which writes are 
+   throttled or stopped to mitigate the risk of the member becoming 
+   "stale" and requiring a :ref:`full resync <resync-replica-member>`.
+
+Do **not** run ``compact`` against the primary replica set member.
+Connect a :binary:`mongo <bin.mongo>` shell to the primary and run
+:method:`rs.stepDown()`. If successful, the primary steps down and
+closes all open connections. Reconnect the :binary:`mongo <bin.mongo>`
+shell to the member and run the ``compact`` command on the member.
+
+The following operation runs the ``compact`` command against the
+``oplog.rs`` collection:
+
+.. code-block:: javascript
+
+   use local
+   db.runCommand({ "compact" : "oplog.rs" } )
+
+For clusters enforcing :ref:`authentication <authentication>`, 
+authenticate as a user with the :authaction:`compact` privilege
+action on the ``local`` database and the ``oplog.rs`` collection.
+For complete documentation on :dbcommand:`compact` authentication
+requirements, see :ref:`compact-authentication`. 

source/tutorial/resync-replica-set-member.txt

@@ -1,3 +1,5 @@
+.. _resync-replica-member:
+
 ================================
 Resync a Member of a Replica Set
 ================================