Debian 8.6, Jessie, Installing Guacamole

Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH.

Client-less… yes! Guacamole uses HTML5 to do its stuff, so no client needed. I’ve used this to serve-out my X11rdp-enabled Debian 8.6 client (running guacamole itself) – but you could use this to front a variety of different clients.

This guide covers the steps needed to deploy v0.9.10 on Debian 8.6, Jessie; running 0.9.9? Check out this guide on how to upgrade to 0.9.10.

Lastly, if you want to use MySQL for the back-end – rather than XML files – see this guide:

# Install Guacamole server pre-reqs including MySQL
apt-get install -y libjpeg-dev libcairo2-dev libossp-uuid-dev libpng12-dev libfreerdp-dev libssh2-1-dev libssh-dev libwebp-dev libpulse-dev libavcodec-dev libavutil-dev libswscale-dev libpango1.0-dev libvncserver-dev maven tomcat8 tomcat8-admin tomcat8-user default-jdk openjdk-7-jre openjdk-7-jdk java-common
# Download and install guacamole server
cd ~
git clone
cd incubator-guacamole-server
autoreconf -fi
./configure --with-init-dir=/etc/init.d
make install
mkdir /etc/guacamole/extensions 
mkdir /etc/guacamole/lib

# Resolve freerdp directory issues present when running guacamole on Debian 8.6
mkdir /usr/lib/x86_64-linux-gnu/freerdp
ln -s /usr/local/lib/freerdp/guac* /usr/lib/x86_64-linux-gnu/freerdp/

# Download and package guacamole client
cd ~
git clone
cd incubator-guacamole-client
mvn package

# TomCat WebApp and guacamole environment deployment 
cd ~/incubator-guacamole-client/guacamole/target 
cp guacamole-0.9.10-incubating.war /etc/guacamole/guacamole.war 
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat8/webapps/ 
mkdir /usr/share/tomcat8/.guacamole
echo GUACAMOLE_HOME=/etc/guacamole >> /etc/default/tomcat8

# Create /etc/guacamole/
touch /etc/guacamole/ 
ln -s /etc/guacamole/ /usr/share/tomcat8/.guacamole/

Create /etc/guacamole/ using the command:

vi /etc/guacamole/

Now edit the file and enter the following lines – for more information on this file click here.

guacd-hostname: localhost
guacd-port:    4822
user-mapping:    /etc/guacamole/user-mapping.xml


Create /etc/guacamole/user-mapping.xml using the command:

touch /etc/guacamole/user-mapping.xml

Edit these lines prior to adding them to user-mapping.xml – you will want to change username, password (used to login to guacamole), protocol, target host etc. For more information on options / protocols / usernames / passwords etc see here.

This example is for a Windows 10 client with NLA enabled (the default configuration). You have to use two username/passwords in this example:

  1. The logon credentials for guacamole itself via http://<hostname>/guacamole/ – denoted username1/password1
  2. The pre-authentication (NLA) credentials for the target RDP client (windows credentials) – denoted username2/password2
  <authorize username="username1" password="password1">
   <connection name="WIN-10-RDP">
	<param name="hostname"></param> 
	<param name="username">username2</param>
	<param name="password">password2</param> 
	<param name="security">nla</param>
        <param name="ignore-cert">true</param>

Alternatively, disable the NLA requirement on your Windows 10 client and set security to “tls” – you can then remove the connection specific username/password. When you connect via RDP you’ll then be prompted for credentials.

Another example, a Debian 8.6 x11rdp client – note the credentials here are those used to login to guacamole itself via http://<hostname>/guacamole/ – denoted username1/password1

	<authorize username="username1" password="password1">
		<connection name="DEBIAN-RDP">
			<param name="hostname">localhost</param>
			<param name="port">3389</param>

Once last example, an SSH client (see note about username/password above):

	<authorize username="username1" password="password1">
		<connection name="DEBIAN-SSH">
			<param name="hostname">localhost</param>


If you forget the freerdp fix above, you will get errors such as those below relating to missing freerdp plugins:

LoadLibraryA: /usr/lib/x86_64-linux-gnu/freerdp/ cannot open shared object file: No such file or directory
guacd[7143]: WARNING:    Failed to load guacdr plugin. Drive redirection and printing will not work. Sound MAY not work.
LoadLibraryA: /usr/lib/x86_64-linux-gnu/freerdp/ cannot open shared object file: No such file or directory
guacd[7143]: WARNING:    Failed to load guacsnd alongside guacdr plugin. Sound will not work. Drive redirection and printing MAY not work.


Start tomcat8 and guacamole-server:

systemctl start tomcat8
/etc/init.d/guacd start

Enable tomcat8 and guacd on startup:

systemctl enable tomcat8
systemctl enable guacd

You can now browse to guacamole using the following URL – note the trailing slash, without this you will get a HTTP 404 error!

Not working? Stop guacd using the command:

systemctl stop guacd

Now, from the a terminal, start guacd with debug output enabled:

/usr/local/sbin/guacd -f -L debug

You can now try and connect to guacamole / a client and view debug information such as security / hostname / authentication failures.

Be sure to checkout my posts on how to proxy and secure guacamole either:

Also worth reviewing my post on using a mysql back-end as opposed to the user-mapping.xml file. This makes management and configuration of guacamole a lot easier, IMO.