Installing Apache Guacamole in Ubuntu

This site requires Javascript

You are seeing this if you have Javascript disabled.

Considerations before you begin

This guide has only been tested working on AMD64 architecture. I have had issues trying to do this on ARM based devices as particular packages have been missing from the software repos for that architecture. I may look into work-arounds in the future or the issue may resolve itself over time.

Also Guacamole relies on Tomcat which may complicate things if you are already running:

Tomcat for another webapp
A different web server that uses 8080

Personally I run Guacamole in its own LXD container.

Basic Setup

For convenience start by switching to your root user

sudo su

Because we need to install packages it is recommended that you update your repos first

apt update

In this I use nano for file editing. If you’re doing this in a fresh container and don’t want to use vi you’ll probably want to run

apt install nano -y

Compiling and configuring Guacamole Server

As we are going to be compiling the Guacamole server daemon from source we need to install the prerequisites

apt install build-essential wget libcairo2-dev libjpeg-turbo8-dev libpng-dev libtool-bin libossp-uuid-dev libvncserver-dev freerdp2-dev libssh2-1-dev libtelnet-dev libwebsockets-dev libpulse-dev libvorbis-dev libwebp-dev libssl-dev libpango1.0-dev libswscale-dev libavcodec-dev libavutil-dev libavformat-dev -y

For reference here is the Guacamole page that I got these from: https://guacamole.apache.org/doc/gug/installing-guacamole.html

You may want to reference it if:

You want to be be more selective because you only need certain features
If you want to try to adapt this guide for a RHEL based distro and need their package names
You’re using this in a future where I’ve forgotten about this article and have not updated packages as they change over time

Change to your working directory that you want to download and extract into

cd "{:WorkingDirectory:}"

Download the Guacamole server source

wget https://{:ApacheCDN:}/guacamole/{:GuacamoleVersion:}/source/guacamole-server-{:GuacamoleVersion:}.tar.gz -O  "{:WorkingDirectory:}/guacamole-server-{:GuacamoleVersion:}.tar.gz"

Extract the source

tar -xvf guacamole-server-{:GuacamoleVersion:}.tar.gz

Change into the extracted directory

cd guacamole-server-{:GuacamoleVersion:}

Configure, make, install and link libraries

./configure --with-systemd-dir=/etc/systemd/system/

With Guacamole 1.4.0 on Ubuntu 22.04 I had an issue with my build failing because Guacamole was using depreciated functions. To get around “all warnings being treated as errors” during make run this instead

./configure --with-systemd-dir=/etc/systemd/system/ CFLAGS=-Wno-error

Now make, install and link libraries

make
make install
ldconfig

Before we start the service we need to create our Guacamole config folder

mkdir -p /etc/guacamole

Then create our Guacamole daemon config file

nano /etc/guacamole/guacd.conf

Populate the file with the following:

[server]
bind_host = 127.0.0.1
bind_port = 4822

There are not many options but for reference if you would like to know them they can be found here: https://guacamole.apache.org/doc/gug/configuring-guacamole.html#configuring-guacd

Reload services then enable and start the Guacamole Server

systemctl daemon-reload
systemctl enable guacd
systemctl start guacd

That is it for the server installation, you can check it is working by running

systemctl status guacd

Configuring Guacamole Client

Apache provide the Guacamole Client webapp pre-compiled so we only need to download the Tomcat platform that hosts it

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

Then download the pre-compiled webapp

wget https://{:ApacheCDN:}/guacamole/{:GuacamoleVersion:}/binary/guacamole-{:GuacamoleVersion:}.war -O  "{:WorkingDirectory:}/guacamole-{:GuacamoleVersion:}.war"

And copy it into Tomcat’s webapp folder

cp "{:WorkingDirectory:}/guacamole-{:GuacamoleVersion:}.war" /var/lib/tomcat9/webapps/guacamole.war

Then we can create our main Guacamole config file for the webapp

nano /etc/guacamole/guacamole.properties

Populate the file with the following:

#Guacamole server daemon details
guacd-hostname: 127.0.0.1
guacd-port: 4822

#Guacamole client webapp configuration
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

Next we will need to create the basic user mapping file

nano /etc/guacamole/user-mapping.xml

Here is an example which has a user that connects to RDP:

<user-mapping>
  <authorize
    username="{:GuacUsername:}"
    password="{:GuacPWDMD5:}"
    encoding="md5">

    <connection name="{:ConnectionName:}">
      <protocol>rdp</protocol>
      <param name="hostname">{:RDPHostname:}</param>

      <param name="domain">{:RDPUserDomain:}</param>
      <param name="username">{:RDPUsername:}</param>
      <param name="password">{:RDPUserPassword:}</param>

      <param name="ignore-cert">true</param>
      <param name="resize-method">display-update</param>
    </connection>
  </authorize>
</user-mapping>

To learn more about the options available please read: https://guacamole.apache.org/doc/gug/configuring-guacamole.html

I would recommend not skipping over the section on parameter tokens as they are useful for doing things like passing the Guacamole user’s password into the RDP connection’s password.

As you may have noticed the Guacamole user password is an MD5 hash. If you don’t want to use my website to do the hash for you (I assume because you can’t be bothered inspecting the code to make sure it’s safe) you can also run the following command to generate the hash for you (provided that you have openssl installed).

echo -n "{:GuacPWD:}" | openssl md5

Please note that this will instead save the password into your command history unless you run something like this afterwards: kill -9 $$

With all that complete all you need to do now is restart the Tomcat service and you are good to go

systemctl restart tomcat9

You should now be able to access and use Guacamole via: http://{:GuacamoleServerIP:}:8080/guacamole/

NGINX reverse proxy

If you have NGINX configured as a reverse proxy you can add the following location to your server block to reverse proxy Guacamole (I’m going to assume that you know what I mean by this):

location /guacamole/ {
    proxy_pass http://{:GuacamoleServerIP:}: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;
}

If you would like to rename the location alias you can do so with the following changes:

location /{:LocationAlias:}/ {
    proxy_pass http://{:GuacamoleServerIP:}: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/ /{:LocationAlias:}/;
}

Then restart your NGINX service and you are good to go

systemctl restart nginx

Tags: #Os #Linux #Ubuntu #Apache Guacamole