Chapter 2. Installing Guacamole natively

Guacamole is separated into two pieces: guacamole-server, which provides the guacd proxy and related libraries, and guacamole-client, which provides the client to be served by your servlet container, usually Tomcat.

guacamole-client is available in binary form, but guacamole-server must be built from source. Don't be discouraged: building the components of Guacamole from source is not as difficult as it sounds, and the build process is automated. You just need to be sure you have the necessary tools installed ahead of time. With the necessary dependencies in place, building Guacamole only takes a few minutes.

Building guacamole-server

guacamole-server contains all the native, server-side components required by Guacamole to connect to remote desktops. It provides a common C library, libguac, which all other native components depend on, as well as separate libraries for each supported protocol, and guacd, the heart of Guacamole.

guacd is the proxy daemon that runs on your Guacamole server, accepts users' connections that are tunneled through the Guacamole web application, and then connects to remote desktops on their behalf. Building guacd creates an executable called guacd which can be run manually or, if you wish, automatically when your computer starts up.

To build guacamole-server, you will need a C compiler (such as gcc) and the libraries that guacamole-server depends on. Some dependencies are absolutely required, while others are optional. The presence of optional dependencies enables additional features.

Important

Many Linux distributions separate library packages into binary and "development" packages; you will need to install the development packages. These will usually end in a "-dev" or "-devel" suffix.

Required dependencies

In order to build guacamole-server, you will need Cairo, libpng, and the OSSP UUID library. These libraries are strictly required in all cases - Guacamole cannot be built without them.

Library nameFeatures
Cairo

Cairo is used by libguac for graphics rendering. Guacamole cannot function without Cairo installed.

Debian / Ubuntu packagelibcairo2-dev
Fedora / CentOS / RHEL packagecairo-devel
libpng

libpng is used by libguac to write PNG images, the core image type used by the Guacamole protocol. Guacamole cannot function without libpng.

Debian / Ubuntu packagelibpng12-dev
Fedora / CentOS / RHEL packagelibpng-devel
OSSP UUID

OSSP UUID is used by libguac to assign unique IDs to each Guacamole connection. These unique IDs are the basis for connection sharing support.

Debian / Ubuntu packagelibossp-uuid-dev
Fedora / CentOS / RHEL packageuuid-devel

Optional dependencies

The optional dependencies of Guacamole dictate which protocol support will be built, and whether additional features of those protocols will be enabled.

Guacamole currently supports VNC, RDP, SSH, and telnet. Each protocol corresponds to a separate library that will be built with guacamole-server if you have its corresponding optional dependencies.

VNC support depends on the libvncclient library, which is part of libVNCServer, RDP support depends on a recent version of FreeRDP - 1.0 or higher, SSH support depends on libssh2, and telnet depends on libtelnet. Pango, a font rendering and text layout library, is required for both SSH and telnet support.

Library nameFeatures
FreeRDP

FreeRDP is required for RDP support. If you do not wish to build RDP support, this library is not needed.

Debian / Ubuntu packagelibfreerdp-dev
Fedora / CentOS / RHEL packagefreerdp-devel
Pango

Pango is a text layout library which Guacamole's SSH and telnet support uses to render text. If you do not wish to build SSH or telnet support, this library is not needed.

Debian / Ubuntu packagelibpango1.0-dev
Fedora / CentOS / RHEL packagepango-devel
libssh2

libssh2 is required for SSH support. If you do not wish to build SSH support, this library is not needed.

Debian / Ubuntu packagelibssh2-1-dev
Fedora / CentOS / RHEL packagelibssh2-devel
libtelnet

libtelnet is required for telnet support. If you do not wish to build telnet support, this library is not needed.

Debian / Ubuntu packagelibtelnet-dev
Fedora / CentOS / RHEL packagelibtelnet-devel
libVNCServer

libVNCServer provides libvncclient, which is required for VNC support. If you do not wish to build VNC support, this library is not needed.

Debian / Ubuntu packagelibvncserver-dev
Fedora / CentOS / RHEL packagelibvncserver-devel
PulseAudio

PulseAudio provides libpulse, which is used by Guacamole's VNC support to provide experimental audio support. If you are not going to be using the experimental audio support for VNC, you do not need this library.

Debian / Ubuntu packagelibpulse-dev
Fedora / CentOS / RHEL packagepulseaudio-libs-devel
OpenSSL

OpenSSL provides support for SSL and TLS - two common encryption schemes that make up the majority of encrypted web traffic.

If you have libssl installed, guacd will be built with SSL support, allowing communication between the web application and guacd to be encrypted. This library is also required for SSH support for the sake of manipulating public/private keys.

Without SSL support, there will be no option to encrypt communication to guacd, and support for SSH cannot be built.

Debian / Ubuntu packagelibssl-dev
Fedora / CentOS / RHEL packageopenssl-devel
libvorbis

libvorbis provides support for Ogg Vorbis - a free and open standard for sound compression. If installed, libguac will be built with support for Ogg Vorbis, and protocols supporting audio will use Ogg Vorbis compression when possible.

Otherwise, sound will only be encoded as WAV (uncompressed), and will only be available if your browser also supports WAV.

Debian / Ubuntu packagelibvorbis-dev
Fedora / CentOS / RHEL packagelibvorbis-devel

Obtaining the source code

You can obtain a copy of the guacamole-server source from the Guacamole project web site. These releases are stable snapshots of the latest code which have undergone enough testing that the Guacamole team considers them fit for public consumption. Source downloaded from the project web site will take the form of a .tar.gz archive which you can extract from the command line:

$ tar -xzf guacamole-server-0.9.7.tar.gz
$ cd guacamole-server-0.9.7/
$

If you want the absolute latest code, and don't care that the code hasn't been as rigorously tested as the code in stable releases, you can also clone the Guacamole team's git repository on GitHub:

$ git clone git://github.com/glyptodon/guacamole-server.git
Cloning into 'guacamole-server'...
remote: Counting objects: 6769, done.
remote: Compressing objects: 100% (2244/2244), done.
remote: Total 6769 (delta 3058), reused 6718 (delta 3008)
Receiving objects: 100% (6769/6769), 2.32 MiB | 777 KiB/s, done.
Resolving deltas: 100% (3058/3058), done.
$

The build process

Once the guacamole-server source has been downloaded and extracted, you need to run configure. This is a shell script automatically generated by GNU Autotools, a popular build system used by the Guacamole project for guacamole-server. Running configure will determine which libraries are available on your system and will select the appropriate components for building depending on what you actually have installed.

Important

Source downloaded directly from git will not contain this configure script, as autogenerated code is not included in the project's repositories. If you downloaded the code from the project's git repositories directly, you will need to generate configure manually:

$ cd guacamole-server/
$ autoreconf -fi
$

Doing this requires GNU Autotools to be installed.

Source archives downloaded from the project website contain the configure script and all other necessary build files, and thus do not require GNU Autotools to be installed on the build machine.

Once you run configure, you can see what a listing of what libraries were found and what it has determined should be built:

$ ./configure --with-init-dir=/etc/init.d
checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...

------------------------------------------------
guacamole-server version 0.9.7
------------------------------------------------

   Library status:

     freerdp ............. yes
     pango ............... yes
     libssh2 ............. yes
     libssl .............. yes
     libtelnet ........... yes
     libVNCServer ........ yes
     libvorbis ........... yes
     libpulse ............ yes

   Protocol support:

      RDP ....... yes
      SSH ....... yes
      Telnet .... yes
      VNC ....... yes

   Init scripts: /etc/init.d

Type "make" to compile guacamole-server.

$

The --with-init-dir=/etc/init.d shown above prepares the build to install a startup script for guacd into the /etc/init.d directory, such that we can later easily configure guacd to start automatically on boot. If you do not wish guacd to start automatically at boot, leave off the --with-init-dir option. If the directory containing your distribution's startup scripts differs from the common /etc/init.d, replace /etc/init.d with the proper directory here. You may need to consult your distribution's documentation, or do a little digging in /etc, to determine the proper location.

Here, configure has found everything, including all optional libraries, and will build all protocol support, even support for Ogg Vorbis sound in RDP. If you are missing some libraries, some of the "yes" answers above will read "no". If a library which is strictly required is missing, the script will fail outright, and you will need to install the missing dependency. If, after running configure, you find support for something you wanted is missing, simply install the corresponding dependencies and run configure again.

Important

SSH and telnet support both require that fonts are installed in order to function - output from the terminal cannot be rendered otherwise. Support for SSH and telnet will build just fine if fonts are not installed, but it will fail to connect when used:

Aug 23 14:09:45 my-server guacd[5606]: Unable to get font "monospace"

If SSH or telnet connections are not working and you see such a message in syslog, install fonts and try again.

Once configure is finished, just type "make", and it will guacamole-server will compile:

$ make
Making all in src/libguac
make[1]: Entering directory `/home/zhz/guacamole/guacamole-server/src/libguac'
...
make[1]: Leaving directory `/home/zhz/guacamole/guacamole-server/src/protocols/vnc'
make[1]: Entering directory `/home/zhz/guacamole/guacamole-server'
make[1]: Nothing to be done for `all-am'.
make[1]: Leaving directory `/home/zhz/guacamole/guacamole-server'
$

Quite a bit of output will scroll up the screen as all the components are compiled.

Installation

Once everything finishes, all you have left to do is type "make install" to install the components that were built, and then "ldconfig" to update your system's cache of installed libraries:

# make install
Making install in src/libguac
make[1]: Entering directory `/home/zhz/guacamole/guacamole-server/src/libguac'
make[2]: Entering directory `/home/zhz/guacamole/guacamole-server/src/libguac'
...
----------------------------------------------------------------------
Libraries have been installed in:
   /usr/local/lib

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the `-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-Wl,-rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to `/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.
----------------------------------------------------------------------
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/zhz/guacamole/guacamole-server/src/protocols/vnc'
make[1]: Leaving directory `/home/zhz/guacamole/guacamole-server/src/protocols/vnc'
make[1]: Entering directory `/home/zhz/guacamole/guacamole-server'
make[2]: Entering directory `/home/zhz/guacamole/guacamole-server'
make[2]: Nothing to be done for `install-exec-am'.
make[2]: Nothing to be done for `install-data-am'.
make[2]: Leaving directory `/home/zhz/guacamole/guacamole-server'
make[1]: Leaving directory `/home/zhz/guacamole/guacamole-server'
# ldconfig
#   

At this point, everything is installed, but guacd is not running. You will need to run guacd in order to use Guacamole once the client components are installed as well.

Beware that even after installing guacd and its startup script, you will likely still have to activate the service for it to start automatically. Doing this varies by distribution, but each distribution will have documentation describing how to do so.

guacamole-client

Important

Normally, you don't need to build guacamole-client, as it is written in Java and is cross-platform. You can easily obtain the latest version of guacamole-client from the release archives of the Guacamole project web site, including all supported extensions, without having to build it yourself.

If you do not want to build guacamole-client from source, just download guacamole.war from the project web site, along with any desired extensions, and skip ahead to the section called “Deploying Guacamole”.

guacamole-client contains all Java and JavaScript components of Guacamole (guacamole, guacamole-common, guacamole-ext, and guacamole-common-js). These components ultimately make up the web application that will serve the HTML5 Guacamole client to users that connect to your server. This web application will then connect to guacd, part of guacamole-server, on behalf of connected users in order to serve them any remote desktop they are authorized to access.

To compile guacamole-client, all you need is Apache Maven and a copy of the Java JDK. Most, if not all, Linux distributions will provide packages for these.

You can obtain a copy of the guacamole-client source from the Guacamole project web site. These releases are stable snapshots of the latest code which have undergone enough testing that the Guacamole team considers them fit for public consumption. Source downloaded from the project web site will take the form of a .tar.gz archive which you can extract from the command line:

$ tar -xzf guacamole-client-0.9.7.tar.gz
$ cd guacamole-client-0.9.7/
$

As with guacamole-server, if you want the absolute latest code, and don't care that the code hasn't been as rigorously tested as the code in stable releases, you can also clone the Guacamole team's git repository on GitHub:

$ git clone git://github.com/glyptodon/guacamole-client.git
Cloning into 'guacamole-client'...
remote: Counting objects: 12788, done.
remote: Compressing objects: 100% (4183/4183), done.
remote: Total 12788 (delta 3942), reused 12667 (delta 3822)
Receiving objects: 100% (12788/12788), 3.23 MiB | 799 KiB/s, done.
Resolving deltas: 100% (3942/3942), done.
$

Unlike guacamole-server, even if you grab the code from the git repositories, you won't need to run anything before building. There are no scripts that need to be generated before building - all Maven needs is the pom.xml file provided with the source.

To build guacamole-client, just run "mvn package". This will invoke Maven to automatically build and package all components, producing a single .war file, which contains the entire web application:

$ mvn package
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Build Order:
[INFO] 
[INFO] guacamole-common
[INFO] guacamole-ext
[INFO] guacamole-common-js
[INFO] guacamole
[INFO] guacamole-auth-jdbc
[INFO] guacamole-auth-jdbc-base
[INFO] guacamole-auth-jdbc-mysql
[INFO] guacamole-auth-jdbc-postgresql
[INFO] guacamole-auth-ldap
[INFO] guacamole-auth-noauth
[INFO] guacamole-client
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] guacamole-common ................................... SUCCESS [  7.566 s]
[INFO] guacamole-ext ...................................... SUCCESS [  5.594 s]
[INFO] guacamole-common-js ................................ SUCCESS [  1.249 s]
[INFO] guacamole .......................................... SUCCESS [  8.474 s]
[INFO] guacamole-auth-jdbc ................................ SUCCESS [  0.592 s]
[INFO] guacamole-auth-jdbc-base ........................... SUCCESS [  2.548 s]
[INFO] guacamole-auth-jdbc-mysql .......................... SUCCESS [  2.557 s]
[INFO] guacamole-auth-jdbc-postgresql ..................... SUCCESS [  1.990 s]
[INFO] guacamole-auth-ldap ................................ SUCCESS [  1.314 s]
[INFO] guacamole-auth-noauth .............................. SUCCESS [  0.961 s]
[INFO] guacamole-client ................................... SUCCESS [  1.721 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 34.701 s
[INFO] Finished at: 2015-06-08T17:03:15-07:00
[INFO] Final Memory: 34M/340M
[INFO] ------------------------------------------------------------------------
$

Once the Guacamole web application is built, there will be a .war file in the guacamole/target/ subdirectory of the current directory (the directory you were in when you ran mvn). This .war file contains the entirety of the Guacamole web application, including all dependencies. Installing Guacamole means copying this .war file into the directory required by your servlet container.

You will probably have to do this as the root user:

# cp guacamole/target/guacamole-0.9.7.war /var/lib/tomcat7/webapps/guacamole.war
#

The Guacamole web application also depends on a configuration file, guacamole.properties, to tell it the type of authentication to use and how to connect to guacd. A functional example guacamole.properties is contained in the doc/ subdirectory; you can simply copy this somewhere (like /etc/guacamole) and then create a symbolic link to in a directory called .guacamole within the home directory of your servlet container. The home directory of your servlet container will be the home directory of the user that the servlet container runs as.

# mkdir /etc/guacamole
# mkdir /usr/share/tomcat7/.guacamole
# cp guacamole/doc/example/guacamole.properties /etc/guacamole/guacamole.properties
# ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole/
#           

You will need to edit guacamole.properties to be sure that all the settings are valid for your installation.

If you are using the default authentication method, you will also need to install the user-mapping.xml file. This file describes the users that should be allowed to log into Guacamole, as well as their passwords, and all corresponding remote desktop connections they should have access to.

An example user-mapping.xml file is provided in the doc/ subdirectory. You can simply copy this file to a reasonable location (like /etc/guacamole/user-mapping.xml) and then edit guacamole.properties to specify the correct location of this file.

You will need to edit user-mapping.xml to add and remove users, as well as to remove the "default" users included as examples.

Deploying Guacamole

Typically, deploying Guacamole is a one-time process, and needs to be done only when Guacamole is initially installed. If done correctly, future upgrades to Guacamole will be automatically deployed.

There are two critical files involved in the deployment of Guacamole: guacamole.war, which is the file containing the web application, and guacamole.properties, the main configuration file for Guacamole. The recommend way to set up Guacamole involves placing these files in standard locations, and then creating symbolic links to them so that Tomcat can find them.

Ultimately, the guacamole.war file, or a symbolic link to it, must be found by your servlet container within the directory it uses for .war files, and the guacamole.properties file must be within the .guacamole directory in the home directory of the user your servlet container runs as. Legacy installations will have guacamole.properties placed in the classpath of the servlet container, but this is officially deprecated, and will be unsupported in future releases.

We recommend placing guacamole.properties and any other configuration files in /etc/guacamole, and guacamole.war in /var/lib/guacamole. You will likely have to create each of these directories manually, as root.

With these files in place, you can create symbolic links in the places Tomcat and Guacamole require them, such that future upgrades will only involve placing the new files in standard locations. The standard locations involved are the Tomcat "webapps" directory (below, /var/lib/tomcat7/webapps, but your installation may be different), and the ".guacamole" directory, which must be manually created within the Tomcat user's home directory.

# ln -s /var/lib/guacamole/guacamole.war /var/lib/tomcat7/webapps
# ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole/
#

If you are using a different servlet container or Tomcat is installed in a different location, you will need to replace the directories above with the corresponding directories of your install.

Once Guacamole has been deployed, Tomcat must be restarted (as guacamole.properties will only be read on servlet container start) and the guacd daemon must be started if it isn't running already. After restarting Tomcat and starting guacd, Guacamole is successfully installed and running.

The command to restart Tomcat and guacd will vary by distribution. Typically, you can do this by running the corresponding init scripts with the "restart" option:

# /etc/init.d/tomcat7 restart
Stopping Tomcat... OK
Starting Tomcat... OK
# /etc/init.d/guacd start
Starting guacd: SUCCESS
guacd[6229]: INFO:  Guacamole proxy daemon (guacd) version 0.9.7 started
#

If you want Guacamole to start on boot, you will need to configure the Tomcat and guacd services to run automatically. Your distribution will provide documentation for doing this.

What about WebSocket?

Guacamole will use WebSocket automatically if supported by the browser and your servlet container. In the event that Guacamole cannot connect using WebSocket, it will immediately and transparently fall back to using HTTP.

WebSocket is supported in Guacamole for Tomcat 7.0.37 or higher, Jetty 8 or higher, and any servlet container supporting JSR 356, the standardized Java API for WebSocket.