Difference between revisions of "Cool Solution - Guacamole"

From Univention Wiki

Jump to: navigation, search
(Updated the page to UCS 4.2)
Line 1: Line 1:
{{Version|UCS=4.1}}
+
{{Version|UCS=4.2}}
 
{{Cool Solutions Disclaimer}}
 
{{Cool Solutions Disclaimer}}
 +
{{Review-Status}}
  
 
Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC and RDP.
 
Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC and RDP.
  
The version of Guacamole used in this article is Guacamole 0.9.8.
+
The version of Guacamole used in this article is Guacamole 0.9.12-incubating.
 
== Installation ==
 
== Installation ==
 
To successfully deploy and start Guacamole, three images must be downloaded via Docker:
 
To successfully deploy and start Guacamole, three images must be downloaded via Docker:
Line 12: Line 13:
 
At the moment, Docker images of Guacamole can only be started when a database is provided.
 
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.
+
''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 [https://guacamole.incubator.apache.org/doc/gug/jdbc-auth.html#jdbc-auth-postgresql Guacamole manual] for downloading and configuring PostgreSQL. This article will use the MySQL connection.
  
== Configuration ==
+
In this article the following Guacamole docker containers are used:
=== Automatically start Docker container ===
+
* https://hub.docker.com/r/mjumper/guacd/
If the container should start automatically, eg. after a server reboot, add the following line to the <code>docker run</code> command:
+
* https://hub.docker.com/r/mjumper/guacamole/
<pre>
 
--restart=always
 
</pre>
 
  
 
=== MySQL ===
 
=== MySQL ===
Line 33: Line 31:
 
Download and deploy the guacd image:
 
Download and deploy the guacd image:
 
<pre>
 
<pre>
docker run --name guacd -d glyptodon/guacd
+
docker run --name guacd -d mjumper/guacd
 
</pre>
 
</pre>
 
This will provide the guacd daemon that handles all Guacamole connections. Nothing more must be done with this container.
 
This will provide the guacd daemon that handles all Guacamole connections. Nothing more must be done with this container.
Line 40: Line 38:
 
First, run the following command to create the tables for the database:
 
First, run the following command to create the tables for the database:
 
<pre>
 
<pre>
docker run --rm glyptodon/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
+
docker run --rm mjumper/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql
 
</pre>
 
</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.
 
''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.
Line 46: Line 44:
 
Next, copy the local file '''initdb.sql''' to the MySQL Docker container:
 
Next, copy the local file '''initdb.sql''' to the MySQL Docker container:
 
<pre>
 
<pre>
cp initdb.sql /var/lib/docker/overlay/<MySQL ID>/merged/root/
+
docker cp initdb.sql mysql:/root
 
</pre>
 
</pre>
  
Line 85: Line 83:
 
-e MYSQL_USER=guacamole_user \
 
-e MYSQL_USER=guacamole_user \
 
-e MYSQL_PASSWORD=<GUACAMOLE_PASSWORD> \
 
-e MYSQL_PASSWORD=<GUACAMOLE_PASSWORD> \
-d -p 8181:8080 glyptodon/guacamole
+
-d -p 8181:8080 mjumper/guacamole
 
</pre>
 
</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.
 
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.
 +
 +
== 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>
  
 
=== Apache ===
 
=== 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>:
+
To provide Guacamole via Apache, add the following site as a new file <code>guacamole.conf</code> to your Apache installation in <code>/etc/apache2/sites-available</code>:
 
<pre>
 
<pre>
 
<Location /guacamole>
 
<Location /guacamole>
Order allow,deny
+
Require all granted
Allow from all
 
 
ProxyPass http://localhost:8181/guacamole max=20 flushpackets=on
 
ProxyPass http://localhost:8181/guacamole max=20 flushpackets=on
 
ProxyPassReverse http://localhost:8181/guacamole
 
ProxyPassReverse http://localhost:8181/guacamole
Line 104: Line 108:
 
<pre>
 
<pre>
 
a2ensite guacamole
 
a2ensite guacamole
invoke-rc.d apache2 reload
+
systemctl reload apache2.service
 
</pre>
 
</pre>
  
Line 114: Line 118:
 
ucr set \
 
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/de="Guacamole für Remote-Zugriff per RDP oder VNC." \
 +
ucs/web/overview/entries/service/guacamole/description/fr="Guacamole pour l'accès distant via RDP ou VNC." \
 
ucs/web/overview/entries/service/guacamole/description="Guacamole for accessing remote systems via RDP or 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/icon="/guacamole/images/logo-64.png" \
 
ucs/web/overview/entries/service/guacamole/label/de="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/label/de="Guacamole" \
 +
ucs/web/overview/entries/service/guacamole/label/fr="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/label="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/label="Guacamole" \
 
ucs/web/overview/entries/service/guacamole/link="/guacamole"
 
ucs/web/overview/entries/service/guacamole/link="/guacamole"
 
</pre>
 
</pre>
 +
''Note'': The UCR variables can be set on a UCS 4.2 system, a Portal entry is created automatically.
  
 
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.
 
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.
Line 127: Line 134:
 
''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.
 
''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 ===
+
=== Accessing the container ===
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:
 
The conainter can either be accessed by starting a shell inside the container:
 
<pre>
 
<pre>
Line 141: Line 142:
 
or by changing into the started Docker container's filesystem directory in the local server's filesystem:
 
or by changing into the started Docker container's filesystem directory in the local server's filesystem:
 
<pre>
 
<pre>
DOCKER_ID=$(docker ps --no-trunc | awk '/glyptodon\/guacamole:latest/ {print $1}')
+
DOCKER_ID=$(docker ps --no-trunc | awk '/mjumper\/guacamole:latest/ {print $1}')
 
cd /var/lib/docker/overlay/"${DOCKER_ID}"/merged
 
cd /var/lib/docker/overlay/"${DOCKER_ID}"/merged
 
</pre>
 
</pre>
  
==== Installing auth plugins ====
+
=== User authentication ===
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]].
+
==== Installing the "No auth" plugins ====
 +
To use Guacamole with no user login, download the "No auth" plugin from [https://guacamole.incubator.apache.org/releases/0.9.12-incubating/ here] (file name: guacamole-auth-noauth-<VERSION>-incubating.tar.gz). To install the plugin, download the 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'''.
+
''Hint'': Depending on how you initally configured the Guacamole container, choose either '''mysql''' or '''postgres'''.<br>
 +
''Note'': Download <VERSION> accordingly to the Guacamole version.
  
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:
+
Next, add a line near the end to the <code>/opt/guacamole/bin/start.sh</code> script to enable your plugin:
  
 
Before:
 
Before:
Line 192: Line 195:
  
 
The configuration must be saved in the file <code>/opt/guacamole/noauth.xml</code> inside the Guacamole container.
 
The configuration must be saved in the file <code>/opt/guacamole/noauth.xml</code> inside the Guacamole container.
 +
 +
==== Using the LDAP ====
 +
 +
Edit the start script <code>/opt/guacamole/bin/start.sh</code> inside the docker container and add the following block at the end of the file, just before the <code>start_guacamole</code> command:
 +
<pre>
 +
echo "ldap-hostname: <IP or FQDN of the LDAP server>" >> $GUACAMOLE_HOME/guacamole.properties
 +
echo "ldap-port: 7389" >> $GUACAMOLE_HOME/guacamole.properties
 +
echo "ldap-search-bind-dn: <DN of LDAP search user>" >> $GUACAMOLE_HOME/guacamole.properties
 +
echo "ldap-search-bind-password: <Password of LDAP search user>" >> $GUACAMOLE_HOME/guacamole.properties
 +
echo "ldap-user-base-dn: cn=users,<LDAP base>" >> $GUACAMOLE_HOME/guacamole.properties
 +
echo "ldap-username-attribute: uid" >> $GUACAMOLE_HOME/guacamole.properties
 +
ln -s /opt/guacamole/ldap/guacamole-auth-ldap-*-incubating.jar $GUACAMOLE_HOME/extensions
 +
</pre>
 +
''Note'': To get the LDAP base, run <code>ucr get ldap/base</code> on the command line.
 +
 +
The users, who should be able to login to Guacamole, must be added to the Guacamole database.
 +
 +
To do this, login to Guacamole using the '''guacadmin''' user and add users using the administration panel. Create the connections like described in the [https://guacamole.incubator.apache.org/doc/gug/administration.html#connection-management documentation].
 +
 +
After creating a connection, users must be added, take a look at the [https://guacamole.incubator.apache.org/doc/gug/administration.html#user-management documentation] for details. While creating a user, any password can be entered (not necessarily the user's LDAP password). Since Guacamole is configured to also authenticate against the LDAP, Guacamole will try to bind the user to any available database with the given credentials, and the first one succeeds. Guacamole matches the LDAP username with the MySQL username and provides all connections to the username. While creating a user it can be configured which connections or connection groups a user is allowed to use.<br>
 +
''Note'': Connections can be grouped together in "Connection groups", which then can be configured to be accessed by a user. All connections of a connection group are available to the user.<br>
 +
''Attention'''': It is important that the username matches the LDAP username!
  
 
== Further information ==
 
== Further information ==
More information about configuration can be obtained from the [http://guac-dev.org/doc/gug/ Guacamole manual].
+
* More information about configuration can be obtained from the [https://guacamole.incubator.apache.org/doc/gug/ Guacamole manual].
 +
* Creating an [[Cool Solution - LDAP search user | LDAP search user]]
  
 
[[Category: EN]]
 
[[Category: EN]]

Revision as of 11:41, 21 April 2017

Produktlogo UCS Version 4.2

Note: Cool Solutions are articles documenting additional functionality based on Univention products. Not all of the shown steps in the article are covered by Univention Support. For questions about your support coverage contact your contact person at Univention before you want to implement one of the shown steps.

Also regard the legal notes at Terms of Service.
Note: This article is not yet reviewed.


Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC and RDP.

The version of Guacamole used in this article is Guacamole 0.9.12-incubating.

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 Docker documentation and Guacamole manual for downloading and configuring PostgreSQL. This article will use the MySQL connection.

In this article the following Guacamole docker containers are used:

MySQL

Download and deploy the MySQL image:

docker run --name mysql -e MYSQL_ROOT_PASSWORD=<MYSQL_PASSWORD> -d mysql:5.7.7

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:

docker run --name guacd -d mjumper/guacd

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:

docker run --rm mjumper/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql

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 --restart parameter.

Next, copy the local file initdb.sql to the MySQL Docker container:

docker cp initdb.sql mysql:/root

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:

docker exec -it mysql bash

This will provide a bash inside the MySQL container.

Next, connect to MySQL to create the database and user for Guacamole:

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

Hint: Change <GUACAMOLE_PASSWORD> to the actual password used for the Guacamole database user.

Next, create the database structure needed by Guacamole:

cat /root/initdb.sql | mysql -uroot -p<MYSQL_PASSWORD> guacamole_db

Leave the container with:

exit

guacamole

Since the Guacamole image is already downloaded, just deploy Guacamole itself. Guacamole comes with a Apache Tomcat8 server:

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 mjumper/guacamole

With the parameter -p 8181:8080, 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.

Configuration

Automatically start Docker container

If the container should start automatically, eg. after a server reboot, add the following line to the docker run command:

--restart=always

Apache

To provide Guacamole via Apache, add the following site as a new file guacamole.conf to your Apache installation in /etc/apache2/sites-available:

<Location /guacamole>
	Require all granted
	ProxyPass http://localhost:8181/guacamole max=20 flushpackets=on
	ProxyPassReverse http://localhost:8181/guacamole
</Location>

Next you must make the new site available and reload the Apache webserver:

a2ensite guacamole
systemctl reload apache2.service

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 ucs/web/overview/entries/service must be set:

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/fr="Guacamole pour l'accès distant via RDP ou 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/fr="Guacamole" \
ucs/web/overview/entries/service/guacamole/label="Guacamole" \
ucs/web/overview/entries/service/guacamole/link="/guacamole"

Note: The UCR variables can be set on a UCS 4.2 system, a Portal entry is created automatically.

The above configuration assumes that your Guacamole installation is configured via Apache. The UCR variable ucs/web/overview/entries/service/guacamole/link 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.

Accessing the container

The conainter can either be accessed by starting a shell inside the container:

docker exec -it guacamole bash

or by changing into the started Docker container's filesystem directory in the local server's filesystem:

DOCKER_ID=$(docker ps --no-trunc | awk '/mjumper\/guacamole:latest/ {print $1}')
cd /var/lib/docker/overlay/"${DOCKER_ID}"/merged

User authentication

Installing the "No auth" plugins

To use Guacamole with no user login, download the "No auth" plugin from here (file name: guacamole-auth-noauth-<VERSION>-incubating.tar.gz). To install the plugin, download the plugin and place it inside the mysql or postgres folder in /opt/guacamole in the Guacamole container, and remove any other auth plugin available in that folder. For accessing the container, look at Accessing the container.

Hint: Depending on how you initally configured the Guacamole container, choose either mysql or postgres.
Note: Download <VERSION> accordingly to the Guacamole version.

Next, add a line near the end to the /opt/guacamole/bin/start.sh script to enable your plugin:

Before:

[...]
#
# Finally start Guacamole (under Tomcat)
#

start_guacamole

After:

[...]
#
# Finally start Guacamole (under Tomcat)
#

echo "noauth-config: /opt/guacamole/noauth.xml" >> $GUACAMOLE_HOME/guacamole.properties
start_guacamole

Save the file and restart the docker container:

docker restart guacamole

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:

<configs>
	<config name="UCC session" protocol="rdp">
		<param name="hostname" value="ucc-ts" />
		<param name="port" value="3389" />
	</config>
</configs>

The configuration must be saved in the file /opt/guacamole/noauth.xml inside the Guacamole container.

Using the LDAP

Edit the start script /opt/guacamole/bin/start.sh inside the docker container and add the following block at the end of the file, just before the start_guacamole command:

echo "ldap-hostname: <IP or FQDN of the LDAP server>" >> $GUACAMOLE_HOME/guacamole.properties
echo "ldap-port: 7389" >> $GUACAMOLE_HOME/guacamole.properties
echo "ldap-search-bind-dn: <DN of LDAP search user>" >> $GUACAMOLE_HOME/guacamole.properties
echo "ldap-search-bind-password: <Password of LDAP search user>" >> $GUACAMOLE_HOME/guacamole.properties
echo "ldap-user-base-dn: cn=users,<LDAP base>" >> $GUACAMOLE_HOME/guacamole.properties
echo "ldap-username-attribute: uid" >> $GUACAMOLE_HOME/guacamole.properties
ln -s /opt/guacamole/ldap/guacamole-auth-ldap-*-incubating.jar $GUACAMOLE_HOME/extensions

Note: To get the LDAP base, run ucr get ldap/base on the command line.

The users, who should be able to login to Guacamole, must be added to the Guacamole database.

To do this, login to Guacamole using the guacadmin user and add users using the administration panel. Create the connections like described in the documentation.

After creating a connection, users must be added, take a look at the documentation for details. While creating a user, any password can be entered (not necessarily the user's LDAP password). Since Guacamole is configured to also authenticate against the LDAP, Guacamole will try to bind the user to any available database with the given credentials, and the first one succeeds. Guacamole matches the LDAP username with the MySQL username and provides all connections to the username. While creating a user it can be configured which connections or connection groups a user is allowed to use.
Note: Connections can be grouped together in "Connection groups", which then can be configured to be accessed by a user. All connections of a connection group are available to the user.
Attention'': It is important that the username matches the LDAP username!

Further information

Personal tools