diff --git a/source/_static/images/ssl-certificates.png b/source/_static/images/ssl-certificates.png new file mode 100644 index 0000000000..8bfcc434b0 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 7812b42099..a6df867c4c 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~