Remote Desktop Gateway via Guacamole App

Guacamole is a clientless remote desktop gateway on the UCS system and allows users to connect to remote computers. No dedicated direct access is required for this. The only requirements are that the computer is accessible from the same UCS system and that the web browser has access to the UCS system on which Guacamole is installed.


The first step will be the installation of Guacamole on your system. You can either use the Univention-App-Center catalogue or in the terminal execute:

univention-app install guacamole

Tip: If you want to use Windows Systems make sure to also install the app “Active Directory Domain Controller“ in addition to Guacamole. This app extends UCS with Active Directory functionality as it is delivered by the software Samba. It allows to operate an Active Directory compatible domain controller with UCS and therefore provides a login service for Windows systems that are part of the domain. You can again use the univention-app-center or execute univention-app install samba4 in the terminal.

Configuration for UCS

All Guacamole-Connections will be configured in the LDAP directory. For every client that offers remote access, a unique LDAP-Object "Guacamole configuration" has to be created.

I. Creating a new LDAP-Object

For your first connection, create a new configuration in the Guacamole container within the LDAP directory. Go to [Domain] → [LDAP directory] and in the Guacamole container click on ADD and choose Guacamole configuration from the drop-down menu.

In the next step the connection-protocol and the according parameter will be defined.
Detailed information about the supported protocols, network parameter and optional settings can be found in the Guacamole User’s Guide, Chapter 5.

Following configurations are recommended for the initial setup:

Procotol Parameter
hostename=hostname or IP address 
port=22 (optional)
hostename=hostname or IP address 
port=3389 (optional)
security=tls or any
hostename=hostname or IP address 
port=5900 or 5900 + display number
(e.g. if VNC server is serving display number 1 -> port=5901)
hostename=hostname or IP address 
port=23 (optional)

Note: Guacamole configurations can also be created over the command line via
udm guacamole/config create as seen in this example for the RDP protocol:

udm guacamole/config create --position cn=guacamole,dc=ucs,dc=demo\ 
--set name=winclient1\
--set nestedGroup="cn=Domain Users,cn=groups,dc=test,dc=guacamole" \ 
--set guacConfigParameter="hostname=winclient.test.guacamole" \ 
--set guacConfigParameter="enable-font-smooting=true" \ 
--set guacConfigParameter="ignore-cert=true" \ 
--set guacConfigParameter="server-layout=de-de-qwertz" \ 
--set guacConfigParameter="security=tls" \ 
--set guacConfigParameter="username=" \ 
--set guacConfigParameter="domain=test.guacamole" \ 
--set guacConfigParameter="password=" \ 
--set guacConfigProtocol="rdp" 

II. Add User Groups to the Guacamole configuration

Add the user groups to your guacamole configuration which should be granted access to the remote connection. This can either be done by clicking ADD in the group section of your Guacamole configuration or over the terminal via udm parameter “ --set nestedGroup=“ as seen in the example above.

III. Activate Guacamole-App

Guacamole has to be activated for every user that wants to use the app. Using the Univention Management Console you can tick the associated box in the Apps menu on the user page or you can modify the corresponding LDAP-Object via udm over the terminal:
udm users/user modify --dn uid=mustermann,cn=users,$(ucr get ldap/base)\ 
 --set guacamoleActivated=TRUE

Tip: RDP Configuration on Windows
For Guacamole to work with RDP some prerequisites have to be met on your Windows system.

  1. Join Domain
  2. Make sure that your Windows system is part of the same domain as your Primary Domain Controller / Guacamole Memberserver. If you don't know how to join your Windows System to a domain you can follow these instructions: Join A Computer To A Domain
  3. Enable RDP-Protocol
  4. On current Windows systems the remote desktop protocol is deactivated by default. In order to enable RDP follow these instructions: Remote Desktop Allow Access
  5. Add User to Remote Desktop Users Group
  6. Lastly add the corresponding user groups to your Windows system. Therefore use the same menu as in the instructions for enabling the RDP-Protocol.

Guacamole App Usage

To use the guacamole app open up the main page of the Univention Portal and click on the Guacamole tile to launch the app. After start-up enter the required credentials and log in to the Guacamole interface, where all active systems will be listed. Click on the remote-client you want to access and Guacamole will establish the remote connection to the requested system and open up the graphical user interface in your browser.