DaveWentzel.com            All Things Data


Guacamole 0.9.4

Posts about setting up guacamole (a client-less RDP Gateway) still tend to be the most read posts on my site.  guac let's you rdp to your desktop using a web-browser (or your mobile device).  Very handy.  You can also ssh and vnc as well.  In this post I'll cover how I upgraded guac 0.9.2 to guac 0.9.4 which was released earlier this month.  

My original post on setting up guac

My post on upgrading to 0.9.2

We are going to follow the steps in my original post on setting up guac.  Please refer to that as needed.  

  1. Backups are always prudent.  
  2. Do Step 4 and 5 in my original blog post but change the file name to 0.9.4.  
  3. Replace the old war file with the new version you just downloaded:  sudo mv guacamole-0.9.4.war /var/lib/tomcat7/webapps/guacamole.war
  4. Do Step 6-12.  
  5. Restart Ubuntu.  
  6. Close your browser and reopen it (otherwise the javascript from the old version will be cached and guac will act strangely).  
  7. Connect to your previous guac URL and log in.  

Seems to be a stable release.  Awesome piece of software...can't say enough good things.  

You have just read Guacamole 0.9.4 on davewentzel.com. If you found this useful please feel free to subscribe to the RSS feed.  

Upgrading Guacamole

Update:  Upgrading to guac 0.9.4

I wrote about Guacamole (a client-less RDP Gateway) a few months ago.  In that post I covered how to install Guacamole 0.9.0 on a Ubuntu server.  In this post I'll quickly cover how to upgrade 0.9.0 to guac 0.9.2.  Actually, this method should work for any guac upgrade.  

Firstly, what is guacamole?  Let's say you need to RDP (or even SSH or VNC) to a machine at a client site (or your home).  You can certainly use a VPN to tunnel the RDP traffic for port 3389.  Or you could poke a hole in your  firewall for 3389 (which is a bad idea).  Guacamole is a nifty alternative.  It runs on a Ubuntu VM (for one or two connections you need about 256MB RAM) allowing you to RDP to any server behind the firewall using HTTP(S) ports ONLY.  It's wicked fast and even works on a smartphone without having to deal with a VPN setup.  When you log in to your Guacamole server you pick which internal server you want to RDP to and you get a RDP session right in the browser.  To the right is a screenshot of an RDP session from IE 9.  It's like the mstsc client is right in your browser!  Below is a screenshot of a guac connection using my Galaxy S5...no VPN, no RDP app...you do it right from the browser.  

The Upgrade Process

Sometimes OSS like guacamole lacks documentation, or at least good documentation for noobs.  Guac doesn't have an official upgrade document so I worked out the kinks on my own.  

We are going to follow the steps in my original post on setting up guac.  Please refer to that as needed.  

  1. Take a backup of your VM or at least your .properties file and user file.  
  2. Do Step 4 and 5 in my original blog post but change the file name to 0.9.2.  
  3. Replace the old war file with the new version you just downloaded:  sudo mv guacamole-0.9.2.war /var/lib/tomcat7/webapps/guacamole.war
  4. Do Step 6 and 7.  
  5. I think there is a bug in make with guac where they reference uuid incorrectly, but I'm not the expert.  I didn't want to change the official configure script (which has lots of checkins regarding the uuid bug) so I got it to finally work by installing a few extra packages.  Run this command:  sudo apt-get install uuid osspd osspd-alsa osspd-dbg osspd-pulseaudio libossp-sa12 libossp-sa-dev ibossp-uuid16 libossp-uuid-dev libossp-uuid-perl
  6. Now you can run steps 8 - 12.  
  7. Restart Ubuntu.  
  8. Close your browser and reopen it (otherwise the javascript from the old version will be cached and guac will act strangely).  
  9. Connect to your previous guac URL and log in.  

I don't advocate upgrading software unless there is a compelling reason to do so.  Guacamole 0.9.2 anecdotally seems to be quite a bit faster than 0.9.0, especially over low-bandwidth connections such as Android tablets.  In all, I can't praise the guac team enough for this great piece of software.  I use guac daily for hours at a time and it just works perfectly.  

You have just read Upgrading Guacamole on davewentzel.com. If you found this useful please feel free to subscribe to the RSS feed.  

Guacamole: A clientless RDP gateway

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

The Process

  1. 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.
  2. 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.  

  3. sudo apt-get install libpango1.0-dev libssh2-1-dev
  4. 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). 
  5. wget -O guacamole-0.9.0.war http://sourceforge.net/projects/guacamole/files/current/binary/guacamole-0.9.0.war/download
  6. sudo tar -xzf guacamole-server-0.9.0.tar.gz
  7. cd guacamole-server-0.9.0
  8. ./configure --with-init-dir=/etc/init.d  This will configure autostart on reboot for the necessary services.  
  9. make
  10. sudo make install
  11. sudo update-rc.d guacd defaults  This sets the autostart for the default runlevels.  
  12. sudo ldconfig (that is ell dee config.  It essentially loads your config changes)
  13. sudo mkdir /etc/guacamole
  14. sudo nano /etc/guacamole/guacamole.properties  //enter the items from the screenshot at the right
  15. Ctl+O  (writes out the changes)
  16. Ctl+X  (exits nano, the text editor)
  17. 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.  
  18. Ctl+O  (writes out the buffered changes)
  19. Ctl+X (exits the editor)
  20. sudo mkdir /usr/share/tomcat7/.guacamole
  21. sudo ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole
  22. sudo cp guacamole.0.9.0.war /var/lib/tomcat7/webapps/guacamole.war
  23. sudo service guacd start
  24. sudo service tomcat7 restart
  25. 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
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 ...
//not necessary unless you want to push to your git repo server
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
    ProxyPassReverse /guacamole
    <Location /guacamole>
       Order allow,deny
       Allow from all
 # /guacamole settings
 ProxyPass /guacamole http://<guac ip>:8080/guacamole
 ProxyPassReverse /guacamole http://<guac ip>:8080/guacamole
 <Location /guacamole>
      Order allow,deny
      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.  

Subscribe to RSS - Guacamole