Apache Guacamole managed by EGroupware

Guacamole makes RDP or VNC desktops available via html5 inside EGroupware. EGroupware supplies account information, authentication via OpenID Connect and allows to manage connections.

EGroupware Guacamole app does the following:

• Installs all tables (or views) for Apache Guacamole
• Everything account-related is a view, not a table
• EGroupware UI to create connections (Admin >> Guacamole >> Connections)
• One has to use EGroupware to assign permissions to connections
• Guacamole UI can be used to set advanced connection options

Installation instructions via your package manager

Installation requirements (please check before attempting an installation!)

• Installation must happen on same physical machine as EGroupware itself
• You already installed EGroupware itself AND secured the installation with https / a certificate under it's final domain-name eg. https://example.org/egroupware
• MariaDB/MySQL can be used by user root without entering a password, create a /root/.my.cnf file with following content:

[client]
password = my secret root password

• Accounts are stored in SQL database, not LDAP or ActiveDirectory. Using the two or anything else for authentication is ok

A workaround for using LDAP or ActiveDirectory for account storage (not just authentication), is to regularly use setup to migrate users and groups to SQL. An other new alternative is to switch on the periodic account import, instead of using the accounts directly from LDAP/AD.

Installation (as user root replacing example.org with your actual domain)

apt update
HTTP_HOST=example.org apt install egroupware-guacamole

List of resources / further reading:

• Apache Guacamole website
• Using Guacamole section of Guacamole manual
• Administration section of Guacamole manual (keep in mind to use EGroupware UI to assign connection permissions!)
• Frequently Asked Questions from Guacamole
• Guacamole category in our forum (German)
• Guacamole EGroupware application repo on GitHub

Troubleshooting

• Guacamole can't connect to windows machine:

Remote Desktop Protocol need to be enabled AND Network Level Authentication need to be disabled (or username and password specified in the connection)

Network Level Authentication is a security measure mitigating risks of RPD exposed to the Internet, which is not the case for Guacamole used to make desktops available via HTML5, using strong authentication mechanisms available in EGroupware like TwoFactorAuth or WebAuthn.

• check the log of the guacamole container (almost all of the problem below are reported there!)

docker logs -f guacamole

• check MariaDB/MySQL is not bound on localhost (package tries to change that to docker0 address 172.17.0.1)

netstat -ln | grep 3306
tcp        0      0 172.17.0.1:3306         0.0.0.0:*               LISTEN

• enable OpenID Connect request log in EGroupware (Administration > Applications > OpenID Connect / OAuth > Request log)
• if Guacamole can not talk to EGroupware (because your firewall is blocking access from inside to the external IP / NAT traversal), you can set the docker0 IP for the external hostname by uncommenting the following in /etc/egroupware-guacamole/docker-compose.yaml (be careful as indention by space is important in YAML files!)

    # set the ip-address of your docker host AND your official DNS name so Guacamole
    # can access EGroupware without the need to go over your firewall
    extra_hosts:
    - "example.org:172.17.0.1"

After uncommenting and replacing example.org with your actual domain you need to recreate the container:

cd /etc/egroupware-guacamole
docker-compose stop guacamole
docker-compose rm -f guacamole
docker-compose up -d guacamole

• Guacamole requires a websocket connection! If you use your firewall or something else to terminate https (eg. a Synology), you have to configure it to proxy websockets too! Use developer tools of your browser an check for failed websocket messages on the console or pending websockets in the network tab.
• ask for help under Guacamole category in our forum or buy a support budget from EGroupware GmbH