| <?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>There is also a PPA which contains the most recent stable build of Guacamole while |
| updates to the official Debian and Ubuntu repositories are pending. If you don't |
| want to wait for the main repositories to update, users of Ubuntu can just add the |
| PPA and install the packages from there:</para> |
| <informalexample> |
| <indexterm> |
| <primary>PPA</primary> |
| </indexterm> |
| <screen><prompt>$</prompt> <userinput>sudo add-apt-repository ppa:guacamole/stable</userinput> |
| <computeroutput>[sudo] password for user: |
| You are about to add the following PPA to your system: |
| The most recent stable release of Guacamole and its components. The packages |
| here use the same packaging as the downstream Debian and Ubuntu packages, but |
| are updated more frequently, usually while the corresponding downstream |
| packages are under official review. |
| More info: https://launchpad.net/~guacamole/+archive/stable |
| Press [ENTER] to continue or ctrl-c to cancel adding it |
| |
| gpg: keyring `/tmp/tmpc7ipgi/secring.gpg' created |
| gpg: keyring `/tmp/tmpc7ipgi/pubring.gpg' created |
| gpg: requesting key 106BB296 from hkp server keyserver.ubuntu.com |
| gpg: /tmp/tmpc7ipgi/trustdb.gpg: trustdb created |
| gpg: key 106BB296: public key "Launchpad PPA for Guacamole" imported |
| gpg: Total number processed: 1 |
| gpg: imported: 1 (RSA: 1) |
| OK</computeroutput> |
| <prompt>$</prompt> </screen> |
| </informalexample> |
| <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-privilege <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 automatically 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 servlet 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.</para> |
| <informaltable frame="all"> |
| <tgroup cols="3"> |
| <colspec colname="c1" colnum="1" colwidth="1*"/> |
| <colspec colname="c2" colnum="2" colwidth="1*"/> |
| <colspec colname="c3" colnum="3" colwidth="3.8*"/> |
| <thead> |
| <row> |
| <entry>Library name</entry> |
| <entry>Required?</entry> |
| <entry>Features</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry>Cairo</entry> |
| <entry>Yes.</entry> |
| <entry> |
| <para>Cairo is used by libguac for graphics rendering. Guacamole |
| cannot function without Cairo installed.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libpng</entry> |
| <entry>Yes.</entry> |
| <entry> |
| <para>libpng is used by libguac to write PNG images, the core image |
| type used by the Guacamole protocol. Guacamole cannot function |
| without libpng.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>FreeRDP</entry> |
| <entry>Only for RDP.</entry> |
| <entry> |
| <para>FreeRDP is required for RDP support. If you do not wish to |
| build RDP support, this library is not needed.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>Pango</entry> |
| <entry>Only for SSH.</entry> |
| <entry> |
| <para>Pango is a text layout library which Guacamole's SSH support |
| uses to render text. If you do not wish to build SSH support, |
| this library is not needed.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libssh</entry> |
| <entry>Only for SSH.</entry> |
| <entry> |
| <para>libssh is required for SSH support. If you do not wish to |
| build SSH support, this library is not needed.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libVNCServer</entry> |
| <entry>Only for VNC.</entry> |
| <entry> |
| <para>libVNCServer provides libvncclient which is required for VNC |
| support. If you do not wish to build VNC support, this library |
| is not needed.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libpulse</entry> |
| <entry>No.</entry> |
| <entry> |
| <para>libpulse provides support for PulseAudio, which is used by |
| Guacamole's VNC support to provide experimental audio. If you |
| are not going to be using the experimental audio support for |
| VNC, you do not need this library.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libssl</entry> |
| <entry>No.</entry> |
| <entry> |
| <para>libssl provides support for SSL and TLS - two common |
| encryption schemes that make up the majority of encrypted web |
| traffic.</para> |
| <para>If you have libssl installed, guacd will be built with SSL |
| support, allowing communication between the web application and |
| guacd to be encrypted.</para> |
| </entry> |
| </row> |
| <row> |
| <entry>libvorbis</entry> |
| <entry>No.</entry> |
| <entry> |
| <para>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.</para> |
| <para>Otherwise, sound will only be encoded as WAV (uncompressed), |
| and will only be available if your browser also supports |
| WAV.</para> |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| <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.3.tar.gz</userinput> |
| <prompt>$</prompt> <userinput>cd guacamole-server-0.8.3/</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 Guacamole |
| team's git repository on GitHub:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <userinput>git clone <uri>git://github.com/glyptodon/guacamole-server.git</uri></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.3 |
| ------------------------------------------------ |
| |
| Library status: |
| |
| freerdp ............. yes |
| pango ............... yes |
| libssh .............. yes |
| libssl .............. yes |
| libVNCServer ........ yes |
| libvorbis ........... yes |
| libpulse ............ 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 boot. 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> |
| <important> |
| <para>SSH support requires that fonts are installed in order to function - output |
| from the terminal cannot be rendered otherwise. Support for SSH will build just |
| fine if fonts are not installed, but it will fail to connect when used:</para> |
| <informalexample> |
| <screen>Aug 23 14:09:45 my-server guacd[5606]: Unable to get font "monospace"</screen> |
| </informalexample> |
| <para>If SSH connections are not working and you see such a message in syslog, |
| install fonts and try again.</para> |
| </important> |
| <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.3.tar.gz</userinput> |
| <prompt>$</prompt> <userinput>cd guacamole-client-0.8.3/</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 Guacamole team's git repository on GitHub:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <userinput>git clone <uri>git://github.com/glyptodon/guacamole-client.git</uri></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.3.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 servlet 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><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><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/ |
| </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 noticeable 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><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><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/ |
| </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><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> |
| </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> |