Friday, November 13, 2015

How to install Guacamole 0.9.8 for Ubuntu 14.04 and secure with Nginx ssl

Guacamole is a pretty straightforward RDP/VNC/SFTP utility that requires no plugins on client systems. It utilizes HTML5 to serve up the connections directly over a browser.

This is a pretty standard install to connect to a windows RDP host. We will be securing the server with UFW, fail2ban and SSL using NGINX as a reverse proxy.

First, enable the firewall and allow the following ports:

sed -i 's/ENABLED=no/ENABLED=yes/g' /etc/ufw/ufw.conf
ufw allow 22 && ufw allow 8080

Install the prerequisite software

apt-get update && apt-get install -y fail2ban build-essential htop libcairo2-dev libjpeg62-dev libpng12-dev libossp-uuid-dev tomcat7
apt-get install -y libfreerdp-dev libpango1.0-dev libssh2-1-dev libtelnet-dev libvncserver-dev libpulse-dev libssl-dev libvorbis-dev

Download and extract the guacamole server files

cd ~
tar -xzf guacamole-server-0.9.8.tar.gz && cd guacamole-server-0.9.8/

Compile and make the program (this may take some time depending on your hardware).

./configure --with-init-dir=/etc/init.d && make && make install

Now we want to update the library cache and update the init scripts so it will start on bootup

ldconfig && update-rc.d guacd defaults

Create the main Guacamole configuration folder and file

cd ~ && mkdir /etc/guacamole

Vi (or, you can use Nano/your file editor of choice) the main configuration which provides the location of the user-mapping.xml file.

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

# Location to read extra .jar's from
lib-directory: /var/lib/tomcat7/webapps/guacamole/WEB-INF/classes

# Authentication provider class

# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

For the Guacamole client, we are going to add a simple RDP connection. This is highly configurable, so be sure to read up on their site to see all the variables.

The Guacamole website will have a username of guacadmin and a password of guacpass.

For our purposes we are going to connect to a windows box, with the username: winuser and the password winpassword on the standard port 3389. Change these fields to the Windows box you want to connect to.

vi /etc/guacamole/user-mapping.xml
 <authorize username="guacadmin" password="guacpass">
  <param name="hostname"></param>
  <param name="port">3389</param>
  <param name="username">winuser</param>
  <param name="password">winpass</param>

You may need to adjust your remote desktop settings to allow connections from non-NLA authenticated servers, such as this.

Update tomcat to point to the user authentication files.

mkdir /usr/share/tomcat7/.guacamole
ln -s /etc/guacamole/ /usr/share/tomcat7/.guacamole
cp guacamole-0.9.8.war /var/lib/tomcat7/webapps/guacamole.war

Restart the tomcat and guacamole services

service guacd start && service tomcat7 restart

You should now be able to access your server via port 8080. For instance, my server which is

Log in with the guacadmin/guacpass credentials and it will automatically log you into windows using the credentials you supplied in the user-mapping.xml file.

If you do not want it running in the /guacamole subfolder and want to place it in the server root

service tomcat7 stop
mv /var/lib/tomcat7/webapps/ROOT /var/lib/tomcat7/webapps/ROOT.bkp
mv /var/lib/tomcat7/webapps/guacamole /var/lib/tomcat7/webapps/ROOT
service tomcat7 start

You should now be able to access it via the ip and port:

To further strengthen the server and allow https over a standard port, nginx can be installed side-by-side with tomcat to provide a reverse proxy and allow encryption.

apt-get install -y nginx

Don't forget to update the firewall to allow port 443 and remove port 8080

ufw allow 443 && ufw delete allow 8080

Generate the SSL keys

mkdir /etc/nginx/ssl && openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/nginx/ssl/guacamole.key -out /etc/nginx/ssl/guacamole.crt

If you are using a DNS name to access the server, or anything other than an IP address, make sure you include the FQDN.

We want to clear out the default nginx configuration and add our own

mv /etc/nginx/sites-available/default /etc/nginx/sites-available/default.bkp
rm /etc/nginx/sites-enabled/default

vi /etc/nginx/sites-available/guacamole
server {
        listen 443 ssl;

        access_log   /var/log/nginx/guacamole.access.log ;
        error_log    /var/log/nginx/guacamole.error.log info ;

        ssl_certificate /etc/nginx/ssl/guacamole.crt;
        ssl_certificate_key /etc/nginx/ssl/guacamole.key;

        location / {
        proxy_buffering off;

ln -s /etc/nginx/sites-available/guacamole /etc/nginx/sites-enabled/guacamole

Restart nginx

service nginx restart

You should now be able to access the server via the standard https port

1 comment:

  1. How do I redirect to the original Guacamole webb page instead of go direct to the RDP session?