Apache Guacamole on OpenBSD

Guacamole showing a desktop via HTML5 and VNC

(Guacamole showing a desktop via HTML5 & VNC)

Apache Guacamole is a “clientless” remote desktop gateway. It allows users to control remote computers via a web browser. The guacamole daemon is able to connect to remote machines via VNC, RDP and other protocols, with just a HTML5 capable browser as the client application. This enables users to access their machines using almost any system, including e.g. public computers available in libraries or kiosk setups without additional rights and software.

It’s similar to Citrix Virtual Desktops (formerly XenDesktop) or Microsoft Remote Desktop Services, but it’s free and open-source.

Here’s how to deploy Apache Guacamole on OpenBSD.

            ┌──────────────────────────┐
            │                          │
            │ ┌──────────────────────┐ │		 
 ┌───────┐  │ │Servlet container     │ │
 │       │  │ │(Apache Tomcat)       │ │         ┌───────────────┐
 │HTML5  │  │ │ ┌─────────┐  ┌─────┐ │ │   VNC   │ reachable     │
 │web-   │◄►│ │ │Guacamole│◄►│guacd│ │ │◄► RDP ◄►│Remote machines│
 │browser│  │ │ └─────────┘  └─────┘ │ │  other  │(GUI and CLI)  │
 │       │  │ │         (Guacamole   │ │         └───────────────┘
 └───────┘  │ │         protocol)    │ │
            │ └──────────────────────┘ │
            │                          │
            └──────────────────────────┘

Environment
Additional Resources
Install Guacamole-Server
Install Tomcat
Deploy Guacamole.war
Enable Tomcat and Guacamole Daemons
Configure Guacamole
Install x11vnc
Try Guacamole
Reverse-proxying Tomcat using relayd & TLS
- Create a TLS Keypair for a Test Deployment
- Create and Edit /etc/relayd.conf
Verify

Environment

This documents a proof of concept setup using a local VM running OpenBSD 7.4, Tomcat 7.9, Guacamole 1.5.3, relayd and a self-signed TLS keypair. I made localhost (the VM) available via Guacamole using x11vnc and accessed it from the host, a notebook running Windows.

Additional Resources

Deploying Guacamole (guacamole.apache.org)
Configuring Guacamole (guacamole.apache.org)
man guacd
man ssl.8
man relayd

Install Guacamole-Server

This provides guacd and automatically includes libvncserver.

pkg_add guacamole-server

Install Tomcat

I choose to install version 9. Tomcat has no man page, the readme is located under /usr/local/share/doc/pkg-readme/tomcat.

pkg_add tomcat

Deploy Guacamole.war

Download guacamole.war; This is the webapplication, packed as a single .war servlet: https://guacamole.apache.org/releases/1.5.3/.

Copy guacamole.war to the directory in which tomcat webapps are stored:

cp guacamole-1.5.3.war /var/tomcat/webapps/
chown _tomcat:_tomcat /var/tomcat/webapps/guacamole-1.5.3.war

Enable Tomcat and Guacamole Daemons

Tomcat:

rcctl enable tomcat
rcctl start tomcat

Guacamole-Server:

rcctl enable guacd
rcctl start guacd

Verify:

# netstat -na -f inet
Active Internet connections (including servers)
Proto   Recv-Q Send-Q  Local Address          Foreign Address        TCP-State
...
tcp          0      0  127.0.0.1.4822         *.*                    LISTEN
tcp          0      0  127.0.0.1.8005         *.*                    LISTEN
tcp          0      0  *.8080                 *.*                    LISTEN
...

# fstat | grep ':4822'
_guacd   guacd      83745    3* internet stream tcp 0xffff800000982650 127.0.0.1:4822

# fstat | grep ':8080'
_tomcat  java       34741   56* internet stream tcp 0xffff8000009832f0 *:8080

There should now be a new directory guacamole-1.5.3/ in /var/tomcat/webapps/. Browse http://localhost:8080/guacamole-1.5.3/ - it should show the guacamole login page:

(Guacamole login page)

Configure Guacamole

GUACAMOLE_HOME = /etc/guacamole
/etc/guacamole/guacamole.properties guacamole config
/etc/guacamole/guacd.conf guacd config
/etc/guacamole/user-mapping.xml simple auth config
guacd logs to /var/log/daemon on OpenBSD

Create and edit /etc/guacamole/guacamole.properties

guacd-hostname: localhost
guacd-port: 4822

# allow these authentication providers to be unavailable
skip-if-unavailable: mysql, ldap

Create and edit /etc/guacamole/user-mapping.xml

<user-mapping>
    <authorize
    username="juka"
    password="juka2">			
    <!-- First authorized connection -->
        <connection name="localhost">
        <protocol>vnc</protocol>
	<param name="hostname">localhost</param>			
	<param name="port">5900</param>
	<param name="password">VNCPASS</param>
    </connection>
    </authorize>
</user-mapping>

Install x11vnc

Install and enable x11vnc

pkg_add x11vnc
rcctl enable x11vnc
rcctl start x11vnc

Try Guacamole

Browse to http://guachost:8080/guacamole-1.5.3/
Login with credentials from user-mapping.xml

This should connect to X11 via VNC on the Guacamole localhost:

Guacamole showing a desktop via HTML and VNC

(Guacamole showing a desktop via HTML5 & VNC)

Reverse-proxying Tomcat using relayd & TLS

Create a TLS Keypair for a Test Deployment

Generate an RSA certificate:

openssl genrsa -out /etc/ssl/private/server.key 4096

Generate a Certificate Signing Request (CSR):

openssl req -new -key /etc/ssl/private/server.key \
   -out /etc/ssl/private/server.csr

Self-sign the key:

openssl x509 -sha256 -req -days 365 \
  -in /etc/ssl/private/server.csr \
  -signkey /etc/ssl/private/server.key \
  -out /etc/ssl/server.crt

Create and Edit /etc/relayd.conf

ext_ipv4 = 10.13.16.29
table <tomcat> { 127.0.0.1 }

http protocol https {
    match request header append "X-Forwarded-For" value "$REMOTE_ADDR"
    match request header append "X-Forwarded-By" \
        value "$SERVER_ADDR:$SERVER_PORT"
    match request header set "Connection" value "close"
    tls keypair "server"
}

relay wwwtls {
    listen on $ext_ipv4 port 443 tls
    protocol https
    forward to <tomcat> port 8080
}

Verify

Enable & start relayd

# rcctl enable relayd
# rcctl start relayd

Browse: https://10.13.16.29/guacamole-1.5.3/

[back to top]