Guacamole

A Linux desktop in a browser

Overview

Guacamole is a program to control a Linux desktop over the network in a browser.

Sometimes in your Linux life, you need to control your servers in the internet with a graphical user interface. This is tedious when you are behind a corporate firewall blocking ssh requests to the public internet. Typical corporate firewalls only allow proxified client access to port 80, 8080 and 443 in the public internet. One way to go is to use a browser to display a Linux desktop. The solution is guacamole.

Quickstart

This will show you

• how to install guacamole 1.3.0 on Ubuntu (tested with 20.04)
• how to make this configuration survive a reboot
• how to secure transmission with SSL
• how to make the website accessible from behind a firewall (port 80 or 443)

Here's what you do as root user:

• install software that we will need later:

apt-get update
apt-get install tomcat9 tightvncserver gcc make xterm ubuntu-gnome-desktop

configure VNC server

Guacamole does the communication between a VNC server and the web browser. So whatever you see in VNC will be in the browser. In this example let's use GNOME as desktop environment:

• write the startup for your VNC sessions:

cd
mkdir .vnc
cat >> .vnc/xstartup <<EOF
#!/bin/sh

export XKL_XMODMAP_DISABLE=1
export XDG_CURRENT_DESKTOP="GNOME-Flashback:GNOME"
export XDG_MENU_PREFIX="gnome-flashback-"

gnome-session --builtin --session=gnome-flashback-metacity --disable-acceleration-check --debug &
EOF
chmod +x xstartup

deploy guacamole client

• download the guacamole webapp from https://guacamole.apache.org/releases/
• deploy it, in this case, we selected version 1.3.

# mv guacamole-1.3.0.war /var/lib/tomcat9/webapps/guacamole.war

• surf to http://localhost:8080/guacamole
• although login is not yet possible your browser will show a login screen like that:

install guacamole server

• install some dependencies that the server will need to build with vnc support:

apt-get install libvncserver-dev libpng-dev libcairo-dev libossp-uuid-dev

• download guacamole-server, in this case version 1.3:

wget https://archive.apache.org/dist/guacamole/1.3.0/source/guacamole-server-1.3.0.tar.gz

• unpack it, in this example 1.3.0:

tar xvzf guacamole-server-1.3.0.tar.gz

• build the server:

cd guacamole-server-1.3.0
./configure && make -j8 && make install

• the following step is ugly; installation and binary do not completely fit so we must do that:

ln -s /usr/local/lib/libguac.so* /lib
ln -s /usr/local/lib/libguac-client-vnc.so* /lib/

• now we start the guacamole daemon:

# guacd
guacd[17871]: INFO:     Guacamole proxy daemon (guacd) version 1.3.0 started

configure guacamole

• create a folder for guacamole's configuration:

mkdir /etc/guacamole

• create a file /etc/guacamole/guacamole.properties with the content

# Hostname and port of guacamole proxy
guacd-hostname: localhost
guacd-port:     4822

# Location to read extra .jar's from
lib-directory:  /var/lib/tomcat9/webapps/guacamole-1.3.0/WEB-INF/classes

# Authentication provider class
auth-provider: net.sourceforge.guacamole.net.basic.BasicFileAuthenticationProvider

# Properties used by BasicFileAuthenticationProvider
basic-user-mapping: /etc/guacamole/user-mapping.xml

• create a file /etc/guacamole/user-mapping.xml with the content

<user-mapping>
   <authorize username="user" password="password">
      <protocol>vnc</protocol>
         <param name="hostname">localhost</param>
         <param name="port">5901</param>
         <param name="password">password</param>
    </authorize>
</user-mapping>

configure tomcat

• find out your tomcat's user directory:

# cat /etc/passwd|grep tomcat
tomcat6:x:113:116::/usr/share/tomcat9:/bin/false

in this case it is /usr/share/tomcat9

• create a folder .guacamole in your tomcat's user directory:

mkdir /usr/share/tomcat9/.guacamole

• link guacamole.properties into your tomcat's user directories' guacamole folder

ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat9/.guacamole

finishing

• start a vnc server, as password set password (the vnc password given in user-mappings.xml)

vncserver

• if it requires a password, use password. Don't set a view-only password.
• point your browser to http://localhost:8080/guacamole
• log in as user, password password (the user given in user-mappings.xml)
• you should see a screen like this:

Now when you click on "Default" you will see your VNC desktop in your browser.

secure transmission

Set up apache for https so your passwords are not transmitted unencrypted over the internet

make it work from behind a firewall

Most companies will have an internet proxy that does not allow users to access port 8080 on a server outside the company network. So you need a reverse proxy that tells apache if someone calls http://yourserver.yourdomain/guacamole this is forwarded to http://yourserver.yourdomain:8080 internally. To do this,

• edit /etc/sysconfig/apache2 and add the following words to APACHE_MODULES: proxy proxy_http. In the end your line may read like this:

APACHE_MODULES="actions alias auth_basic proxy proxy_http authn_file authz_host authz_groupfile authz_default authz_user autoindex cgi dir env expires include log_config mime negotiation setenvif ssl userdir php5"

• edit /etc/apache2/default-server.conf, add a block

<IfModule mod_proxy.c>
<Location /guacamole>
    ProxyPass http://127.0.0.1:8080
</Location>
</IfModule>

Persist it

You want your configuration to survive a reboot so add the following lines to /etc/crontab:

@reboot root /usr/local/sbin/guacd &
@reboot  thorsten USER=thorsten /usr/bin/vncserver >>/tmp/vnc-startup-error 2>&1

Replace thorsten with the OS user to start vncserver.

Beautify it

You may want to run bash as a shell, in this case edit /etc/passwd and enter /bin/bash instead of /bin/sh

TroubleShooting

invalid login

• now the problem is that tomcat does not know where to find the Authentication class:

/var/lib/tomcat6/webapps/guacamole/WEB-INF/classes/net/sourceforge/guacamole/net/basic/BasicFileAuthenticationProvider.class

is not in /etc/guacamole/guacamole.properties

• so add it
• cat /etc/passwd gives me a line

tomcat6:x:113:116::/usr/share/tomcat6:/bin/false

ll /usr/share/tomcat6/.guacamole/
total 8
drwxr-xr-x 2 root root 4096 Nov 26 07:58 ./
drwxr-xr-x 6 root root 4096 Nov 26 07:57 ../
lrwxrwxrwx 1 root root   35 Nov 26 07:58 guacamole.properties -> /etc/guacamole/guacamole.properties

• works now. So the thing is:
  • take care that it is called guacamole and not guacamole-0.8.3 (sure?)
  • make sure the classpath in /etc/guacamole/guacamole.properties is correct, e.g.

# Location to read extra .jar's from
lib-directory:  /var/lib/tomcat6/webapps/guacamole/WEB-INF/classes

Server error

• now I got a server error so I straced guacd:

strace -p 15332

and saw

[pid 20344] open("/usr/lib/x86_64-linux-gnu/libguac-client-vnc.so", O_RDONLY) = -1 ENOENT (No such file or directory)

so the problem is that libguac-client-vnc.so is missing.

• downloaded java version 1.7.45 and compiled guacamole-client using mvn. But there was no *.so* file in it
• so installed libvncserver-dev and rebuild and reinstalled guacamole-server
• and there it is, libguac-client-vnc.so
• now the error message changed from "server error" to "unauthorized"

Failed to load

When logging in I got an error message

Failed to execute 'send' on 'XMLHttpRequest': Failed to load 'http://162.209.103.145:8080/guacamole-0.8.3/login'.

Solution was to:

/etc/init.d/tomcat6 restart

Error initializing VNC client

After logging in I got the error message

Error initializing VNC client

Solution was to start

vncserver

Could not connect

If you surf to the page and get an error message like

Unable to connect

It probably means that tomcat is not running. It must be possible to connect to port 8080, a java process for tomcat must be running.

/etc/init.d/tomcat6 status

must deliver something like

* Tomcat servlet engine is running with pid 17546

See also

• connect to a Linux computer
• guacamole 0.8 on SUSE
• guacamole 0.3.0 on Ubuntu 10.04
• cool things
• schedule tAsks
• http://guac-dev.org/Debian%20Install%20Instructions
• ulteo
• http://www.filegott.se/prd/index.php/how-tos/19-how-to-setup-guacamole-in-linux-ubuntu
• http://guac-dev.org/doc/gug/installing-guacamole.html#idp99200