Documentation

Skip to end of metadata
Go to start of metadata

Using noVNC in Abiquo 3.8+

Client: By default the Abiquo client UI has an integrated noVNC viewer. The noVNC viewer is an HTML5 VNC viewer. You can brand the noVNC viewer for your platform. See Branding noVNCAs part of each Abiquo upgrade process, check your noVNC branding.noVNC does not support user specified keyboard mappings, so settings in the UI client will not be taken into account. You must configure the noVNC settings for the Abiquo client UI to connect to the proxy. See Configure Remote Access to Virtual Machines

Proxy: noVNC requires a proxy to forward websocket requests to traditional sockets. The proxy should be installed on a separate machine from any other Abiquo service.  Every VNC connection will be to the same IP and port on the proxy, but Abiquo will provide a unique token for each VM that will tell the proxy where to connect. A script is run with a cron job to obtain VM information from the Abiquo API and update the tokens and configure the proxy.

Hypervisor: For ESXi, you must define the VNC ports. And you must define a password for VMs in ESXi in order to be able to connect.

Load balancing: If you require more than one websockify proxy for a large environment, you can use a load balancer. See Load balance websockify proxy

Websockify proxy

Because noVNC uses websockets to establish connections, instead of traditional sockets, we will need to set up software that will forward these requests. Moreover, this software can also act as a proxy for VNC connections, so you only need to expose one IP/Port to the Internet, and through this, you can connect to any VM on your Abiquo platform.

Ports and communications

  • By default the Abiquo client GUI requires access to the websockify proxy at its public IP address on port 41337
  • The websockify proxy requires access to the Abiquo API on port 80 or port 443 if SSL is used
  • The websockify proxy also requires access to the management network address of every hypervisor in your infrastructure and its VNC port range

noVNC and websockify configuration diagram

Note that the diagrams on this page do not show the firewall or DMZ because their use depends on your security policy.

Client-side configuration

In the Abiquo user interface, the noVNC default remote access application requires the following new properties that were added to client-config-default.json.

"client.remoteaccess.novnc.host": "",
"client.remoteaccess.novnc.port": "41337",

You can customize these values in client-config-custom.json to point to your proxy server or a load balancer, for example.

Install Abiquo websockify package

  • Make sure you have cron installed and crond service is running

  • On the websockify server, install abiquo repositories

    This installs base and update repositories. Please locate the abiquo-release-ee package of your destination version and install it with the following command. This example is for the latest Abiquo major version of 3.8.

    yum localinstall http://mirror.abiquo.com/abiquo/3.8/os/x86_64/abiquo-release-ee-3.8.0-2.el6.noarch.rpm

    Update yum cache

    yum clean all && yum makecache

    Install the Abiquo websockify package

    # yum install abiquo-websockify
  • The package contains a script to create tokens for each VM proxy connection. The script that obtains the VM information from Abiquo and creates the tokens is called novnc_tokens.rb

  • The package will create a cron task in /etc/cron.d/novnc_tokens to keep the token list up to date:

    # VNC Proxy (set to run every minute in the example)
    #
    # -a: The API URL to connect to. Should be the same as abiquo.server.api.location property in abiquo.properties file.
    # -u: The username that will be used to interact with the API. Requires a role with following privileges: 
    # USERS_MANAGE_ENTERPRISE, ENTERPRISE_ADMINISTER_ALL, VDC_ENUMERATE, VAPP_CUSTOMIZE_SETTINGS
    # -p: The password for the user
    # -f: The file the results will be written to
    #
    * * * * * root /opt/websockify/novnc_tokens.rb -a http://localhost/api -u admin -p xabiquo -f /opt/websockify/config.vnc
  • Check that the command is correctly configured with your API IP address, Abiquo credentials, etc.
  • The script outputs a file that is used to configure the websockify daemon. This file will contain one line for each VM with the format "HASH: DST_IP:DST_PORT":

    [root@localhost ~]# cat /opt/websockify/config.vnc
    4cc06e6c0d41937e605472601c19a097: 192.168.2.54:5908
    ....
  • If you are using SSL on your platform, then you must also configure the websockify server with SSL.

Configure SSL

Browsers do not allow you to open an unencrypted websocket connection from a page that is accessed using SSL for security reasons. Hence, if you set up SSL to access your Abiquo GUI, you must set up websockify to use SSL.

For that, you will need an SSL certificate and its private key. Note that this certificate needs to be accepted by the client browser, so they should be emitted by a trusted entity. Also check that the hostname that noVNC connects to matches the hostname in the certificate used. If you are testing a test environment which lacks a trusted certificate, you may need to manually open a connection to the IP and port the proxy is running in using your browser, and accept the provided certificate.

NOTE: Certificate must be a bundled certificate that contains all intermediate certificates from the server certificate to the CA root certificate.

-----BEGIN CERTIFICATE-----
websockify server proxy contents...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CA intermediate certificate contents...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
CA root certificate contents ...
-----END CERTIFICATE-----

Edit the script /etc/init.d/websockify and set the proper cert and key file by modifying the lines, to point to your cert and key files.:

CERT_FILE=/etc/pki/tls/certs/localhost.cert
KEY_FILE=/etc/pki/tls/certs/localhost.key

 

Start websockify

To start the proxy, use the following command.

service websockify start

Websockify should now be listening for VM connections on port 41337.