Using noVNC in the current version of Abiquo

By default Abiquo has an integrated TightVNC applet viewer to provide remote connections to VM consoles. This can be changed to noVNC, an HTML5 VNC viewer, by following the steps below.

Caveats

• You must add a proxy to forward websockets requests to traditional sockets. This proxy should be installed on a separate machine from any other Abiquo service.
• You must define a password for VMs in ESXi in order to be able to connect.
• At the time of writing, noVNC does not support user specified keyboard mappings, so these will not be taken into account.

Background

Because noVNC uses websockets to establish connections, instead of traditional sockets, we will need to set up an additional piece of 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.

The proxy we will use is called websockify and it is included in the noVNC distribution package. This software should run on a separate machine from any other Abiquo service. It requires public IP addressing and access to port 41337 from the Abiquo Server where client-premium is running, access to Abiquo API and access to every hypervisor in your infrastructure (just like the vncproxy) and its VNC port range. 

As we are going to replace part of the platform, some small changes will be needed in order for all of this to work with the current release of Abiquo.

Prerequisites

On the dedicated server where websockify will run, you'll need python and three modules installed:

• numpy (to improve performance)
• ssl (to run websockify over SSL, which is mandatory if you are accessing the Abiquo GUI using SSL)
• note: if you are using Python 2.6 or later, ssl may be already built in  
• multiprocessing (to allow multiple connections at a time).

# python setup.py install

Install noVNC proxy

Download the noVNC distribution package from: http://kanaka.github.com/noVNC/

# wget http://github.com/kanaka/noVNC/tarball/master
# tar xvzf master
# ls -l
 total 716
 drwxrwxr-x 8 root root 4096 Apr 4 16:22 kanaka-noVNC-c2b1409
 -rw-r--r-- 1 root root 724988 Apr 5 04:21 master

Almost every file we are going to need is included in the kanaka-noVNC-????? directory (the last part of the name can change with the version of the package).

On the websockify server, we just need to copy the "utils" folder:

# cp -r kanaka-noVNC-c2b1409/utils /opt/
# mv /opt/utils /opt/websockify

Every VNC connection will be to the same IP and port (websockify IP and default port), but we will provide a unique token for each VM that will tell the proxy where to connect. To create the token, we will use the IP and port that Abiquo passes to the tightvnc applet to generate an md5 hash of the string "IP:PORT". So for a VM that has VNC listening at IP 192.168.2.54 and port 5908, we will calculate the md5 hash of the string "192.168.2.54:5908" to be used as a token.

The proxy needs to know these hashes and destination addresses beforehand, in order to route the requests. 

To set this up, download the novnc_tokens.rb script. To be able to run this script you will need to install some packages:

# yum install ruby rubygems ruby-devel libxml2-devel.x86_64 libxslt-devel.x86_64 make

Install some ruby gems:

# gem install rest-client
# gem install nokogiri
# gem install libxml2 

Run the command manually to check that it is working fine and set up a cron task to keep the token list up to date:

# VNC Proxy (set to run every minute in the example)
* * * * * root /root/novnc_tokens.rb -a http://10.60.13.4/api -u admin -p xabiquo > /opt/websockify/config.vnc

The script requires 3 parameters:

• -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 CLOUD_ADMIN role.
• -p: The password for the user.

The output is then redirected to a file that will be used as a config file for 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
....

Now that everything is in place, we can run the proxy:

# /opt/websockify/websockify -D 41337 --target-config=/opt/websockify/config.vnc

The -D flag is to daemonize websockify, 41337 is the port where websockify will be listening, and --target-config specifies the file containing the hash to IP and port mappings.

Adding 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.

To run the websockify proxy with SSL, enter:

# /opt/websockify/websockify -D 41337 --target-config=/opt/websockify/config.vnc --cert=<path_to_your_cert_file> --key=<path_to_your_key_file>

Replacing TightVNC applet with noVNC in the client-premium webapp

Download the noVNC distribution package from: http://kanaka.github.com/noVNC 

Note that this is the same package we used for the websockify

# wget http://github.com/kanaka/noVNC/tarball/master
# tar xvzf master
# ls -l
 total 716
 drwxrwxr-x 8 root root 4096 Apr 4 16:22 kanaka-noVNC-c2b1409
 -rw-r--r-- 1 root root 724988 Apr 5 04:21 master

To replace the tightvnc applet without changing any code in Abiquo, we will need to rename tightvnc to back up this file and replace the tightvnc file with the noVNC one.

# cp -r kanaka-noVNC-c2b1409 /opt/abiquo/tomcat/webapps/client-premium/
# cd /opt/abiquo/tomcat/webapps/client-premium/
# mv tightvnc tightvnc.old
# mv kanaka-noVNC-c2b1409 tightvnc

Download the tarball with the required files for the next steps from http://download.abiquo.com/extras/abiquo-novnc.tar.gz.

We will use the vnc_auto.html file from noVNC but with some changes. Place the tightvnc.html file under /opt/abiquo/tomcat/webapps/client-premium/tightvnc/. Now you will need to edit this file to suit your environment. Edit the file and change the following values to contain the websockify public IP and port the proxy will be listening on:

host = "8.8.8.100";
port = 41337;

Also place .js files under /opt/abiquo/tomcat/webapps/client-premium/tightvnc/include.

Finally, you will need to restart the abiquo-tomcat service on your Abiquo management server.

Load balancing the websockify proxy

You can run multple websockify proxies to spread load and achieve high availability of the remote console viewers. Follow the instructions above on "Replacing TightVNC with noVNC in Abiquo" to get several proxies running. For the sake of simplicity this document refers to 2 backend servers running the websockify proxy and one load balancer using HAProxy.

Installing HAProxy

You will need the gcc compiler and make to compile HAProxy.

# yum -y install gcc gcc-c++ make

Next download and uncompress the HAProxy tarball:

# wget http://haproxy.1wt.eu/download/1.5/src/devel/haproxy-1.5-dev18.tar.gz
# tar xzf haproxy-1.5-dev18.tar.gz

Change to the extracted directory, then compile and install HAProxy.

# cd haproxy-1.5-dev18
# make TARGET=linux26
# make install

Configuration file

Once haproxy is installed, create its config file, /etc/haproxy.cfg with the following contents:

global
 log 127.0.0.1 local0

frontend public
 bind *:41338
 timeout client 3600s
 default_backend ws


backend ws
 balance source
 timeout queue 3600s
 timeout server 3600s
 timeout connect 3600s
 server websockify1 192.168.2.218:41337 weight 1 maxconn 1024 check
 server websockify2 192.168.2.219:41337 weight 1 maxconn 1024 check


listen stats
 bind *:80
 mode http
 stats enable
 stats uri /admin?stats
 stats refresh 5s
 stats auth admin:xabiquo
 timeout client 3600s
 timeout server 3600s
 timeout connect 3600s

To activate logging, create /etc/rsyslog.d/20-haproxy.conf file with the following content:

local0.*         /var/log/haproxy.log

And reload the rsyslog daemon:

# service rsyslog reload

Note that the previous configuration file also enables the HAProxy stats page on http://<your_balancer_address>/admin?stats with authentication credentials  user: admin and password: xabiquo.

Starting haproxy

Run haproxy from the command line by typing:

# haproxy -f /etc/haproxy.cfg

To run haproxy as a daemon, download the attached haproxy script and copy it to /etc/init.d/ directory. Change permissions to 755, and you can perform the following commands:

# service haproxy {start|stop|restart|reload|condrestart|status|check}

Set it up to start at boot with:

# chkconfig haproxy on