When you need to access OCP using HTTPS, you can refer to this section to configure the SSL certificate for OCP.
Prerequisites
Before configuring SSL for OCP, you need to prepare the following certificate files and import them into a PKCS12 format keystore file.
File |
Description |
Format example |
|---|---|---|
| Server Certificate | SSL certificate issued by a CA. The domain name or IP address must be included in the SAN field. | .cer、.crt、.pem |
| Server Private Key | Private key corresponding to the server certificate | .key、.pem |
| CA Root Certificate | The root certificate or intermediate certificate of the CA institution, used to complete the certificate chain. | .cer、.crt、.pem |
Note
OCP uses a PKCS12 format keystore to load SSL certificates. The keystore must contain the server private key, server certificate, and CA root certificate; none of these can be missing. If you only have the certificate files without the private key, it cannot be used for SSL communication.
Possess a public CA certificate
If you have obtained a certificate from an authoritative CA, first confirm that the server certificate is complete and not expired:
# View Certificate Details (ocp.cer as an Example)
openssl x509 -in ocp.cer -text -noout
# Pay special attention to the following fields:
# - Not After: Certificate expiration date
# - Subject Alternative Name (SAN): Whether it contains the access domain name or IP address of OCP.
After confirming the certificate is correct, use openssl to package the private key, server certificate, and CA root certificate into a PKCS12 format keystore:
openssl pkcs12 -export \
-in ocp.cer \
-inkey ocp.key \
-certfile ca.cer \
-name ocp \
-out ocp.keystore \
-passout pass:<your_keystore_password>
Parameter |
Description |
|---|---|
ocp.cer |
Server certificate file. |
ocp.key |
The server private key file. |
ca.cer |
Root CA certificate file. If multiple intermediate certificates are used, you can use-certfileThe file containing the complete certificate chain. |
ocp |
The alias of the key entry in the keystore, which must match the one used in subsequent OCP configurations.server.ssl.key-aliasConsistency. |
<your_keystore_password> |
Replace it with a custom password. |
Note
The keytool -import command can only import certificates as trusted entries and will not import the private key. Therefore, it cannot be used to create the keystore required for SSL. You must use methods such as openssl pkcs12 -export or keytool -importkeystore to import the private key together with the certificate.
No public CA certificate
If you do not have a public CA certificate (for example, in an intranet environment), you can generate a self-signed certificate. For details, see Appendix: Generate a self-signed certificate.
Load SSL configuration for OCP
After obtaining the keystore containing the certificate, you need to load it in OCP. The assumptions are as follows:
- The keystore file name is
ocp.keystore. - The keystore is mounted in the
/home/admin/data/keystoredirectory inside the OCP container. - The keystore type is PKCS12.
- The alias of the key is
ocp. - The password for the keystore is
store_pswd. - The password for the key is
key_pswd(if not set separately, it is empty. By default, the key password is the same as the keystore password for a keystore created usingopenssl pkcs12 -export).
Notice
After OCP is restarted, the files inside the container deployed by using containers are restored to their initial image state. Do not copy the keystore file directly into the container; otherwise, the certificate files will be lost after OCP restarts. You must use Docker volumes to map the keystore directory on the host to the container, ensuring the certificate files remain present after the container restarts.
Execute the following SQL in the corresponding MetaDB of OCP to set SSL-related configurations:
UPDATE `config_properties` SET `value`='8443' WHERE `key`='server.port';
UPDATE `config_properties` SET `value`='true' WHERE `key`='server.ssl.enabled';
UPDATE `config_properties` SET `value`='ocp' WHERE `key`='server.ssl.key-alias';
UPDATE `config_properties` SET `value`='key_pswd' WHERE `key`='server.ssl.key-password';
UPDATE `config_properties` SET `value`='/home/admin/data/keystore/ocp.keystore' WHERE `key`='server.ssl.key-store';
UPDATE `config_properties` SET `value`='store_pswd' WHERE `key`='server.ssl.key-store-password';
UPDATE `config_properties` SET `value`='PKCS12' WHERE `key`='server.ssl.key-store-type';
UPDATE `config_properties` SET `value`='https://<OCP access address>:8443' WHERE `key`='ocp.site.url';
When running OCP using Docker, you also need to add parameters for mounting the keystore in the container startup arguments. For example, if the keystore is located in the host directory /data/ocp/keystore, add the following parameter when starting the OCP container:
-v /data/ocp/keystore:/home/admin/data/keystore
After restarting OCP, OCP will listen on port 8443 using the HTTPS protocol.
Appendix: Generate a self-signed certificate
If you do not have a public CA certificate, you can use keytool to generate a self-signed certificate.
Notice
The self-signed certificate must include the IP addresses and domain names of all OCP instances in the SAN extension; otherwise, mutual access between multiple nodes will fail. Clients must add the root certificate to the trusted list before they can access the service.
Generate a self-signed certificate
You can use the following script to generate a self-signed certificate and a root certificate. Before executing, modify configuration information such as the domain name and IP address according to your actual situation.
#!/bin/bash
set -euo pipefail
# ===================== Configuration section =====================
domain="ocp.oceanbase.com"
ips="30.142.17.125"
root_password='root4321'
ocp_password="Oceanbase4321"
validity_days=3650
# ==================================================
# Check whether keytool is available.
if ! command -v keytool &> /dev/null; then
echo "keytool not found. Please install JDK and ensure JAVA_HOME is correctly set."
exit 1
fi
echo "Using keytool: $(which keytool)"
echo "Domain: ${domain}"
echo "IPs: ${ips}"
# Build DN and SAN
dname="CN=${domain}"
san="SAN=DNS:${domain}"
for ip in ${ips}; do
san="${san},IP:${ip}"
done
# ---------- 1. Generate the root CA certificate ----------
echo ">>> [1/8] Generating root CA certificate..."
keytool -genkeypair \
-keyalg RSA -keysize 4096 \
-dname "CN=OCP Root CA" \
-alias root \
-keystore root.keystore \
-storetype PKCS12 \
-storepass "${root_password}" \
-ext BasicConstraints=CA:TRUE \
-ext KeyUsage=keyCertSign,cRLSign
# ---------- 2. Generate an OCP server key pair ----------
echo ">>> [2/8] Generating OCP TLS key pair..."
keytool -genkeypair \
-keyalg RSA -keysize 4096 \
-validity ${validity_days} \
-dname "${dname}" \
-alias ocp \
-keystore ocp.keystore \
-storetype PKCS12 \
-storepass "${ocp_password}" \
-ext "${san}"
# ---------- 3. Create a Certificate Signing Request (CSR) ----------
echo ">>> [3/8] Creating CSR..."
keytool -certreq \
-file server.csr \
-alias ocp \
-keystore ocp.keystore \
-storepass "${ocp_password}" \
-ext "${san}"
# ---------- 4. Issue server certificates with the root CA ----------
echo ">>> [4/8] Issuing server certificate under root CA..."
keytool -gencert \
-infile server.csr \
-outfile server.cer \
-alias root \
-keystore root.keystore \
-storepass "${root_password}" \
-ext "${san}" \
-rfc
# ---------- 5. Export the root certificate (DER) ----------
echo ">>> [5/8] Exporting root certificate..."
keytool -exportcert \
-file root.cer \
-alias root \
-keystore root.keystore \
-storepass "${root_password}"
# ---------- 6. Import the root certificate into the OCP keystore ----------
# You must import the root certificate first so that the certificate chain can be verified when importing server certificates later.
echo ">>> [6/8] Import the root certificate to the OCP keystore..."
keytool -importcert \
-file root.cer \
-alias root \
-keystore ocp.keystore \
-storepass "${ocp_password}" \
-noprompt
# ---------- 7. Import the issued server certificate into the OCP keystore ----------
echo ">>> [7/8] Importing the issued server certificate..."
keytool -importcert \
-file server.cer \
-alias ocp \
-keystore ocp.keystore \
-storepass "${ocp_password}"
# ---------- 8. Export the root certificate in PEM format (for client trust) ----------
echo ">>> [8/8] Exporting the PEM format root certificate..."
keytool -exportcert \
-file root.pem \
-alias root \
-keystore root.keystore \
-storepass "${root_password}" \
-rfc
# ---------- Clean up temporary files ----------
rm -f server.csr server.cer root.cer
echo "Certificate generation completed! Output file:"
echo " ocp.keystore - For use by OCP Server (including the complete certificate chain)"
echo " root.pem - Client adds trust for use"
Usage:
chmod +x gen_ocp_tls.sh
./gen_ocp_tls.sh
To add more IPs, modify the ips variable at the top of the script, separating multiple entries with spaces:
ips="30.142.17.125 10.0.0.1 192.168.1.100"
Notice
In a production environment, keep the root.keystore file (containing the CA private key) secure. After certificate distribution is complete, it is recommended to delete the root.keystore file and intermediate files (such as server.csr and server.cer) from the host where the certificates were generated. However, do not delete the ocp.keystore file mounted in the OCP container, otherwise the SSL configuration of OCP will become invalid.
Trust the root certificate
When using a self-signed certificate, you must add the root certificate to the trusted certificate list on the machines where the OBServer and OBProxy nodes reside, to ensure that components such as OB, Proxy, and Agent can access OCP normally.
Here, root.pem is the root certificate file.
# RHEL series
sudo cp root.pem /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
# Debian series
sudo cp root.pem /usr/local/share/ca-certificates/root.crt
sudo update-ca-certificates
# SUSE series
sudo cp root.pem /usr/share/pki/trust/anchors
sudo update-ca-certificates
Notice
When subsequently scaling out an OceanBase cluster by adding OBServer nodes, or adding OBProxy nodes to an OBProxy cluster, the new nodes' machines may not yet trust the self-signed root certificate, which will prevent those nodes from accessing OCP properly. Please promptly perform the above operation to trust the root certificate on the machine where the new node is located after the scaling is completed.