OpenSearch custom certificate
- Updated: 2025/09/26
During the installation of the Control Room in a cluster setup, you can upload custom certificates with a trusted Certificate Authority (CA) instead of using the default certificate provided by the product for enhanced security.
Ensure you review the following guidelines and recommendations before you upload custom
certificates:
- Ensure that the certificates have an appropriate validity (duration) so that the installation does not fail.
- Review the following naming convention for the custom certificate files that must
have specific names for installation in Windows:
File Expected file naming Expected file format Root (CA certificate) root-ca-cert.pem .pem Certificate/Key (nodes-administrative/intercommunication) elasticsearch-cert.pem .pem elasticsearch-key.pem Note:- If you have an intermediate certificate, you can rename it to root-ca-cert.pem to use it as the root certificate. The system will then recognize this intermediate certificate as the root after performing a certificate chain validation up to it.
- The .zip file must contain the certificate, key, and root CA certificate files.
- Review the following naming conventions for the custom
certificate files in Linux:
File Expected file naming Expected file format Root (CA certificate) root-ca-cert.pem .pem Certificate/Key (nodes-administrative) elasticsearch-cert.pem .pem elasticsearch-key.pem Certificate/Key (nodes-intercommunication) elasticsearch-node-cert.pem .pem elasticsearch-node-key.pem - Although elasticsearch-cert.pem is for administrative
purposes, we recommend that you use the firstnode
hostname. Note:
- For Linux, the elasticsearch-node-cert.pem is used to secure inter-node communication. It must include the host names of the second or third node, ensuring encrypted and trusted communication between cluster members.
- For Windows, elasticsearch-cert.pem is used for both securing inter-node communication as well as for administrative purposes.
- Ensure that the following certificates are signed by root/intermediate CA
certificate:
- elasticsearch-cert.pem
Applicable for both Windows and Linux.
- elasticsearch-node-cert.pem
Applicable only for Linux.
- elasticsearch-cert.pem
- Although elasticsearch-cert.pem is for administrative
purposes, we recommend that you use the firstnode
hostname.
- Ensure the certificates in the .zip file follow the below
guidelines so that they can be easily accessed and processed by the Control Room.
- Ensure certificates are not encrypted (no password protection)
- Include only the three required certificate files
- Folder structure should not contain any sub folders inside the
.zip file.
- Example for Windows:
- Example for Linux:
- Example for Windows:
- The certificate must have a common name (CN). We recommend using the hostname as CN.
Debugging common custom certificate upload errors
Custom certificate retrieval might fail due to the following reasons. For detailed
information, check msi logs in the temp
folder. Example:
C:\Users\<Username>\AppData\Local\Temp.
Error code | Possible reason | Mitigation |
---|---|---|
java.security.cert.CertificateExpiredException | Certificate is invalid error. | Ensure the certificate has not expired, and check for any mismatches in the certificate details. Re-upload the certificate after correcting any issues. |
java.Lang.RuntimeException: ERROR required certificate does not exist | The .zip folder structure is incorrect or the certificate is missing certificate error. | Ensure that the certificates are correctly placed in the .zip folder. |
ERROR: java.lang.RuntimeException: Elasticsearch root certificate is not a CA | The root CA does not match with node certificate. | Verify that the certificate is a valid CA certificate. Correct any issues and re-upload the certificate. |