Debian 8.6, Jessie, Installing Guacamole

Update 09/2017 : I’d seriously consider using Docker to deploy Guacamole. See this article for more information : https://www.cb-net.co.uk/linux/running-guacamole-from-a-docker-container-on-ubuntu-16-04-lts-16-10

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: http://www.cb-net.co.uk/linux/guacamole-0-9-10-automated-install-with-mysql-on-debian-8-6/

# 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 https://github.com/apache/incubator-guacamole-server
cd incubator-guacamole-server
autoreconf -fi
./configure --with-init-dir=/etc/init.d
make
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 https://github.com/apache/incubator-guacamole-client
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/guacamole.properties
touch /etc/guacamole/guacamole.properties 
ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat8/.guacamole/

Create /etc/guacamole/guacamole.properties using the command:

vi /etc/guacamole/guacamole.properties

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
auth-provider:    net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

 

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

<user-mapping>
  <authorize username="

username1

" password="

password1

">
   <connection name="

WIN-10-RDP

">
	<protocol>rdp</protocol>
	<param name="hostname">

192.168.1.5

</param> 
	<param name="username">

username2

</param>
	<param name="password">

password2

</param> 
	<param name="security">

nla

</param>
        <param name="ignore-cert">

true

</param>
   </connection>
  </authorize>
</user-mapping>

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

<user-mapping>
	<authorize username="

username1

" password="

password1

">
		<connection name="

DEBIAN-RDP

">
			<protocol>

rdp

</protocol>
			<param name="hostname">

localhost

</param>
			<param name="port">

3389

</param>
		</connection>
	</authorize>
</user-mapping>

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

<user-mapping>
	<authorize username="

username1

" password="

password1

">
		<connection name="

DEBIAN-SSH

">
			<protocol>

ssh

</protocol>
			<param name="hostname">

localhost

</param>
		</connection>
	</authorize>
</user-mapping>

 

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/guacdr-client.so: 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/guacsnd-client.so: 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:

ldconfig
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!
http://localhost:8080/guacamole/

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:

• Via nginx
• Via Apache2

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.