shutdown
Changed in version 5.0.
shutdown
The
shutdown
command cleans up all database resources and then terminates the process. You must issue theshutdown
command against the admin database.
Syntax
The command has the following syntax:
db.adminCommand( { shutdown: 1, force: <boolean> timeoutSecs: <int>, comment: <any> } )
Command Fields
The command takes these fields:
Field | Description |
---|---|
Specify | |
Optional. Starting in MongoDB 5.0, If a
For a The quiesce period is specified by the:
Clients cannot open new connections to a timeoutSecs specifies a time period in seconds. The default is:
Starting in MongoDB 5.0, For a | |
comment | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:
A comment can be any valid BSON type (string, integer, object, array, etc). New in version 4.4. |
Behavior
For a mongod
started with Authentication,
you must run shutdown
over an authenticated connection.
See Access Control for more information.
For a mongod
started without Authentication,
you must run shutdown
from a client connected to the
localhost interface. For example, run mongosh
with
the --host "127.0.0.1"
option on the
same host machine as the mongod
.
shutdown
on Replica Set Members
shutdown
fails if the replica set member is running
certain operations such as index builds. You can specify
force: true to force the member
to interrupt those operations and shut down.
Shutting Down the Replica Set Primary, Secondary, or mongos
Starting in MongoDB 5.0, mongod
and mongos
enter a quiesce period to allow any ongoing database operations to
complete before shutting down.
If a mongod
primary receives a shut down request,
the primary:
Attempts to step down to a secondary.
If the step down fails and a:
Enters the quiesce period.
Ends any remaining database operations.
Shuts down.
For a mongod
secondary or mongos
shut down request, the quiesce period is entered after a shut down was
requested.
The quiesce period is specified by the:
timeoutSecs field if a
shutdown
ordb.shutdownServer()
command was run, orshutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongod
, ormongosShutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongos
.
Clients cannot open new connections to a mongod
or
mongos
that is shutting down.
timeoutSecs specifies a time period in seconds. The default is:
15 seconds starting in MongoDB 5.0.
10 seconds in MongoDB versions earlier than 5.0.
mongod
uses timeoutSecs as follows:
If the current node is the primary node of a replica set,
mongod
waits for a period of up to the number of seconds specified by the timeoutSecs field for an electable node to catch up before stepping down the primary node. For details about the catch up time, see replication lag.If the current node is in the
SECONDARY
state after stepping down from being the primary, any remaining time specified in timeoutSecs is used for a quiesce period, which allows existing operations to complete. New operations are sent to other replica set nodes.
Starting in MongoDB 5.0, mongos
uses timeoutSecs as a
quiesce period, which allows existing operations to complete. New
operations are sent to other mongos
nodes. In MongoDB
versions earlier than 5.0, mongos
shuts down immediately
and does not use timeoutSecs.
For a mongod
primary in MongoDB 4.4 and earlier,
timeoutSecs
specifies the time in seconds that the primary
waits for a secondary to catch up for the shutdownServer
command. If no secondaries catch up within timeoutSecs
, the
shutdownServer
command fails.
In MongoDB 4.4 and earlier, if running shutdown
against the
replica set primary, the operation implicitly uses
replSetStepDown
to step down the primary before shutting
down the mongod
. If no secondary in the replica set can
catch up to the primary within 10
seconds, the shutdown operation
fails. You can issue shutdown
with force: true to shut down the primary even if the step down
fails.
Warning
Force shutdown of the primary can result in the rollback of any writes not yet replicated to a secondary.
Access Control
To run shutdown
on a mongod
enforcing
Authentication, the authenticated user must have the
shutdown
privilege. For example, a user with the
built-in role hostManager
has the appropriate permissions.
Examples
Shut down a mongod
db.adminCommand({ "shutdown" : 1 })
Force Shut Down a mongod
db.adminCommand({ "shutdown" : 1, "force" : true })
Shut Down a Primary mongod
With Longer Timeout
db.adminCommand({ "shutdown" : 1, timeoutSecs: 60 })