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
- tomcat6
- libvncserver
- freerdp (This is official on the Guacamole site. Fedora 14 will not support Freerdp 1.0 or higher, thus RDP protocol in Guacamole is not available. Leave freerdp out of the code below if you are running Fedora 14.)
- libvorbis
In terminal, as root, install dependencies with the following:
| bash code |
|---|
$ su Password: # yum install tomcat6 libvncserver freerdp libvorbis
|
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.
Downloading the Binary Packages
Go to http://guac-dev.org/ and choose from the table the binary packages for your system. For Fedora 14, I chose the Fedora 15 packages and they worked flawlessly.
Installing Guacamole
In terminal, change directories to where the packages downloaded and execute the following as root:
| bash code |
|---|
# tar -xzf guacamole-0.8.0-fedora-15-i386.tar.gz # cd guacamole-0.8.0-fedora-15-i386/ # rpm -i *.rpm
|
- Be aware that you may have to adjust the above code to match the file name you downloaded.
Setting up MySQL Authentication
Making the Directory
As root, create the "classpath" directory
| bash code |
|---|
mkdir /var/lib/guacamole/classpath
|
Installing MySQL Authentication Module
Download the MySQL Authentication Module http://sourceforge.net/projects/guacamole/files/current/extensions/guacamole-auth-mysql-0.8.0.tar.gz/download
Move to the directory containing the download and unpack the download
| bash code |
|---|
# tar -xzf guacamole-auth-mysql-0.8.0.tar.gz
|
- Be aware that you may have to adjust the above code to match the file name you downloaded.
Copy all of the ".jar" files in the /lib of the downloaded file to the classpath directory you created.
| bash code |
|---|
cp -r /whereever/you/downloaded/it/guacamole-auth-mysql-0.8.0/lib/*.jar /var/lib/guacamole/classpath
|
You need one more ".jar" file (MySQL Connector-J)that is not included in the guacamole-auth-mysql module. You can get it here: http://dev.mysql.com/downloads/connector/j/
Move to the directory containing the download and unpack the download
| bash code |
|---|
# tar -xzf mysql-connector-java-5.1.25.tar.gz
|
- Be aware that you may have to adjust the above code to match the file name you downloaded.
Copy mysql-connector-java-5.1.23-bin.jar to the classpath directory you created.
| bash code |
|---|
cp -r /whereever/you/downloaded/it/mysql-connector-java-5.1.25/mysql-connector-java-5.1.23-bin.jar /var/lib/guacamole/classpath
|
Making the MySQL Tables
Now we need to create a MySQL Table that Guacamole can use
| bash code |
|---|
$ mysql -u root -p Enter password: default for Amahi is hda mysql> CREATE DATABASE guacamole; Query OK, 1 row affected (0.00 sec) mysql> CREATE USER 'guacamole'@'localhost' IDENTIFIED BY 'some_password'; Query OK, 0 rows affected (0.00 sec) mysql> GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole.* TO 'guacamole'@'localhost'; Query OK, 0 rows affected (0.00 sec) mysql> FLUSH PRIVILEGES; Query OK, 0 rows affected (0.02 sec) mysql> quit Bye
|
The database and user can be named whatever you like, but the above code refers to both as "guacamole". Naturally, you should choose a real password for your user rather than the string "some_password" shown above.
Running the SQL scripts
The SQL scripts that create the database schema and default administrator user are included in the guacamole-auth-mysql-0.8.0 archive you downloaded within the schema/ directory. Change directories to the guacamole-auth-mysql-0.8.0 archive.
| bash code |
|---|
cd /whereever/you/downloaded/it/guacamole-auth-mysql-0.8.0
|
The scripts are named such that they can be run in order with one command:
mysql code = $ cat schema/*.sql | mysql -u root -p guacamole Ender password: Amahi default is hda
Configuring Guacamole to Use MySQL Authentication
You will need to edit /etc/guacamole/guacamole.properties
Start at the line "# Hostname and port of guacamole proxy" and replace everything below it with this:
guacd-hostname: localhost guacd-port: 4822 # Auth provider class (authenticates user/pass combination, needed if using the provided login screen) auth-provider: net.sourceforge.guacamole.net.auth.mysql.MySQLAuthenticationProvider basic-user-mapping: /etc/guacamole/user-mapping.xml # Location to read extra .jar's from lib-directory: /var/lib/guacamole/classpath # MySQL properties mysql-hostname: localhost mysql-port: 3306 mysql-database: guacamole mysql-username: guacamole mysql-password: some_password
Use the real password you chose when creating the MySQL database for the Guacamole database in place of the string "some_password" as shown above.
Deploying Guacamole
To deploy Guacamole, you must make two symbolic links: one effectively copying the web application (now located at /var/lib/guacamole/guacamole.war) into the directory Tomcat monitors for web application deployment, and the other effectively copying the configuration file, guacamole.properties, into the Tomcat's classpath, such that Guacamole can find it once it runs. This must be done as root:
| bash code |
|---|
# ln -s /var/lib/guacamole/guacamole.war /var/lib/tomcat6/webapps # ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat6/lib
|
Restart Tomcat
| bash code |
|---|
service tomcat6 restart
|
Start Guacamole's service
| bash code |
|---|
service guacd start
|
Now configure the tomcat6 and guacd services to run automatically
| bash code |
|---|
# chkconfig tomcat6 on # chkconfig guacd on
|
Configuring Guacamole and Amahi
Create Symbolic links between guacamole in Tomcat and Amahi's webapp directory
| bash code |
|---|
# ln -s /var/lib/tomcat6/webapps/guacamole/admin.xhtml /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/agpl-3.0-standalone.html /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/client.xhtml /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/guacamole-common-js /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/images /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/index.xhtml /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/layouts /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/META-INF /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/scripts /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/styles /var/hda/web-apps/guacamole/html # ln -s /var/lib/tomcat6/webapps/guacamole/WEB-INF /var/hda/web-apps/guacamole/html
|
Create .htaccess file in /var/hda/web-apps/guacamole/html
| bash code |
|---|
# cd /var/hda/web-apps/guacamole/html # gedit .htaccess
|
This is the text for the .htaccess file:
RewriteEngine On
RewriteCond %{SERVER_PORT} 80
RewriteRule (.*) http://%{HTTP_HOST}:8080/guacamole [R,L]
Make sure the owner of the file is apache and the group is users.
| bash code |
|---|
# chown apache .htaccess # chgrp users .htaccess
|
In /etc/httpd/conf.d/####-guacamole.conf, change "AllowOverride AuthConfig" to "AllowOverride FileInfo Limit Options Indexes"
Logging In to Guacamole
You can access the web login screen for Guacamole from the server at http://127.0.0.1:8080/guacamole
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.
