As a part of deprecating realhostip.com (explanation of realhostip here), we wish to provide ability for HTTP and HTTPS based console proxy access. HTTPS with custom (wildcard) domain is already supported, as documented here : http://support.citrix.com/article/CTX133468


Console Proxy

The new implementation adheres to the following :

Console proxy will support following working modes

  1. HTTP
  2. HTTPS with wildcard certificate
  3. HTTPS with a certificate signed under an exact name, which IP points to a Load Balancer IP address

We will use the configured console proxy suffix domain name to identify following console proxy working modes. The config parameter is "consoleproxy.url.domain".
             if console proxy suffix domain is “empty” —> work mode 1
             if console proxy suffix domain is configured as *.somedomain.com  —> work mode 2 (PLEASE note that * is the actual asterisk character here)
             if console proxy suffix domain is configured as xyz.somedomain.com —> work mode 3

When we give out console access URL to client,  the URL should be configured per current console proxy working mode

             work mode 1                     —> http://<ip>.<ip>.<ip>.<ip>/xxxxxx
             work mode 2                     —> https://<ip>-<ip>-<ip>-<ip>.somedomain.com/xxxxx
             work mode 3                     —> https://xyz.somedomain.com/xxxxx



SSVM refers to realhostip.com to form some URLs - like URLs for template download, extract and copy. SSVM already supports the ability to turn on or off SSL support, via the parameter secstorage.encrypt.copy.
Configuration parameter secstorage.ssl.cert.domain, as per https://issues.apache.org/jira/browse/CLOUDSTACK-2940 , is used to configure for SSL case. To keep things consistent with console proxy, the configuration parameter expects a value of the form "*.somedomain.com" for customization.

The Java Keystore for SSVM agents is updated as well when a SSL certificate is uploaded via the UI or API. The UI option is under Infrastructure tab. For API, please refer to the documentation for uploadCustomCertificate API relevant to your CloudStack version. The format of the certificate is same as that of the Console Proxy VMs, please refer to the documentation section "Replacing realhostip with your domain" in the CloudStack Admin Guide for steps to generate the correct format for certificates.

Implementation change here is minimal, of handing out the correct domain URL for the above mentioned tasks.

Fresh Installation

For fresh installs, console proxy will, by default, work in HTTP mode. Same is the case with SSVM.


Previously, only wildcard-based custom domains (workmode 2 above for Console Proxy, and secstorage.ssl.cert.domain for SSVM) were supported. Hence, the DB upgrade script maintains consistency by converting the existing domain values say, somedomain.com, to *.somedomain.com. People who wish to use the new features may modify this value to suit their needs after the upgrade.

Doc changes


As of now this is how it works and will need update to KB:

Console Proxy

     (a) if empty use HTTP (NEW)
     (b) if *.somedomain.com , use HTTPS like today. Change being instead of specifying somedomain.com, we will explicitly need the wildcard
     (c) if xyz.somedomain.com, use HTTPS with a LB pointing xyz…. To console proxy IPs (NEW)

NOTE : The Load Balancer case is not implemented fully in the current release. Ideally, CS should have the functionality of configuring LB and the console proxy IPs automatically, in such a way that needs no change on LB to map the IPs. This is not implemented yet.

To test this case, one can set-up a LB with a mapping to an already running console proxy IP or IPs, and test the console access.


secstorage.encrypt.copy to turn on SSL.

secstorage.ssl.cert.domain to customize the domain name. If domain is empty or null, the above SSL setting will be ignored and a warning will be thrown.


Provide the full certificate path for the System VMs if you are using a certificate from
an intermediate CA. The certificate path begins with the certificate of that certifying entity, and each certificate in the chain is signed by the entity identified by the next certificate in the chain. The chain terminates with a root CA certificate. For browsers to trust the site's certificate, you must specify the full chain: site certificate, intermediate CA, and root CA. Use the uploadCustomCertificate API calls for each level of the
chain. The certificate and private key parameters need to have the full text in PEM encoded format. For example:
'certificate':'-----BEGIN CERTIFICATE----- \nMIIDYTCCAkmgAwIBAgIQCgEBAQAAAnwasdfKasd

TIP : The information in this blog post is good to have, for real-life SSL scenarios : http://www.chipchilders.com/blog/2013/1/2/undocumented-feature-using-certificate-chains-in-cloudstack.html

Creating your own chained certificate for testing

This is meant for testing purposes only, for the lack of a better way without obtaining an actual intermediate CA. In essence, the process is to :

  1. Create your own root CA
  2. Create your own intermediate CA, who is signed by the root CA
  3. Create your domain specific certificate request, and sign it using the intermediate CA
  4. Upload all the above in CloudStack
  5. Optionally, you will need to add the root CA and intermediate CA in your browser. NOTE that if you created the above using openssl on your machine, they would exist in the OS as well. Hence, a good way to test it is to create the above on a different machine.

For step 1 : https://jamielinux.com/articles/2013/08/act-as-your-own-certificate-authority/

For step 2: https://jamielinux.com/articles/2013/08/create-an-intermediate-certificate-authority/   (BEWARE of a typo in the blog. Refer to the comments section below it)

For step 3: https://jamielinux.com/articles/2013/08/create-and-sign-ssl-certificates-certificate-authority/

For step 4 : http://www.chipchilders.com/blog/2013/1/2/undocumented-feature-using-certificate-chains-in-cloudstack.html  (You may also use CloudMonkey instead of the python API mentioned)

For step 5 : Follow your browser / OS specific steps.

Obtaining certificate for testing

There are free trial certificates available for testing things out. Unfortunately, they don't allow for a wilcard-certificate. Hence, to do some testing you can :

Step 1 : Set-up your CloudStack environment - zones etc.

Step 2 : Obtain the public IP of your SSVM to act as source for all operations - say

Step 3 : Generate a CSR using openssl or any other tool, following procedure in admin guide for replacing your own domain. For the CSR, use "10-10-10-10.mytestdomain.com" as the Common Name (replace testdomain with any domain you are using). Use US as country, California as state, Santa Clara as city (or just replace with your favorite state and city - just make sure they are real ones)

Step 4 : Go to http://www.symantec.com/verisign/ssl-certificates# , select Trial version for "Secure Site SSL Certificates"

Step 5 : Give YOUR e-mail ID (certificate will be sent there), use CSR generated in step 3

You should get a certificate in your e-mail. Use the certificate to upload. Note that it is NOT a wild-card certificate, and hence some functionalities like Console Access etc may throw errors. However, from the SSVM whose IP you have used, you should be able to dowload templates and issue copyTemplate command to (i.e. this SSVM as source for copy)

*Please* note that these free certs are signed by a Trial CA authority, and hence not trusted by default. Refer to the additional steps in the e-mail sent by Symantec for details

  • No labels