Google Git
Sign in
apache / guacamole-website / 7c7a9ac6679809c00ed92c542587763e1814c11c / . / doc / 0.9.4 / gug / installing-guacamole.html
blob: 9a8b1c31a46b49c2cc0fc75ca7cb5ddeded5a02a [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 2. Installing Guacamole</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="guacamole-architecture.html" title="Chapter 1. Implementation and architecture" /><link rel="next" href="configuring-guacamole.html" title="Chapter 3. Configuring Guacamole" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/>
</head><body>
<!-- CONTENT -->
<div id="page"><div id="content">
<div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 2. Installing Guacamole</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-architecture.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="configuring-guacamole.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="installing-guacamole"></a>Chapter 2. Installing Guacamole</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="installing-guacamole.html#building-guacamole-server">Building <span class="package">guacamole-server</span></a></span></dt><dd><dl><dt><span class="section"><a href="installing-guacamole.html#required-dependencies">Required dependencies</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#optional-dependencies">Optional depedencies</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#guacamole-server-source">Obtaining the source code</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#guacamole-server-build-process">The build process</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#guacamole-server-installation">Installation</a></span></dt></dl></dd><dt><span class="section"><a href="installing-guacamole.html#building-guacamole-client"><span class="package">guacamole-client</span></a></span></dt><dt><span class="section"><a href="installing-guacamole.html#deploying-guacamole">Deploying Guacamole</a></span></dt><dd><dl><dt><span class="section"><a href="installing-guacamole.html#idm139657086793728">What about WebSocket?</a></span></dt></dl></dd><dt><span class="section"><a href="installing-guacamole.html#mod-proxy">Using Apache as a frontend (<span class="package">mod_proxy</span>)</a></span></dt><dd><dl><dt><span class="section"><a href="installing-guacamole.html#ajp-proxy">Using AJP</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#http-proxy">Using HTTP</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#disable-tunnel-logging">Disable logging of tunnel requests</a></span></dt><dt><span class="section"><a href="installing-guacamole.html#change-web-app-path">Proxying under a different path</a></span></dt></dl></dd></dl></div>
<a id="idm139657087061984" class="indexterm"></a>
<a id="idm139657087061216" class="indexterm"></a>
<p>Guacamole is separated into two pieces: <span class="package">guacamole-server</span>, which
provides the <span class="package">guacd</span> proxy and related libraries, and
<span class="package">guacamole-client</span>, which provides the client to be served by your
servlet container, usually <a class="ulink" href="http://tomcat.apache.org/" target="_top">Tomcat</a>.</p>
<p><span class="package">guacamole-client</span> is available in binary form, but
<span class="package">guacamole-server</span> must be built from source. Don't be discouraged:
building the components of Guacamole from source is <span class="emphasis"><em>not</em></span> 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.</p>
<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-guacamole-server"></a>Building <span class="package">guacamole-server</span></h2></div></div></div>
<a id="idm139657087054304" class="indexterm"></a>
<a id="idm139657087053024" class="indexterm"></a>
<a id="idm139657087051872" class="indexterm"></a>
<a id="idm139657087050720" class="indexterm"></a>
<a id="idm139657087049568" class="indexterm"></a>
<a id="idm139657087048416" class="indexterm"></a>
<a id="idm139657087047264" class="indexterm"></a>
<a id="idm139657087045984" class="indexterm"></a>
<a id="idm139657087044704" class="indexterm"></a>
<a id="idm139657087043424" class="indexterm"></a>
<a id="idm139657087042144" class="indexterm"></a>
<p><span class="package">guacamole-server</span> contains all the native, server-side components
required by Guacamole to connect to remote desktops. It provides a common C library,
<span class="package">libguac</span>, which all other native components depend on, as well as
separate libraries for each supported protocol, and <span class="package">guacd</span>, the heart
of Guacamole.</p>
<p><span class="package">guacd</span> 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 <span class="package">guacd</span>
creates an executable called <code class="filename">guacd</code> which can be run manually or, if
you wish, automatically when your computer starts up.</p>
<p>To build <span class="package">guacamole-server</span>, you will need a C compiler (such as
<span class="package">gcc</span>) and the libraries that <span class="package">guacamole-server</span>
depends on. Some dependencies are absolutely required, while others are optional. The
presence of optional dependencies enables additional features.</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>Many Linux distributions separate library packages into binary and "development"
packages; <span class="emphasis"><em>you will need to install the development packages</em></span>.
These will usually end in a "-dev" or "-devel" suffix.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="required-dependencies"></a>Required dependencies</h3></div></div></div>
<p>In order to build <span class="package">guacamole-server</span>, you will need
<span class="package">Cairo</span>, <span class="package">libpng</span>, and the OSSP UUID library.
These libraries are strictly required <span class="emphasis"><em>in all cases</em></span> - Guacamole
cannot be built without them.</p>
<div class="informaltable">
<table border="1"><colgroup><col class="lib-name" /><col class="features" /></colgroup><thead><tr><th>Library name</th><th>Features</th></tr></thead><tbody><tr><td><a class="ulink" href="http://cairographics.org/" target="_top">Cairo</a></td><td>
<p>Cairo is used by libguac for graphics rendering. Guacamole
cannot function without Cairo installed.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libcairo2-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">cairo-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://www.libpng.org/pub/png/libpng.html" target="_top">libpng</a></td><td>
<p>libpng is used by libguac to write PNG images, the core image
type used by the Guacamole protocol. Guacamole cannot function
without libpng.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libpng12-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">libpng-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://www.ossp.org/pkg/lib/uuid/" target="_top">OSSP
UUID</a></td><td>
<p>OSSP UUID is used by libguac to assign unique IDs to each
Guacamole connection. These unique IDs are the basis for
connection sharing support.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libossp-uuid-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">uuid-devel</span></td></tr></tbody></table>
</div>
</td></tr></tbody></table>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="optional-dependencies"></a>Optional depedencies</h3></div></div></div>
<p>The optional dependencies of Guacamole dictate which protocol support will be
built, and whether additional features of those protocols will be enabled.</p>
<p>Guacamole currently supports VNC, RDP, SSH, and telnet. Each protocol corresponds
to a separate library that will be built with <span class="package">guacamole-server</span> if
you have its corresponding optional dependencies.</p>
<p>VNC support depends on the <span class="package">libvncclient</span> library, which is part
of <span class="package">libVNCServer</span>, RDP support depends on a recent version of
<span class="package">FreeRDP</span> - 1.0 or higher, SSH support depends on
<span class="package">libssh2</span>, and telnet depends on <span class="package">libtelnet</span>.
<span class="package">Pango</span>, a font rendering and text layout library, is required
for both SSH and telnet support.</p>
<div class="informaltable">
<table border="1"><colgroup><col class="lib-name" /><col class="features" /></colgroup><thead><tr><th>Library name</th><th>Features</th></tr></thead><tbody><tr><td><a class="ulink" href="http://www.freerdp.com/" target="_top">FreeRDP</a></td><td>
<p>FreeRDP is required for RDP support. If you do not wish to
build RDP support, this library is not needed.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libfreerdp-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">freerdp-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://www.pango.org/" target="_top">Pango</a></td><td>
<p>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.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libpango1.0-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">pango-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://www.libssh2.org/" target="_top">libssh2</a></td><td>
<p>libssh2 is required for SSH support. If you do not wish to
build SSH support, this library is not needed.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libssh2-1-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">libssh2-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="https://github.com/seanmiddleditch/libtelnet" target="_top">libtelnet</a></td><td>
<p>libtelnet is required for telnet support. If you do not wish
to build telnet support, this library is not needed.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libtelnet-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">libtelnet-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://libvnc.github.io/" target="_top">libVNCServer</a></td><td>
<p>libVNCServer provides libvncclient, which is required for VNC
support. If you do not wish to build VNC support, this library
is not needed.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libvncserver-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">libvncserver-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://www.freedesktop.org/wiki/Software/PulseAudio/" target="_top">PulseAudio</a></td><td>
<p>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.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libpulse-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">pulseaudio-libs-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="https://www.openssl.org/" target="_top">OpenSSL</a></td><td>
<p>OpenSSL provides support for SSL and TLS - two common
encryption schemes that make up the majority of encrypted web
traffic.</p>
<p>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.</p>
<p>Without SSL support, there will be no option to encrypt
communication to guacd, and support for SSH cannot be
built.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libssl-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">openssl-devel</span></td></tr></tbody></table>
</div>
</td></tr><tr><td><a class="ulink" href="http://xiph.org/vorbis/" target="_top">libvorbis</a></td><td>
<p>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.</p>
<p>Otherwise, sound will only be encoded as WAV (uncompressed),
and will only be available if your browser also supports
WAV.</p>
<div class="informaltable">
<table border="0"><colgroup><col class="c1" /><col class="c2" /></colgroup><tbody><tr><th>Debian / Ubuntu package</th><td><span class="package">libvorbis-dev</span></td></tr><tr><th>Fedora / CentOS / RHEL package</th><td><span class="package">libvorbis-devel</span></td></tr></tbody></table>
</div>
</td></tr></tbody></table>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-server-source"></a>Obtaining the source code</h3></div></div></div>
<p>You can obtain a copy of the <span class="package">guacamole-server</span> 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 <code class="filename">.tar.gz</code> archive which you can extract from the command
line:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>tar -xzf guacamole-server-0.9.4.tar.gz</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>cd guacamole-server-0.9.4/</code></strong>
<code class="prompt">$</code></pre>
</div>
<p>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:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>git clone <code class="uri">git://github.com/glyptodon/guacamole-server.git</code></code></strong>
<code class="computeroutput">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.</code>
<code class="prompt">$</code></pre>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-server-build-process"></a>The build process</h3></div></div></div>
<p>Once the <span class="package">guacamole-server</span> source has been downloaded and
extracted, you need to run <code class="filename">configure</code>. This is a shell script
automatically generated by GNU Autotools, a popular build system used by the
Guacamole project for <span class="package">guacamole-server</span>. Running
<code class="filename">configure</code> will determine which libraries are available on
your system and will select the appropriate components for building depending on
what you actually have installed.</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>Source downloaded directly from git will not contain this
<code class="filename">configure</code> 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 <code class="filename">configure</code>
manually:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>cd guacamole-server/</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>autoreconf -fi</code></strong>
<code class="prompt">$</code></pre>
<p>Doing this requires GNU Autotools to be installed.</p>
<p>Source archives downloaded from the project website contain the
<code class="filename">configure</code> script and all other necessary build
files, and thus do not require GNU Autotools to be installed on the build
machine.</p>
</div>
</div>
<p>Once you run <code class="filename">configure</code>, you can see what a listing of what
libraries were found and what it has determined should be built:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>./configure --with-init-dir=<em class="replaceable"><code>/etc/init.d</code></em></code></strong>
<code class="computeroutput">checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
------------------------------------------------
guacamole-server version 0.9.4
------------------------------------------------
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.
</code>
<code class="prompt">$</code></pre>
</div>
<p><a id="idm139657086890560" class="indexterm"></a>The <code class="option">--with-init-dir=/etc/init.d</code> shown above prepares
the build to install a startup script for <span class="package">guacd</span> into the
<code class="filename">/etc/init.d</code> directory, such that we can later easily
configure <span class="package">guacd</span> to start automatically on boot. If you do not
wish guacd to start automatically at boot, leave off the
<code class="option">--with-init-dir</code> option. If the directory containing your
distribution's startup scripts differs from the common
<code class="filename">/etc/init.d</code>, replace <code class="filename">/etc/init.d</code> with
the proper directory here. You may need to consult your distribution's
documentation, or do a little digging in <code class="filename">/etc</code>, to determine the
proper location.</p>
<p>Here, <code class="filename">configure</code> 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
"<code class="computeroutput">yes</code>" answers above will read
"<code class="computeroutput">no</code>". 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 <code class="filename">configure</code>, you find support for
something you wanted is missing, simply install the corresponding dependencies and
run <code class="filename">configure</code> again.</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>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:</p>
<div class="informalexample">
<pre class="screen">Aug 23 14:09:45 my-server guacd[5606]: Unable to get font "monospace"</pre>
</div>
<p>If SSH or telnet connections are not working and you see such a message in
syslog, install fonts and try again.</p>
</div>
<p>Once <code class="filename">configure</code> is finished, just type
"<strong class="userinput"><code>make</code></strong>", and it will <span class="package">guacamole-server</span>
will compile:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>make</code></strong>
<code class="computeroutput">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'</code>
<code class="prompt">$</code></pre>
</div>
<p>Quite a bit of output will scroll up the screen as all the components are
compiled.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-server-installation"></a>Installation</h3></div></div></div>
<p>Once everything finishes, all you have left to do is type "<strong class="userinput"><code>make
install</code></strong>" to install the components that were built, and then
"<strong class="userinput"><code>ldconfig</code></strong>" to update your system's cache of installed
libraries:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>make install</code></strong>
<code class="computeroutput">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'</code>
<code class="prompt">#</code> <strong class="userinput"><code>ldconfig</code></strong>
<code class="prompt">#</code> </pre>
</div>
<p>At this point, everything is installed, but <span class="package">guacd</span> is not
running. You will need to run guacd in order to use Guacamole once the client
components are installed as well.</p>
<p>Beware that even after installing <span class="package">guacd</span> 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.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="building-guacamole-client"></a><span class="package">guacamole-client</span></h2></div></div></div>
<a id="idm139657086862704" class="indexterm"></a>
<a id="idm139657086861168" class="indexterm"></a>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>Normally, you don't need to build <span class="package">guacamole-client</span>, as it is
written in Java and is cross-platform. You can easily obtain the latest version of
<span class="package">guacamole-client</span> from the release archives of the Guacamole
project web site, including all supported extensions, without having to build it
yourself.</p>
<p>If you do not want to build guacamole-client from source, just download
<code class="filename">guacamole.war</code> from the project web site, along with any
desired extensions, and skip ahead to <a class="xref" href="installing-guacamole.html#deploying-guacamole" title="Deploying Guacamole">the section called “Deploying Guacamole”</a>.</p>
</div>
<p><span class="package">guacamole-client</span> contains all Java and JavaScript components of
Guacamole (<span class="package">guacamole</span>, <span class="package">guacamole-common</span>,
<span class="package">guacamole-ext</span>, and <span class="package">guacamole-common-js</span>). 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
<span class="package">guacd</span>, part of <span class="package">guacamole-server</span>, on behalf of
connected users in order to serve them any remote desktop they are authorized to
access.</p>
<p>To compile <span class="package">guacamole-client</span>, all you need is Apache Maven and a
copy of the Java JDK. Most, if not all, Linux distributions will provide packages for
these.</p>
<p>You can obtain a copy of the <span class="package">guacamole-client</span> 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
<code class="filename">.tar.gz</code> archive which you can extract from the command
line:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>tar -xzf guacamole-client-0.9.4.tar.gz</code></strong>
<code class="prompt">$</code> <strong class="userinput"><code>cd guacamole-client-0.9.4/</code></strong>
<code class="prompt">$</code></pre>
</div>
<p>As with <span class="package">guacamole-server</span>, 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:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>git clone <code class="uri">git://github.com/glyptodon/guacamole-client.git</code></code></strong>
<code class="computeroutput">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.</code>
<code class="prompt">$</code></pre>
</div>
<p>Unlike <span class="package">guacamole-server</span>, 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
<code class="filename">pom.xml</code> file provided with the source.</p>
<p>To build <span class="package">guacamole-client</span>, just run "<strong class="userinput"><code>mvn
package</code></strong>". This will invoke Maven to automatically build and package all
components, producing a single <code class="filename">.war</code> file, which contains the entire
web application:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>mvn package</code></strong>
<code class="computeroutput">[INFO] Scanning for projects...
[INFO] Reactor build order:
[INFO] guacamole-common
[INFO] guacamole-ext
[INFO] guacamole-common-js
[INFO] guacamole
[INFO] guacamole-client
...
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] ------------------------------------------------------------------------
[INFO] guacamole-common ...................................... SUCCESS [4.467s]
[INFO] guacamole-ext ......................................... SUCCESS [1.479s]
[INFO] guacamole-common-js ................................... SUCCESS [3.680s]
[INFO] guacamole ............................................. SUCCESS [3.729s]
[INFO] guacamole-client ...................................... SUCCESS [0.008s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 13 seconds
[INFO] Finished at: Mon Jul 08 00:44:42 PDT 2013
[INFO] Final Memory: 43M/354M
[INFO] ------------------------------------------------------------------------</code>
<code class="prompt">$</code></pre>
</div>
<p>Once the Guacamole web application is built, there will be a .war file in the
<code class="filename">guacamole/target/</code> subdirectory of the current directory (the
directory you were in when you ran <span class="application">mvn</span>). This
<code class="filename">.war</code> file contains the entirety of the Guacamole web
application, including all dependencies. Installing Guacamole means copying this
<code class="filename">.war</code> file into the directory required by your servlet
container.</p>
<p>You will probably have to do this as the root user:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>cp guacamole/target/guacamole-0.9.4.war /var/lib/tomcat7/webapps/guacamole.war</code></strong>
<code class="prompt">#</code></pre>
</div>
<p>The Guacamole web application also depends on a configuration file,
<code class="filename">guacamole.properties</code>, to tell it the type of authentication to
use and how to connect to guacd. A functional example
<code class="filename">guacamole.properties</code> is contained in the
<code class="filename">doc/</code> subdirectory; you can simply copy this somewhere (like
<code class="filename">/etc/guacamole</code>) and then create a symbolic link to in a
directory called <code class="filename">.guacamole</code> 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.</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>mkdir /etc/guacamole</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>mkdir <em class="replaceable"><code>/usr/share/tomcat7</code></em>/.guacamole</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>cp guacamole/doc/example/guacamole.properties /etc/guacamole/guacamole.properties</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>ln -s /etc/guacamole/guacamole.properties <em class="replaceable"><code>/usr/share/tomcat7</code></em>/.guacamole/</code></strong>
<code class="prompt">#</code> </pre>
</div>
<p>You will need to edit <code class="filename">guacamole.properties</code> to be sure that all
the settings are valid for your installation.</p>
<p>If you are using the default authentication method, you will also need to install the
<code class="filename">user-mapping.xml</code> 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.</p>
<p>An example <code class="filename">user-mapping.xml</code> file is provided in the
<code class="filename">doc/</code> subdirectory. You can simply copy this file to a
reasonable location (like <code class="filename">/etc/guacamole/user-mapping.xml</code>) and then
edit <code class="filename">guacamole.properties</code> to specify the correct location of this
file.</p>
<p>You will need to edit <code class="filename">user-mapping.xml</code> to add and remove users,
as well as to remove the "default" users included as examples.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="deploying-guacamole"></a>Deploying Guacamole</h2></div></div></div>
<a id="idm139657086814944" class="indexterm"></a>
<p>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.</p>
<p>There are two critical files involved in the deployment of Guacamole:
<code class="filename">guacamole.war</code>, which is the file containing the web
application, and <code class="filename">guacamole.properties</code>, 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.</p>
<p>Ultimately, the <code class="filename">guacamole.war</code> file, or a symbolic link to it,
must be found by your servlet container within the directory it uses for
<code class="filename">.war</code> files, and the <code class="filename">guacamole.properties</code>
file must be within the <code class="filename">.guacamole</code> directory in the home directory
of the user your servlet container runs as. Legacy installations will have
<code class="filename">guacamole.properties</code> placed in the classpath of the servlet
container, but this is officially deprecated, and will be unsupported in future
releases.</p>
<p>We recommend placing <code class="filename">guacamole.properties</code> and any other
configuration files in <code class="filename">/etc/guacamole</code>, and
<code class="filename">guacamole.war</code> in <code class="filename">/var/lib/guacamole</code>. You
will likely have to create each of these directories manually, as root.</p>
<p>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
"<code class="filename">webapps</code>" directory (below,
<code class="filename">/var/lib/tomcat7/webapps</code>, but your installation may be
different), and the "<code class="filename">.guacamole</code>" directory, which must be manually
created within the Tomcat user's home directory.</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>ln -s /var/lib/guacamole/guacamole.war <em class="replaceable"><code>/var/lib/tomcat7</code></em>/webapps</code></strong>
<code class="prompt">#</code> <strong class="userinput"><code>ln -s /etc/guacamole/guacamole.properties <em class="replaceable"><code>/usr/share/tomcat7</code></em>/.guacamole/</code></strong>
<code class="prompt">#</code></pre>
</div>
<p>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.</p>
<p>Once Guacamole has been deployed, Tomcat must be restarted (as
<code class="filename">guacamole.properties</code> 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.</p>
<p>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:</p>
<div class="informalexample">
<pre class="screen"><code class="prompt">#</code> <strong class="userinput"><code>/etc/init.d/tomcat7 restart</code></strong>
<code class="computeroutput">Stopping Tomcat... OK
Starting Tomcat... OK</code>
<code class="prompt">#</code> <strong class="userinput"><code>/etc/init.d/guacd start</code></strong>
<code class="computeroutput">Starting guacd: SUCCESS
guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 0.9.4 started</code>
<code class="prompt">#</code></pre>
</div>
<p>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.</p>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm139657086793728"></a>What about WebSocket?</h3></div></div></div>
<a id="idm139657086792992" class="indexterm"></a>
<p>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.</p>
<p>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.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mod-proxy"></a>Using Apache as a frontend (<span class="package">mod_proxy</span>)</h2></div></div></div>
<p>Many users end up serving Guacamole through Apache using <span class="package">mod_proxy</span>,
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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>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, with the notable
exception of AJP, which may not be supported by your servlet container.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="ajp-proxy"></a>Using AJP</h3></div></div></div>
<p>AJP is the Apache JServ Protocol - a protocol specifically designed for proxy
communication between a web server like Apache and Tomcat. The AJP protocol is
intended to be faster than HTTP when it comes to proxying web traffic, and it
implements features that allow load balancing between multiple servlet
containers.</p>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139657086782160"></a>Configuring Tomcat for AJP</h4></div></div></div>
<p>To allow AJP connections to Tomcat, you must add a connector to Tomcat's
<code class="filename">conf/server.xml</code>. There may already be an example
connector in your <code class="filename">server.xml</code>, in which case all you need to
do is uncomment it, editing the port number as desired:</p>
<div class="informalexample">
<pre class="programlisting">&lt;Connector port="8009" protocol="AJP/1.3"
URIEncoding="UTF-8"
redirectPort="8443" /&gt;</pre>
</div>
<p>Tomcat must be restarted after the connector is added.</p>
<p>The <code class="code">URIEncoding="UTF-8"</code> attribute above ensures that connection
names, user names, etc. which contain non-latin characters are properly
received. If you will be creating connections that have Cyrillic, Chinese,
Japanese, etc. characters in the names or parameter values, you should be sure
to set this attribute.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139657086777056"></a>Forwarding HTTP requests over AJP</h4></div></div></div>
<p>Once the connector is open, and Tomcat is listening on the port specified, you
can edit your Apache configuration, adding a location which will proxy the
Guacamole web application served via AJP by Tomcat:</p>
<div class="informalexample">
<pre class="programlisting">&lt;Location /guacamole/&gt;
Order allow,deny
Allow from all
ProxyPass ajp://<em class="replaceable"><code>HOSTNAME</code></em>:<em class="replaceable"><code>8009</code></em>/guacamole/ max=20 flushpackets=on
ProxyPassReverse <em class="replaceable"><code>http://HOSTNAME</code></em>/guacamole/
&lt;/Location&gt;</pre>
</div>
<p>The most important thing in this entire section is the option
<code class="option">flushpackets=on</code>. Most proxies, including
<span class="package">mod_proxy</span>, 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.</p>
<p><span class="emphasis"><em>If the option <code class="option">flushpackets=on</code> is not specified,
Guacamole will not work</em></span>.</p>
<p>Note also the protocol of the URL specified in the
<em class="parameter"><code>ProxyPassReverse</code></em> directive. The protocol
<span class="emphasis"><em>MUST</em></span> match the protocol that will be used to connect to
to Apache. The example above specifies <em class="replaceable"><code>http</code></em>, but if
you are using HTTPS then the URL specified here will have to reflect
this.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="http-proxy"></a>Using HTTP</h3></div></div></div>
<p>If you don't wish to use AJP, the default HTTP connector (or any HTTP connector)
can be used without any noticeable performance hit.</p>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139657086766048"></a>Configuring Tomcat for HTTP</h4></div></div></div>
<p>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
<code class="filename">conf/server.xml</code>:</p>
<div class="informalexample">
<pre class="programlisting">&lt;Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
URIEncoding="UTF-8"
redirectPort="8443" /&gt;</pre>
</div>
<div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
<p>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.</p>
</div>
<p>As with AJP, be sure to specify the <code class="code">URIEncoding="UTF-8"</code> 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.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="idm139657086760352"></a>Forwarding HTTP requests over HTTP</h4></div></div></div>
<p>The configuration necessary to proxy HTTP requests is similar to the
configuration required for proxying requests through AJP. In fact, it is
completely identical except for the differing protocol names in the URIs given
to the proxy directives:</p>
<div class="informalexample">
<pre class="programlisting">&lt;Location /guacamole/&gt;
Order allow,deny
Allow from all
ProxyPass http://<em class="replaceable"><code>HOSTNAME</code></em>:<em class="replaceable"><code>8080</code></em>/guacamole/ max=20 flushpackets=on
ProxyPassReverse http://<em class="replaceable"><code>HOSTNAME</code></em>:<em class="replaceable"><code>8080</code></em>/guacamole/
&lt;/Location&gt;</pre>
</div>
<p>Again, take note of the option <code class="option">flushpackets=on</code>. This option
is absolutely critical as <span class="package">mod_proxy</span> will otherwise buffer all
data sent over the connection, rendering Guacamole unusable.</p>
<p><span class="emphasis"><em>If the option <code class="option">flushpackets=on</code> is not specified,
Guacamole will not work</em></span>.</p>
</div>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="disable-tunnel-logging"></a>Disable logging of tunnel requests</h3></div></div></div>
<p>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 don not explicitly disable logging of
those requests.</p>
<p>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:</p>
<div class="informalexample">
<pre class="programlisting">SetEnvIf Request_URI "^<em class="replaceable"><code>/guacamole</code></em>/tunnel" dontlog
CustomLog <em class="replaceable"><code>/var/log/apache2/guac.log</code></em> common env=!dontlog</pre>
</div>
<p>There is little value in a log file filled with identical tunnel requests.</p>
<p>Note that if you are serving Guacamole under a path different from
<code class="uri">/guacamole/</code>, you will need to change the value of
<em class="parameter"><code>Request_URI</code></em> above accordingly.</p>
</div>
<div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="change-web-app-path"></a>Proxying under a different path</h3></div></div></div>
<p>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.</p>
<p>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
(<code class="uri">/guacamole</code>). 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, <span class="package">mod_proxy</span> has a directive for this:
<em class="parameter"><code>ProxyPassReverseCookiePath</code></em>.</p>
<div class="informalexample">
<pre class="programlisting">&lt;Location /<em class="replaceable"><code>new-path/</code></em>&gt;
Order allow,deny
Allow from all
ProxyPass ajp://<em class="replaceable"><code>HOSTNAME</code></em>:<em class="replaceable"><code>8009</code></em>/guacamole/ max=20 flushpackets=on
ProxyPassReverse <em class="replaceable"><code>http://HOSTNAME</code></em>/guacamole/
ProxyPassReverseCookiePath /guacamole/ <em class="replaceable"><code>/new-path/</code></em>
&lt;/Location&gt;</pre>
</div>
<p>The configuration shown above is similar to the configuration shown for generic
AJP proxying, except that the additional
<em class="parameter"><code>ProxyPassReverseCookiePath</code></em> directive is given,
instructing <span class="package">mod_proxy</span> to update the cookie path, changing
<code class="uri">/guacamole/</code> to <code class="uri">/new-path/</code>, the same path specified when
the location was declared.</p>
<p>Be careful when specifying the URL in the <em class="parameter"><code>ProxyPassReverse</code></em>
directive. The protocol of the URL <span class="emphasis"><em>MUST</em></span> match the protocol that
will be used to connect to to Apache, even if it differs from the protocol being
used to connect to Tomcat.</p>
</div>
</div>
</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-architecture.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-guacamole.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 1. Implementation and architecture </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 3. Configuring Guacamole</td></tr></table></div>
</div></div>
<!-- Google Analytics -->
<script type="text/javascript">
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-75289145-1', 'auto');
ga('send', 'pageview');
</script>
<!-- End Google Analytics -->
</body></html>