Google Git
Sign in
apache / guacamole-manual / 31fd53e920dd50fe6c1abd3a963a9d30931983fa / . / src / chapters / installing.xml
blob: 82aafd139c38d4acc18c9a9b92de19af1adb9b1e [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<chapter xml:id="installing-guacamole" xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:lang="en" xmlns:xl="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">
<title>Installing Guacamole</title>
<indexterm>
<primary>installing</primary>
</indexterm>
<section xml:id="binary-packages">
<title>Packages from your distribution</title>
<indexterm>
<primary>packages</primary>
</indexterm>
<para>Guacamole is included in the repositories of several Linux distributions. If your
distribution provides Guacamole packages for you, this is the preferred method of
installing Guacamole. If your distribution does not provide Guacamole packages, or the
packages provided are too old, you can build Guacamole from source fairly easily.</para>
<important>
<para>Be aware that Guacamole is a remote desktop gateway, and cannot access your
desktop's display without a remote desktop server of some kind to connect to.
Guacamole does not contain its own VNC or RDP server, and these installation
procedures will not walk you through the installation of a VNC or RDP server.</para>
<para>Your distribution of choice will provide documentation for setting up VNC, as will
the documentation provided by those that created the VNC server you wish to use. If
you are going to use RDP to connect to Windows computers, Microsoft (and many others
on the internet) provides documentation describing how to set up remote
desktop.</para>
</important>
<para>Installing Guacamole from your distribution's <package>guacamole</package> package
will typically install the web application and the proxy <package>guacd</package>, along
with support for VNC (<package>libguac-client-vnc</package>). If you want support for
RDP or SSH, you will need to install those packages as well.</para>
<para>After the Guacamole packages are installed, the web application may still need to be
deployed to your servlet container. Some packages, like the Debian package called
<package>guacamole-tomcat</package>, will do this for you, but if your distribution
provides no such package, you will have to deploy Guacamole yourself.</para>
<section>
<title>Debian and Ubuntu</title>
<para>The Debian repositories contain packages for all of Guacamole's components, and
Ubuntu has inherited those packages (being Debian-based).</para>
<para>For users of Debian or any flavor of Ubuntu, installing Guacamole is as simple as
installing the <package>guacamole-tomcat</package> package, and then editing the
<filename>/etc/guacamole/user-mapping.xml</filename> file to add some
connections. The <package>guacamole-tomcat</package> package will install Tomcat and
automatically create the necessary symbolic links to deploy Guacamole. If you don't
want to use Tomcat, or you want to deploy Guacamole manually, you can install the
<package>guacamole</package> package instead, and follow the deployment
instructions provided in this chapter.</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>apt-get install guacamole-tomcat</userinput>
<prompt>#</prompt> </screen>
</informalexample>
<para>If you install the <package>guacamole-tomcat</package> package, you will be
prompted for whether you wish to restart Tomcat automatically. Tomcat must be
restarted after Guacamole is installed or upgraded. If you don't want to do this, or
you want to do this manually, choose "No" (the default). Choosing "Yes" will restart
Tomcat for this and future installs of Guacamole.</para>
<important>
<para>The Debian and Ubuntu packages will set up <package>guacd</package> such that
it runs as its own reduced-privlege <code>guacd</code> user, for the sake of
security. Similarly, the <filename>user-mapping.xml</filename> file will only be
readable by users in the <code>guacamole-web</code> group, as it will
potentially contain sensitive information like passwords in plain text.</para>
<para>The guacamole-tomcat package will automcatically put the tomcat6 user in the
<code>guacamole-web</code> group, but if you are installing Tomcat manually
or using another servlet container, <emphasis>you must ensure your servlet
container's user is a member of the <code>guacamole-web</code>
group</emphasis>. If you do not do this, your serlvet container will not be
able to read <filename>user-mapping.xml</filename>, and all attempts to login to
Guacamole will fail.</para>
</important>
<para>By default, VNC support will be installed as a dependency of the
<package>guacamole</package> package. If you want SSH or RDP support, you will
need to install <package>libguac-client-ssh0</package> or
<package>libguac-client-rdp0</package> manually:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>apt-get install libguac-client-ssh0 libguac-client-rdp0</userinput>
<prompt>#</prompt> </screen>
<para>Recent versions of Debian and Ubuntu have a recent-enough version of FreeRDP
and include <package>libguac-client-rdp0</package>, but if you're using an older
version of Debian (such as Debian 6.0 a.k.a. "squeeze"), you will have to either
do without RDP support or install FreeRDP and
<package>guacamole-server</package> manually, without using your
distribution's packages.</para>
<para>Once installed, both Tomcat and <package>guacd</package> will start
automatically and on boot.</para>
</informalexample>
</section>
<section>
<title>Fedora, RHEL, and CentOS</title>
<para>Fedora has an excellent Guacamole package, <package>guacamole</package>, which
will automatically install deploy Guacamole to Tomcat. It does not depend on
<package>guacd</package>, however, and you thus must install the
<package>guacd</package> package manually alongside
<package>guacamole</package>:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>yum install guacamole guacd</userinput>
<prompt>#</prompt> </screen>
</informalexample>
<para>Depending on which protocols you require support for, you will need to install one
of the <package>libguac-client-*</package> packages to provide support for those
protocols. Most users will want at least <package>libguac-client-vnc</package>. If
you want SSH support, or access to RDP servers, you will need to install
<package>libguac-client-ssh</package> or <package>libguac-client-rdp</package>
respectively.</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>yum install libguac-client-vnc libguac-client-ssh libguac-client-rdp</userinput>
<prompt>#</prompt> </screen>
</informalexample>
<para>Neither RHEL nor CentOS include Guacamole packages in their main repositories,
however Fedora maintains a repository called EPEL which contains binaries compatible
with both RHEL and CentOS. The EPEL repository contains the Guacamole packages
described above. If you wish to install Guacamole on RHEL or CentOS, you should
either add the EPEL repository and install from that, or build Guacamole from
source.</para>
<para>Once everything is installed, you will still need to configure
<package>guacd</package> and Tomcat to start automatically on boot (assuming
this is what you want):</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>chkconfig tomcat6 on</userinput>
<computeroutput>Note: forwarding request to 'systemctl enable tomcat6.service'
ln -s '/usr/lib/systemd/system/tomcat6.service'
'/etc/systemd/system/multi-user.target.wants/tomcat6.service'</computeroutput>
<prompt>#</prompt> <userinput>chkconfig guacd on</userinput>
<prompt>#</prompt></screen>
</informalexample>
<para>If you don't want Tomcat and guacd to start automatically, you can start them
manually instead:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>service tomcat6 start</userinput>
<computeroutput>Redirecting to /bin/systemctl start tomcat6.service</computeroutput>
<prompt>#</prompt> <userinput>service guacd start</userinput>
<computeroutput>Starting guacd: SUCCESS
guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 0.7.0
guacd[6229]: INFO: Unable to bind socket to host ::1, port 4822: Address family not supported by
protocol
guacd[6229]: INFO: Successfully bound socket to host 127.0.0.1, port 4822
guacd[6229]: INFO: Exiting and passing control to PID 6230
guacd[6230]: INFO: Exiting and passing control to PID 6231</computeroutput>
<prompt>#</prompt></screen>
</informalexample>
<para>At this point, all you need to do is edit the
<filename>/etc/guacamole/user-mapping.xml</filename> file to add some
connections. You do not need to restart Tomcat after editing this file; it will be
reloaded automatically by Guacamole.</para>
</section>
<section>
<title>Other distributions</title>
<para>If you distribution isn't listed above, there is still a chance your distribution
provides Guacamole packages. A search for "guacamole" in your distribution's package
manage should answer that question quickly. If no package is provided, your only
option is to build Guacamole from source.</para>
<para>Building Guacamole from source is not hard. In most cases, all you need to do is
download the latest source for <package>guacamole-server</package>, and the latest
guacamole.war from the Guacamole project website, build
<package>guacamole-server</package>, and then deploy
<filename>guacamole.war</filename>.</para>
<para>The method for installing Guacamole is fairly constant across platforms, and the
instructions given here should apply almost universally (and in the case that they
don't, you probably already know what you need to do).</para>
</section>
</section>
<section xml:id="building-guacamole-from-source">
<title>Building Guacamole from source</title>
<indexterm>
<primary>compiling</primary>
<secondary>Guacamole</secondary>
</indexterm>
<para>Building the components of Guacamole from source is not difficult, providing you have
the necessary tools installed already. The source for the entirety of Guacamole is
available from the Guacamole project web site in convenient source archives, each named
after the component they contain. Each archive also contains a file named
<filename>README</filename> which lists detailed instructions for building and
installing. </para>
<para>Guacamole is separated into two pieces: <package>guacamole-server</package>, which
provides the <package>guacd</package> proxy and related libraries, and
<package>guacamole-client</package>, which provides the client to be served by your
servlet container. In most cases, the only source you will need to build is
<package>guacamole-server</package>, and downloading the latest
<filename>guacamole.war</filename> from the project website will be sufficient to
provide the client. Building <package>guacamole-client</package> is really only
necessary when you wish to modify the source or when you want to try the latest
unreleased changes.</para>
<para>To compile the C components, you will need a C compiler (such as
<package>gcc</package>) and the libraries that each component depends on. Note that
many Linux distribution separates 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.</para>
<section xml:id="compiling-guacamole-server">
<title><package>guacamole-server</package></title>
<indexterm>
<primary><package>libguac</package></primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary>guacd</primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary>VNC support</primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary>RDP support</primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary>SSH support</primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary><package>libguac-client-vnc</package></primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary><package>libguac-client-rdp</package></primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary><package>libguac-client-ssh</package></primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary><package>guacamole-server</package></primary>
<secondary>compiling</secondary>
</indexterm>
<para><package>guacamole-server</package> contains all the native, server-side
components required by Guacamole to connect to remote desktops. It provides a common
C library, <package>libguac</package>, which all other native components depend on,
as well as separate libraries for each supported protocol, and a proxy daemon,
<package>guacd</package>, the heart of Guacamole.</para>
<para><package>guacd</package> is the proxy daemon that runs on your Guacamole server,
accepting connections from the Guacamole web application on behalf of remote users.
It effectively translates between common remote desktop protocols like VNC or RDP by
dynamically loading protocol support plugins. Building <package>guacd</package>
creates an executable called <filename>guacd</filename> which can be run manually
or, if you wish, automatically when your computer starts up.</para>
<para>In order to build <package>guacamole-server</package>, you will need
<package>Cairo</package>, a graphics library, and <package>libpng</package>, the
official PNG library. These libraries are strictly required <emphasis>in all
cases</emphasis>. Guacamole cannot be built without them. The other dependencies
of <package>guacamole-server</package> are optional. Which libraries you will need
to install depends on what support you need.</para>
<para>Guacamole currently supports VNC, RDP, and SSH. Each protocol corresponds to a
separate library that will be built with <package>guacamole-server</package> if you
have its corresponding optional dependencies. VNC support depends on the
<package>libvncclient</package> library, which is part of
<package>libVNCServer</package>, RDP support depends on a recent version of
<package>FreeRDP</package> - 1.0 or higher, and SSH support depends on
<package>libssh</package> and <package>Pango</package>, a font rendering and
text layout library.</para>
<para>Optional features of these protocols will be enabled if you have other libraries
installed as well. Currently, the RDP support also provides sound encoded with Ogg
Vorbis if you have <package>libvorbis</package> installed while building
<package>guacamole-server</package>.</para>
<para>You can obtain a copy of the <package>guacamole-server</package> source from the
Guacamole project web site if you want the latest released code. 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 <filename>.tar.gz</filename> archive which
you can extract from the command line:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>tar -xzf guacamole-server-0.8.2.tar.gz</userinput>
<prompt>$</prompt> <userinput>cd guacamole-server-0.8.2/</userinput>
<prompt>$</prompt></screen>
</informalexample>
<para>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 unstable
branch from the Guacamole team's git repository on GitHub:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>git clone <uri>git://github.com/glyptodon/guacamole-server.git</uri> -b unstable</userinput>
<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.</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para>Once the <package>guacamole-server</package> source has been downloaded and
extracted, you need to run <filename>configure</filename>. This is a shell script
automatically generated by GNU Autotools, a popular build system used by the
Guacamole project for <package>guacamole-server</package>. Running
<filename>configure</filename> will determine which libraries are available on
your system and will select the appropriate components for building depending on
what you actually have installed.</para>
<important>
<para>Source downloaded directly from git will not contain this
<filename>configure</filename> 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 <filename>configure</filename>
manually:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>cd guacamole-server/</userinput>
<prompt>$</prompt> <userinput>autoreconf -fi</userinput>
<prompt>$</prompt></screen>
<para>Doing this requires GNU Autotools to be installed.</para>
<para>Source archives downloaded from the project website contain the
<filename>configure</filename> script and all other necessary build
files, and thus do not require GNU Autotools to be installed on the build
machine.</para>
</informalexample>
</important>
<para>Once you run <filename>configure</filename>, you can see what a listing of what
libraries were found and what it has determined should be built:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>./configure --with-init-dir=<replaceable>/etc/init.d</replaceable></userinput>
<computeroutput>checking for a BSD-compatible install... /usr/bin/install -c
checking whether build environment is sane... yes
...
------------------------------------------------
guacamole-server version 0.8.0
------------------------------------------------
Library status:
freerdp ............. yes
pango ............... yes
libssh .............. yes
libVNCServer ........ yes
libvorbisenc ........ yes
Protocol support:
RDP ....... yes
SSH ....... yes
VNC ....... yes
Init scripts: /etc/init.d
Type "make" to compile guacamole-server.
</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para><indexterm>
<primary><package>guacd</package></primary>
<secondary>startup script</secondary>
</indexterm>The <option>--with-init-dir=/etc/init.d</option> shown above prepares
the build to install a startup script for <package>guacd</package> into the
<filename>/etc/init.d</filename> directory, such that we can later easily
configure <package>guacd</package> to start automatically on bot. If you do not wish
guacd to start automatically at boot, leave off the <option>--with-init-dir</option>
option. If the directory containing your distribution's startup scripts differs from
the common <filename>/etc/init.d</filename>, replace
<filename>/etc/init.d</filename> with the proper directory here. You may need to
consult your distribution's documentation, or do a little digging in
<filename>/etc</filename>, to determine the proper location.</para>
<para>Here, <filename>configure</filename> 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
"<computeroutput>yes</computeroutput>" answers above will read
"<computeroutput>no</computeroutput>". 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 <filename>configure</filename>, you find support for
something you wanted is missing, simply install the corresponding dependencies and
run <filename>configure</filename> again.</para>
<para>Once <filename>configure</filename> is finished, just type
"<userinput>make</userinput>", and it will <package>guacamole-server</package>
will compile:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>make</userinput>
<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'</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para>Quite a bit of output will scroll up the screen as all the components are
compiled. Once everything finishes, all you have left to do is type "<userinput>make
install</userinput>" to install the components that were built, and then
"<userinput>ldconfig</userinput>" to update your system's cache of installed
libraries:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>make install</userinput>
<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'</computeroutput>
<prompt>#</prompt> <userinput>ldconfig</userinput>
<prompt>#</prompt> </screen>
</informalexample>
<para>At this point, everything is installed, but <package>guacd</package> is not
running. You will need to run guacd in order to use Guacamole once the client
components are installed as well.</para>
<para>Beware that even after installing <package>guacd</package> 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.</para>
</section>
<section xml:id="compiling-guacamole-client">
<title><package>guacamole-client</package></title>
<indexterm>
<primary><filename>guacamole.war</filename></primary>
<secondary>compiling</secondary>
</indexterm>
<indexterm>
<primary><package>guacamole-client</package></primary>
<secondary>compiling</secondary>
</indexterm>
<para><package>guacamole-client</package> contains all Java and Maven components of
Guacamole (<package>guacamole</package>, <package>guacamole-common</package>,
<package>guacamole-ext</package>, and <package>guacamole-common-js</package>).
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
connect to <package>guacd</package>, part of <package>guacamole-server</package>, on
behalf of connected users in order to serve them any remote desktop they are
authorized to access.</para>
<para>Normally, you don't need to build <package>guacamole-client</package> manually, as
it is written in Java and is cross-platform. The easiest way to obtain the latest
version of <package>guacamole-client</package> is to simply download the latest
<filename>guacamole.war</filename> (the compiled form of
<package>guacamole-client</package>) from the Guacamole project web site.</para>
<para>To compile <package>guacamole-client</package>, all you need is Apache Maven and a
copy of the Java JDK. Most, if not all, Linux distributions will provide packages
for these.</para>
<para>You can obtain a copy of the <package>guacamole-client</package> source from the
Guacamole project web site if you want the latest released code. 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 <filename>.tar.gz</filename> archive which
you can extract from the command line:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>tar -xzf guacamole-client-0.8.2.tar.gz</userinput>
<prompt>$</prompt> <userinput>cd guacamole-client-0.8.2/</userinput>
<prompt>$</prompt></screen>
</informalexample>
<para>As with <package>guacamole-server</package>, 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 unstable branch from the Guacamole team's git
repository on GitHub:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>git clone <uri>git://github.com/glyptodon/guacamole-client.git</uri> -b unstable</userinput>
<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.</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para>Unlike <package>guacamole-server</package>, 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
<filename>pom.xml</filename> file provided with the source.</para>
<para>To build <package>guacamole-client</package>, just run "<userinput>mvn
package</userinput>". This will invoke Maven to automatically build and package
all components, producing a single <filename>.war</filename> file, which contains
the entire web application:</para>
<informalexample>
<screen><prompt>$</prompt> <userinput>mvn package</userinput>
<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] ------------------------------------------------------------------------</computeroutput>
<prompt>$</prompt></screen>
</informalexample>
<para>Once the Guacamole web application is built, there will be a .war file in the
<filename>guacamole/target/</filename> subdirectory of the current directory
(the directory you were in when you ran <application>mvn</application>). This
<filename>.war</filename> file contains the entirety of the Guacamole web
application, including all dependencies. Installing Guacamole means copying this
<filename>.war</filename> file into the directory required by your servlet
container.</para>
<para>You will probably have to do this as the root user:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>cp guacamole/target/guacamole-0.8.2.war /var/lib/tomcat6/webapps/guacamole.war</userinput>
<prompt>#</prompt></screen>
</informalexample>
<para>The Guacamole web application also depends on a configuration file,
<filename>guacamole.properties</filename>, to tell it the type of authentication
to use and how to connect to guacd. A functional example
<filename>guacamole.properties</filename> is contained in the
<filename>doc/</filename> subdirectory; you can simply copy this somewhere (like
<filename>/etc/guacamole</filename>) and then create a symbolic link to in a
directory called <filename>.guacamole</filename> 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.</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>mkdir /etc/guacamole</userinput>
<prompt>#</prompt> <userinput>mkdir <replaceable>/usr/share/tomcat6</replaceable>/.guacamole</userinput>
<prompt>#</prompt> <userinput>cp doc/guacamole.properties /etc/guacamole/guacamole.properties</userinput>
<prompt>#</prompt> <userinput>ln -s /etc/guacamole/guacamole.properties <replaceable>/usr/share/tomcat6</replaceable>/.guacamole/</userinput>
<prompt>#</prompt> </screen>
</informalexample>
<para>You will need to edit <filename>guacamole.properties</filename> to be sure that
all the settings are valid for your installation.</para>
<para>If you are using the default authentication method, you will also need to install
the <filename>user-mapping.xml</filename> 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.</para>
<para>An example <filename>user-mapping.xml</filename> file is provided in the
<filename>doc/</filename> subdirectory. You can simply copy this file to a
reasonable location (like <filename>/etc/guacamole/user-mapping.xml</filename>) and
then edit <filename>guacamole.properties</filename> to specify the correct location
of this file.</para>
<para>You will need to edit <filename>user-mapping.xml</filename> to add and remove
users, as well as to remove the "default" users included as examples.</para>
</section>
</section>
<section xml:id="deploying-guacamole">
<title>Deploying Guacamole</title>
<indexterm>
<primary>deploying</primary>
</indexterm>
<para>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.</para>
<para>There are two critical files involved in the deployment of Guacamole:
<filename>guacamole.war</filename>, which is the file containing the web
application, and <filename>guacamole.properties</filename>, 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.</para>
<para>Ultimately, the <filename>guacamole.war</filename> file, or a symbolic link to it,
must be found by your servler container within the directory it uses for
<filename>.war</filename> files, and the <filename>guacamole.properties</filename>
file must be within the <filename>.guacamole</filename> directory in the home directory
of the user your servlet container runs as. Legacy installations will have
<filename>guacamole.properties</filename> placed in the classpath of the servlet
container, but this is officially deprecated, and will be unsupported in future
releases.</para>
<para>We recommend placing <filename>guacamole.properties</filename> and any other
configuration files in <filename>/etc/guacamole</filename>, and
<filename>guacamole.war</filename> in <filename>/var/lib/guacamole</filename>. You
will likely have to create each of these directories manually, as root.</para>
<para>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
"<filename>webapps</filename>" directory (below,
<filename>/var/lib/tomcat6/webapps</filename>, but your installation may be
different), and the "<filename>.guacamole</filename>" directory, which must be manually
created within the Tomcat user's home directory.</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>ln -s /var/lib/guacamole/guacamole.war <replaceable>/var/lib/tomcat6</replaceable>/webapps</userinput>
<prompt>#</prompt> <userinput>ln -s /etc/guacamole/guacamole.properties <replaceable>/usr/share/tomcat6</replaceable>/.guacamole/</userinput>
<prompt>#</prompt></screen>
</informalexample>
<para>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.</para>
<para>Once Guacamole has been deployed, Tomcat must be restarted (as
<filename>guacamole.properties</filename> 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.</para>
<para>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:</para>
<informalexample>
<screen><prompt>#</prompt> <userinput>/etc/init.d/tomcat6 restart</userinput>
<computeroutput>Stopping Tomcat... OK
Starting Tomcat... OK</computeroutput>
<prompt>#</prompt> <userinput>/etc/init.d/guacd start</userinput>
<computeroutput>Starting guacd: SUCCESS
guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 0.7.0
guacd[6229]: INFO: Unable to bind socket to host ::1, port 4822: Address family not supported by
protocol
guacd[6229]: INFO: Successfully bound socket to host 127.0.0.1, port 4822
guacd[6229]: INFO: Exiting and passing control to PID 6230
guacd[6230]: INFO: Exiting and passing control to PID 6231</computeroutput>
<prompt>#</prompt></screen>
</informalexample>
<para>If you want Guacamole to start on boot, you will need to configure the tomcat6 and
guacd services to run automatically. Your distribution will provide documentation for
doing this.</para>
</section>
<section xml:id="mod-proxy">
<title>Using Apache as a frontend (<package>mod_proxy</package>)</title>
<para>Many users end up serving Guacamole through Apache using <package>mod_proxy</package>,
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.</para>
<para>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.</para>
<para>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.</para>
<para>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.</para>
<important>
<para>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.</para>
</important>
<section xml:id="ajp-proxy">
<title>Using AJP</title>
<para>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.</para>
<section>
<title>Configuring Tomcat for AJP</title>
<para>To allow AJP connections to Tomcat, you must add a connector to Tomcat's
<filename>conf/server.xml</filename>. There may already be an example
connector in your <filename>server.xml</filename>, in which case all you need to
do is uncomment it, editing the port number as desired:</para>
<informalexample>
<programlisting>&lt;Connector port="8009" protocol="AJP/1.3"
URIEncoding="UTF-8"
redirectPort="8443" /></programlisting>
</informalexample>
<para>Tomcat must be restarted after the connector is added.</para>
<para>The <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.</para>
</section>
<section>
<title>Forwarding HTTP requests over AJP</title>
<para>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:</para>
<informalexample>
<programlisting>&lt;Location /guacamole/>
Order allow,deny
Allow from all
ProxyPass ajp://<replaceable>HOSTNAME</replaceable>:<replaceable>8009</replaceable>/guacamole/ max=20 flushpackets=on
ProxyPassReverse ajp://<replaceable>HOSTNAME</replaceable>:<replaceable>8009</replaceable>/guacamole/
&lt;/Location></programlisting>
</informalexample>
<para>The most important thing in this entire section is the option
<option>flushpackets=on</option>. Most proxies, including
<package>mod_proxy</package>, 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.</para>
<para><emphasis>If the option <option>flushpackets=on</option> is not specified,
Guacamole will not work</emphasis>.</para>
</section>
</section>
<section xml:id="http-proxy">
<title>Using HTTP</title>
<para>If you don't wish to use AJP, the default HTTP connector (or any HTTP connector)
can be used without any noticable performance hit.</para>
<section>
<title>Configuring Tomcat for HTTP</title>
<para>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
<filename>conf/server.xml</filename>:</para>
<informalexample>
<programlisting>&lt;Connector port="8080" protocol="HTTP/1.1"
connectionTimeout="20000"
URIEncoding="UTF-8"
redirectPort="8443" /></programlisting>
</informalexample>
<important>
<para>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.</para>
</important>
<para>As with AJP, be sure to specify the <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.</para>
</section>
<section>
<title>Forwarding HTTP requests over HTTP</title>
<para>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:</para>
<informalexample>
<programlisting>&lt;Location /guacamole/>
Order allow,deny
Allow from all
ProxyPass http://<replaceable>HOSTNAME</replaceable>:<replaceable>8080</replaceable>/guacamole/ max=20 flushpackets=on
ProxyPassReverse http://<replaceable>HOSTNAME</replaceable>:<replaceable>8080</replaceable>/guacamole/
&lt;/Location></programlisting>
</informalexample>
<para>Again, take note of the option <option>flushpackets=on</option>. This option
is absolutely critical as <package>mod_proxy</package> will otherwise buffer all
data sent over the connection, rendering Guacamole unusable.</para>
<para><emphasis>If the option <option>flushpackets=on</option> is not specified,
Guacamole will not work</emphasis>.</para>
</section>
</section>
<section xml:id="disable-tunnel-logging">
<title>Disable logging of tunnel requests</title>
<para>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.</para>
<para>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:</para>
<informalexample>
<programlisting>SetEnvIf Request_URI "^<replaceable>/guacamole</replaceable>/tunnel" dontlog
CustomLog <replaceable>/var/log/apache2/guac.log</replaceable> common env=!dontlog</programlisting>
</informalexample>
<para>There is little value in a log file filled with identical tunnel requests.</para>
<para>Note that if you are serving Guacamole under a path different from
<uri>/guacamole/</uri>, you will need to change the value of
<parameter>Request_URI</parameter> above accordingly.</para>
</section>
<section xml:id="change-web-app-path">
<title>Proxying under a different path</title>
<para>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.</para>
<para>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
(<uri>/guacamole</uri>). 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, <package>mod_proxy</package> has a directive for this:
<parameter>ProxyPassReverseCookiePath</parameter>.</para>
<informalexample>
<programlisting>&lt;Location /<replaceable>new-path/</replaceable>>
Order allow,deny
Allow from all
ProxyPass ajp://<replaceable>HOSTNAME</replaceable>:<replaceable>8009</replaceable>/guacamole/ max=20 flushpackets=on
ProxyPassReverse ajp://<replaceable>HOSTNAME</replaceable>:<replaceable>8009</replaceable>/guacamole/
ProxyPassReverseCookiePath /guacamole/ <replaceable>/new-path/</replaceable>
&lt;/Location></programlisting>
</informalexample>
<para>The configuration shown above is similar to the configuration shown for generic
AJP proxying, except that the additional
<parameter>ProxyPassReverseCookiePath</parameter> directive is given,
instructing <package>mod_proxy</package> to update the cookie path, changing
<uri>/guacamole/</uri> to <uri>/new-path/</uri>, the same path specified when
the location was declared.</para>
</section>
</section>
</chapter>