Guacamole

What is Guacamole?

Guacamole is an HTML5 remote desktop gateway.

Guacamole provides access to desktop environments using remote desktop protocols like VNC and RDP. A centralized server acts as a tunnel and proxy, allowing access to multiple desktops through a web browser.

No browser plugins are needed, and no client software needs to be installed. The client requires nothing more than a web browser supporting HTML5 and AJAX.

Installing Guacamole on Amahi

Dependencies

The following dependencies are included so as to make as many features in Guacamole available to the installer.

In terminal, as root, install dependencies with the following:

For Fedora 23 or newer (Fedora 21, substitute yum for dnf):

sudo dnf install tomcat gcc cairo-devel libjpeg-devel libpng-devel uuid-devel freerdp-devel \
pango-devel libssh2-devel libtelnet-devel libvncserver-devel pulseaudio-libs-devel openssl-devel \
libvorbis-devel libwebp-devel wget

Some packages may be already included in your Amahi install. If this is so Fedora / Amahi will skip that package.

NOTE: You will need to install the Amahi Web Apps plug-in to use this guidance. Ensure you enable Advanced Settings.

Preparing Amahi

Login to your Amahi Dashboard and choose "Set Up" in the upper right. Now select the "Apps" tab. Click on "Webapps" and on the page that comes up choose the "New Web App" button at the bottom. Fill in the name (guacamole) and leave everything else as it is.

Setting up MySQL Authentication

Creating the Database

hda-create-db-and-user guacdb

Installing MySQL Authentication Module

Create a working directory and move there

sudo mkdir -p /var/hda/web-apps/guacamole/sqlauth && cd /var/hda/web-apps/guacamole/sqlauth

Download Guacamole's authorization module

sudo wget http://sourceforge.net/projects/guacamole/files/current/extensions/guacamole-auth-jdbc-0.9.9.tar.gz

Unpack it

sudo tar -zxf guacamole-auth-jdbc-0.9.9.tar.gz

Download MySQL and Java Connector

sudo wget http://dev.mysql.com/get/Downloads/Connector/j/mysql-connector-java-5.1.38.tar.gz

Unpack it

sudo tar -zxf mysql-connector-java-5.1.38.tar.gz

Create directories for the extensions in Tomcat's folders

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

Move the modules to their respective directories.

sudo mv guacamole-auth-jdbc-0.9.9/mysql/guacamole-auth-jdbc-mysql-0.9.9.jar /usr/share/tomcat/.guacamole/extensions/
sudo mv mysql-connector-java-5.1.38/mysql-connector-java-5.1.38-bin.jar /usr/share/tomcat/.guacamole/lib/

Restart MariaDB

sudo systemctl restart mariadb.service

Loading Guacamole's schema into the MySQL Tables

The schema for MySQL was downloaded in the previous process. Just change directories to the files location

cd /var/hda/web-apps/guacamole/sqlauth/guacamole-auth-jdbc-0.9.9/mysql/schema/ 

and run the following command:

sudo cat ./*.sql | mysql -u root -p hda

Installing Guacamole Server

Guacamole uses "guacd", a Guacamole server and a Guacamole Client for users to connect to the "guacd" server. We first install Guacamole Server.

Change Directories

cd /var/hda/web-apps/guacamole

Download Guacamole Server

sudo wget https://sourceforge.net/projects/guacamole/files/current/source/guacamole-server-0.9.9.tar.gz

Unpackage it

tar -xzf guacamole-server-0.9.9.tar.gz

Move to the Guacamole source code directory

cd guacamole-server-0.9.9/

Configure, make and install it.

sudo ./configure --with-init-dir=/etc/init.d
sudo make
sudo make install
sudo ldconfig

Installing Guacamole Client

Create a new directory and move to it.

sudo mkdir -p /var/lib/guacamole && cd /var/lib/guacamole/

Download Guacamole Client.

sudo wget http://sourceforge.net/projects/guacamole/files/current/binary/guacamole-0.9.9.war -O guacamole.war

Create a symbolic link of the file for Tomcat.

sudo ln -s /var/lib/guacamole/guacamole.war /var/lib/tomcat/webapps/

Guacamole's Configuration File

Create a directory for the configuration file.

sudo mkdir -p /etc/guacamole/

Create a file called "guacamole.properties" in that directory

sudo vi /etc/guacamole/guacamole.properties

Press the i key to begin inserting text into the guacamole.properties file and include the following contents:

# MySQL properties
mysql-hostname: localhost
mysql-port: 3306
mysql-database: guacdb
mysql-username: guacdb
mysql-password: guacdb

# Additional settings
mysql-default-max-connections-per-user: 0
mysql-default-max-group-connections-per-user: 0

If you use vi for creating this file, press the Esc key to get back in command mode and :wq to write the changes and quit vi.

Now create a symbolic link of this file for Tomcat

sudo ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat/.guacamole/

Starting Guacamole Server

Restart Tomcat.

sudo ​service tomcat restart​

Start Guacamole Server. sudo /etc/init.d/guacd start

Configure Guacamole Server to start at boot.

sudo chkconfig tomcat on # chkconfig guacd on

Configuring Guacamole and Amahi

Create Symbolic links between guacamole in Tomcat and Amahi's webapp directory

sudo ln -s /var/lib/tomcat/webapps/guacamole/* /var/hda/web-apps/guacamole/html

As root, create .htaccess file in /var/hda/web-apps/guacamole/html

vi /var/hda/web-apps/guacamole/html/.htaccess

Press the i key to begin inserting text into the .htaccess file and include the following:

RewriteEngine On
RewriteCond %{SERVER_PORT} 80
RewriteRule (.*) http://%{HTTP_HOST}:8080/guacamole [R,L]

Again, if you use vi for creating this file, press the Esc key to get back in command mode and :wq to write the changes and quit vi.

Make sure the owner of all the file is apache and the group is users.

sudo chown -R apache:users /var/hda/web-apps/guacamole

Restart Apache

sudo service httpd restart

Logging In to Guacamole

You can access the web login screen for Guacamole from the server at http://localhost:8080/guacamole

From other computers in the network you can access Guacamole by http://****:8080/guacamole (Where the "****" is the ip address of your Amahi server).

The default user is "guacadmin", with the default password of "guacadmin". You can change your password by editing your own user in the administration screen.

With everything configured correctly you should be able to access the web login screen through Amahi at http://guacamole.yourhdaname.com:8080/guacamole/

Port Forwarding

If you want Guacamole's web interface to be accessible outside of your LAN you will have to forward a random, unused port (1111, for example) to port 8080 in your router. Then when you access Guacamole from outside your LAN you will need to add "/guacamole" to the end of your url. (serverblahblah.yourhda.com:1111/guacamole) If you do not add "/guacamole" to your url, you will see a blank page since you did not specify which application in Tomcat you wanted to access.