[cloudstack-documentation] branch main updated: Add CreateConsoleEndpoint docs (#284)

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

rohit pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/cloudstack-documentation.git


The following commit(s) were added to refs/heads/main by this push:
     new d692aa7  Add CreateConsoleEndpoint docs (#284)
d692aa7 is described below

commit d692aa722224d528a3c819238b70d412f6ccaebf
Author: Nicolas Vazquez <ni...@gmail.com>
AuthorDate: Wed Sep 14 04:10:35 2022 -0300

    Add CreateConsoleEndpoint docs (#284)
    
    * Add CreateConsoleEndpoint docs
    
    * Format
    
    * Update systemvm.rst
    
    * Update systemvm.rst
---
 source/adminguide/systemvm.rst | 53 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/source/adminguide/systemvm.rst b/source/adminguide/systemvm.rst
index c190a13..fd6c34c 100644
--- a/source/adminguide/systemvm.rst
+++ b/source/adminguide/systemvm.rst
@@ -194,6 +194,57 @@ the capacity to handle new sessions is used.
 Console proxies can be restarted by administrators but this will
 interrupt existing console sessions for users.
 
+Creating a VM Console Endpointy
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The access to a VM Console is created by the API 'createConsoleEndpoint', 
+for the VM specified in the parameter 'virtualmachineid'. By default, 
+the CloudStack UI connects to the URL that this API generates.
+
+The response of the 'createConsoleEndpoint' API also contain the information 
+to create a websocket session to the VNC server on the console proxy, this 
+infomation includes: the host, port, path and token parameters required to 
+establish a websocket session, bypassing the VNC client on the console proxy.
+
+It is possible to add extra validation for the console proxy authentication, 
+with the following configurations:
+
+- ‘consoleproxy.extra.security.validation.enabled’: Enable/disable extra security 
+  validation for console proxy using a token
+
+When ‘consoleproxy.extra.security.validation.enabled’ is true: then CloudStack 
+requests the ‘token’ parameter to the ‘createConsoleEndpoint’ API. The console URL 
+retrieved on the API response includes an ‘extra’ parameter for users validation on 
+the console proxy. 
+
+When the console proxy receives a request including the ‘extra’ parameter it 
+will decode the ‘token’ parameter and uses the original token to compare it with 
+the ‘extra’ token. Only in case both matches, then the console access is allowed. 
+   
+When ‘consoleproxy.extra.security.validation.enabled’ is false: then CloudStack 
+does not require a token for validation.
+
+The websocket port is passed as a boot argument to the console proxy and the 
+management server decides between the secure or unsecure port (8443 or 8080) when 
+setting the boot arguments for the CPVM.
+
+- The secure port 8443 is sent as a boot argument when:
+
+   - The setting ‘consoleproxy.sslEnabled’ is true
+   
+   - The setting ‘consoleproxy.url.domain’ is not empty
+   
+   - There is a record on the ‘keystore’ database with name ‘CPVMCertificate’
+
+- In any other case, then the port 8080 is selected
+
+
+Administrators must ensure a new console proxy VM is recreated after changing 
+the value of any of the settings. Once the console proxy VM is recreated, 
+the new VNC server port will be used as the websocket traffic port. The console proxy 
+VM startup will also ensure a new iptable rule is added for the new VNC port, 
+allowing the traffic on it.
+
 
 Using a SSL Certificate for the Console Proxy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -950,4 +1001,4 @@ generated diagnostics data files and are as follows:
 
   Sets the secondary storage disk utilisation percentage for file retrieval.
   An exception is thrown when no secondary store is found with a lower capacity
-  than the specified value. The default value is 0.95 (95 %).
\ No newline at end of file
+  than the specified value. The default value is 0.95 (95 %).