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.

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 package

libossp-uuid-dev

Fedora / CentOS / RHEL package

uuid-devel

Optional depedencies

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.

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.

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.

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 package

libvorbis-dev

Fedora / CentOS / RHEL package

libvorbis-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.4.tar.gz$cd guacamole-server-0.9.4/$

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:

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:

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:

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 installMaking 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.4.tar.gz$cd guacamole-client-0.9.4/$

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:

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:

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.

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.

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.

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:

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.

Using Apache as a frontend (mod_proxy)

Many users end up serving Guacamole through Apache using mod_proxy,
a module which allows Apache to be used as a reverse proxy for other servers, such as a
servlet container like Tomcat. The need to do this can range from simply wanting to use
port 80, to sharing an SSL certificate with your web server, to security and load
balancing.

By default, servlet containers like Tomcat listen on port 8080, which is not the
standard HTTP port (port 80). If you are using Linux (or another UNIX system), only the
root user can run programs which listen on ports less than 1024, including port 80, and
reducing the number of programs that run with root privileges is always a good
idea.

If you have an SSL certificate, it may make sense to use Apache for SSL processing and
save Tomcat from having to do this itself, which may not be as efficient. Again, this
also makes sense from the perspective of security, as it reduces the number of users
that require read access to identifying certificates.

While load balancing won't be covered here, if you are expecting large numbers of
users, balancing the load on Tomcat across multiple Tomcat instances is a common
solution.

Important

Beware that, like the rest of this manual, we assume here that you are using
Tomcat. If you are using a different servlet container, the same principles apply,
and the Apache configuration examples will still be valid.

Configuring Tomcat for HTTP

Tomcat is most likely already configured to listen for HTTP connections on port
8080 as this is the default. In the case that the default HTTP connector has been
disabled or removed, you need to add a connector entry to
conf/server.xml:

Important

If you want to edit or add this connector just to change the port used by
Tomcat to port 80, you should consider simply proxying the original port through
Apache instead. On Linux and UNIX systems, a process must be running with root
privileges to listen on any port under 1024, including port 80. Proxying Tomcat
through Apache means Tomcat can run as a reduced-privilege user, while Apache
can bear the burden of root privileges. Further, as Apache is a native
application, it can make system calls to safely drop root privileges once the
port is open; a Java application like Tomcat cannot do this.

Be sure to specify the URIEncoding="UTF-8" attribute as above to
ensure that connection names, user names, etc. are properly received. If you will be
creating connections that have Cyrillic, Chinese, Japanese, etc. characters in the
names or parameter values, this attribute is required.

Configuring Apache and mod_proxy

Configuring Apache to proxy HTTP requests requires using the
ProxyPass and ProxyPassReverse
directives, which are provided by the mod_proxy module. These
directives describe how HTTP traffic should be routed to the web server behind the
proxy (Tomcat, in our case):

The most important thing in this entire section is the option
flushpackets=on. Most proxies, including
mod_proxy, will buffer all data sent over the connection,
waiting until the connection is closed before sending that data to the client. As
Guacamole's tunnel will stream data to the client over an open connection, buffering
this stream breaks Guacamole's communication.

If the option flushpackets=on is not specified,
Guacamole will not work.

Disable logging of tunnel requests

The Guacamole HTTP tunnel works by transferring a continuous stream of data over
multiple short-lived streams, each associated with a separate HTTP request. Each
HTTP request will be logged by Apache if you do not explicitly disable logging of
those requests.

Apache provides a means of matching URL patterns and setting environment variables
based on whether the URL matches. Logging can then be restricted to requests which
lack this environment variable:

There is little value in a log file filled with identical tunnel requests.

Note that if you are serving Guacamole under a path different from
/guacamole/, you will need to change the value of
Request_URI above accordingly.

Proxying under a different path

If you wish to serve Guacamole through Apache under a different path than it is
served under Tomcat, the configuration required for Apache will be slightly
different than the examples above due to cookies.

When a user logs in to Guacamole, a new session is created, and that session is
associated with a cookie sent to the user after they successfully log in. This
cookie is specific to the absolute path of the web application
(/guacamole). If the path being used for Guacamole under Apache
differs from that used by Tomcat, the path in the cookie needs to be modified.
Thankfully, mod_proxy has a directive for this:
ProxyPassReverseCookiePath.

The configuration shown above is similar to the configuration shown for generic
HTTP proxying, except that the additional
ProxyPassReverseCookiePath directive is given,
instructing mod_proxy to update the cookie path, changing
/guacamole/ to /new-path/, the same path specified when
the location was declared.