Guacamole Integration

Lindenberg Software Backup integrates with Apache Guacamole. Among other protocols and scenarios, Guacamole provides a gateway between HTML and MP4 (video) used in a browser to a virtual machine using Remote Desktop Protocol (RDP). Lindenberg Software provides an authentication extension that integreates Guacamole and Lindenberg Software Backup.

Guacamole can be built from scratch or run using docker containers. As the docker approach has clear advantages, it is described in the following. Nevertheless, the extension can be used without docker as well.

Docker is available for Windows and Linux, and in two flavors, community edition (CE) and enterprise edition (EE). While the CE runs flawlessly on Linux, Docker for Windows CE has the clear restriction that it does not support operations in production mode because a docker user has to login and then start the containers. Unfortunately, Docker for Windows EE has the restriction that it cannot be installed on Windows desktop operating systems nor on Hyper-V (tested with 2016). As a consequence I can recommend Docker for Windows CE only for experimental use in order to see what you get, otherwise I recommend to move to Docker on Linux for production.

Installation

As with any new software it is always a good idea to try it out in a virtual machine. In case you haven't done so far, enable the Hyper-V Windows Feature. After that follow instructions for either Windows or Linux.

Installation of Docker for Windows is as follows:

Installation on Linux is similar, except that Linux needs less resources:
  • Create a virtual machine. Recommended settings are 8GB disk space, same number of processors as real host, memory 1024MB, dynamic memory on, lower limit 512MB, limit 1024 GB. Safe-Boot turned off.
  • enable nested virtualization for that virtual machine
  • install Linux (e.g. Ubuntu Server, preferrably with SSH enabled.).
  • install Docker
  • install Docker-Compose.

Configuration

Go to a directory where you want to put your configuration. On Linux the recommendation is /opt/guacamole, on Windows you can do this anywhere within the shared drive above (you won't be using it productively anyway).

You need a total of four configuration files, which are explained in the following.
  1. The solution is composed out of three containers, and that is described in docker-compose.yml:
    version: "2"networks:  guacnw:services:  guacd:    image: "guacamole/guacd"    container_name: "guacd"    restart: always    networks:      - guacnw  guacamole:    container_name: "guacamole"    build:      context: .      dockerfile: guac.ext.backup    restart: always    networks:      - guacnw    depends_on:      - "guacd"    ports:      - "127.0.0.1:8080:8080"#      - "8080:8080"    environment:      - GUACAMOLE_HOME=/etc/guacamole      - GUACD_HOSTNAME=guacd      - GUACD_PORT=4822    links:      - guacd  nginx:    image: "nginx"    container_name: "nginx"    restart: always    networks:      - guacnw    volumes:      - ./nginx.conf:/etc/nginx/nginx.conf:ro#      - /etc/letsencrypt:/etc/letsencrypt:ro#      - /var/logs/nginx:/var/log/nginx    ports:        - "443:443"    links:      - guacamole
    Note that the nginx paths for certificates and logs are commented out, as you very likely need to adjust the certificate path and the paths fail to work on Windows.

  2. The Guacamole application needs to be extended. This is expressed by a "docker file" or container build instructions in guac.ext.backup:
    FROM guacamole/guacamoleADD https://software.lindenberg.one/backup/downloads/guacamole-lindenberg-backup-0.9.14.jar /etc/guacamole/extensions/COPY guacamole.properties /etc/guacamole/

  3. The Guacamole application needs to be configured. This is done via guacamole.properties (which unfortuantely has to also be included into the container build above):
    hyperv-url-connections=https://your-backup-server-URLhyperv-user=Guacamole-Userhyperv-domain=Guacamole-Domainhyperv-password=Guacamole-Passwordhyperv-security=nlahyperv-ignore-cert=truehyperv-server-layout=de-de-qwertzconsole=falseconsole-audio=false

    You have to update the URL and the credentials used to connect to Hyper-V. Recommendation is to create a dedicated user on Windows that is member of the Hyper-V-Admin group.

  4. The webserver nginx needs to be configured. This is done via nginx.conf:
    events {        worker_connections 768;        # multi_accept on;}http {     access_log /var/log/nginx/access.log;     error_log /var/log/nginx/error.log debug;     server {        listen 443 ssl;        ssl_certificate         /etc/letsencrypt/live/guacamole2.lindenberg.one/fullchain.pem;        ssl_certificate_key     /etc/letsencrypt/live/guacamole2.lindenberg.one/privkey.pem;        server_name guacamole2.lindenberg.one;        location / {    proxy_buffering off;    proxy_http_version 1.1;    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection $http_connection;    access_log off;            proxy_pass http://guacamole:8080;        }    }}
    You have to update this configuration to match your own hostname and certificates.
In order to offer Guacamole also from the user interface of Lindenberg Software Backup you need to do a registry setting on the server: please create a String "GuacamoleUrl" in HKLM\SOFTWARE\Lindenberg Software\Backup containing the URL (e.g. https://<yourguacamolehostname>/guacamole) of your Guacamole installation.

Running

  • Go to the directory you used for configuration and run the command: "docker-compose up --build -d". Then connect to https://<yourguacamolehostname>/guacamole. When running Docker for Windows, you can also connect to http://localhost:8080/guacamole using a browser on the same virtual machine.
  • The user interface will show all backups grouped by users and disk. Selecting one of them is equivalent to selecting them in the user interface of Lindenberg Software Backup.
  • In order to stop use "docker-compose down".

Trouble Shooting

Obviously I cannot provide lots of instructions withoug knowing what went wrong. Nevertheless two tips:
  • Console output of a specific container is available via "docker logs <container>"
  • You can run a command inside a container via "docker exec -it <container> echo Hello from container!"

Alternatives

  • Instead of running nginx as a docker container you might want to use Internet Information Services (IIS) as a reverse proxy server that connects to the guacamole port (there is no advantage of proxying twice). One reason could be that you are more familiar with Windows administration, and know how to reuse the same server certificates then. This option is available whether you run Docker for Windows or move to Linux, but be sure to run IIS and docker on the same physical system, as otherwise someone can sniff credentials on the local area network, and open the guacamole part in your docker-compose.yml only to the specific static IP-address of the system running the IIS.