| <?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 natively</title> |
| <indexterm> |
| <primary>installing</primary> |
| </indexterm> |
| <indexterm> |
| <primary>compiling</primary> |
| <secondary>Guacamole</secondary> |
| </indexterm> |
| <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, usually <link xl:href="http://tomcat.apache.org/">Tomcat</link>.</para> |
| <para><package>guacamole-client</package> is available in binary form, but |
| <package>guacamole-server</package> must be built from source. Don't be discouraged: |
| building the components of Guacamole from source is <emphasis>not</emphasis> as difficult as |
| it sounds, and the build process is automated. You just need to be sure you have the |
| necessary tools installed ahead of time. With the necessary dependencies in place, building |
| Guacamole only takes a few minutes.</para> |
| <section xml:id="building-guacamole-server"> |
| <title>Building <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>telnet 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>libguac-client-telnet</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 <package>guacd</package>, the heart |
| of Guacamole.</para> |
| <para><package>guacd</package> is the proxy daemon that runs on your Guacamole server, |
| accepts users' connections that are tunneled through the Guacamole web application, and |
| then connects to remote desktops on their behalf. Building <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>To build <package>guacamole-server</package>, you will need a C compiler (such as |
| <package>gcc</package>) and the libraries that <package>guacamole-server</package> |
| depends on. Some dependencies are absolutely required, while others are optional. The |
| presence of optional dependencies enables additional features.</para> |
| <important> |
| <para>Many Linux distributions separate library packages into binary and "development" |
| packages; <emphasis>you will need to install the development packages</emphasis>. |
| These will usually end in a "-dev" or "-devel" suffix.</para> |
| </important> |
| <section xml:id="required-dependencies"> |
| <title>Required dependencies</title> |
| <para>In order to build <package>guacamole-server</package>, you will need |
| <package>Cairo</package>, <package>libjpeg</package>, <package>libpng</package>, |
| and the OSSP UUID library. These libraries are strictly required <emphasis>in all |
| cases</emphasis> - Guacamole cannot be built without them.</para> |
| <informaltable frame="all"> |
| <tgroup cols="2"> |
| <colspec colname="lib-name" colnum="1" colwidth="1*"/> |
| <colspec colname="features" colnum="2" colwidth="3.8*"/> |
| <thead> |
| <row> |
| <entry>Library name</entry> |
| <entry>Features</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><link xl:href="http://cairographics.org/">Cairo</link></entry> |
| <entry> |
| <para>Cairo is used by libguac for graphics rendering. Guacamole |
| cannot function without Cairo installed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libcairo2-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>cairo-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://libjpeg-turbo.virtualgl.org/" |
| >libjpeg-turbo</link></entry> |
| <entry> |
| <para>libjpeg-turbo is used by libguac to provide JPEG support. |
| Guacamole will not build without this library present:</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian package</entry> |
| <entry><package>libjpeg62-turbo-dev</package></entry> |
| </row> |
| <row> |
| <entry>Ubuntu package</entry> |
| <entry><package>libjpeg-turbo8-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libjpeg-turbo-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| <para>If libjpeg-turbo is unavailable on your platform, and you do |
| not wish to build it from source, <link |
| xl:href="http://www.ijg.org/">libjpeg</link> will work as |
| well, though it will not be quite as fast:</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libjpeg62-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libjpeg-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://www.libpng.org/pub/png/libpng.html" |
| >libpng</link></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> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libpng12-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libpng-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="https://www.gnu.org/software/libtool/manual/libtool.html" |
| >libtool</link></entry> |
| <entry> |
| <para>libtool is used during the build process. |
| libtool creates compiled libraries needed for Guacamole.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libtool-bin</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libtool</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://www.ossp.org/pkg/lib/uuid/">OSSP |
| UUID</link></entry> |
| <entry> |
| <para>OSSP UUID is used by libguac to assign unique IDs to each |
| Guacamole connection. These unique IDs are the basis for |
| connection sharing support.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libossp-uuid-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>uuid-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </section> |
| <section xml:id="optional-dependencies"> |
| <title>Optional dependencies</title> |
| <para>The optional dependencies of Guacamole dictate which parts of |
| <package>guacamole-server</package> will be built. This includes the support for |
| various remote desktop protocols, as well as any additional features of those |
| protocols:</para> |
| <itemizedlist> |
| <listitem> |
| <para>VNC support depends on the <package>libvncclient</package> library, which |
| is part of <package>libVNCServer</package>.</para> |
| </listitem> |
| <listitem> |
| <para>RDP support depends on a recent version of <package>FreeRDP</package> (1.0 |
| or higher, but please <link |
| xl:href="https://github.com/FreeRDP/FreeRDP/issues/2839">not a |
| non-release version from git</link>).</para> |
| </listitem> |
| <listitem> |
| <para>SSH support depends on <package>libssh2</package>, <package>OpenSSL</package> |
| and <package>Pango</package> (a font rendering and text layout library, used |
| by Guacamole's built-in terminal emulator).</para> |
| </listitem> |
| <listitem> |
| <para>Telnet depends on <package>libtelnet</package> and |
| <package>Pango</package>.</para> |
| </listitem> |
| </itemizedlist> |
| <para>The <command>guacenc</command> utility, provided by |
| <package>guacamole-server</package> to translate screen recordings into video, |
| depends on FFmpeg, and will only be built if at least the |
| <package>libavcodec</package>, <package>libavutil</package>, and |
| <package>libswscale</package> libraries provided by FFmpeg are installed.</para> |
| <important> |
| <para>If you lack these dependencies, <emphasis>then the features or protocols which |
| depend on them will not be enabled</emphasis>. Please read this section |
| carefully before deciding not to install an optional dependency.</para> |
| </important> |
| <informaltable frame="all"> |
| <tgroup cols="2"> |
| <colspec colname="lib-name" colnum="1" colwidth="1*"/> |
| <colspec colname="features" colnum="2" colwidth="3.8*"/> |
| <thead> |
| <row> |
| <entry>Library name</entry> |
| <entry>Features</entry> |
| </row> |
| </thead> |
| <tbody> |
| <row> |
| <entry><link xl:href="https://ffmpeg.org/">FFmpeg</link></entry> |
| <entry> |
| <para>The <package>libavcodec</package>, |
| <package>libavutil</package>, and |
| <package>libswscale</package> libraries provided by FFmpeg |
| are used by <command>guacenc</command> to encode video streams |
| when translating recordings of Guacamole sessions. Without |
| FFmpeg, the <command>guacenc</command> utility will simply not |
| be built.</para> |
| <para>If you do not wish to make graphical recordings of Guacamole |
| sessions, or do not wish to translate such recordings into |
| video, then FFmpeg is not needed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry> |
| <para><package>libavcodec-dev</package>, |
| <package>libavutil-dev</package>, |
| <package>libswscale-dev</package></para> |
| </entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>ffmpeg-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://www.freerdp.com/">FreeRDP</link></entry> |
| <entry> |
| <para>FreeRDP is required for RDP support. If you do not wish to |
| build RDP support, this library is not needed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libfreerdp-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>freerdp-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://www.pango.org/">Pango</link></entry> |
| <entry> |
| <para>Pango is a text layout library which Guacamole's SSH and |
| telnet support uses to render text. If you do not wish to build |
| SSH or telnet support, this library is not needed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libpango1.0-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>pango-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://www.libssh2.org/">libssh2</link></entry> |
| <entry> |
| <para>libssh2 is required for SSH support. If you do not wish to |
| build SSH support, this library is not needed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libssh2-1-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libssh2-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="https://github.com/seanmiddleditch/libtelnet" |
| >libtelnet</link></entry> |
| <entry> |
| <para>libtelnet is required for telnet support. If you do not wish |
| to build telnet support, this library is not needed.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libtelnet-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libtelnet-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://libvnc.github.io/" |
| >libVNCServer</link></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> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libvncserver-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libvncserver-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link |
| xl:href="http://www.freedesktop.org/wiki/Software/PulseAudio/" |
| >PulseAudio</link></entry> |
| <entry> |
| <para>PulseAudio provides libpulse, which is used by Guacamole's VNC |
| support to provide experimental audio support. If you are not |
| going to be using the experimental audio support for VNC, you do |
| not need this library.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libpulse-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>pulseaudio-libs-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="https://www.openssl.org/">OpenSSL</link></entry> |
| <entry> |
| <para>OpenSSL 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. This library is also required for SSH |
| support for the sake of manipulating public/private keys.</para> |
| <para>Without SSL support, there will be no option to encrypt |
| communication to guacd, and support for SSH cannot be |
| built.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libssl-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>openssl-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="http://xiph.org/vorbis/">libvorbis</link></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> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libvorbis-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libvorbis-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| <row> |
| <entry><link xl:href="https://developers.google.com/speed/webp/" |
| >libwebp</link></entry> |
| <entry> |
| <para>libwebp is used by libguac to write WebP images. Though |
| support for WebP is not mandated by the Guacamole protocol, WebP |
| images will be used if supported by both the browser and by |
| libguac.</para> |
| <para>Lacking WebP support, Guacamole will simply use JPEG in cases |
| that it would have preferred WebP.</para> |
| <informaltable frame="none" rowheader="firstcol"> |
| <tgroup cols="2"> |
| <colspec colname="c1" colnum="1" colwidth="1.0*"/> |
| <colspec colname="c2" colnum="2" colwidth="1.0*"/> |
| <tbody> |
| <row> |
| <entry>Debian / Ubuntu package</entry> |
| <entry><package>libwebp-dev</package></entry> |
| </row> |
| <row> |
| <entry>Fedora / CentOS / RHEL package</entry> |
| <entry><package>libwebp-devel</package></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </informaltable> |
| </section> |
| <section xml:id="guacamole-server-source"> |
| <title>Obtaining the source code</title> |
| <para>You can obtain a copy of the <package>guacamole-server</package> source from the |
| Guacamole project web site. These releases are stable snapshots of the latest code |
| which have undergone enough testing that the Guacamole team considers them fit for |
| public consumption. Source downloaded from the project web site will take the form |
| of a <filename>.tar.gz</filename> archive which you can extract from the command |
| line:</para> |
| <informalexample> |
| <screen><prompt>$</prompt> <userinput>tar -xzf guacamole-server-0.9.14.tar.gz</userinput> |
| <prompt>$</prompt> <userinput>cd guacamole-server-0.9.14/</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/apache/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> |
| </section> |
| <section xml:id="guacamole-server-build-process"> |
| <title>The build process</title> |
| <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.9.14 |
| ------------------------------------------------ |
| |
| Library status: |
| |
| freerdp ............. yes |
| pango ............... yes |
| libavcodec .......... yes |
| libavutil ........... yes |
| libssh2 ............. yes |
| libssl .............. yes |
| libswscale .......... yes |
| libtelnet ........... yes |
| libVNCServer ........ yes |
| libvorbis ........... yes |
| libpulse ............ yes |
| libwebp ............. yes |
| |
| Protocol support: |
| |
| RDP ....... yes |
| SSH ....... yes |
| Telnet .... yes |
| VNC ....... yes |
| |
| Services / tools: |
| |
| guacd ...... yes |
| guacenc .... yes |
| guaclog .... 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 and telnet support both require that fonts are installed in order to |
| function - output from the terminal cannot be rendered otherwise. Support for |
| SSH and telnet will build just fine if fonts are not installed, but it will fail |
| to connect when used:</para> |
| <informalexample> |
| <screen>Aug 23 14:09:45 my-server guacd[5606]: Unable to get font "monospace"</screen> |
| </informalexample> |
| <para>If SSH or telnet 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.</para> |
| </section> |
| <section xml:id="guacamole-server-installation"> |
| <title>Installation</title> |
| <para>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> |
| <section xml:id="building-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> |
| <important> |
| <para>Normally, you don't need to build <package>guacamole-client</package>, as it is |
| written in Java and is cross-platform. You can easily obtain the latest version of |
| <package>guacamole-client</package> from the release archives of the Guacamole |
| project web site, including all supported extensions, without having to build it |
| yourself.</para> |
| <para>If you do not want to build guacamole-client from source, just download |
| <filename>guacamole.war</filename> from the project web site, along with any |
| desired extensions, and skip ahead to <xref linkend="deploying-guacamole"/>.</para> |
| </important> |
| <para><package>guacamole-client</package> contains all Java and JavaScript 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 then 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>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. 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.9.14.tar.gz</userinput> |
| <prompt>$</prompt> <userinput>cd guacamole-client-0.9.14/</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/apache/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] ------------------------------------------------------------------------ |
| [INFO] Reactor Build Order: |
| [INFO] |
| [INFO] guacamole-common |
| [INFO] guacamole-ext |
| [INFO] guacamole-common-js |
| [INFO] guacamole |
| [INFO] guacamole-auth-jdbc |
| [INFO] guacamole-auth-jdbc-base |
| [INFO] guacamole-auth-jdbc-mysql |
| [INFO] guacamole-auth-jdbc-postgresql |
| [INFO] guacamole-auth-ldap |
| [INFO] guacamole-auth-noauth |
| [INFO] guacamole-client |
| ... |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] Reactor Summary: |
| [INFO] |
| [INFO] guacamole-common ................................... SUCCESS [ 7.566 s] |
| [INFO] guacamole-ext ...................................... SUCCESS [ 5.594 s] |
| [INFO] guacamole-common-js ................................ SUCCESS [ 1.249 s] |
| [INFO] guacamole .......................................... SUCCESS [ 8.474 s] |
| [INFO] guacamole-auth-jdbc ................................ SUCCESS [ 0.592 s] |
| [INFO] guacamole-auth-jdbc-base ........................... SUCCESS [ 2.548 s] |
| [INFO] guacamole-auth-jdbc-mysql .......................... SUCCESS [ 2.557 s] |
| [INFO] guacamole-auth-jdbc-postgresql ..................... SUCCESS [ 1.990 s] |
| [INFO] guacamole-auth-ldap ................................ SUCCESS [ 1.314 s] |
| [INFO] guacamole-auth-noauth .............................. SUCCESS [ 0.961 s] |
| [INFO] guacamole-client ................................... SUCCESS [ 1.721 s] |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] BUILD SUCCESS |
| [INFO] ------------------------------------------------------------------------ |
| [INFO] Total time: 34.701 s |
| [INFO] Finished at: 2015-06-08T17:03:15-07:00 |
| [INFO] Final Memory: 34M/340M |
| [INFO] ------------------------------------------------------------------------</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>), ready to be deployed |
| to a servlet container like Tomcat.</para> |
| </section> |
| <section xml:id="deploying-guacamole"> |
| <title>Deploying Guacamole</title> |
| <indexterm> |
| <primary>deploying</primary> |
| </indexterm> |
| <para>The web application portion of Guacamole is packaged as a fully self-contained |
| <filename>.war</filename> file. If you downloaded Guacamole from the main project |
| web site, this file will be called <filename>guacamole.war</filename>. Deploying this |
| involves copying the file into the directory your servlet container uses for |
| <filename>.war</filename> files. In the case of Tomcat, this will be |
| <filename><replaceable>CATALINA_HOME</replaceable>/webapps/</filename>. The |
| location of <envar>CATALINA_HOME</envar> will vary by how Tomcat was installed, but is |
| commonly <filename>/var/lib/tomcat</filename>, <filename>/var/lib/tomcat7</filename>, or |
| similar:</para> |
| <informalexample> |
| <screen><prompt>#</prompt> <userinput>cp guacamole.war <replaceable>/var/lib/tomcat</replaceable>/webapps</userinput> |
| <prompt>#</prompt></screen> |
| </informalexample> |
| <para>If you have built guacamole-client from source, the required <filename>.war</filename> |
| file will be within the <filename>guacamole/target/</filename> directory and will |
| contain an additional version suffix. As Tomcat will determine the location of the web |
| application from the name of the <filename>.war</filename> file, you will likely want to |
| rename this to simply <filename>guacamole.war</filename> while copying:</para> |
| <informalexample> |
| <screen><prompt>#</prompt> <userinput>cp guacamole/target/guacamole-0.9.14.war <replaceable>/var/lib/tomcat/webapps</replaceable>/guacamole.war</userinput> |
| <prompt>#</prompt></screen> |
| </informalexample> |
| <para>Again, if you are using a different servlet container or if Tomcat is installed to a |
| different location, you will need to check the documentation of your servlet container, |
| distribution, or both to determine the proper location for deploying |
| <filename>.war</filename> files like <filename>guacamole.war</filename>.</para> |
| <para>Once the <filename>.war</filename> file is in place, you may need to restart Tomcat to |
| force Tomcat to deploy the new web application, and the <package>guacd</package> daemon |
| must be started if it isn't running already. The command to restart Tomcat and |
| <package>guacd</package> 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/tomcat7 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.9.14 started</computeroutput> |
| <prompt>#</prompt></screen> |
| </informalexample> |
| <important> |
| <para>If you want Guacamole to start on boot, you will need to configure the Tomcat and |
| <package>guacd</package> services to run automatically. Your distribution will |
| provide documentation for doing this.</para> |
| </important> |
| <para>After restarting Tomcat and starting <package>guacd</package>, Guacamole is |
| successfully installed, though it will not be fully running. In its current state, it is |
| completely unconfigured, and further steps are required to add at least one Guacamole |
| user and a few connections. This is covered in <xref |
| xmlns:xlink="http://www.w3.org/1999/xlink" linkend="configuring-guacamole"/>.</para> |
| <section> |
| <title>What about WebSocket?</title> |
| <indexterm> |
| <primary>WebSocket</primary> |
| </indexterm> |
| <para>Guacamole will use WebSocket automatically if supported by the browser and your |
| servlet container. In the event that Guacamole cannot connect using WebSocket, it |
| will immediately and transparently fall back to using HTTP.</para> |
| <para>WebSocket is supported in Guacamole for Tomcat 7.0.37 or higher, Jetty 8 or |
| higher, and any servlet container supporting JSR 356, the standardized Java API for |
| WebSocket.</para> |
| </section> |
| </section> |
| </chapter> |
