Guacamole -- HTML5 based RDP/VNC/SSH Connections

This guide is no longer maintained. Check out my new Guacamole guide for CentOS 7 HERE!

In my quest to simplify my technical life, I have been entertaining the idea of retiring my laptop and buying a Chromebook. From a hardware perspective, Chrome OS is mostly web based and doesn't require much for end user hardware. Not to mention the low price of $200-250 for a Samsung Chromebook, I would much rather buy one of those every few years instead of a new $1,000 laptop. At first thought, I was certain that a Chromebook would not allow me to do everything I need to do from a laptop. My primary use on a laptop is for web based applications and browsing, email, Office, and RDP. RDP is very important for me so that I can manage the 25-30 Windows based devices on my network. I currently use Devolution's Remote Desktop Manager, which is a very nice piece of software. It manages all of my RDP connections, as well as SSH connections, certain websites (i.e., Webmin), and organizes it all with saved credentials. I have my RDM profile stored via FTP on a server at home, so my config is always up to date from any computer that I used RDM from, which is the nicest feature in my opinion.

With researching a Chromebook, I have discovered that HTML5 based RDP apps are a thing. Who knew??! From some basic testing, they seem to work pretty well. Chrome RDP is a Chrome App that allows for a simple RDP connection, and you can save your list of connections, but for me there are three faults. Can't save credentials, doesn't support NLA (Network Level Authentication) and can't use RD Gateway. I have a RD Gateway in place, so that is very important for me, so that's a deal breaker. With a little bit of research, I found a few HTML5 RDP products that have their own Gateway server that I would put on my network, so I could access a website, login (with LDAP integration, mind you), and click on the connection I want and it would log me in via RDP (or SSH, or VNC) to a server on my internal network. This is great!

There are a few products out there, but I like Open Source because I'm cheap. Guacamole seems to be the logical choice, from a pure research perspective. It seems to do what I am looking for, so I decided to set it up. Here's how I did it. So since my personal environment at home runs on Hyper-V, and Guacamole runs on Linux, I decided to use CentOS 6 since it just works with Hyper-V (CentOS 6, as well as RHEL, now include Hyper-V drivers so no more installing Integration Components and not having mouse support). So I spun up a new VM (20GB dynamically expanding HDD, 1 vCPU, 2GB of static RAM, and 1 NIC on my LAN), installed CentOS 6, and enabled SSH; very basic setup. So let's build this from source! **Note, I am also installing the MySQL Authentication package which allows me to store connections and authentication information in a database, instead of a plain-text XML file.

Let's Get Started!

1.) Prerequisites:
arch=$(uname -p)
rpm -Uvh$arch/epel-release-6-8.noarch.rpm
yum -y install wget
mv home\:felfert.repo /etc/yum.repos.d/
yum -y install tomcat6 libvncserver freerdp libvorbis libguac \
libguac-client-vnc libguac-client-rdp libguac-client-ssh \
cairo-devel pango-devel libvorbis-devel openssl-devel libssh-devel \
pulseaudio-libs-devel libvncserver-devel java-1.7.0-openjdk.x86_64 \
freerdp-devel uuid-devel libssh2-devel libtelnet libtelnet-devel \
tomcat6-webapps tomcat6-admin-webapps

The above is going to first set the architecture variable (I am using x86_64) and add the EPEL repo as well as the felfert repo, which contains some of the prereqs we need. Finally, it's installing all of the packages we need for Guacamole to work, as well as all the dev tools we need to compile from source.

2.) Download & Compile Binary
mkdir guacamole
cd guacamole
tar -xzf guacamole-server-0.9.5.tar.gz
cd guacamole-server-0.9.5
./configure --with-init-dir=/etc/init.d
make install

The above is going to make a new directory, download the binary, tar, and load the configure script that is included. When this script runs it will echo the library status as well as what protocols are supported. With the above prerequisites, all library should be included and all three protocols (RDP, SSH, VNC) should be supported. Make and make install will create the package and install it for us, while ldconfig is clearing the library cache so that is fully up to date.

3.) Guacamole Client

The guacd (aka, Guacamole Server) service should have been created, but not yet started. The second piece is the Guacamole Client which is the web interface (aka, front end). We do not need to build this from source since the wonderful devs who work with Guacamole have released a .war file for us.

mkdir /var/lib/guacamole && cd /var/lib/guacamole/
wget -O guacamole.war
ln -s /var/lib/guacamole/guacamole.war /var/lib/tomcat6/webapps
4.) MySQL Authentication

We now have the Guacamole Server and Guacamole Client pieces installed. Next up is the MySQL Authentication piece.

rpm -Uvh
yum -y --enablerepo=remi,remi-test install mysql mysql-server
mkdir /root/guacamole/sqlauth && cd /root/guacamole/sqlauth
tar -zxf guacamole-auth-mysql-0.9.5.tar.gz
tar -zxf mysql-connector-java-5.1.34.tar.gz
mv /root/guacamole/sqlauth/mysql-connector-java-5.1.34/mysql-connector-java-5.1.32-bin.jar /root/guacamole/sqlauth/guacamole-auth-mysql-0.9.5/lib/
mkdir /var/lib/guacamole/classpath/
cp /root/guacamole/sqlauth/guacamole-auth-mysql-0.9.5/lib/* /var/lib/guacamole/classpath/
/etc/init.d/mysqld start

The above is adding the correct repos, installing mysql, downloading the needed .jar's, and moving them to where they belong. All but one jar file is included in the Guacamole MySQL Auth download, which is the MySQL Java Connector.

5.) Configure Database
mysqladmin -u root password MySQLRootPass
mysql -u root -p
create database guacamole;
create user 'guacamole'@'localhost' identified by 'guacDBPass';
grant select,insert,update,delete on guacamole.* to 'guacamole'@'localhost';
flush privileges;

The above will set your MySQL Root password (consider changing this, or feel free to use the one in my scripts), create the guacamole database, and create a user called guacamole with the needed permissions on the guacamole database.

6.) Database Schema
cd /root/guacamole/sqlauth/guacamole-auth-mysql-0.9.5/schema/
cat ./*.sql | mysql -u root -p guacamole

The above will run the .SQL scripts that are included with the Guacamole MySQL Authentication package to generate the neede tables and create the default administrator user.

7.) Configure Guacamole for Database Communication
mkdir /etc/guacamole
mkdir /usr/share/tomcat6/.guacamole
vi /etc/guacamole/

The above is creating our needed directories, and then creating the file. This file is what tomcat6 uses to know what port to talk to guacd on as well as how to access the database. Here is a basic file that will do what you need.

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# Location to read extra .jar's from
lib-directory:  /var/lib/guacamole/classpath

# Authentication provider class

# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacamole
mysql-username: guacamole
mysql-password: guacDBPass

This will configure guacamole to use the database and user that we created on the default port of 4822. Note, this is for internal communication only and is not the port that you will be accessing the web interface on. And we have to create a symlink so Guacamole can read the config file:

ln -sf /etc/guacamole/ /usr/share/tomcat6/.guacamole/
8.) Cleanup
cd /
rm -rf /var/lib/guacamole/classpath/schema
rm -rf /root/guacamole
chkconfig tomcat6 on && chkconfig mysqld on && chkconfig guacd on
/etc/init.d/tomcat6 restart && /etc/init.d/mysqld restart && /etc/init.d/guacd restart

Guacamole is now running, and is set to start at boot.

That wasn't so hard, now what is?? Now that everything is installed and configured, we can access our Guacamole install at http://<(IP OR SERVER NAME):8080/guacamole **Please note that iptables is probably running and won't allow you to access that IP from outside the local host. I disabled iptables for my install, for simplicity. You probably want to take a minute and configure iptables for optimal security. The default login information is:

  • Username: guacadmin
  • Password: guacadmin

Guac Login

Once logged in, you will see a green "Manage" button in the top right, which is where you go to configure users and connections.

Guac Manage Button

To add a new connection, click the green "New Connection" button in the middle of the screen. When creating an RDP connection for use with NLA, you have to have credentials stored, otherwise the connection will fail. Here is what my connections look like.

Guac Connection

I use 24 colors just because I don't notice a difference vs 32 colors on my 10" Chromebook screen, and performace is better. Here is an open connection to one of my Server 2012 Hyper-V hosts. This is connected over the internet (I use Dynamic DNS to a domain name I own, and also use Port Address Translation on my firewall, keeping port 8080 for internal, but external it is a different port). It connected in about 7-10 seconds, and that includes the time to log into the box. Overall, performance is great and I love it!

Guac Connected

So there it is. Give it a try and let me know what you think!