Apache Guacamole 1.2.0 Install Guide

The Apache Software Foundation released Guacamole v1.2.0 on 28 June 2020. In this guide we will be building a Guacamole instance on CentOS 8. We have also posted a video on Youtube that follows this guide.

---

Prerequisites:

CentOS 8 (we are using a “minimal install” but any installation should work)

---

This guide is written assuming that you are logged in as root. You can do this from a non root account with sudo privileges, but sudo will need to be placed before each command.

1. Once we have a installed CentOS 8, we are going to set the hostname, update the OS and other packages, and enable the Enterprise Linux Repositories (EPEL):

hostnamectl set-hostname guac

dnf install -y epel-release

dnf update -y

2. Guacamole requires ffmpeg-devel, and that package is not included with the base CentOS or EPEL repositories so we will need to enable/install a repository that includes ffmpeg-devel and its dependencies. For this tutorial we will be using RPM Fusion but other 3rd party repositories that have the necessary packages will work as well. Use this command to install RPM Fusion:

dnf install -y --nogpgcheck https://mirrors.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm https://mirrors.rpmfusion.org/nonfree/el/rpmfusion-nonfree-release-8.noarch.rpm

3. We also need to enable two built in repos:

dnf config-manager --set-enabled powertools

dnf config-manager --set-enabled devel

4. Next we need to download and install several dependencies:

dnf install -y make cairo-devel libjpeg-turbo-devel libwebsockets-devel libpng-devel uuid-devel ffmpeg-devel freerdp-devel pango-devel libssh2-devel libvncserver-devel pulseaudio-libs-devel openssl-devel libvorbis-devel libwebp-devel libtool libuv-devel freerdp mariadb-server wget pkgconfig libtelnet libtelnet-devel

5. Apache Tomcat, which is the web server Guacamole runs on, is also not yet available via the default CentOS8 repos. Instead, we are going to rely on a third party repository.

dnf install -y https://harbottle.gitlab.io/harbottle-main/8/x86_64/harbottle-main-release.rpm

dnf install -y tomcat9

6. Now download and extract the Guacamole server source code (.tar.gz) and download the Guacamole Web Application (.war)

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

tar -xzf guacamole-server-1.2.0.tar.gz

wget https://downloads.apache.org/guacamole/1.2.0/binary/guacamole-1.2.0.war

7. Once the source code is downloaded and extracted, we need to prep it for compiling and installation.

cd guacamole-server-1.2.0

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

If the required dependencies from the previous steps were installed correctly, all of the libraries, protocols, and services/tools should say yes except for wsock32. If you see any “no” items, go back to step 3 and verify all of the packages installed correctly.

8. We can now run make/install.

make install

ldconfig && cd ~

9. We need to enable tomcat, mariadb, and guacd to start each time our system starts or reboots.

systemctl enable tomcat9 && systemctl enable mariadb && systemctl enable guacd

10. The guacamole web application that we downloaded in step 4 needs to be copied to the correct directory

cp ~/guacamole-1.2.0.war /var/lib/tomcat9/webapps/guacamole.war

11. The firewall needs to be opened to allow tomcat/guacamole to connect via port 8080.

firewall-cmd --permanent --add-port=8080/tcp

firewall-cmd --reload

12. To configure Guacamole to support multiple users and connections, we need to download and configure the MariaDB J/Connector and the Guacamole JDBC module.

mkdir -p /usr/share/tomcat9/.guacamole/{extensions,lib}

wget https://downloads.mariadb.com/Connectors/java/connector-java-2.7.0/mariadb-java-client-2.7.0.jar

cp mariadb-java-client-2.7.0.jar /usr/share/tomcat9/.guacamole/lib/

wget https://downloads.apache.org/guacamole/1.2.0/binary/guacamole-auth-jdbc-1.2.0.tar.gz

tar -xzf guacamole-auth-jdbc-1.2.0.tar.gz

cp guacamole-auth-jdbc-1.2.0/mysql/guacamole-auth-jdbc-mysql-1.2.0.jar /usr/share/tomcat9/.guacamole/extensions/

13. Let’s now start mariadb and tomcat.

systemctl start mariadb && systemctl start tomcat9

14. Next we need to better secure our mysql/mariadb installation

mysql_secure_installation

15. Press enter when asked “Enter current password for root (enter for none):”

16. Enter “Y” to set your own root password. This should be different from your normal root user password. Make sure you save this password for future use. For this demo, we are going to use GuacDemo as our password.

17. Enter “Y” to remove anonymous users, and then “Y” again to disallow remote root login.

18. Enter “Y” to remove the test database, and finally “Y” again to reload the privilege tables.

19. Now we need to configure the tables and database scheme so that Guacamole can store connection and user information in the database. Log into mysql, you will be promoted to enter the password you created in step 16.

mysql -u root -p

20. Enter the following lines of SQL once you’ve been greeted with the MariaDB prompt.

CREATE DATABASE IF NOT EXISTS guacdb DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;

GRANT SELECT,INSERT,UPDATE,DELETE ON guacdb.* TO 'guacuser'@'localhost' IDENTIFIED BY 'guacpass' WITH GRANT OPTION;

flush privileges;

quit

21. We now need to download and extract the guacamole client, and cat the .sql files to mysql from inside the jbdc folder.

wget https://downloads.apache.org/guacamole/1.2.0/source/guacamole-client-1.2.0.tar.gz

tar -xzf guacamole-client-1.2.0.tar.gz

cat guacamole-client-1.2.0/extensions/guacamole-auth-jdbc/modules/guacamole-auth-jdbc-mysql/schema/*.sql | mysql -u root -p guacdb

Note: You will be prompted for a password after this step. Use the MySQL password you created back in step 16.

22. Now we need to create the Guacamole configuration file.

mkdir -p /etc/guacamole/ && vi /etc/guacamole/guacamole.properties

Now paste the following into the file (press i on the keyboard to enter insert mode):

----------------------------------Inset Into VI---------------------------------------
MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacdb
mysql-username: guacuser
mysql-password: guacpass
Additional settings
mysql-driver: mariadb
mysql-default-max-connections-per-user: 0
mysql-default-max-group-connections-per-user: 0
----------------------------------End Inset Into VI-----------------------------------

Note: To exit vi and save the file, press esc, then the colon symbol ":", type wq, and press enter.

23. Now we fix some file permissions and create a symbolic link.

chmod 0400 /etc/guacamole/guacamole.properties

chown tomcat9:tomcat9 /etc/guacamole/guacamole.properties

ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat9/.guacamole/

chown tomcat9:tomcat9 /var/lib/tomcat9/webapps/guacamole.war

24. Finally, we need to fix a permission issue with SELinux that will prevent Guacamole from working correctly.

setsebool -P tomcat_can_network_connect_db on

restorecon -R -v /usr/share/tomcat9/.guacamole/lib/mariadb-java-client-2.7.0.jar

25. That should be it! Just reboot your machine, and with any luck you will be greeted with the guacamole login screen when you navigate to:

[your_ip]:8080/guacamole

The default username is: guacadmin and the default password: guacadmin.

If you get a blank white screen, try step 25 again and reboot your computer. If you are still

met with a blank white screen, try disabling SELinux.