
------------------------------------------------------------
 Contents
------------------------------------------------------------

 * About this README
 * What is Guacamole?
 * Installation within Servlet Container
 * Adding / Removing User Accounts
 * Permissions and Security
 * Reporting problems


------------------------------------------------------------
 About this README
------------------------------------------------------------

This README is intended to provide quick and to-the-point documentation for
installing and configuring Guacamole under Debian.

Distribution-independent configuration documentation is provided on the
Guacamole wiki:

    http://guac-dev.org/Configuring%20Guacamole


------------------------------------------------------------
 What is Guacamole?
------------------------------------------------------------

Guacamole is an HTML5 web application that provides access to your desktop
using remote desktop protocols. A centralized server acts as a tunnel and
proxy, allowing access to multiple desktops through a web browser; no plugins
needed. The client requires nothing more than a web browser supporting HTML5
and AJAX.


------------------------------------------------------------
 Installation within Servlet Container
------------------------------------------------------------

Although Guacamole documentation frequently references Tomcat, the application
is servlet container agnostic, and should work under any servlet container.
Your servlet container of choice will have documentation for web application
installation similar to what is provided here.

If you already use Tomcat, the easiest way to install Guacamole is to install
the guacamole-tomcat package. This package depends on Tomcat and Guacamole,
and will automatically create links and set permissions appropriately for a
Tomcat-based Guacamole installation.

For a complete installation, you must:

    1) Place a link to /etc/guacamole/guacamole.properties in your servlet
       container's classpath.

       In the case of Tomcat, this means creating a symbolic link in
       /usr/share/tomcat8/lib:

       ln -s /etc/guacamole/guacamole.properties /usr/share/tomcat8/lib/

       The guacamole.properties file is the core configuration file for the
       Guacamole web application. It tells Guacamole what authentication method
       to use, the location of the file containing user account definitions,
       and the host and port guacd will be listening on.

    2) Place a link to /var/lib/guacamole/guacamole.war in the directory
       your servlet container looks for .war files.

       In the case of Tomcat, this means creating a symbolic link in
       /var/lib/tomcat8/webapps:

       ln -s /var/lib/guacamole/guacamole.war /var/lib/tomcat8/webapps/

    3) Restart your servlet container.

       Most servlet containers will only search their classpaths once on
       startup, thus the servlet container will only pick up and read the
       guacamole.properties file if it is restarted. Even though many
       servlet containers (including Tomcat) will automatically deploy
       the web application once the .war file is in place, Guacamole will
       not be able to read its configuration until the servlet container
       is restarted.

       If you are using Tomcat, just use the init.d script to restart:

       /etc/init.d/tomcat8 restart

    4) Install VNC support and a VNC server.

       The Guacamole architecture supports multiple protocols, even though
       the only current stable support is for VNC.

       VNC support for Guacamole on Debian is provided by the
       libguac-client-vnc0 package. This package will be installed
       automatically if you install guacamole-tomcat.

       Once VNC support for Guacamole is installed, you need to install and
       configure a VNC server. The server from RealVNC (available in the
       vnc4server package) is a good choice and performs well.

    5) Configure user accounts.

       Once Guacamole is installed and you visit it in a browser, you will be
       given a login page. Logging in on this page will connect you to
       whichever server is configured for that user in user-mapping.xml.

       See the section below entitled "Adding / Removing User Accounts" for
       instructions on configuring users.

    6) Set permissions such that your servlet container can read user
       account information, and other users cannot.

       The user-mapping.xml file will contain sensitive information including
       passwords and should be readable only by the user that your servlet 
       container runs as.

       See the section below entitled "Permissions and Security" for
       instructions on setting permissions properly.


------------------------------------------------------------
 Adding / Removing User Accounts
------------------------------------------------------------

User accounts correspond to available connections and not necessarily to
individual users of the system.

Examples of user accounts are available (commented out) in the provided
/etc/guacamole/user-mapping.xml file.

In general, a user account definition in the user-mapping.xml file will
look like this:

    <authorize username="SOMEUSER" password="SOMEPASSWORD">
        <protocol>vnc</protocol>
        <param name="hostname">localhost</param>
        <param name="port">5900</param>
        <param name="password">VNCPASS</param>
    </authorize>

The authorize tag defines a single authorized username/password combination and
associates it with specific connection parameters. It may contain a single
protocol tag, which defines which protocol will be used, and any number of
param tags, which define protocol-specific parameters (such as hostname, port,
and password).

The username and password attributes are required. If you wish to store your
password hashed rather than in plain-text, you can also specify encoding="md5"
and include your MD5-hashed password instead.

Included in the above example are three VNC-specific parameters. The VNC
support plugin accepts other parameters, not all of which are required:

    hostname
        The hostname or IP of the VNC server you wish to connect to.
        This parameter is REQUIRED.

    port
        The port of the VNC server you wish to connect to.
        This parameter is REQUIRED.

    password
        The password required, if any, when connecting to the VNC server. Note
        that unlike the passwords specified in authorize tags, this password
        must be stored unhashed, as it needs to be sent to the VNC server.

    read-only
        Set to true if you wish to disallow input and clipboard functions, and
        force server-side rendering of the mouse cursor. This is distinct from
        the "view-only" feature provided by some VNC servers and will work even
        if your VNC server does not provide a "view-only" mode.


------------------------------------------------------------
 Permissions and Security
------------------------------------------------------------

As VNC and user account passwords may be stored in user-mapping.xml, only the
servlet container user should have permission to read this file, and only root
should have permission to write to it.

The Debian "guacamole" package will set permissions appropriately, with this
file owned by the user root and the group guacamole-web, where the user has
read/write permissions, guacamole-web has read permissions, and no other user
can read or write. This means you should add the user that your servlet
container runs as to the group guacamole-web.

If you are using Tomcat, installed via the Debian tomcat8 package, the
use you need to add to guacamole-web is tomcat8. If you installed the
guacamole-tomcat package, this has been done for you.


------------------------------------------------------------
 Reporting problems
------------------------------------------------------------

Please report any bugs encountered by opening a new ticket at the Trac system
hosted at:
    
    http://sourceforge.net/apps/trac/guacamole/

