(Update: Upgrading to guac 0.9.4)
(UPDATE: Guac 0.9.2 is out and I'm running it and very satisfied. These instructions work equally well with 0.9.2 you simply need to change "0.9.0" to "0.9.2" in the requisite spots in the instructions below. I also wrote nodetitle which covers how to upgrade an existing guac instance to 0.9.2.)
Guacamole is an open source (MIT licensed, so it's "free", see my recent Open Source Licensing post on this), clientless RDP solution that runs in any HTML5 browser (which is any browser from the last few years). Why do you need this or should you care? If you need to remotely connect over the internet to Windows servers (you deal with small clients or your home network) and you don't want to open up Port 3389 (the default RDP port) then guacamole is an excellent choice. If you currently have Port 3389 open I suggest closing it. I can tell you that every script kiddie out there has password crackers that attempt to brute force attack against open, internet-facing RDP ports.
Guacamole runs on Java/tomcat/Linux on your internal network that then serves up the RDP session via Port 80/443. So, it's a gateway. Then why not use /tsweb and IIS that comes with Windows Server? Because /tsweb still uses Port 3389 to connect, /tsweb merely allows the client to be downloaded from a website.
With guac no new ports need to be open so it should be much more secure. Since it doesn't need a client (other than a HTML5 browser) you should be able to connect to your Windows machines from anywhere on the planet including iPhones and Android devices. You can certainly use something like LogMeIn (which costs a few bucks) or OpenVPN (free, but takes some time to setup and still requires a client) to accomplish secure remote access. Guacamole is just another tool in your toolbelt. Guacamole is my solution of choice because it is fast, requires about 256 MB of RAM in a Hyper-V and takes only a few minutes to set up.
The guacamole install manual, like most OSS, is not user-friendly if you are not a Linux wizpert. In fact, if you follow the manual you will end up installing an ancient version which does not handle logging in to "modern" Window boxes (Windows 2012/WIN8 has new NLA security features with RDP). So, this post will show how to setup a VM on your Hyper-V server to host Guacamole. I assume you understand the absolute basics of VMs and ubuntu. You need no knowledge of tomcat or Java. In fact, you really don't even need to know ubuntu if you can type text without too many typos.
- Install Ubuntu (14.04 is best as of this writing) in your VM. Patch it (
sudo apt-get update;sudo apt-get upgrade), give it a static IP address.
sudo apt-get install make libcairo2-dev libpng12-dev freerdp-x11 libssh2-1 libfreerdp-dev libvorbis-dev libssl0.9.8 gcc libssh-dev libpulse-dev tomcat7 tomcat7-admin tomcat7-docs These are the standard packages you'll need.
sudo apt-get install libpango1.0-dev libssh2-1-dev
wget -O guacamole-server-0.9.0.tar.gz http://sourceforge.net/projects/guacamole/files/current/source/guacamole-server-0.9.0.tar.gz/download. We can't use apt-get because it is currently serving up Guacamole 0.6.0 which doesn't work well with Windows 2012 or Win8. Instead, we get the source code from sourceforge directly (you may want to see if there is something newer than 0.9.0 since improvements are being made to guacamole weekly).
wget -O guacamole-0.9.0.war http://sourceforge.net/projects/guacamole/files/current/binary/guacamole-0.9.0.war/download
sudo tar -xzf guacamole-server-0.9.0.tar.gz
./configure --with-init-dir=/etc/init.d This will configure autostart on reboot for the necessary services.
sudo make install
sudo update-rc.d guacd defaults This sets the autostart for the default runlevels.
sudo ldconfig (that is ell dee config. It essentially loads your config changes)
sudo mkdir /etc/guacamole
sudo nano /etc/guacamole/guacamole.properties //enter the items from the screenshot at the right
- Ctl+O (writes out the changes)
- Ctl+X (exits nano, the text editor)
sudo nano /etc/guacamole/user-mapping.xml (a sample is to the right). There are so many options for rdp that you can use that you should probably eventually read the user-mapping documentation. You can start apps directly using remote-app and you can autologin using username/password. I use guacamole to remotely connect to my Linux boxes using ssh too, without opening ssh ports (22) or having an ssh client on my android devices. You can also use guacamole as a clientless VNC gateway too.
- Ctl+O (writes out the buffered changes)
- Ctl+X (exits the editor)
sudo mkdir /usr/share/tomcat7/.guacamole
sudo ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole
sudo cp guacamole.0.9.0.war /var/lib/tomcat7/webapps/guacamole.war
sudo service guacd start
sudo service tomcat7 restart
- Open a browser on your local network and navigate to
http://<ipaddress>:8080/guacamole. Login with your credentials from user-mapping.xml. At this point you've got a working guacamole rdp gateway server.
Any errors you may get will be "Invalid login" at this point. This is the generic error message. The errors will likely be a typo in either the .properties file or the user-mapping.xml file. You can find the logs at sudo nano /var/log/tomcat7/catalina.<today>.log. There isn't much that can go wrong other than typos. Doublecheck the two hand-crafted files we created above.
At this point guacamole is working but it is listening in on port 8080. If you are OK with that then poke a hole in your firewall/router and you can begin using guacamole. Read on for some additional improvements you can make to guacamole...
Backing up your guacamole server
There's not much to backup on your guacamole server, other than config files, so I like to use git for things like this. If it's easier you can just take a snasphot of your vm too and save it off somewhere. For Git:
sudo apt-get install git
cd /etc/guacamole //this contains your .props file and user-mapping.xml
sudo git init //not necessary unless you want to push to your git repo server
sudo git add guacamole.properties
sudo git add user-mapping.xml
sudo git config --global user.email ""
sudo git config --global user.name ""
sudo git commit -m 'initial configuration'
sudo git remote add origin ...
sudo git push -u origin master //again, not necessary
I want guacamole to be available on <main web server>/guacamole, not on Port 8080
In other words, you want guacamole to be served up by your standard webserver in a folder there, not on a separate tomcat webserver running guacamole. This is a fairly simple mod. On your main webserver you need to create a folder that is used to proxy to your guacamole server. I assume your main webserver is also Apache, if not you'll have to do some research on your webserver to determine how to proxy to another webserver under the same namespace (ARR in IIS for instance). In your Apache http.conf (or equiv) file you'll need these entries
# /guacamole settings
ProxyPass /guacamole http://<guac ip>:8080/guacamole
ProxyPassReverse /guacamole http://<guac ip>:8080/guacamole
Allow from all
Restart Apache and you should be able to use guacamole on your main webserver by browsing to /guacamole, using standard Port 80. No changes needed to the guac installation for this. The ProxyPass simply tells apache that when requests come to /guacamole that they should be rerouted to the guac server on a different port. ProxyPassReverse handles rewriting the headers on the response from guacamole so the client doesn't get confused. Remember, guac, in this configuration, does not know it is directly attached to the internet because we did not set a hostname anywhere.
At this point it is also advisable to set up SSL encryption if you deem it necessary. SSL only needs to be setup on your main webserver, not on the guac server. So if you have SSL working already the proxying will work transparently with nothing else to do. You can definitely run guac without https just be aware that you are taking a bit of a risk.
I do a lot of consulting for small mom-and-pop shops that can't afford expensive IT infrastructure. When I need to connect to their internal resources the easiest way to do this is to set up a VM with guacamole on it. Formerly I used LogMeIn but that isn't free anymore. OpenVPN is an excellent choice but it requires a client and a VM that acts as the gateway, plus a hole in the firewall for OpenVPN. Guac needs none of this. Once you setup a guac VM you can save the vhdx file (or equiv if you are using another virtualization technology) and then you have a quick guac server for your next client. Big time saver...no cost.
You have just read "Guacamole: A clientless RDP gateway" on davewentzel.com. If you found this useful please feel free to subscribe to the RSS feed.