db.shutdownServer.txt

===================
db.shutdownServer()
===================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

.. versionchanged:: 5.0

.. method:: db.shutdownServer()

   Shuts down the current :binary:`~bin.mongod` or :binary:`~bin.mongos`
   process cleanly and safely. You must issue the
   :method:`db.shutdownServer()` operation against the 
   :term:`admin database`.

   :method:`db.shutdownServer()` has this syntax:

   .. code-block:: javascript

      db.shutdownServer({ 
        force: <boolean>,
        timeoutSecs: <int> 
      })

   The method takes these fields:

   .. list-table::
      :header-rows: 1
      :widths: 20 80

      * - Field
        - Description

      * - :ref:`force <shutdownServer-method-force>`

        - .. _shutdownServer-method-force:
        
          Optional. Specify ``true`` to force the :binary:`~bin.mongod`
          or :binary:`~bin.mongos` to shut down. Force shutdown
          interrupts any ongoing operations on the :binary:`~bin.mongod`
          or :binary:`~bin.mongos` and may result in unexpected
          behavior.

          You can pause and resume in-progress index builds using 
          ``force``. See :ref:`method-shutdown-replica-set` for more 
          information.

      * - :ref:`timeoutSecs <shutdownServer-method-timeoutSecs>`

        - .. _shutdownServer-method-timeoutSecs:
        
          Optional.

          .. _shutdownServer-method-quiesce-period:

          .. |force| replace:: :ref:`force <shutdownServer-method-force>`
          .. |timeout| replace:: :ref:`timeoutSecs <shutdownServer-method-timeoutSecs>`

          .. include:: /includes/quiesce-period.rst

This operation provides a wrapper around the :dbcommand:`shutdown`
command.

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-no-atlas-support.rst

.. include:: /includes/fact-environments-onprem-only.rst

Behavior
--------

For a :binary:`~bin.mongod` started *with* :ref:`authentication`, you
must run :method:`db.shutdownServer()` over an authenticated connection.
See :ref:`method-shutdown-access-control` for more information.

For a :binary:`~bin.mongod` started *without* :ref:`authentication`, you
must run :method:`db.shutdownServer()` from a client connected to the
localhost interface. For example, run :binary:`~bin.mongosh` with the
:option:`--host "127.0.0.1" <mongosh --host>` option on the same host
machine as the :binary:`~bin.mongod`.

.. _method-shutdown-replica-set:

``db.shutdownServer()`` on Replica Set Members
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:method:`db.shutdownServer()` fails if the :binary:`~bin.mongod` replica
set member is running certain operations such as :ref:`index builds
<index-operations-replicated-build>`. You can specify :ref:`force: true
<shutdownServer-method-force>` to save index build progress to disk. 
The :binary:`~bin.mongod` recovers the index build when it restarts 
and continues from the saved checkpoint.

Shutting Down the Replica Set Primary, Secondary, or ``mongos``
```````````````````````````````````````````````````````````````

.. include:: /includes/quiesce-period.rst

.. warning::

   Force shutdown of the primary can result in the 
   :ref:`rollback <replica-set-rollback>` of any writes not 
   yet replicated to a secondary.

.. _method-shutdown-access-control:

Access Control
--------------

To run :method:`db.shutdownServer()` on a :binary:`~bin.mongod`
enforcing :ref:`authentication`, the authenticated user *must* have the
:method:`db.shutdownServer()` privilege. For example, a user with the
built-in role :authrole:`hostManager` has the appropriate permissions.

Examples
--------

Shut down a ``mongod``
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: javascript

   db.getSiblingDB("admin").shutdownServer()

Force Shut Down a ``mongod``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: javascript

   db.getSiblingDB("admin").shutdownServer({ "force" : true })

Shut Down a Primary ``mongod`` With Longer Timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: javascript

   db.getSiblingDB("admin").shutdownServer({ "timeoutSecs": 60 })