How to install the web-based Guacamole Remote Desktop Client on Ubuntu 20.04 LTS

Guacamole is a free, open-source and web-based remote desktop control panel used for managing Linux and Windows systems from the web browser. It supports standard protocols like VNC, RDP, SSH and Kubernetes, and you don't need to install any software on the client computer. It supports clipboard, file transfer via SFTP and allows you to manage multiple remote desktop sessions.

In this tutorial, we will show you how to install and configure Guacamole remote desktop client on Ubuntu 20.04 server.

Prerequisites

  • A server running Ubuntu 20.04 with minimum 2GB RAM.
  • A root password is configured the server.

Getting Started

First, you will need to update your system to the latest stable version. You can do this by updating all system packages using the following command:

apt-get update -y

Once your system is updated, restart your system to apply the changes.

Install Required Dependecies

First, you will need to install some dependencies in your server to compile the Guacamole from source. You can install all of them with the following command:

apt-get install make gcc g++ libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev libavcodec-dev libavutil-dev libswscale-dev freerdp2-dev libpango1.0-dev libssh2-1-dev libvncserver-dev libtelnet-dev libssl-dev libvorbis-dev libwebp-dev -y

Once all the dependencies are installed, you can proceed to the next step.

Install Tomcat Server

Guacamole uses Tomcat to serve guacamole client content to users that connect to the guacamole server via the web browser. So the Tomcat server must be installed in your server. If not installed you can install it with the following command:

apt-get install tomcat9 tomcat9-admin tomcat9-common tomcat9-user -y

After installing Tomcat server, start the Tomcat service and enable it to start at system reboot with the following command:

systemctl start tomcat9
systemctl enable tomcat9

You can also verify the status of the Tomcat service with the following command:

systemctl status tomcat9

You should get the following output:

? tomcat9.service - Apache Tomcat 9 Web Application Server
     Loaded: loaded (/lib/systemd/system/tomcat9.service; enabled; vendor preset: enabled)
     Active: active (running) since Tue 2020-08-25 14:48:50 UTC; 29min ago
       Docs: https://tomcat.apache.org/tomcat-9.0-doc/index.html
    Process: 27982 ExecStartPre=/usr/libexec/tomcat9/tomcat-update-policy.sh (code=exited, status=0/SUCCESS)
   Main PID: 27990 (java)
      Tasks: 38 (limit: 4691)
     Memory: 241.5M
     CGroup: /system.slice/tomcat9.service
             ??27990 /usr/lib/jvm/default-java/bin/java -Djava.util.logging.config.file=/var/lib/tomcat9/conf/logging.properties -Djava.util.l>

Once you are finished, you can proceed to the next step.

Install Guacamole

By default, the Guacamole package is not available in the Ubuntu 20.04 default repository. So you will need to compile it from the source.

First, download the latest version of the Guacamole from the Apache website using the following command:

wget https://downloads.apache.org/guacamole/1.1.0/source/guacamole-server-1.1.0.tar.gz

Once the download is completed, extract the downloaded file with the following command:

tar -xvzf guacamole-server-1.1.0.tar.gz

Next, change the directory to the extracted directory and run the configure script to check if any required dependency is missing or not:

cd guacamole-server-1.1.0
./configure --with-init-dir=/etc/init.d

If everything is fine, you should see the following output:

     freerdp2 ............ yes
     pango ............... yes
     libavcodec .......... yes
     libavutil ........... yes
     libssh2 ............. yes
     libssl .............. yes
     libswscale .......... yes
     libtelnet ........... yes
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ no
     libwebsockets ....... no
     libwebp ............. yes
     wsock32 ............. no

   Protocol support:

      Kubernetes .... no
      RDP ........... yes
      SSH ........... yes
      Telnet ........ yes
      VNC ........... yes

   Services / tools:

      guacd ...... yes
      guacenc .... yes
      guaclog .... yes

   FreeRDP plugins: /usr/lib/x86_64-linux-gnu/freerdp2
   Init scripts: /etc/init.d
   Systemd units: no

Type "make" to compile guacamole-server.

Now, compile and install Guacamole Server by running the following command:

make
make install

Next, run the following command to update your system's cache of installed libraries:

ldconfig

Next, enable and start the Guacamole service using the following command

systemctl enable guacd
systemctl start guacd

You can now check the status of the Guacamole service with the following command:

systemctl status guacd

You should get the following output:

? guacd.service - LSB: Guacamole proxy daemon
     Loaded: loaded (/etc/init.d/guacd; generated)
     Active: active (running) since Tue 2020-08-25 12:02:26 UTC; 4s ago
       Docs: man:systemd-sysv-generator(8)
    Process: 27536 ExecStart=/etc/init.d/guacd start (code=exited, status=0/SUCCESS)
      Tasks: 1 (limit: 4691)
     Memory: 10.1M
     CGroup: /system.slice/guacd.service
             ??27555 /usr/local/sbin/guacd -p /var/run/guacd.pid

Aug 25 12:02:26 ubuntu2004 systemd[1]: Starting LSB: Guacamole proxy daemon...
Aug 25 12:02:26 ubuntu2004 guacd[27551]: Guacamole proxy daemon (guacd) version 1.1.0 started
Aug 25 12:02:26 ubuntu2004 guacd[27536]: Starting guacd:
Aug 25 12:02:26 ubuntu2004 guacd[27551]: Starting guacd:
Aug 25 12:02:26 ubuntu2004 guacd[27551]: uacd[27551]: INFO:        Guacamole proxy daemon (guacd) versio
Aug 25 12:02:26 ubuntu2004 systemd[1]: Started LSB: Guacamole proxy daemon.
Aug 25 12:02:26 ubuntu2004 guacd[27555]: Listening on host 127.0.0.1, port 4822
Aug 25 12:02:26 ubuntu2004 guacd[27536]: uacd[275

Once you are finished, you can proceed to the next step.

Install Guacamole Client

Next, you will need to install Guacamole client on your server. Guacamole client is written in Java and is cross-platform. This will make up the final HTML5 application that will be presented to you.

First, download the Guacamole binary using the following command:

wget https://mirrors.estointernet.in/apache/guacamole/1.1.0/binary/guacamole-1.1.0.war

After downloading the Guacamole binary, copy it to the /etc/guacamole directory using the following command:

mkdir /etc/guacamole
mv guacamole-1.1.0.war /etc/guacamole/guacamole.war

Next, create a symbolic link of the guacamole client to Tomcat webapps directory with the following command:

ln -s /etc/guacamole/guacamole.war /var/lib/tomcat9/webapps/

Finally, restart the Tomcat and Guacamole service to deploy the new web application:

systemctl restart tomcat9
systemctl restart guacd

Once you are finished, you can proceed to the next step.

Configure Guacomole

Next, you need to configure users and connections in order to work Guacamole properly.

First, create a Guacamole main configuration file named guacamole.properties.

nano /etc/guacamole/guacamole.properties

Add the following lines:

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

Save and close the file when you are finished.

Next, you will need to create directories for library and extension. You can create them with the following command:

mkdir /etc/guacamole/{extensions,lib}

Next, set the guacamole home directory environment variable and add it to /etc/default/tomcat9 configuration file.

echo "GUACAMOLE_HOME=/etc/guacamole" >> /etc/default/tomcat9

Next, you will need to create a file called user-mapping.xml to define the user allowed to access Guacamole web UI.

Before creating it, generate md5 hash for the password with the following command:

echo -n yoursecurepassword | openssl md5

You should see the following output:

(stdin)= 55b38b03e7587a45fd886977842ff9b8

Note : Remember the above md5 password. You will need to define this in the user-mapping.xml file.

Next, create a new user-mapping.xml with the following command:

nano /etc/guacamole/user-mapping.xml
<user-mapping>
    <authorize 
            username="admin"
            password="55b38b03e7587a45fd886977842ff9b8"
            encoding="md5">

        <connection name="Ubuntu20.04-Server">
            <protocol>ssh</protocol>
            <param name="hostname">192.168.10.50</param>
            <param name="port">22</param>
            <param name="username">root</param>
        </connection>
        <connection name="Windows Server">
            <protocol>rdp</protocol>
            <param name="hostname">192.168.10.51</param>
            <param name="port">3389</param>
        </connection>
    </authorize>
</user-mapping>

Save and close the file when you are finished.

Where:

  • 192.168.10.50 is the IP address of the remote Ubuntu server.
  • 192.168.10.51 is the IP address of the remove Windows server.

Next, restart Tomcat and Guacamole service to apply the changes:

systemctl restart tomcat9
systemctl restart guacd

At this point, the Guacamole server and client has been installed and configured.

Access Guacamole Web Interface

Now, open your web browser and access the Guacamole web interface using the URL http://your-server-ip:8080/guacamole. You will be redirected to the Guacamole login page:

Guacamole login

Provide the username and password that you defined in the user-mapping.xml file, and click on the Login button. You should see the Guacamole dashboard in the following page:

Guacamole dashboard

Now, click on the Ubuntu20.04-Server to connect the remote server using the SSH protocol. You should see the login screen of the Ubuntu server as shown below:

Guacamole remote login

Provide the root password of your Ubuntu server and hit Enter. You will be login to the Ubuntu server as shown below:

Shell login via guacamole

Configure Nginx for Guacamole

It is recommended to configure the Nginx as a reverse proxy to access the Guacamole through the port 80.

First, install the Nginx web server using the following command:

apt-get install nginx -y

After installing Nginx, create a new Nginx virtual host configuration file:

nano /etc/nginx/sites-available/guacamole.conf

Add the following lines:

server {
        listen 80;
        server_name your-server-ip;
        access_log  /var/log/nginx/guac_access.log;
        error_log  /var/log/nginx/guac_error.log;

        location / {
                    proxy_pass http://your-server-ip:8080/guacamole/;
                    proxy_buffering off;
                    proxy_http_version 1.1;
                    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
                    proxy_set_header Upgrade $http_upgrade;
                    proxy_set_header Connection $http_connection;
                    proxy_cookie_path /guacamole/ /;
        }

}

Save and close the file when you are finished. Then, enable the Nginx virtual host with the following command:

ln -s /etc/nginx/sites-available/guacamole.conf /etc/nginx/sites-enabled/

Next, restart the Nginx service to apply the configuration changes:

systemctl restart nginx

Now, you can access your Guacamole using the URL http://your-server-ip.

Conclusion

Congratulations! you have successfully installed and configured Guacamole remote desktop client on Ubuntu 20.04 server. You can now add more RDP or VNC connections to your Guacamole and start managing them from the web-based interface.

Share this page:

Suggested articles

6 Comment(s)

Add comment

Comments

By: Scott

Great tutorial. Almost everything worked. I had to install freerdp2-x11 as a dependency to connect to Win10 via RDP.  Also, this tutorial did not enable the ability to add new connections from within the web interface. I'm still required to do this via the terminal. It appears to me that the web interface is actually missing a lot of capability compared to installing via docker or another solution.

By: IceManXS

Thank you for the tutorial.

@Scott Editing a user-mapping.xml-File is the default way to use Connections in Guacamole. If you want to use the ability to add new connections from within the web interface, the graphical way, you have to connect Guacamole to a database like MySQL, MariaDB or PostgreSQL.

You can find the steps for this here: https://guacamole.apache.org/doc/gug/jdbc-auth.html

I´m not sure what the better way is. I think it depends on what you plan to do with Guacamole. I tested both of them. Using the webinterface is more easy to create new users and connections. For the way with the user-mapping.xml-File you have to know all the parameters for the xml-File.

So I think this tutorial is perfect for installing Guacamole. If you want to use and configure Guacamole you have to use the Guacamole documentation to get familiar with it.

https://guacamole.apache.org/doc/gug/users-guide.html

The 2 examples of connections Hitesh has in his tutorial are just a small example of what is necessary and possible. For instance it is not possible to connect to a Window 10 Computer with the given connection example. Windows will reject the connection.

For me it worked with:

<connection name="Windows 10">    <protocol>rdp</protocol>    <param name="hostname">192.168.10.51</param>    <param name="username">YourWindowsUsername</param>    <param name="password">YourWindowsPassword</param>    <param name="port">3389</param>    <param name="security">nla</param>    <param name="ignore-cert">true</param></connection>

By: IceManXS

By the way since June there is a version 1.2.0 of Guacamole available. If you want to use the latest version just change the version number from 1.1.0 to 1.2.0. in all 5 affected commands in this tutorial. Pay attention to change it everywhere, for server and client of Guacamole.

 

By: Suresh R

I have configured as per guide but getting The remote desktop server is currently unreachable. If the problem persists, please notify your system administrator, or check your system logs. error. 

Please help me to solve.

By: User1

Hello, 

if I try to access Apacha Guacamole with this link http://your-server-ip:8080/guacamole. 

I get an error "Invalid Login" even my credentials are correct. 

 

By: George

Thanks, this is very well researched. I was struggling follwoing the official documentation and couldn't get it to work.  Worked first time with this guide