Setup Guacamole Remote Desktop Access Tool on Ubuntu 18.04

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;

How to Enable RDP/SSH File Transfer Over Guacamole

Install and Setup Guacamole on Ubuntu 18.04

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

Building guacamole-server on Ubuntu 18.04

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;

wget http://archive.apache.org/dist/guacamole/0.9.14/source/guacamole-server-0.9.14.tar.gz

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.

./configure --with-init-dir=/etc/init.d

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[2]: Leaving directory '/home/amos/guacamole-server-0.9.14/src/guacenc'
make[2]: Entering directory '/home/amos/guacamole-server-0.9.14'
make[2]: Nothing to be done for 'all-am'.
make[2]: Leaving directory '/home/amos/guacamole-server-0.9.14'
make[1]: Leaving directory '/home/amos/guacamole-server-0.9.14

Once the compilation is done, run make install to install the components that were built.

make install

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.

ldconfig

Start and enable guacd (Guacamole Daemon) to run on boot.

systemctl enable guacd
systemctl start guacd

Installing Guacamole Client

guacamole-client contains all Java and JavaScript components of Guacamole (guacamole, guacamole-common, guacamole-ext, and guacamole-common-js). These components make up the web application that will serve the HTML5 Guacamole client to users that connect to your server. This web application will then connect to guacd on behalf of connected users in order to serve them any remote desktop they are authorized to access.

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.

wget http://archive.apache.org/dist/guacamole/0.9.14/binary/guacamole-0.9.14.war

Deploying Guacamole Client

Once the download above is done, it is time to deploy Guacamole.

Create Guacamole configuration directory

mkdir /etc/guacamole

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/

Once the .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

Setup Guacamole on Ubuntu 18.04

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 user-mapping.xml.

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/extensions/and /etc/guacamole/lib/ directories. We therefore have to create these directories.

mkdir /etc/guacamole/{extensions,lib}

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.

vim /etc/guacamole/guacamole.properties

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.

vim /etc/guacamole/user-mapping.xml

<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, http://server-IP:8080/guacamole.

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;

Configure Guacamole SSL/TLS with Nginx Reverse Proxy

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.

That concludes our guide on how to install and setup Guacamole on Ubuntu 18.04 for accessing your remote devices via web browser.

Are you looking for IT system administration jobs? Please check them here.

Reference:

Apache Guacamole website

You can check our other articles for Ubuntu 18.04 by following the links below;

How to Install Acutenix on Ubuntu 18.04

How to Install and Use WPScan WordPress Vulnerability Scanner Ubuntu 18.04

How to Install and Setup OpenVAS 9 Vulnerability Scanner on Ubuntu 18.04

How to Install and Use Nikto Web Scanner on Ubuntu 18.04

How to Install and Configure Nessus Scanner on Ubuntu 18.04/CentOS 7