Apache Guacamole is a clientless HTML5 web based remote desktop gateway that makes it easy to access remote servers and desktops through a web browser. It supports standard protocols like VNC, RDP, and SSH.
In this tutorial, we are going to learn how to setup Guacamole web-based remote desktop access tool on Ubuntu 18.04 server and demonstrate how to access a remote Linux server as well as a remote windows 7 server.
You might as well be interested in running the same setups in Debian 9.8. Check the link below;
- How to Install and Setup Guacamole on Debian 9.8
- How to Install and Configure Guacamole on Fedora 29
Want to transfer files over Guacamole? Check our guide by following the link below;
Installing Guacamole on Ubuntu 18.04
Guacamole is made up of two parts; guacamole-server, which provides the guacd proxy and related libraries, and guacamole-client which provides the client to be served by the servlet container which is usually Tomcat.
While guacamole-client is available in binary form, the guacamole-server must be built from source and therefore before we can proceed with installation, we need to first install all the required dependencies.
Install Required Dependencies
Run the command below to install all the requires dependencies.
apt install -y gcc-6 g++-6 libcairo2-dev libjpeg-turbo8-dev libpng-dev \ libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev libfreerdp-dev \ libpango1.0-dev libssh2-1-dev libvncserver-dev libssl-dev libvorbis-dev libwebp-dev
You can find a comprehensive description of all the required and the optional dependencies here.
Install Tomcat Servlet
Apache Tomcat is used to serve guacamole client content to users that connects to guacamole server via the web browser. To install Tomcat, run the command below;
apt install tomcat8 tomcat8-admin tomcat8-common tomcat8-user -y
If UFW is running, allow Tomcat through it.
ufw allow 8080 ufw reload
guacamole-server contains all the native, server-side components required by Guacamole to connect to remote desktops. To build guacamole server, download the latest source code from Guacamole releases page.
Guacamole 0.9.14 is the latest release as of this writing. You can simply run the command below to download it;
Once the download is done, extract and navigate to the source code directory as shown below.
tar xzf guacamole-server-0.9.14.tar.gz cd guacamole-server-0.9.14
In the source directory, run the
configure script. This script will determine the libraries that are available on your system and will select the appropriate components for building guacamole server based on what is installed.
You can also set the script to install a startup script for guacd as shown below.
If the script executes successfully, you should be able to see the output similar to the one shown below.
...output snipped... ------------------------------------------------ guacamole-server version 0.9.14 ------------------------------------------------ Library status: freerdp ............. yes pango ............... yes libavcodec .......... yes libavutil ........... yes libssh2 ............. yes libssl .............. yes libswscale .......... yes libtelnet ........... no libVNCServer ........ yes libvorbis ........... yes libpulse ............ no libwebp ............. yes wsock32 ............. no Protocol support: RDP ....... yes SSH ....... yes Telnet .... no VNC ....... yes Services / tools: guacd ...... yes guacenc .... yes Init scripts: /etc/init.d Type "make" to compile guacamole-server.
Now that the configure script has not complained, go ahead and compile the code as shown below;
make CC=gcc-6 ...output cut.. make: Leaving directory '/home/amos/guacamole-server-0.9.14/src/guacenc' make: Entering directory '/home/amos/guacamole-server-0.9.14' make: Nothing to be done for 'all-am'. make: Leaving directory '/home/amos/guacamole-server-0.9.14' make: Leaving directory '/home/amos/guacamole-server-0.9.14
Once the compilation is done, run
make install to install the components that were built.
Once the installation is done, run the
ldconfig command to create the necessary links and cache to the most recent shared libraries found in the guacamole server directory.
Start and enable guacd (Guacamole Daemon) to run on boot.
systemctl enable guacd systemctl start guacd
Installing Guacamole Client
In this tutorial, we are going to install the binary form of the guacamole-client. If you want to build it from the source code, see how to do so here.
To download the client, run the command below. You can check the latest version from the releases page.
Deploying Guacamole Client
Once the download above is done, it is time to deploy Guacamole.
Create Guacamole configuration directory
Move the download guacamole-client binary to the configuration file created above as shown below;
mv guacamole-0.9.14.war /etc/guacamole/guacamole.war
Create a symbolic link of the guacamole client to Tomcat webapps directory as shown below;
ln -s /etc/guacamole/guacamole.war /var/lib/tomcat8/webapps/
.war file is in place, you may need to restart Tomcat to force Tomcat to deploy the new web application, and the guacd daemon must be started if it isn’t running already
systemctl restart tomcat8 systemctl restart guacd
Guacamole is now successfully installed even though in its current state, it is completely unconfigured, and further steps are required to add Guacamole users and a connections.
Guacamole’s default authentication method reads all users and connections from a single file called
Guacamole has two major configuration files;
/etc/guacamole which is referenced by the
GUACAMOLE_HOME environment variable and
/etc/guacamole/guacamole.properties which is the main configuration file used by Guacamole and its extensions.
Other guacamole configurations reside in
/etc/guacamole/lib/ directories. We therefore have to create these directories.
Add the guacamole home directory environment variable to
tomcat8 configuration file.
echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat8
Define how Guacamole connects to guacd
To define how Guacamole connects to
guacd, create the
guacamole.properties file under /etc/guacamole with the following content.
guacd-hostname: localhost guacd-port: 4822 user-mapping: /etc/guacamole/user-mapping.xml auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
After that, save the configuration file and link the Guacamole configurations to Tomcat servlet as shown below.
ln -s /etc/guacamole /usr/share/tomcat8/.guacamole
Set the default authentication
Guacamole’s default authentication module consists of a mapping of usernames to configurations in an XML format, the
user-mapping.xml in this case. In this file, we will define the user allowed to access Guacamole web UI, the servers to connect to and the method of connection. Therefore, run the command below to create this file with the following contents.
<user-mapping> <!-- Per-user authentication and config information --> <!-- A user using md5 to hash the password amos user and its md5 hashed password below is used to login to Guacamole Web UI--> <authorize username="amos" password="d6a6bc0db10694a2d90e3a69648f3a03" encoding="md5"> <!-- First authorized connection --> <connection name="Ubuntu-Server"> <protocol>ssh</protocol> <param name="hostname">192.168.43.154</param> <param name="port">22</param> <param name="username">mibey</param> </connection> <!-- Second authorized connection --> <connection name="Windows 7"> <protocol>rdp</protocol> <param name="hostname">192.168.43.218</param> <param name="port">3389</param> <param name="username">mibeyki</param> </connection> </authorize> </user-mapping>
To generate md5 hash for the password, run either of the commands below;
echo -n password | openssl md5
printf '%s' password | md5sum
Be sure to replace password with your strong password.
Restart both Tomcat and guacd to effect the changes.
systemctl restart tomcat8 systemctl restart guacd
Verify the Setup
Now that we have done almost all the configurations, it is time to test it up. To access the Guacamole web interface. navigate to web browser and enter your url in the format,
Want to run Guacamole in production with SSL/TLS enabled? See our guide on how to configure Guacamole SSL/TLS with Nginx Reverse Proxy using the link below;
If everything is okay, you should see a login prompt as shown in the screenshot below.
Enter your username and password set above and login to Guacamole Dashboard.
There you go. To login to any of the servers, just click on it and you will be prompted to enter the password for the user defined in the
user-mapping.xml. For example to login to Ubuntu server, click on it, enter password at for user mibey at prompt and there you are, inside Ubuntu server. See the screenshot below.
To login to Windows 7 system, see below demo.
You have now successfully installed Guacamole Web based Remote desktop access tool on Ubuntu 18.04 server and can now be able to access your remote devices via web browser.
You can check our other articles for Ubuntu 18.04 by following the links below;