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 integrates Guacamole and Lindenberg Software Backup.

In the diagramm below, the left shows a standard Guacamole setup. Even though most users don't consider it an extension, the standard database or LDAP implementation are extensions that are provided with Guacamole. Thanks to the extension mechanism,Lindenberg Software Backup just adds another extension that delegates most operations to Lindenberg Software Backup.

Guacanole Extensions

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.

With Windows 2020 May update, Windows Subsystem for Linux (WSL) 2 becomes generally available. WSL2 allows to run Linux and Docker kind of natively on Windows, which simplifies using Docker on Windows a lot. Docker for Windows supports WLS2 starting with version 2.3, but enthusiast also run Docker Linux on WSL2. In total there are four options:
  1. Docker on Linux on Virtual Machine
  2. Docker on Linux on WSL2
  3. Docker on Windows without WSL2
  4. Docker on Windows on WSL2
At present it is not clear how to automatically start WSL or Docker automatically on system startup in any scenario except for 1, as a login is required. For options 3 and 4, automatic login appears to be an option, which however is a security issue unless you do this in a dedicated virtual machine. Using a virtual machine is however a good idea anyway to try out new software. Be aware that an extra windows virtual machine requires a lot more resources than a Linux VM or WSL2. An alternative can be to install Reboot Blocker in order to prevent unexpected restarts and thus missing logins.

Installation

Scenario
1234Installation Step
mooo Installation Windows Hyper-V
ooo Windows Virtual Machine (optional, see above)
  • Create a virtual machine. Recommended settings are 60GB disk space, same number of processors as real host, memory 3072MB, dynamic memory on, limit 4096 GB.
  • enable nested virtualization for that virtual machine
  • Install Windows. If you want to use WSL2, it has to be Windows 10 2020 May. You may want to use an evaluation version of windows 10 enterprise.
Installation of the following steps then is performed within the virtual machine just installed, starting over from the top and skipping this step.
mInstallation of a Linux Virtual Machine
  • 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.).
mmWindow Subsytem for Linux 2 (WSL2)
mmDocker and Docker-Compose for Linux
mmDocker for Windows
  • follow the Install Docker CE instructions. Note that Docker for Windows includes Docker-Compose.
  • when not using WSL2, you may need to adjust memory settings (minimum is fine) and you need to share the drive you will store configuration on.
mConfigure Docker for Windows
  • after that you may need to adjust memory settings (minimum is fine) and you need to share the drive you will store configuration on.

Configuration

Note: Guacamole 1.1 is out, but does not work because of GUACAMOLE-952. The issue is fixed in 1.2, which however is not yet released. Therefore the following uses Guacamole 1.0. 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:1.0.0"    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/guacamole:1.0.0ADD https://software.lindenberg.one/backup/downloads/guacamole-lindenberg-backup-1.0.0.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-Password// replace nla with vmconnect for Guacamole 1.2 and uphyperv-security=nla// assumption: Hyper-V and Guacamole are on same physical hosthyperv-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.