Difference between revisions of "Cool Solution - Guacamole"

From Univention Wiki

Jump to: navigation, search
(Updated article to use LDAP integration)
Line 1: Line 1:
 
{{Version|UCS=4.2}}
 
{{Version|UCS=4.2}}
{{Cool Solutions Disclaimer}}
+
{{Cool Solutions Disclaimer|Repository=yes}}
 +
{{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.12-incubating.
+
The version of Guacamole used in this article is Guacamole 0.9.13-incubating.
 +
 
 
== Installation ==
 
== Installation ==
To successfully deploy and start Guacamole, three images must be downloaded via Docker:
+
To successfully deploy and start Guacamole, two images are downloaded via Docker by a joinscript:
 
* guacd
 
* guacd
 
* guacamole
 
* 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 [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.
 
  
 
In this article the following Guacamole docker containers are used:
 
In this article the following Guacamole docker containers are used:
Line 18: Line 16:
 
* https://hub.docker.com/r/mjumper/guacamole/
 
* https://hub.docker.com/r/mjumper/guacamole/
  
=== MySQL ===
+
=== Package "univention-guacamole-schema" ===
Download and deploy the MySQL image:
+
The package <code>univention-guacamole-schema</code> can only be installed on the following UCS server roles:
<pre>
+
* UCS DC Master
docker run --name mysql -e MYSQL_ROOT_PASSWORD=<MYSQL_PASSWORD> -d mysql:5.7.7
+
* UCS DC Backup
</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 ===
+
Install the package with the following command:
Download and deploy the guacd image:
 
 
<pre>
 
<pre>
docker run --name guacd -d mjumper/guacd
+
univention-install univention-guacamole-schema
 
</pre>
 
</pre>
This will provide the guacd daemon that handles all Guacamole connections. Nothing more must be done with this container.
 
  
==== Creating the Guacamole database ====
+
During the installation, the joinscript "99univention_register_guacamole_schema.inst" is called automatically and registers a new LDAP schema and adds two extended attributes to the UMC which extend the Groups module. After the joinscript is finished existing and new groups can be configured to provide a Guacamole configuration.
First, run the following command to create the tables for the database:
 
<pre>
 
docker run --rm mjumper/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:
+
=== Package "univention-guacamole-rollout" ===
<pre>
+
This package <code>univention-guacamole-rollout</code> can be installed in all UCS server roles. The package provides two joinscripts: one which creates a search user for Guacamole, and one which deploys the two containers:
docker cp initdb.sql mysql:/root
+
* guacd
</pre>
+
* guacamole
 
 
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 ===
+
Install the package with the following command:
Since the Guacamole image is already downloaded, just deploy Guacamole itself. Guacamole comes with a Apache Tomcat8 server:
 
 
<pre>
 
<pre>
docker run --name guacamole --link guacd:guacd --link mysql:mysql \
+
univention-install univention-guacamole-rollout
-e MYSQL_DATABASE=guacamole_db \
 
-e MYSQL_USER=guacamole_user \
 
-e MYSQL_PASSWORD=<GUACAMOLE_PASSWORD> \
 
-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.
+
==== Creating the searchuser ====
 +
The joinscript "98univention-guacamole-searchuser.inst" checks if the searchuser is already present in the LDAP. If not, the searchuser is created as a "Simple authentication account" user and the password is saved in the file <code>/etc/guacamole.secret</code>.
  
== Configuration ==
+
'''Attention''': If the package <code>univention-guacamole-rollout</code> is installed on a second server, the file <code>/etc/guacamole.secret</code> must be copied by hand, else the joinscript "99univention_install_guacamole.inst" will fail with an error message in the join.log file.
=== 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 ===
+
==== Deploying Guacamole ====
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>:
+
The joinscript "99univention_install_guacamole-inst" must be executed either by running the joinscript via the UMC or on the shell via <code>univention-run-join-scripts</code>. The reaseon for this behaviour is that some Guacamole UCR variables should be checked first:
<pre>
+
{|class="wikitable"
<Location /guacamole>
+
|-
Require all granted
+
! UCR variable                      || Default value              || Description
ProxyPass http://localhost:8181/guacamole max=20 flushpackets=on
+
|-
ProxyPassReverse http://localhost:8181/guacamole
+
| guacamole/user/dn                || cn=users,dc=example,dc=com  || Top-most DN to search for users
</Location>
+
|-
</pre>
+
| guacamole/config/base/dn          || cn=groups,dc=example,dc=com || DN for configuration groups
 +
|-
 +
| guacamole/ldap/username/attribute || uid                        || Attribute to map usernames to
 +
|-
 +
| guacamole/external/port          || 8080                        || Port to which the Guacamole Tomcat should be mapped to
 +
|}
  
Next you must make the new site available and reload the Apache webserver:
+
After any of these variables is changed, '''<code>univention-guacamole-renew</code>''' must be run to recreate the Guacamole container. Additionally, when the UCR variable '''guacamole/external/port''' is changed, the Apache2 webserver must be reloaded:
 
<pre>
 
<pre>
a2ensite guacamole
 
 
systemctl reload apache2.service
 
systemctl reload apache2.service
 
</pre>
 
</pre>
  
It is possible to get access to Guacamole via Tomcat. For this, please refer to the Tomcat manual for accessing applications.
+
Guacamole can be accessed from the Univention Portal.
  
=== UCS overview ===
+
== Configuration ==
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:
+
Start by editing an existing group, or by creating a new group. On the tab '''Guacamole''' the protocol and parameter can be edited. Every user, that is a direct member of this group can access this configuration. Only one connection can be configured for a group.
<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/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"
 
</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.
 
 
 
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:
 
<pre>
 
docker exec -it guacamole bash
 
</pre>
 
 
 
To edit files inside the container, install your favourite editor, eg. vim:
 
<pre>
 
apt update
 
apt install vim
 
</pre>
 
 
 
=== User authentication ===
 
==== 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'''.<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:
 
 
 
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.
+
=== RDP ===
 +
At least the following parameters must be provided for the connection to success:
 +
* hostname
  
==== Using the LDAP ====
+
For a full list of parameters, please have a look at the [http://guacamole.incubator.apache.org/doc/gug/configuring-guacamole.html#rdp Guacamole manual].
  
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:
+
=== Telnet ===
<pre>
+
At least the following parameters must be provided for the connection to success:
echo "ldap-hostname: <IP or FQDN of the LDAP server>" >> $GUACAMOLE_HOME/guacamole.properties
+
* hostname
echo "ldap-port: 7389" >> $GUACAMOLE_HOME/guacamole.properties
+
* port
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 docker container must be restarted for the LDAP authentication to be effective:
+
For a full list of parameters, please have a look at the [http://guacamole.incubator.apache.org/doc/gug/configuring-guacamole.html#telnet Guacamole manual].
<pre>
 
docker restart guacamole
 
</pre>
 
  
Next, log in using the '''guacadmin''' user and add one user user using the administration panel. It is important to give the user at least the right to create new users, optionally the right to create connections, and edit users. Also, the username must match the LDAP user name. The password fields can be left blank. Logout and login with the newly created user, using the LDAP password. Since this user can create users, all users from the LDAP matching the "ldap-user-base-dn" path are now able to login to Guacamole.
+
=== SSH ===
 +
At least the following parameters must be provided for the connection to success:
 +
* hostname
  
Next, create the connections needed described in the [https://guacamole.incubator.apache.org/doc/gug/administration.html#connection-management documentation], using the '''guacadmin''' user, or the administrative user from above.
+
For a full list of parameters, please have a look at the [http://guacamole.incubator.apache.org/doc/gug/configuring-guacamole.html#ssh Guacamole manual].
  
After creating a connection, users must be allowed to use the connection. To give users the rights to use a connection, edit the user in Guacamole and connect the connection to the user account. See the [https://guacamole.incubator.apache.org/doc/gug/administration.html#user-management documentation] for details.
+
=== VNC ===
 +
At least the following parameters must be provided for the connection to success:
 +
* hostname
 +
* port
  
== Further information ==
+
For a full list of parameters, please have a look at the [http://guacamole.incubator.apache.org/doc/gug/configuring-guacamole.html#vnc 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]]
 
  
 
== Archive ==
 
== Archive ==
 
 
There is a version of this article for [http://wiki.univention.de/index.php?title=Cool_Solution_-_Guacamole&oldid=11794 UCS 4.1].
 
There is a version of this article for [http://wiki.univention.de/index.php?title=Cool_Solution_-_Guacamole&oldid=11794 UCS 4.1].
  
 
[[Category: EN]]
 
[[Category: EN]]

Revision as of 12:20, 7 July 2017

Produktlogo UCS Version 4.2

Note: Cool Solutions are articles documenting additional functionality based on Univention products. Packages provided by a Cool Solutions Repository are built by Univention, but will not be maintained. 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.13-incubating.

Installation

To successfully deploy and start Guacamole, two images are downloaded via Docker by a joinscript:

  • guacd
  • guacamole

In this article the following Guacamole docker containers are used:

Package "univention-guacamole-schema"

The package univention-guacamole-schema can only be installed on the following UCS server roles:

  • UCS DC Master
  • UCS DC Backup

Install the package with the following command:

univention-install univention-guacamole-schema

During the installation, the joinscript "99univention_register_guacamole_schema.inst" is called automatically and registers a new LDAP schema and adds two extended attributes to the UMC which extend the Groups module. After the joinscript is finished existing and new groups can be configured to provide a Guacamole configuration.

Package "univention-guacamole-rollout"

This package univention-guacamole-rollout can be installed in all UCS server roles. The package provides two joinscripts: one which creates a search user for Guacamole, and one which deploys the two containers:

  • guacd
  • guacamole

Install the package with the following command:

univention-install univention-guacamole-rollout

Creating the searchuser

The joinscript "98univention-guacamole-searchuser.inst" checks if the searchuser is already present in the LDAP. If not, the searchuser is created as a "Simple authentication account" user and the password is saved in the file /etc/guacamole.secret.

Attention: If the package univention-guacamole-rollout is installed on a second server, the file /etc/guacamole.secret must be copied by hand, else the joinscript "99univention_install_guacamole.inst" will fail with an error message in the join.log file.

Deploying Guacamole

The joinscript "99univention_install_guacamole-inst" must be executed either by running the joinscript via the UMC or on the shell via univention-run-join-scripts. The reaseon for this behaviour is that some Guacamole UCR variables should be checked first:

UCR variable Default value Description
guacamole/user/dn cn=users,dc=example,dc=com Top-most DN to search for users
guacamole/config/base/dn cn=groups,dc=example,dc=com DN for configuration groups
guacamole/ldap/username/attribute uid Attribute to map usernames to
guacamole/external/port 8080 Port to which the Guacamole Tomcat should be mapped to

After any of these variables is changed, univention-guacamole-renew must be run to recreate the Guacamole container. Additionally, when the UCR variable guacamole/external/port is changed, the Apache2 webserver must be reloaded:

systemctl reload apache2.service

Guacamole can be accessed from the Univention Portal.

Configuration

Start by editing an existing group, or by creating a new group. On the tab Guacamole the protocol and parameter can be edited. Every user, that is a direct member of this group can access this configuration. Only one connection can be configured for a group.

RDP

At least the following parameters must be provided for the connection to success:

  • hostname

For a full list of parameters, please have a look at the Guacamole manual.

Telnet

At least the following parameters must be provided for the connection to success:

  • hostname
  • port

For a full list of parameters, please have a look at the Guacamole manual.

SSH

At least the following parameters must be provided for the connection to success:

  • hostname

For a full list of parameters, please have a look at the Guacamole manual.

VNC

At least the following parameters must be provided for the connection to success:

  • hostname
  • port

For a full list of parameters, please have a look at the Guacamole manual.

Archive

There is a version of this article for UCS 4.1.

Personal tools