Apache Guacamole is a great project which uses a daemon, guacd, to make RDP/VNC/SSH/Telnet connections to servers, and serves a Java WAR application with Tomcat to provide HTML5 access to those servers.
Guacamole is running under tomcat, and the tomcat server is probably starting under tomcat user. It might be the case that you have defined GUACAMOLEHOME in your shell, but this is not visible by tomcat user. I prefer to store guacamole.properties file under.guacamole directory, the. The installation of Apache Guacamole is done by compiling the source code.
In this article, I will go over setting up a secure, SSL, 2fa-enabled, database backed RDGateway replacement for use on small sites which can’t justify the cost/expense of setting up Microsoft RDS.
First of all, ensure that your server/workstation has NLA turned off. Unfortunately, NLA doesn’t work well with Apache Guacamole, and tends to cause problems. Luckily RDP will not be exposed to the internet so NLA is not neccessarily required here, although this does not exactly follow de-perimetisation techniques that are all the rage at the moment in network security.
The official manual states to build guacamole from source, so lets do that.
Installing guacd
Install a Linux server on the network. I will be using Ubuntu 16.04, but Debian 9 is also a good choice. Lets install the pre-requisites for Guacamole and guacd:
Okay, lets go ahead and download the release files for guacamole-0.9.14 and guacd-0.9.14:
Extract the files using:
Let’s get into the build of guacd:
If you look in /etc/init.d, there is now a script that you can use with systemctl to start, stop, restart guacd.
Install Guacamole
Lets install tomcat8 to run our java web application:
Tomcat holds the web application files in /var/lib/tomcat8/webapps . Lets put the .war file there:
Before we go any further, I want to let you all know about debugging Guacamole. Does lg smart tv have screen mirroring. Guacd runs as a daemon and logs to syslog. Tomcat logs to /var/log/tomcat/catalina.out, and captures the stdout output from the web application and redirects it there. The following commands should help you track down errors if there are any:
If you run
You will notice that tomcat is now listening on 8080/tcp and guacd is listening on localhost:4822.
Setting up basic users for testing
Guacamole reads it’s config from /etc/guacamole by default. We need to create that and touch a few files before we get started:
user-mapping.xml controls the basic users and their connections using the built in basic user mode. This file only requires that a user logs out and back in again for changes to happen. guacamole.properties will control options for the guacamole Java applet. This file requires tomcat8 to be restarted for changes to take effect.
Lets put some basic content into user-mapping.xml for testing:
Note: Change the 10.1.1.11 to match your server’s IP address.
DANGER: Always set the security level to TLS and ignore-cert to yes! Otherwise it won’t work. Trust me.
Browse to http://server-ip:8080/guacamole and login with USERNAME and PASSWORD. You should be automatically redirected to the RDP connection. Bravo! Else, check the log files and message me if you can’t figure it out.
Let’s continue on with the configuration. I want this Guacamole installation to use LDAP for users, but i’m using Microsoft Active Directory, and storing the connection details in LDAP requires modifying the schema, so I am going to also use a database backend to hold the connection details.
Configure connection to a database
Install PostgreSQL:
Download and extract the Guacamole jDBC extension:
Download the postgreSQL driver:
Make the extensions and lib directories and copy required files there:
Create the PostgreSQL database:
Add the following lines into your /etc/guacamole/guacamole.properties file:
There are lots more properties you can set here including password policies, etc as per the manual
Start and enable PostgreSQL:
Restart Tomcat to finalise the changes:
Check the web interface to make sure your changes have stuck. The default username/password is guacadmin. Bravo!
Install 2 Factor Authentication
Guacamole has built in support for Duo, which is also free for up to ten users. To get started with 2fa for our RD Gateway replacement, head over to Duo and sign up for an account. Install the Duo application on your mobile phone. Create a user with the alias as the same name as your user account in Guacamole. For a quick test, guacadmin will suffice.
Enroll your device in Duo following their instructions in the enrolment email. Download, extract, and install the extensions on your Guacamole server:
Generate a application key:
Add a “Web SDK” application to Duo, and note down the secret key, api endpoint, and the integration key.
Add the following properties to guacamole.properties:
Restart tomcat8 and test!
Great! Now you have a pretty secure web application providing html5 RDP to your network. Let’s make it even better with SSL from an nginx reverse proxy.
Configure nginx reverse proxy
We are going to have nginx listen on 443/tcp, and serve SSL, proxying back to Guacamole’s web interface on port 8080. Start by installing nginx on the host:
Remove the link for the default site in sites-enabled:
Guacamole Tomcat Config
Create a new file for the guacamole site:
Make sure you change the <server-ip> and <dns-name> parts in the config file above!
The “include snippets/snakeoil.conf” section above includes using ssl certificates that are self signed. You may want to change this to use ssl certificates that are signed by let’s encrypt or a different third party provider!
Guacamole Tomcat Recipe
Link the new file in sites-enabled:
Restart nginx to apply the changes:
Browse to https://<dns-name> in your browser. If everything worked, you now have a https connection to your guacamole system! All that is left is to port forward a port on your router to your internal system and setup external DNS.
Guacamole Tomcat Mix
I hope you can see the power in this. It’s taken me a while to write this guide, but I can spin up a server like this in around 2-3 hours. Which means that instead of someone paying $5000 to Microsoft in licensing for RDS, they can leverage their existing desktops and use Guacamole as a RD Gateway and provide secure, 2fa protected connections to their workstations. If you made it this far, congratulations. I hope this is useful to you!