rotateCertificates (database command数据库命令)

Definition定义

rotateCertificates

Rotates the currently used TLS certificates for a mongod or mongos to use the updated values for these certificates defined in the configuration file.旋转mongod或mongos当前使用的TLS证书，以使用配置文件中定义的这些证书的更新值。

Compatibility兼容性

This command is available in deployments hosted in the following environments:此命令在以下环境中托管的部署中可用：

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud：云中MongoDB部署的完全托管服务

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB：MongoDB的基于订阅的自我管理版本
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB：MongoDB的源代码可用、免费使用和自我管理版本

Syntax语法

The command has the following syntax:该命令具有以下语法：

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

Command Fields命令字段

The command takes the following optional field:该命令接受以下可选字段：

Output输出

The rotateCertificates command returns a document with the following field:rotateCertificates命令返回一个包含以下字段的文档：

Behavior行为

Rotation includes the following certificates:轮换包括以下证书：

• TLS Certificates
• CRL (Certificate Revocation List) files (on Linux and Windows platforms)（在Linux和Windows平台上）
• CA (Certificate Authority) files

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, its password must be the same as the password for the old certificate (as specified to the certificateKeyFilePassword configuration file setting). Certificate rotation does not support the interactive password prompt.
2. Connect mongosh to the mongod or mongos instance that you wish to perform certificate rotation on.
3. Run the rotateCertificates command to rotate the certificates used by the mongod or mongos instance.

When certificate rotation takes place:证书轮换时：

• Existing connections to the mongod or mongos instance are not terminated, and will continue to use the old certificates.与mongod或mongos实例的现有连接不会终止，并将继续使用旧证书。
• Any new connections will use the new certificates.任何新连接都将使用新证书。

If you have configured OCSP for your deployment, the rotateCertificates command will also fetch stapled OCSP responses during rotation.如果您已为部署配置了OCSP，则rotateCertificates命令还将在轮换期间获取装订好的OCSP响应。

The rotateCertificates command may be run on a running mongod or mongos regardless of replication status.

Only one instance of db.rotateCertificates() or rotateCertificates may run on each mongod or 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 or mongos process.不正确、过期、吊销或丢失的证书文件将导致证书轮换失败，但不会使现有的TLS配置无效或终止正在运行的mongod或mongos进程。

If the mongod or mongos is running with --tlsCertificateSelector set to thumbprint, rotateCertificates will fail and write a warning message to the log file.如果mongod或mongos在运行时将--tlsCertificateSelector设置为thumbprint，rotateCertificates将失败并在日志文件中写入警告消息。

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. 成功轮换后，主题名称、指纹以及服务器和群集证书指纹的有效期将记录到配置的日志目标中。If auditing is enabled, this information is also written to the audit log.如果启用了审核，此信息也会写入审核日志。

On Linux and Windows platforms, if a CRL file is present, its thumbprint and validity period are also logged to these locations.在Linux和Windows平台上，如果存在CRL file，其指纹和有效期也会记录到这些位置。

Required Access所需访问权限

You must have the rotateCertificates action in order to use the rotateCertificates command. 您必须执行rotateCertificates操作才能使用rotateCertificates命令。The rotateCertificates action is part of the hostManager role.rotateCertificates操作是hostManager角色的一部分。

Example示例

The following operation rotates the certificates on a running mongod instance, after having made the appropriate updates to the configuration file to specify the updated certificate information:在对配置文件进行了适当的更新以指定更新的证书信息后，以下操作将轮换正在运行的mongod实例上的证书：

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 and audit file:以下操作与上述操作相同，但也会在轮换时将自定义日志消息写入日志文件和审核文件：

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