API-driven Console Access l CloudStack Feature First Look



The Apache CloudStack Console Proxy (CPVM) is a type of system virtual machine that presents an Instance’s console view via the web UI (connecting to the VNC port made available through the hypervisor). Both the admin and end-user web UIs offer a console connection.

To provide access to the Instances console service, the CPVM has the following characteristics:
• An HTTP server listens to incoming requests from browsers.
• A TCP client to connect to the Instance’s VNC port when requested.

The CPVM provides a proxy between the user’s browser and the Instance’s console, allowing interaction with the user’s input devices (ie. keyboard, mouse) and the Instance operational system through an encapsulated VNC connection.

To clarify the inner workings in previous CloudStack versions, a sequence of events is triggered when a user launches the console in the UI:

1. User initiates a console session by accessing the URL: <MGMT_SERVER_IP>:<PORT>/client/console&command=access&vm=<VM_ID>
2. The Management Server chooses a suitable CPVM and creates a token ticket for the user.
3. The Management Server sends HTML content including the token and a redirection URL to the user’s browser.
4. The user’s browser requests the console to the CPVM via HTTP protocol using the redirection URL.
5. The CPVM check the user token to identify the user’s session.
6. The CPVM connects to the hypervisor via VNC and presents the session to the user encapsulating the VNC console over HTTP.

API-driven Console Access

Apache CloudStack 4.18 introduces a new way to access an Instance’s console, extending the previous diagram to easily integrate CloudStack with other services. The console access is now triggered through a new API call “createConsoleEndpoint”. The API response returns the console URL and a one-time token to avoid replay attacks so that the user can securely connect to the Instance’s console. The generated URL will be only used once per session, ensuring that other users intercepting the generated URL will not be able to access the Instance’s console once the token has been authenticated on a session.

Furthermore, this new improvement allows users to easily obtain the console URL and access it through different UI interfaces. With the previous approach, the URL had to be extracted from the returned HTML page. Also, the API response includes WebSocket information to allow WebSocket clients to directly connect to the CPVM and display the Instance’s console.

API changes

The new “createConsoleEndpoint” API call accepts two parameters:
• virtualmachineid: The UUID of the virtual machine to access the console
• token (optional): A security token for extra validation on the console proxy VM

The “createConsoleEndpoint” API has the following response fields:
• result (true/false): indicates the success of the console access operation
• details – in case result=false, describes the error
• url – the default web URL to be used to connect to the console
• websocket: (a nested object that provides information for WebSocket connections)
o host: the WebSocket host IP
o port: the WebSocket port
o path: the WebSocket path
o token: the WebSocket token
o extra: (only if the extra validation has been enabled) the extra security token to be validated by the console proxy)

Secure WebSocket traffic port

With this new feature, the admin can now enable secure WebSocket traffic between CPVM and end-users. By default, the unencrypted 8080 TCP port is used and when enabled, TCP port 8443 is used instead. To enable a secure WebSocket, set “consoleproxy.sslEnabled” variable in the Global Settings to “true” and follow the additional steps for TLS/HTTPS configuration.

To perform TLS/HTTPS configuration, follow this ShapeBlue article: https://www.shapeblue.com/securing-cloudstack-4-11-with-https-tls/. After applying the new configuration, you will need to recreate the CPVM.


This improvement allows CloudStack to integrate with third-party applications, enabling a way to display the Instance’s console in different UIs without compromising security requirements. For deployment, where the CloudStack UI is replaced by a business dashboard, the loophole regarding console access has been addressed by adding an API response instead of an HTML code with a redirection URL.

This new functionality is available as of Apache CloudStack 4.18 LTS.