> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# rotateCertificates (database command)

## Definition

**New in version 5.0**

Rotates the currently used [TLS certificates](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#std-label-rotated-certs-command) for a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) to use the updated values for these certificates defined in the [configuration file.](https://www.mongodb.com/docs/manual/reference/configuration-options.md)

## Compatibility

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

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Note:**

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

**Note:**

Atlas automatically rotates the certificates. You don't need to run the `rotateCertificates` command when using Atlas. Use the `rotateCertificates` command only if you want to rotate the certificates manually.

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
   {
     rotateCertificates: 1,
     message: "<optional log message>"
   }
)
```

## Command Fields

The command takes the following optional field:

| Parameter | Type | Description |
| --- | --- | --- |
| `message` | string | *optional* A message logged by the server to the log file and audit file. |

## Output

The [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) command returns a document with the following field:

| Field | Type | Description |
| --- | --- | --- |
| `ok` | bool | Contains the command's execution status. `true` on success, or `false` if an error occurred. If `false`, an `errmsg` field is additionally provided with a detailed error message. |

## Behavior

Rotation includes the following certificates:

- [`TLS Certificates`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile)

- [`CRL (Certificate Revocation List) files`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.CRLFile) (on Linux and Windows platforms)

- [`CA (Certificate Authority) files`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.CAFile)

To rotate one or more of these certificates:

1. Replace the certificate or certificates you wish to rotate on the filesystem, noting the following constraints:

   - Each new certificate must have the *same filename* and *same filepath* as the certificate it is replacing.

   - If rotating an encrypted [`TLS Certificate`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFile), its password must be the same as the password for the old certificate (as specified to the [`certificateKeyFilePassword`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.certificateKeyFilePassword) configuration file setting). Certificate rotation does not support the interactive password prompt.

2. Connect [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) to the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance that you wish to perform certificate rotation on.

3. Run the [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) command to rotate the certificates used by the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance.

When certificate rotation takes place:

- Existing connections to the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) instance are not terminated, and will continue to use the old certificates.

- Any new connections will use the new certificates.

If you have configured [`OCSP`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.ocspEnabled) for your deployment, the [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) command will also fetch stapled OCSP responses during rotation.

The [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) command may be run on a running [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) regardless of replication status.

Only one instance of [`db.rotateCertificates()`](https://www.mongodb.com/docs/manual/reference/method/db.rotatecertificates.md#mongodb-method-db.rotateCertificates) or [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) may run on each [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) process at a time. Attempting to initiate a second instance while one is already running will result in an error.

Incorrect, expired, revoked, or missing certificate files will cause the certificate rotation to fail, but will not invalidate the existing TLS configuration or terminate the running [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) process.

If the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) or [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) is running with [`--tlsCertificateSelector`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--tlsCertificateSelector) set to `thumbprint`, [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) will fail and write a warning message to the log file.

## Logging

On successful rotation, the subject names, thumbprints, and the validity period of the server and cluster certificate thumbprints are logged to the configured [log destination](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-message-destinations). If [auditing](https://www.mongodb.com/docs/manual/core/auditing.md#std-label-auditing) is enabled, this information is also written to the audit log.

On Linux and Windows platforms, if a [`CRL file`](https://www.mongodb.com/docs/manual/reference/configuration-options.md#mongodb-setting-net.tls.CRLFile) is present, its thumbprint and validity period are also logged to these locations.

## Required Access

You must have the [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-rotateCertificates) [action](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#std-label-security-user-actions) in order to use the [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/command/rotatecertificates.md#mongodb-dbcommand-dbcmd.rotateCertificates) command. The [`rotateCertificates`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-rotateCertificates) action is part of the [`hostManager`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-hostManager) role.

## Example

The following operation rotates the certificates on a running [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instance, after having made the appropriate updates to the configuration file to specify the updated certificate information:

```javascript
db.adminCommand( { rotateCertificates: 1 } )
```

The following performs the same as above, but also writes a custom log message at rotation time to the [log file](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-message-destinations) and [audit file:](https://www.mongodb.com/docs/manual/core/auditing.md#std-label-auditing)

```javascript
db.adminCommand( { rotateCertificates: 1, message: "Rotating certificates" } )
```