Difference between revisions of "Cool Solution - Guacamole"

From Univention Wiki

Jump to: navigation, search
(Migrated into App Center)
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Version|UCS=4.1}}
+
{{#seo:
{{Cool Solutions Disclaimer}}
+
|title={{#replace:{{#replace:{{#replace:{{#replace:{{FULLPAGENAME}}|'|'}}|&|&}}|"|"}}|Cool Solution - |}} - {{SITENAME}}
 +
<!--|description=-->
 +
}}
  
Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC and RDP.
+
Guacamole has been moved to the Univention App Center and can be reached under https://www.univention.com/products/univention-app-center/app-catalog/guacamole/.
 
 
The version of Guacamole used in this article is Guacamole 0.9.8.
 
== Installation ==
 
To successfully deploy and start Guacamole, three images must be downloaded via Docker:
 
* guacd
 
* guacamole
 
* mysql
 
At the moment, Docker images of Guacamole can only be started when a database is provided.
 
 
 
''Hint'': Instead of MySQL, PostgreSQL can be used as well. In this case the image '''postgres''' must be downloaded. Refer to the [https://registry.hub.docker.com/_/postgres/ Docker documentation] and [http://guac-dev.org/doc/gug/jdbc-auth.html#jdbc-auth-postgresql Guacamole manual] for downloading and configuring PostgreSQL. This article will use the MySQL connection.
 
 
 
== Configuration ==
 
=== Automatically start Docker container ===
 
If the container should start automatically, eg. after a server reboot, add the following line to the <code>docker run</code> command:
 
<pre>
 
--restart=always
 
</pre>
 
 
 
=== MySQL ===
 
Download and deploy the MySQL image:
 
<pre>
 
docker run --name mysql -e MYSQL_ROOT_PASSWORD=<MYSQL_PASSWORD> -d mysql:5.7.7
 
</pre>
 
''Hint'': Change <MYSQL_PASSWORD> to an actual password of your choice.
 
 
 
This will download and deploy the MySQL image and provide an instance as "mysql". After the command is finished, a 65 character long ID is printed out. Save this ID for the next step.
 
 
 
=== guacd ===
 
Download and deploy the guacd image:
 
<pre>
 
docker run --name guacd -d glyptodon/guacd
 
</pre>
 
This will provide the guacd daemon that handles all Guacamole connections. Nothing more must be done with this container.
 
 
 
==== Creating the Guacamole database ====
 
First, run the following command to create the tables for the database:
 
<pre>
 
docker run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
 
</pre>
 
''Hint'': This command will also download the Guacamole image, but does not start Guacamole for using. This is a one-time command and should not contain a <code>--restart</code> parameter.
 
 
 
Next, copy the local file '''initdb.sql''' to the MySQL Docker container:
 
<pre>
 
cp initdb.sql /var/lib/docker/overlay/<MySQL ID>/merged/root/
 
</pre>
 
 
 
Replace <MySQL ID> with the ID you saved in the step above.
 
 
 
Next, connect to the MySQL container to create the Guacamole databse, user and tables:
 
<pre>
 
docker exec -it mysql bash
 
</pre>
 
This will provide a bash inside the MySQL container.
 
 
 
Next, connect to MySQL to create the database and user for Guacamole:
 
<pre>
 
mysql -uroot -p<MYSQL_PASSWORD>
 
CREATE DATABASE guacamole_db;
 
CREATE USER 'guacamole_user'@'%' IDENTIFIED BY '<GUACAMOLE_PASSWORD>';
 
GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'%';
 
FLUSH PRIVILEGES;
 
quit
 
</pre>
 
''Hint'': Change <GUACAMOLE_PASSWORD> to the actual password used for the Guacamole database user.
 
 
 
Next, create the database structure needed by Guacamole:
 
<pre>
 
cat /root/initdb.sql | mysql -uroot -p<MYSQL_PASSWORD> guacamole_db
 
</pre>
 
 
 
Leave the container with:
 
<pre>
 
exit
 
</pre>
 
 
 
=== guacamole ===
 
Since the Guacamole image is already downloaded, just deploy Guacamole itself. Guacamole comes with a Apache Tomcat8 server:
 
<pre>
 
docker run --name guacamole --link guacd:guacd --link mysql:mysql \
 
-e MYSQL_DATABASE=guacamole_db \
 
-e MYSQL_USER=guacamole_user \
 
-e MYSQL_PASSWORD=<GUACAMOLE_PASSWORD> \
 
-d -p 8181:8080 glyptodon/guacamole
 
</pre>
 
 
 
With the parameter <code>-p 8181:8080</code>, the Tomcat port 8080 from inside the container is routed to the local port 8181. This is done to prevent other software, like Zarafa (which also uses port 8080) to malfunction.
 
 
 
=== Apache ===
 
To provide Guacamole via Apache, add the following site as a new file <code>guacamole</code> to your Apache installation in <code>/etc/apache2/sites-available</code>:
 
<pre>
 
<Location /guacamole>
 
Order allow,deny
 
Allow from all
 
ProxyPass http://localhost:8181/guacamole max=20 flushpackets=on
 
ProxyPassReverse http://localhost:8181/guacamole
 
</Location>
 
</pre>
 
 
 
Next you must make the new site available and reload the Apache webserver:
 
<pre>
 
a2ensite guacamole
 
invoke-rc.d apache2 reload
 
</pre>
 
 
 
It is possible to get access to Guacamole via Tomcat. For this, please refer to the Tomcat manual for accessing applications.
 
 
 
=== UCS overview ===
 
To configure the UCS startsite to provide a link to Guacamole as a webservice, the UCR variables <code>ucs/web/overview/entries/service</code> must be set:
 
<pre>
 
ucr set \
 
ucs/web/overview/entries/service/guacamole/description/de="Guacamole für Remote-Zugriff per RDP oder VNC." \
 
ucs/web/overview/entries/service/guacamole/description="Guacamole for accessing remote systems via RDP or VNC." \
 
ucs/web/overview/entries/service/guacamole/icon="/guacamole/images/logo-64.png" \
 
ucs/web/overview/entries/service/guacamole/label/de="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/label="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/link="/guacamole"
 
</pre>
 
 
 
The above configuration assumes that your Guacamole installation is configured via Apache. The UCR variable <code>ucs/web/overview/entries/service/guacamole/link</code> must be changed accordingly.
 
 
 
After that, you can access you Guacamole installation via http://FQDN-of-your-UCS/guacamole or via the overview site http://FQDN-of-your-UCS/ucs-overview.
 
 
 
''Note'': The default administration user is '''guacadmin''', the password is '''guacadmin'''. It is advised to change the password after the first login! To do this, open the top-right drop down menu and go to Settings → Preferences.
 
 
 
=== Authentication ===
 
Guacamole can be configured to use several backends for authentication:
 
* [http://guac-dev.org/doc/gug/ldap-auth.html LDAP]
 
* [http://guac-dev.org/doc/gug/noauth.html No authentication]
 
''Hint'': Please take note, that only '''one''' authentication module can be active at time! The default for this Docker image is the '''MySQL authentication'''. Users can be configured via the settings menu from the administrator account.
 
 
 
==== Accessing the container ====
 
The conainter can either be accessed by starting a shell inside the container:
 
<pre>
 
docker exec -it guacamole bash
 
</pre>
 
 
 
or by changing into the started Docker container's filesystem directory in the local server's filesystem:
 
<pre>
 
DOCKER_ID=$(docker ps --no-trunc | awk '/glyptodon\/guacamole:latest/ {print $1}')
 
cd /var/lib/docker/overlay/"${DOCKER_ID}"/merged
 
</pre>
 
 
 
==== Installing auth plugins ====
 
To install other authentication methods than the MySQL authentication, download the according plugin from [http://guac-dev.org/release/release-notes-0-9-8 here] (section '''Compatible extensions''' in the top right corner). To install another auth plugin, download the desired plugin and place it inside the '''mysql''' or '''postgres''' folder in <code>/opt/guacamole</code> in the Guacamole container, and remove any other auth plugin available in that folder. For accessing the container, look at [[Cool Solution - Guacamole#Accessing the container|Accessing the container]].
 
 
 
''Hint'': Depending on how you initally configured the Guacamole container, choose either '''mysql''' or '''postgres'''.
 
 
 
Next, add a line near the end to the <code>/opt/guacamole/bin/start.sh</code> script to enable your plugin. In case of the noauth plugin:
 
 
 
Before:
 
<pre>
 
[...]
 
#
 
# Finally start Guacamole (under Tomcat)
 
#
 
 
 
start_guacamole
 
</pre>
 
 
 
After:
 
<pre>
 
[...]
 
#
 
# Finally start Guacamole (under Tomcat)
 
#
 
 
 
echo "noauth-config: /opt/guacamole/noauth.xml" >> $GUACAMOLE_HOME/guacamole.properties
 
start_guacamole
 
</pre>
 
 
 
Save the file and restart the docker container:
 
<pre>
 
docker restart guacamole
 
</pre>
 
 
 
It can take up to five minutes until Tomcat is started and Guacamole deployed.
 
 
 
===== Example configuration =====
 
An example for the noauth-plugin against a UCC terminal server using RDP:
 
<pre>
 
<configs>
 
<config name="UCC session" protocol="rdp">
 
<param name="hostname" value="ucc-ts" />
 
<param name="port" value="3389" />
 
</config>
 
</configs>
 
</pre>
 
 
 
The configuration must be saved in the file <code>/opt/guacamole/noauth.xml</code> inside the Guacamole container.
 
 
 
== Further information ==
 
More information about configuration can be obtained from the [http://guac-dev.org/doc/gug/ Guacamole manual].
 
 
 
[[Category: EN]]
 

Latest revision as of 11:56, 8 February 2019

Guacamole has been moved to the Univention App Center and can be reached under https://www.univention.com/products/univention-app-center/app-catalog/guacamole/.

Personal tools