How to Create Virtual Cloud Desktop Using Apache Guacamole

By Liptan Biswas, Alibaba Cloud Tech Share Author

Apache Guacamole is a free and open source web application which lets you access your dashboard from anywhere using a modern web browser. It is a clientless remote desktop gateway which only requires Guacamole installed on a server and a web browser supporting HTML5. With Alibaba Cloud, you don’t need a physical hardware to keep a desktop but you can use its virtualized hardware to create as many cloud instances as you want. Guacamole is the best way to keep multiple instances accessible over the internet. Once you add an instance to Guacamole, you don’t need to remember the password as it can securely store the credentials. It also lets you share the desktops among other users in a group. Guacamole supports multiple connection methods such as SSH, Telnet, VNC, and RDP.

In this tutorial, we will install Apache Guacamole on a CentOS 7 instance. We will also secure the connections to the web application using Nginx reverse proxy with SSL.


Alibaba CentOS 7.4 instance with at least 2GB RAM.

Firewall or Security group rules configured to allow the port “80”, “443” and “8080”.

A domain name that needs to be pointed towards your ECS instance.

Connect to the ECS instance through SSH as the root user. You can use sudo -i command to switch to the root user. Make sure that all the packages in the system are updated to the latest version by running the following command.

Install Required Dependencies

Install EPEL repository as few of the dependencies are unavailable in the default repository.

Install the required dependencies.

The above command will install all required dependencies required to successfully compile the source code and also to provide the support for VNC, RDP, and SSH.

Install FFmpeg to enable support for session recording. FFmpeg is available in RPMfusion repository.

Guacamole system is made up of two separate parts: Guacamole server, and Guacamole Client. For Guacamole to work, both of these tools must be installed.

Install Guacamole Server

Guacamole server consists of the native server-side libraries required to connect to the server and the “guacd” tool. guacd is the Guacamole proxy daemon which accepts the user’s connections and connects to the remote desktop on their behalf. Given below is the architecture of Guacamole System.

It is required to compile and install the Guacamole server on the host machine, installing the binary is not possible for Guacamole server. Download the Guacamole server source code files into the temporary directory.

Extract the source code archive.

Compile and install the source code.

The installation will also set up an init script which can be used to manage the guacd daemon. Create the necessary links and cache for the shared libraries.

Guacamole server is now installed on your ECS instance. Start the Guacamole proxy daemon and enable it to automatically start at boot time using the following commands.

You can check the status of the service by running.

Install Guacamole Client

Guacamole client is Java based web application which contains all the Java and JavaScript code required for running the user interface of Guacamole. It ultimately creates a web application which connects to the guacd daemon running in the background using Guacamole protocol. In the foreground, it renders the remote desktop interface using HTML5 on the web browser to the authorized users.

Unlike Guacamole server, Guacamole client is not required to be compiled and install from source. Cross-platform Guacamole client binary is available to download and install. Guacamole binary requires a Java web server to run. In this tutorial, we will install Apache Tomcat 8 to run the Guacamole binary file.

Install Java 8 runtime on your server, installing JDK is not required since we do not need to compile any Java code.

Create a new group and user for Tomcat installation. Running Tomcat server with an unprivileged user is recommended for security reasons.

Download latest Tomcat server of version 8.5 from Apache mirror.

Extract the archive into /opt/tomcat directory.

Provide appropriate permissions and ownership to Tomcat server files.

Create a new systemd service file for managing Tomcat server.

Populate the file with the following configuration.

Start the Tomcat server and enable it to automatically start at boot time.

You can check if Tomcat is running by going to http://your-server-ip:8080 using your favourite web browser. You should see the default Tomcat page. If you are getting some error, then make sure that port “8080” is allowed in Security group rules.

Since we have installed the Tomcat server, download the Guacamole client binary file using the following command.

Move the Guacamole client file to the Tomcat’s webapps directory.

Restart the Tomcat server.

Guacamole client is now installed on your server, you can check if Guacamole client is working by going to http://your-server-ip:8080/guacamole using your favourite browser. You should see Guacamole login interface. You will not be able to log in yet as we have not configured authentication yet.

Setting Up Authentication

Guacamole client supports multiple authentication mechanisms such as file-based auth, database auth, OAuth, LDAP etc. In this section of the tutorial, we will configure database based authentication using MySQL database server.

MySQL database will be used to store the authentication and other data. Since we do not require high performance and scalability which ApasaraDB provides, we will install MySQL server on the same ECS instance.

Install MariaDB server which is an open source fork of MySQL.

Start the MariaDB server and enable it to automatically start at boot time.

Set a password for the MySQL root user and secure the server instance by removing the test database and user.

Now login to your MySQL shell using the root user and the password you just created.

Run the following queries to create a new database named guacdb along with guacdb-user having full access to the database. Please change StrongPassword to a very strong password.

Now that our database server is running, we need to install the MySQL connector and Guacamole JDBC auth plugin. Create the new directories to store the plugins.

Download the MySQL connector extension from MySQL site.

Extract and move the MySQL connector into /etc/guacamole/lib.

Download the Guacamole JDBC authentication extension from Apache Guacamole site.

Extract the archive and move the extension to /etc/guacamole/extensions directory.

Since we have already created the database and database user, we can proceed to create the database schema and import the initial data. The schema is shipped along with the JDBC extension.

Import the SQL schema and initial data into the guacdb database using the following command. Provide the password of the MySQL root user when prompted.

Create a new configuration file for Apache Guacamole so it can override the default configuration.

Populate the file with the following configuration. Make sure to edit the StrongPassword with the actual password of guacdb-user.

Set GUACAMOLE_HOME environment variable so that the Guacamole Server can read the configuration file and the extensions.

Disable SELinux as it causes errors when running Guacamole.

Restart Guacamole proxy daemon and Tomcat server so that the new configuration can take effect.

Guacamole Client authentication is now configured on your server. You can check if you can log in by going to http://your-server-ip:8080/guacamole using your favourite browser. Log in using the default administrator user “guacadmin” and password “guacadmin”.

Setting up Nginx Reverse Proxy

Setting up a reverse proxy secured with SSL is recommended to encrypt the data exchanged between the browser and the Guacamole server. This will also map a domain name to your server so you won’t need to remember the IP address of the server.

Install Nginx web server.

Start the Nginx web server and enable it to automatically start at boot time.

In this tutorial, we will use the certificates generated with Let’s Encrypt certificate authority. If you wish to use more production friendly certificates, you can purchase commercial certificates from Alibaba Cloud.

Download and install Certbot. Certbot is an official client application for Let’s Encrypt SSL generation.

Note: Before requesting SSL certificates, make sure that the domain you are using is pointed towards the IP address of the ECS instance. If not, make an “A” type record in DNS management panel and point the domain or subdomain to the public IP address of ECS instance and wait for the DNS to propagate.

Generate Let’s Encrypt SSL certificates for your domain.

Replace all occurrences of with your actual domain name. The above command will ask you for your email to send you renewal notices. If the certificates are generated successfully, you should get following output.

Create a cron job to renew the certificates as Let’s Encrypt certificates are expired in every three months.

The above command will run the renewal command every day at 2.36 AM. If the certificates are due for expiry it will automatically renew them.

Create a new server block configuration file for Guacamole web application reverse proxy.

Populate the file with the following configuration. Replace the example domain name with the actual one. Also, make sure that the path to the Let’s Encrypt SSL certificate and the private key is correct.

Check the Nginx configuration for errors.

You should see the following output if the configuration is error free.

Restart Nginx web server to implement the changes in the configuration.

Now you can go to to access the Guacamole dashboard. The connections to the server and the browser are also secured with SSL.

Connecting First Client

Guacamole server is now ready and working. You can add as many remote servers as you want. It can connect to the remote clients using SSH, Telnet, RDP, and VNC. To verify if it can connect to the remote server, let’s add our first SSH based connection. Before proceeding further, let’s change the password of the default “guacamole” user. Login with default administrator user “guacadmin” and password “guacadmin” and go to the “Preferences” tab. Change the default password from this tab.

To add a new connection, go to “Connections” tab and click on “Add new Connection” button. Provide a name for the connection and choose the protocol from drop down. Since I am connecting to the Guacamole server via SSH, I am selecting “SSH”.

In “Parameters” provide the hostname of the target server and port. You also use “localhost” for connecting the same server. Provide the username and password, if connecting through private key than provide the contents of the private key. You can also configure the display, such as color scheme and fonts etc. Once you are done, click on “Save” button.

To connect to the SSH server you just added, go to the dashboard and it will automatically try to connect to the SSH when there is only a single connection is available. Once you are connected, you should see the following interface.

Similarly, you can add more SSH clients and graphical dashboards using various connection methods. The remote connections you want to add are not required to have either of Guacamole Server or Client, you can directly add them. Once you add the remote servers in Guacamole, you will only need a web browser to access them from anywhere in the world.


Follow me to keep abreast with the latest technology news, industry insights, and developer trends.