ra6r2015 Chapter 2 nstaing Guacamole
Chapter 2. Installing Guacamole
Guacamole is separated into two pieces: guacamole-server, which provides the guacd proxy and related
libraries, and guacamole-client, which provides the client to be served by your servlet container, usually
Tomeat
guacamole-client is available in binary form, but guacamole-server must be built from source. Don't be
discouraged: building the components of Guacamole from source is not as difficult as it sounds, and the build
process is automated. You just need to be sure you have the necessary tools installed ahead of time. With
the necessary dependencies in place, building Guacamole only takes a few minutes.
Building guacamole-server
guacamole-server contains all the native, server-side components required by Guacamole to connect to
remote desktops. It provides a common C library, libguac, which all other native components depend on, as
well as separate libraries for each supported protocol, and guacd, the heart of Guacamole.
guacd is the proxy daemon that runs on your Guacamole server, accepts users’ connections that are
tunneled through the Guacamole web application, and then connects to remote desktops on their behalf.
Building guacd creates an executable called guacd which can be run manually or, if you wish, automatically
when your computer starts up.
To build guacamole-server, you will need aC compiler (such as gec) and the libraries that guacamole-server
depends on. Some dependencies are absolutely required, while others are optional. The presence of optional
dependencies enables additional features
Important
Many Linux distributions separate library packages into binary and "development" packages;
you will need to install the development packages. These will usually end in a "-dev" or "-
devel" suffix.
Required dependencies
In order to build guacamole-server, you will need Cairo, libpng, and the OSSP UUID library, These libraries
are strictly required in all cases - Guacamole cannot be built without them.
Library name Features
Cairo is used by libguac for graphics rendering. Guacamole cannot function
without Cairo installed.
Cairo
Debian / Ubuntu package libeairo2-dev
Fedora / CentOS / RHEL package cairo-devel
libpng is used by libguac to write PNG images, the core image type used by
the Guacamole protocol. Guacamole cannot function without libpng,
libpng
Debian / Ubuntu package libpng12-dev
Fedora / CentOS / RHEL package libpng-devel
Fipiiguac-dev.crgldcelgugfnstalling-guacamle him! wtra2015 Chapter 2. insta Guacamole
OSSP UUID is used by libguac to assign unique IDs to each Guacamole
connection, These unique IDs are the basis for connection sharing support.
OSSP UUID
—, Debian / Ubuntu package libossp-uuid-dev
Fedora / CentOS / RHEL package uuid-devel
Optional dependencies
The optional dependencies of Guacamole dictate which protocol support will be built, and whether additional
features of those protocols will be enabled.
Guacamole currently supports VNC, RDP, SSH, and telnet. Each protocol corresponds to a separate library
that will be built with guacamole-server if you have its corresponding optional dependencies.
VNC support depends on the libyncolient library, which is part of libVNCServer, RDP support depends on a
recent version of FreeROP - 1.0 or higher, SSH support depends on libssh2, and telnet depends on libtelnet
Pango, a font rendering and text layout library, is required for both SSH and telnet support.
Library name Features
FreeRDP is required for RDP support. If you do not wish to build RDP
support, this library is not needed
FreeRDP.
Debian / Ubuntu package libfreerdp-dev
Fedora / CentOS / RHEL package freerdp-devel
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
b library is not needed
ango
Debian / Ubuntu package libpango1.0-dev
Fedora / CentOS / RHEL package pango-devel
libssh2 is required for SSH support. If you do not wish to build SSH support,
this library is not needed.
libssh2
Debian / Ubuntu package libssh2-1-dev
Fedora / CentOS / RHEL package libssh2-devel
libteinet is required for telnet support. If you do not wish to build telnet
support, this library is not needed
libteinet Debian / Ubuntu package libteInet-dev
Fedora / CentOS / RHEL package libtelnet-devel
libVNCServer provides libyneclient, which is required for VNC support. If
you do not wish to build VNC support, this library is not needed
libVNCServer
Debian / Ubuntu package libvneserver-dev
Fipiiguac-dev crgldclgugfnstallng-guacamle him! amrapr2015 Chapter 2. instaling Guacamole
Fedora / CentOS / RHEL package libvncserver-devel
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.
PulseAudio
Debian / Ubuntu package libpulse-dev
Fedora / CentOS / RHEL package pulseaudio-libs-devel
OpenSSL provides support for SSL and TLS - two common encryption
schemes that make up the majority of encrypted web traffic.
If you have libss! 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
Openssl Public/private keys.
Without SSL support, there will be no option to encrypt communication to
guacd, and support for SSH cannot be built.
Debian / Ubuntu package libssi-dev
Fedora / CentOS / RHEL package openss!-devel
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.
ibvorbis Otherwise, sound will only be encoded as WAV (uncompressed), and will
only be available if your browser also supports WAV.
Debian / Ubuntu package libvorbis-dev
Fedora / CentOS / RHEL package libvorbis-devel
Obtaining the source code
You can obtain a copy of the quacamole-server source from the Guacamole project web site. These releases
are stable snapshots of the latest code which have undergone enough testing that the Guacamole team
considers them fit for public consumption. Source downloaded from the project web site will take the form of a
tar.gz archive which you can extract from the command line!
$ tar -x2f guacamole-server-0.9.6.tar.gz
$ cd guacamole-server-0.9.6/
$
Ifyou 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:
$ git clone git: //github.com/glyptodon/guacamole-server.git
Cloning into ‘guacamole-server'...
remote: Counting objects: 6769, done.
remote: Compressing objects: 100% (2244/2244), done.
Fipiiguac-devcrgldclgugfnstalling-guacamle him! anrae2015 Chapter 2. instaing Guacamole
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.
$
The build process
Once the guacamole-server source has been downloaded and extracted, you need to run configure. This is,
a shell script automatically generated by GNU Autotools, a popular build system used by the Guacamole
project for guacamole-server. Running configure will determine which libraries are available on your system
and will select the appropriate components for building depending on what you actually have installed
Important
Source downloaded directly from git will not contain this configure script, as autogenerated
code is not included in the project's repositories. If you downloaded the code from the
project's git repositories directly, you will need to generate configure manually:
$ cd guacamole-server/
$ autoreconf -fi
$
Doing this requires GNU Autotools to be installed.
Source archives downloaded from the project website contain the configure script and all
other necessary build files, and thus do not require GNU Autotools to be installed on the build
machine,
‘Once you run configure, you can see what a listing of what libraries were found and what it has determined
should be built:
$ ./configure --with-init-dir=/etc/init.d
checking for 2 8SD-compatible install... /usr/bin/install -
checking whether build environment is sane... yes
guacamole-server version 0.9.6
Library status:
freerdp .. + yes
pango .... + yes
LDSSh2 veeeeeeeeeeee Yes
libssl ... + yes
libtelnet + yes
LibVNCServer sos... yes
libvorbis + yes
libpulse . + yes
Protocol support:
Telnet .... yes
VNC ....2-. yes
Fipiiguac-devcrgldclgugfnstalling-guacamle him! anraer2015 Chapter 2 instaing Guacamole
Init scripts: /etc/init.d
Type "make" to compile guacamole-server.
$
The --with-init-dir=/etc/init .d shown above prepares the build to install a startup script for guacd into
the /etc/init.d directory, such that we can later easily configure guacd to start automatically on boot. If you
do not wish guacd to start automatically at boot, leave off the --with-init-dir option, If the directory
containing your distribution’s startup scripts differs from the common /etc/init.d, replace /etc/init.d
with the proper directory here. You may need to consult your distribution’s documentation, or do a little
digging in /etc, to determine the proper location.
Here, configure has found everything, including all optional libraries, and will build all protocol support, even
support for Ogg Vorbis sound in ROP. If you are missing some libraries, some of the "yes" answers above
will read "no". Ifa library which Is strictly required is missing, the script will fail outright, and you will need to
install the missing dependency. if, after running configure, you find support for something you wanted is
missing, simply install the corresponding dependencies and run configure again,
Important
SSH and telnet support both require that fonts are installed in order to function - output from
the terminal cannot be rendered otherwise. Support for SSH and telnet will build just fine if
fonts are not installed, but it will fail to connect when used
‘Aug 23 14:09:45 my-server guacd[ 5606]:
Unable to get font "monospace"
If SSH or telnet connections are not working and you see such a message in syslog, install
fonts and try again
Once configure is finished, just type "make", and it will guacamole-server will compile:
$ make
Making all in src/libguac
make[1]: Entering directory ~ /home/zhz/guacamole/guacamole-server/src/libguac’
make[1]: Leaving directory */home/zhz/guacanole/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’
$
Quite a bit of output will scroll up the screen as all the components are compiled
Installation
Once everything finishes, all you have left to do is type "make instal1" to install the components that were
built, and then "1dconfig” to update your system's cache of installed libraries’
# make install
Making install in sre/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
Jusr/local/lib
Fipiiguac-devcrgldclgugfnstalling-guacamle him! snraer2015 Chapter 2 instaing Guacamole
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 -W1,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 1d(1) and 1d.so(8) manual pages.
make[2]: Nothing to be done for “install-data-an'.
make[2]: Leaving directory * /home/zhz/guacamole/guacamole-server/sr¢/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-an’.
make[2]: Nothing to be done for “install-data-am'.
make[2]: Leaving directory */home/zhz/guacamole/guacamole-server’
make[1]: Leaving directory * /home/zhz/guacamole/guacamole-server'
# ldconfig
*
At this point, everything is installed, but guacd is not running. You will need to run guacd in order to use
Guacamole once the client components are installed as well
Beware that even after installing guacd and its startup script, you will likely still have to activate the service for
it to start automatically. Doing this varies by distribution, but each distribution will have documentation
describing how to do so.
guacamole-client
Important
Normally, you don't need to build guacamole-client, as it is written in Java and is cross-
platform. You can easily obtain the latest version of guacamole-client from the release
archives of the Guacamole project web site, including all supported extensions, without
having to build it yourself
if you do not want to build guacamole-client from source, just download guacamole.war from
the project web site, along with any desired extensions, and skip ahead to the section called
‘Deploying Guacamole"
guacamole-client contains all Java and JavaScript components of Guacamole (guacamole, guacamole-
common, guacamole-ext, and guacamole-common-js). These components ultimately make up the web
application that will serve the HTMLS Guacamole client to users that connect to your server. This web
application will then connect to guacd, part of guacamole-server, on behalf of connected users in order to
serve them any remote desktop they are authorized to access.
To compile guacamole-client, all you need is Apache Maven and a copy of the Java JDK. Most, if not all,
Linux distributions will provide packages for these.
You can obtain a copy of the guacamole-client source from the Guacamole project web site. These releases
are stable snapshots of the latest code which have undergone enough testing that the Guacamole team
considers them fit for public consumption. Source downloaded from the project web site will take the form of a
tar.gz archive which you can extract from the command line:
Fipiiguac-devcrgldclgugfnstalling-guacamle him! enra6r2015 Chapter 2 instaing Guacamole
$ tar -xzF guacamole-client-0.9.6.tar.gz
$ cd guacamole-client-0.9.6/
$
As with guacamole-server, if you want the absolute latest code, and don't care that the code hasn't been as
rigorously tested as the code in stable releases, you can also clone the Guacamole team’s git repository on
GitHub:
$ git clone git: //github.com/glyptodon/guacamole-client.git
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.
$
Unlike guacamole-server, even if you grab the code from the git repositories, you won't need to run anything
before building. There are no scripts that need to be generated before buliding - all Maven needs is the
pom.xml file provided with the source
To build guacamole-client, just run "nvn package”. This will invoke Maven to automatically build and package
all components, producing a single .war file, which contains the entire web application:
$ mvn package
[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 ......
[INFO] guacamole-ext ..
[INFO] guacamole-common-js .
[INFO] guacamole
[INFO] guacamole-client .
[INFO]
[INFO]
[INFO] BUILD SUCCESSFUL
(INFO)
[INFO] Total time: 13 seconds
[INFO] Finished at: Mon Jul @8 00:44:42 POT 2013
[INFO] Final Memory: 43M/354M
[INFO]
$
+ SUCCESS [4.4675]
SUCCESS [1.4795]
SUCCESS [3.6805]
SUCCESS [3.7295]
SUCCESS [2.0085]
Once the Guacamole web application is built, there will be a war file in the guacanole/target/ subdirectory
of the current directory (the directory you were in when you ran myn). This .war file contains the entirety of
the Guacamole web application, including all dependencies. Installing Guacamole means copying this .war
file into the directory required by your servlet container,
You will probably have to do this as the root user:
Fipiiguac-devcrgldclgugfnstalling-guacamle him! ™ra6r2015 Chapter 2 nstaing Guacamole
# cp guacamole/target/guacamole-0.9.6.war /var/lib/tomcat7/webapps/guacamole.war
#
The Guacamole web application also depends on a configuration file, guacamole. properties, to tell it the
type of authentication to use and how to connect to guacd. A functional example guacamole. properties is
contained in the doc/ subdirectory; you can simply copy this somewhere (like /etc/guacamole) and then
create a symbolic link to in a directory called . guacamole within the home directory of your serviet container.
The home directory of your servlet container will be the home directory of the user that the servlet container
runs as,
# mkdir /etc/guacamole
# mkdir /usr/share/tomcat7/ .guacamole
# cp guacamole/doc/example/guacamole.properties /etc/guacamole/guacamole.properties
# In =s /etc/guacamole/guacamole.properties /usr/share/tomcat7/ .guacamole/
#
You will need to edit guacamole. properties to be sure that all the settings are valid for your installation.
If you are using the default authentication method, you will also need to install the user-mapping.xm1 file.
This file describes the users that should be allowed to log into Guacamole, as well as their passwords, and all
corresponding remote desktop connections they should have access to.
‘An example user-mapping.xm1 file is provided in the doc/ subdirectory. You can simply copy this file to a
reasonable location (ike /etc/guacamole/user-mapping.xml) and then edit guacamole.properties to
specify the correct location of this file
You will need to edit user-mapping.xml to add and remove users, as well as to remove the “default” users
included as examples.
Deploying Guacamole
Typically, deploying Guacamole is a one-time process, and needs to be done only when Guacamole is
initially installed. If done correctly, future upgrades to Guacamole will be automatically deployed
There are two critical files involved in the deployment of Guacamole: guacamole.war, which is the file
containing the web application, and guacamole. properties, the main configuration file for Guacamole. The
recommend way to set up Guacamole involves placing these files in standard locations, and then creating
symbolic links to them so that Tomcat can find them.
Ultimately, the guacamole.war file, or a symbolic link to it, must be found by your servlet container within the
directory it uses for .war files, and the guacamole. properties file must be within the . guacamole directory
in the home directory of the user your servlet container runs as. Legacy installations will have
guacamole. properties placed in the classpath of the servlet container, but this is officially deprecated, and
will be unsupported in future releases.
We recommend placing guacamole. properties and any other configuration files in /etc/guacamole, and
guacamole.war in /var/1ib/guacamole. You will likely have to create each of these directories manually,
as root.
With these files in place, you can create symbolic links in the places Tomcat and Guacamole require them,
such that future upgrades will only involve placing the new files in standard locations. The standard locations
involved are the Tomeat "webapps" directory (below, /var/1ib/tomcat7/webapps, but your installation may
be different), and the ". guacamole" directory, which must be manually created within the Tomcat user's home
directory.
# An -s /var/1ib/guacamole/guacamole.war /var/Lib/tomcat7/webapps
# In -s /etc/guacamole/guacamole.properties /usr/share/tomcat7/.guacamole/
#
Fipiiguac-devcrgldclgugfnstalling-guacamle him! antra6r2015 Chapter 2 instaing Guacamole
If you are using a different servlet container or Tomcat is installed in a different location, you will need to
replace the directories above with the corresponding directories of your install.
Once Guacamole has been deployed, Tomcat must be restarted (as guacamole. properties will only be
read on servlet container start) and the guacd daemon must be started if it isn't running already. After
restarting Tomcat and starting guacd, Guacamole is successfully installed and running,
The command to restart Tomcat and guacd will vary by distribution. Typically, you can do this by running the
corresponding init scripts with the “restart” option
# /etc/init.d/tomcat7 restart
Stopping Tomcat... OK
Starting Tomcat... Ok
# /etc/init.d/guacd start
Starting guacd: SUCCESS
guacd[6229]: INFO: Guacamole proxy daemon (guacd) version 0.9.6 started
#
If you want Guacamole to start on boot, you will need to configure the Tomcat and guacd services to run
automatically, Your distribution will provide documentation for doing this.
What about WebSocket?
Guacamole will use WebSocket automatically if supported by the browser and your servlet container. In the
event that Guacamole cannot connect using WebSocket, it will immediately and transparently fall back to
using HTTP.
WebSocket is supported in Guacamole for Tomcat 7.0.37 or higher, Jetty 8 or higher, and any servlet
container supporting JSR 356, the standardized Java API for WebSocket.
Using Apache as a frontend (mod_proxy)
Many users end up serving Guacamole through Apache using mod_proxy, a module which allows Apache to
be used as a reverse proxy for other servers, such as a servlet container like Tomcat. The need to do this can
range from simply wanting to use port 80, to sharing an SSL certificate with your web server, to security and
load balancing.
By default, servlet containers like Tomcat listen on port 8080, which is not the standard HTTP port (port 80). If
you are using Linux (or another UNIX system), only the root user can run programs which listen on ports less
than 1024, including port 80, and reducing the number of programs that run with root privileges is always a
good idea.
Ifyou have an SSL certificate, it may make sense to use Apache for SSL processing and save Tomcat from
having to do this itself, which may not be as efficient. Again, this also makes sense from the perspective of
security, as it reduces the number of users that require read access to identifying certificates,
While load balancing won't be covered here, if you are expecting large numbers of users, balancing the load
on Tomcat across multiple Tomcat instances is a common solution.
Important
Beware that, like the rest of this manual, we assume here that you are using Tomcat. If you
are using a different serviet container, the same principles apply, and the Apache
configuration examples will stil be valid
Configuring Tomcat for HTTP
Tomcat is most likely already configured to listen for HTTP connections on port 8080 as this is the default, in
the case that the default HTTP connector has been disabled or removed, you need to add a connector entry
to conf/server. xml:
Fipiiguac-devcrgldclgugfnstalling-guacamle him! ontraer2015 Chapter 2 instaing Guacamole
L="HTTP/1.1"
20000"
Important
If you want to edit or add this connector just to change the port used by Tomcat to port 80,
you should consider simply proxying the original port through Apache instead. On Linux and
UNIX systems, a process must be running with root privileges to listen on any port under
1024, including port 80. Proxying Tomcat through Apache means Tomcat can run as a
reduced-privilege user, while Apache can bear the burden of root privileges. Further, as
‘Apache is a native application, it can make system calls to safely drop root privileges once
the port is open; a Java application like Tomcat cannot do this.
Be sure to specify the URTEncoding="UTF-8" attribute as above to ensure that connection names, user
names, etc. are properly received. If you will be creating connections that have Cyrillic, Chinese, Japanese,
etc. characters in the names or parameter values, this attribute is required
Configuring Apache and mod_proxy
Configuring Apache to proxy HTTP requests requires using the ProxyPass and ProxyPassReverse
directives, which are provided by the mod_proxy module. These directives describe how HTTP traffic should
be routed to the web server behind the proxy (Tomeat, in our case):
Order allow,deny
Allow from all
ProxyPass http://HOSTNAME: 8080/guacamole/ max=20 flushpackets=on
ProxyPassReverse http: //HOSTNAME: 8080/guacamole/
The most important thing in this entire section is the option flushpackets=on. Most proxies, including
mod_proxy, will buffer all data sent over the connection, waiting until the connection is closed before sending
that data to the client As Guacamole’s tunnel will stream data to the client over an open connection, buffering
this stream breaks Guacamole's communication:
If the option flushpackets=on is not specified, Guacamole will not work.
Disable logging of tunnel requests
The Guacamole HTTP tunnel works by transferring a continuous stream of data over multiple short-lived
streams, each associated with a separate HTTP request. Each HTTP request will be logged by Apache if you
do not explicitly disable logging of those requests.
Apache provides a means of matching URL patterns and setting environment variables based on whether the
URL matches. Logging can then be restricted to requests which lack this environment variable:
SetEnvIf Request_URI "*/guacamole/tunnel" dontlog
Customog /var/Log/apache2/guac. Log common env=!dontlog
‘There is little value in a log file filled with identical tunnel requests.
Note that if you are serving Guacamole under a path different from /guacamole/, you will need to change the
value of Request_URI above accordingly.
Proxying under a different path
Fipiiguac-devcrgldclgugfnstalling-guacamle him! 1011rae2015 Chapter 2. instaing Guacamole
If you wish to serve Guacamole through Apache under a different path than it is served under Tomcat, the
configuration required for Apache will be slightly different than the examples above due to cookies.
‘When a user logs in to Guacamole, a new session is created, and that session is associated with a cookie
sent to the user after they successfully log in. This cookie is specific to the absolute path of the web
application (/guacamole). If the path being used for Guacamole under Apache differs from that used by
Tomeat, the path in the cookie needs to be modified. Thankfully, mod_proxy has a directive for this:
ProxyPassReverseCookiePath
Order allow, deny
Allow from all
ProxyPass http: //HOSTNAME:8080/guacamole/ max=20 flushpackets-on
ProxyPassReverse http: //HOSTNAME : 8080/guacamole/
ProxyPassReverseCookiePath /guacamole/ /new-path/
The configuration shown above is similar to the configuration shown for generic HTTP proxying, except that
the additional ProxyPassReverseCookiePath directive is given, instructing mod_proxy to update the cookie
path, changing /guacamole/ to /new-path/, the same path specified when the location was declared.
ipuiguse-dev crgldocgugtnstallng-guacamole him! wn