This is an automated email from the ASF dual-hosted git repository.
weizhouapache pushed a commit to branch 4.20
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git
The following commit(s) were added to refs/heads/4.20 by this push:
new 059a152e customcertificates: update notes (#603)
059a152e is described below
commit 059a152eecd0f71838d601d19ad8fa1772331aac
Author: Abhishek Kumar <[email protected]>
AuthorDate: Tue Sep 1 17:38:50 2026 +0530
customcertificates: update notes (#603)
* customcertificates: update notes
Signed-off-by: Abhishek Kumar <[email protected]>
* changes
Signed-off-by: Abhishek Kumar <[email protected]>
---------
Signed-off-by: Abhishek Kumar <[email protected]>
---
source/_static/images/ssl-certificates.png | Bin 0 -> 45598 bytes
source/adminguide/systemvm.rst | 110 +++++++++++++++++++++++------
2 files changed, 87 insertions(+), 23 deletions(-)
diff --git a/source/_static/images/ssl-certificates.png
b/source/_static/images/ssl-certificates.png
new file mode 100644
index 00000000..8bfcc434
Binary files /dev/null and b/source/_static/images/ssl-certificates.png differ
diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst
index 7812b420..a6df867c 100644
--- a/source/adminguide/systemvm.rst
+++ b/source/adminguide/systemvm.rst
@@ -382,40 +382,104 @@ The Management Server generates URLs of the form
The new console requests will be served with the new DNS domain name,
certificate, and key.
-Uploading ROOT CA and Intermediate CA
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you need to upload custom certificate with ROOT CA and intermediate CA, you
can find more details here:
+Uploading Certificates
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. |ssl-certificates.png| image:: /_static/images/ssl-certificates.png
+
+Custom certificates for system VMs (SSVM and CPVM) can be uploaded using
+UI or API.
+
+To upload custom certificates following details will be needed:
+
+- ROOT CA certificate
+- Intermediate CA certificate(s) (if any)
+- Site or server certificate
+- Private key (in PKCS8 format)
+- Domain name suffix
+
+To upload custom certificates using UI, go to Infrastructure -> SSL
+Certificates around the top of the summary view. This will open up the
+following form.
+
+ |ssl-certificates.png|
+
+Root Certificate, Server Certificate, PKCS#8 private certificate can be
+added in the straightforward way.
+If there are Intermediate CA certificate(s), then add them one by one
+using the `Add intermediate certificate` button.
+For DNS domain suffix, you may use a wildcard domain name like
+`*.yourdomain.com`.
+Clicking on Submit will add certificate entries in the database,
+one for ROOT certificate, as many Intermediate certificates as added and one
for
+server + private certificate.
+
+
+This can also be achieved using the API `uploadCustomCertificate`. Example
+API calls:
+
+.. code::
+
+ uploadCustomCertificate id=1 name='Root' certificate='-----BEGIN
CERTIFICATE-----...-----END CERTIFICATE-----' domainsuffix='*.yourdomain.com'
+ uploadCustomCertificate id=2 name='Intermediate1' certificate='-----BEGIN
CERTIFICATE-----...-----END CERTIFICATE-----' domainsuffix='*.yourdomain.com'
+ uploadCustomCertificate id=3 certificate='-----BEGIN
CERTIFICATE-----...-----END CERTIFICATE-----' privatekey='-----BEGIN PRIVATE
KEY-----...-----END PRIVATE KEY-----' domainsuffix='*.yourdomain.com'
+
+Note: We do not need to provide a name for the server certificate entry, as
+it will auto-generate a name since the privatekey is provided.
+If there are multiple Intermediate certificates, then multiple API calls will
+be needed to upload them one by one.
+Also, the first two API calls for Root and Intermediate certificates can be
+combined in a single call by using a certificate value which consists of both
+Root and Intermediate certificates.
+
+After successfully uploading custom certificates, CloudStack will attempt to
+restart all SSVMs and CPVMs. If not restarted then it can be done manually.
+
+More details regarding custom certificates can be found here:
https://cwiki.apache.org/confluence/display/CLOUDSTACK/Procedure+to+Replace+realhostip.com+with+Your+Own+Domain+Name
IMPORTANT NOTES:
-In order to avoid errors and problems while uploading custom certificates,
please check following:
-
-1. While doing URL encoding of ROOT CA and any Intermediate CA, be sure that
the plus signs ("+") inside certificates
-are not replaced by space (" "), because some URL/string encoding tools tend
to do that.
+In order to avoid errors and problems while uploading custom certificates,
+please check the following:
-2. If you are renewing certificates it might happen you need to upload new
ROOT CA and Intermediate CA, together with new Server Certificate and key.
-In this case please be sure to use same names for certificates during API
upload of certificate, example:
+1. When calling the API as an HTTP request and while doing URL encoding of
+ ROOT CA and any Intermediate CA, be sure that the plus signs ("+") inside
+ certificates are not replaced by space (" "), because some URL/string
+ encoding tools tend to do that.
-http://123.123.123.123:8080/client/api?command=uploadCustomCertificate&...&name=root1...
-http://123.123.123.123:8080/client/api?command=uploadCustomCertificate&...&name=intermed1...
+2. If you are renewing certificates, you may need to upload new ROOT CA and
+ Intermediate CA, together with new Server Certificate and key.
+ In this case, please be sure to use the same names for certificates during
+ API upload of the certificate, for example:
-Here names are "root1" and "intermed1".
-If you used other names previously, please check the cloud.keystore table to
obtain used names.
+ .. code::
-If you still have problems and following errors in management.log while
destroying CPVM:
+
http://123.123.123.123:8080/client/api?command=uploadCustomCertificate&...&name=root1...
+
http://123.123.123.123:8080/client/api?command=uploadCustomCertificate&...&name=intermed1...
-- Unable to build keystore for CPVMCertificate due to CertificateException
-- Cold not find and construct a valid SSL certificate
+ Here the names are "root1" and "intermed1".
+ If you used other names previously, please check the cloud.keystore table
+ to obtain the used names.
-that means that still some of the Root/intermediate/server certificates or the
key is not in a good format, or incorrectly encoded or multiply Root
CA/Intermediate CA present in database by mistake.
+If you still have problems and see the following errors in
+management-server.log while starting CPVM:
-Other way to renew Certificates (Root,Intermediates,Server certificates and
key) - although not recommended
-unless you fill comfortable - is to directly edit the database,
-while still respect the main requirement that the private key is PKCS8
encoded, while Root CA, Intermediate and Server certificates
-are still in default PEM format (no URL encoding needed here).
-After editing the database, please restart management server, and destroy SSVM
and CPVM after that,
-so the new SSVM and CPVM with new certificates are created.
+- Unable to build keystore for CPVMCertificate due to CertificateException
+- Could not find and construct a valid SSL certificate
+
+This means that some of the Root/Intermediate/Server certificates or the key
+is not in a good format, or is incorrectly encoded, or multiple Root
+CA/Intermediate CA entries are present in the database by mistake.
+
+Another way to renew certificates (Root, Intermediates, Server certificates
+and key) - although not recommended unless you feel comfortable - is to
+directly edit the database, while still respecting the main requirement that
+the private key is PKCS8 encoded, while Root CA, Intermediate and Server
+certificates are in the default PEM format (no URL encoding needed here).
+After editing the database, please restart the management server, and destroy
+the SSVM and CPVM after that, so that new SSVM and CPVM instances with new
+certificates are created.
Load-balancing Console Proxies / Secondary Storage VMs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
