Setting Up Web-Based Guacamole Tool to Access Remote Linux/Windows Machines

As a system administrator, you may find yourself (today or in the future) working in an environment where Windows and Linux coexist. It is no secret that some big companies prefer (or have to) run some of their production services in Windows boxes and others in Linux servers. If that is your case, you will welcome this guide with open arms (otherwise go ahead and at least make sure to add it to your bookmarks).

Install Guacamole for Remote Desktop and SSH Access

Install Guacamole for Remote Desktop and SSH Access

In this article we will introduce you to guacamole, a remote desktop gateway powered by Tomcat that only needs to be installed on a central server.

Read Also: How to Access Remote Linux Desktop Using TightVNC

Guacamole will provide a web-based control panel that will allow you to switch quickly from one machine to another – all within the same web browser window.

Testing Environment

In this article we have used the following machines. We will install Guacamole in an Ubuntu box and use it to access a Windows 10 box over Remote Desktop Protocol (RDP) and a RHEL 7 box using SSH:

Guacamole server: Ubuntu 14.04 - IP 192.168.0.100
SSH box: RHEL 7 – IP 192.168.0.18
Remote desktop box: Windows 10 – IP 192.168.0.19

That said, let’s get started.

Installing Guacamole Server

1. Before installing guacamole, you will need to take care of its dependencies first.

In Debian and Ubuntu (use sudo):

$ sudo apt-get install libcairo2-dev libjpeg62-dev libpng12-dev libossp-uuid-dev libfreerdp-dev libpango1.0-dev libssh2-1-dev libssh-dev tomcat7 tomcat7-admin tomcat7-user 

In RHEL / CentOS / Fedora 18-21:

# yum install cairo-devel libjpeg-devel libpng-devel uuid-devel freerdp-devel pango-devel libssh2-devel libssh-dev tomcat tomcat-admin-webapps tomcat-webapps

In Fedora 22-23:

# dnf install cairo-devel libjpeg-devel libpng-devel uuid-devel freerdp-devel pango-devel libssh2-devel libssh-devel tomcat tomcat-admin-webapps tomcat-webapps

2. Download and extract the tarball.
As of early February, 2016, the latest version of Guacamole is 0.9.9. You can refer to the Downloads page to find out the latest version at a given time.

# wget http://sourceforge.net/projects/guacamole/files/current/source/guacamole-server-0.9.9.tar.gz 
# tar zxf guacamole-server-0.9.9.tar.gz 

3. Compile the software.

# cd guacamole-server-0.9.9 
# ./configure 

As it is to be expected, configure will check your system for the presence of the required dependencies and for supported communication protocols (as can be seen in the highlighted square, Remote Desktop Protocol (RDP) and SSH are supported by the dependencies installed earlier).

If everything goes as expected you should see this when it completes (otherwise, make sure you installed all the necessary dependencies):

Guacamole Server Installation

Guacamole Server Installation

As the last line in the above image suggests, run make and make install to compile the program:

# make 
# make install

4. Update the cache of installed libraries.

# ldconfig 

and hit Enter.

Installing Guacamole Client

After completing the above steps, the guacamole server will have been installed. The following instructions will now help you to set up guacd (the proxy daemon that integrates Javascript with communication protocols such as RDP or SSH) and guacamole.war (the client), the component that makes up the final HTML5 application that will be presented to you.

Note that both components (guacamole server and client) need to be installed on the same machine – there is no need to install a so-called client on the machines you want to connect to).

To download the client, follow these steps:

5. Download the web application archive and change its name to guacamole.war.

Note: Depending on your distribution, the Tomcat libraries directory may be located at /var/lib/tomcat.

# cd /var/lib/tomcat7
# wget http://sourceforge.net/projects/guacamole/files/current/binary/guacamole-0.9.9.war
# mv guacamole-0.9.9.war guacamole.war

6. Create the configuration file (/etc/guacamole/guacamole.properties). This file contains the instructions for Guacamole to connect to guacd:

# mkdir /etc/guacamole
# mkdir /usr/share/tomcat7/.guacamole

Insert the following contents to /etc/guacamole/guacamole.properties. Note that we are referencing a file we will create in the next step (/etc/guacamole/user-mapping.xml):

guacd-hostname: localhost
guacd-port:    4822
user-mapping:    /etc/guacamole/user-mapping.xml
auth-provider:    net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
basic-user-mapping:    /etc/guacamole/user-mapping.xml

And create a symbolic link for Tomcat to be able to read the file:

# ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole/

7. Guacamole uses the user-mapping.xml, create this file to define which users are allowed to authenticate to the Guacamole web interface (between <authorize> tags) and which connections they can use (between <connection> tags):

The following user mapping grants access to the Guacamole web interface to user tecmint with password tecmint01. Then, inside the SSH connection we need to place a valid username to log in to the RHEL box (you will be prompted to enter the corresponding password when Guacamole initiates the connection).

In the case of the Windows 10 box, there is no need to do that as we will be presented with the login screen over RDP.

To obtain the md5 hash of the password tecmint01, type the following command:

# printf '%s' "tecmint01" | md5sum

Then insert the output of the command in the password field inside the <authorize> tags:

<user-mapping>
        <authorize 
                username="tecmint" 
                password="8383339b9c90775ac14693d8e620981f" 
                encoding="md5">
                <connection name="RHEL 7">
                        <protocol>ssh</protocol>
                        <param name="hostname">192.168.0.18</param>
                        <param name="port">22</param>
                        <param name="username">gacanepa</param>
                </connection>
                <connection name="Windows 10">
                        <protocol>rdp</protocol>
                        <param name="hostname">192.168.0.19</param>
                        <param name="port">3389</param>
                </connection>
        </authorize>
</user-mapping>

As it is the case with all files that contain sensitive information, it is important to restrict the permissions and change the ownership of the user-mapping.xml file:

# chmod 600 /etc/guacamole/user-mapping.xml
# chown tomcat7:tomcat7 /etc/guacamole/user-mapping.xml

Start Tomcat and guacd.

# service tomcat7 start
# /usr/local/sbin/guacd &

Launching the Guacamole Web Interface

8. To access the Guacamole web interface, launch a browser and point it to http://server:8080/guacamole where server is the hostname or IP address of your server (in our case it is http://192.168.0.100:8080/guacamole) and login with the credentials given earlier (username: tecmint, password: tecmint01):

Guacamole Login Interface

Guacamole Login Interface

9. After clicking on Login, you will be taken to the administrative interface where you will see the list of connections user tecmint has access to, as per user-mapping.xml:

Guacamole User Connections

Guacamole User Connections

10. Go ahead and click on the RHEL 7 box to login as gacanepa (the username specified in the connection definition).

Note how the connection source is set to 192.168.0.100 (the IP of the Guacamole server), regardless of the IP address of the machine that you use to open the web interface:

Guacamole: Access Remote Linux

Guacamole: Access Remote Linux

11. If you want to close the connection, type exit and hit Enter. You will prompted to return to the main interface (Home), reconnect, or logout from Guacamole:

Guacamole Session Disconnection

Guacamole Session Disconnection

12. Now it’s time to try the remote desktop connection to Windows 10:

Connect Windows Machine from Linux

Connect Windows Machine from Linux

Congratulations! Now you can access a Windows 10 machine and a RHEL 7 server from within a web browser.

Summary

In this article we have explained how to install and configure Guacamole to allow access to remote machines over RDP and SSH. The official website provides an extensive documentation to help you set up access using other protocols, such as VNC and other authentication mechanism, such as DB-based..

As always, don’t hesitate to drop us a note if you have any questions or suggestions about this article. We also look forward to hearing your success stories.

Reference Links: http://guac-dev.org/

If You Appreciate What We Do Here On TecMint, You Should Consider:

TecMint is the fastest growing and most trusted community site for any kind of Linux Articles, Guides and Books on the web. Millions of people visit TecMint! to search or browse the thousands of published articles available FREELY to all.

If you like what you are reading, please consider buying us a coffee ( or 2 ) as a token of appreciation.

Support Us

We are thankful for your never ending support.

Gabriel Cánepa

Gabriel Cánepa is a GNU/Linux sysadmin and web developer from Villa Mercedes, San Luis, Argentina. He works for a worldwide leading consumer product company and takes great pleasure in using FOSS tools to increase productivity in all areas of his daily work.

Your name can also be listed here. Got a tip? Submit it here to become an TecMint author.

RedHat RHCE and RHCSA Certification Book
Linux Foundation LFCS and LFCE Certification Preparation Guide

You may also like...

59 Responses

  1. Meetsoni says:

    Thanks and very help full post. thank you so much. But I want to run only application on web, please help how we can access windows or Linux application from web browsers. i know one method that is using SSH in which we can access apps from Linux to windows and vice versa by enabling x11 forwarding in ssh conf file. but that uses commands, but i want to make access to those apps using GUI. either from browser or app. So can you help me with that?

  2. viaksh says:

    Thanks and very help full post. thank you so much. But I want to run only application on web, please help how we can access windows or Linux application from web browsers.

  3. Sidharth says:

    Hi,
    I have done the same steps, but finally i am facing 404 status error.

    HTTP Status 404 – /guacamole

    type Status report

    message /guacamole

    description The requested resource is not available.
    Apache Tomcat/7.0.64 (Ubuntu)

    any idea where am i missed something?

  4. Jay says:

    Hello,
    Thanks for the post but Im having the error HTTP Status 404 – /guacamole, im using linux mint as server.

    thanks.

  5. marcos says:

    Hi Gabriel,

    I have followed your instructions in a Google Cloud Platform. Put Guaca in a ubuntu box. And I have to other instances, Linux, and windows which I am trying to reach. I can see the Linux machine, but the other windows instance, no success. It even doesn’t appear in the connections dashboard. It says connections error. Any ide? Thanks in advance!

  6. Gulab Pasha says:

    Hi Gabriel,

    How do we connect to Connection Machine without Guacamole authorized user, once we generate the link can we connect to it without login?

    Thanks,
    Gulab Pasha

  7. edgar says:

    we made all steps but some error here: ” ERROR: Unable to bind socket to any addresses.”

  8. vigidr says:

    For anyone stuck on invalid logins: Make sure that the user mapping also is readable for the tomcat user. *[email protected]*

  9. vigidr says:

    Hi Gabriel,

    thanks for the tut. Unfortunately I can’t login. The user mapping seems to be unrecognized even when I link the guacamole.properties file to .guacamole folder in tomcat7s home dir, /usr/share/tomcat7/.guacamole. I’m running Debian 8.5 and installed the server via apt-get install instead of compiling it myself.

    Do you have any idea?

  10. Luke Harper says:

    For anyone else stuck on this where you get a 404 status.

    Move the guacamole.war file to the Webapps folder within your “tomcat7” folder.

Got something to say? Join the discussion.

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.