src/gug.xml

<?xml version="1.0" encoding="UTF-8"?>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
    xmlns:xi="http://www.w3.org/2001/XInclude">
    <info>
        <title>Guacamole Manual</title>
        <edition>1.1.0</edition>
        <legalnotice>
            <para>Licensed to the Apache Software Foundation (ASF) under one or more contributor
                license agreements. See the <link xmlns:xlink="http://www.w3.org/1999/xlink"
                    xlink:href="https://raw.githubusercontent.com/apache/guacamole-manual/master/NOTICE"
                        ><filename>NOTICE</filename></link> file distributed with this work for
                additional information regarding copyright ownership. The ASF licenses this file to
                you under the Apache License, Version 2.0 (the "License"); you may not use this file
                except in compliance with the License. You may obtain a copy of the License
                at:</para>
            <para><link xmlns:xlink="http://www.w3.org/1999/xlink"
                    xlink:href="http://www.apache.org/licenses/LICENSE-2.0"
                        ><uri>http://www.apache.org/licenses/LICENSE-2.0</uri></link></para>
            <para>Unless required by applicable law or agreed to in writing, software distributed
                under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
                CONDITIONS OF ANY KIND, either express or implied. See the License for the specific
                language governing permissions and limitations under the License.</para>
        </legalnotice>
    </info>
    <preface xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="preface">
        <title>Introduction</title>
        <para>This book is the official Apache Guacamole manual, written by the upstream developers
            of the Guacamole project. It is also the official general documentation, and an online
            version at <link xlink:href="http://guacamole.apache.org/"
                >http://guacamole.apache.org/</link>. It is a work in progress which will
            be continuously updated as Guacamole changes with each release.</para>
        <para>We decided to maintain the documentation for Guacamole as a book, as there is an awful
            lot that can be done with the Guacamole web application, and even more that can be done
            with the API. This book is intended to explore the possibilities of Guacamole as an
            application, and to provide documentation necessary to install, maintain, and use
            Guacamole.</para>
        <para>For the sake of users and administrators, we have provided a high-level overview of
            Guacamole's architecture and technical design, as well as basic usage instructions and
            installation instructions for common platforms.</para>
        <para>For the sake of developers, we have provided a protocol reference and tutorials for
            common tasks (implementing protocol support, integrating Guacamole into your own
            application, etc.) to give a good starting point beyond simply looking at the Guacamole
            codebase.</para>
        <para>This particular edition of the <citetitle>Guacamole Manual</citetitle> covers
            Guacamole version 1.1.0. New releases which create new features or break
            compatibility will result in new editions of the user's guide, as will any necessary
            corrections. As the official documentation for the project, this book will always be
            freely available in its entirety online.</para>
        <indexterm>
            <primary>Guacamole</primary>
            <secondary>history</secondary>
        </indexterm>
        <simplesect xml:id="what-is-guac">
            <title>What is Guacamole?</title>
            <indexterm>
                <primary>Guacamole</primary>
                <secondary>definition</secondary>
            </indexterm>
            <para>Guacamole is an HTML5 web application that provides access to desktop environments
                using remote desktop protocols (such as VNC or RDP). Guacamole is also the project
                that produces this web application, and provides an API that drives it. This API can
                be used to power other similar applications or services.</para>
            <para>"Guacamole" is most commonly used to refer to the web application produced by the
                Guacamole project using their API. This web application is part of a stack that
                provides a protocol-agnostic remote desktop gateway. Written in JavaScript and using
                only HTML5 and other standards, the client part of Guacamole requires nothing more
                than a modern web browser or web-enabled device when accessing any of the desktops
                served.</para>
            <indexterm>
                <primary>RealMint</primary>
            </indexterm>
            <para>Historically, Guacamole was an HTML5 VNC client, and before that, a JavaScript
                Telnet client called <application
                    xlink:href="http://sourceforge.net/projects/realmint">RealMint</application>
                ("RealMint" is an anagram for "terminal"), but this is no longer the case.
                Guacamole's architecture has grown to encompass remote desktop in general, and can
                be used as a gateway for any number of computers. Originally a proof-of-concept,
                Guacamole is now performant enough for daily use, and all Guacamole development is
                done over Guacamole.</para>
            <para>As an API, Guacamole provides a common and efficient means of streaming text data
                over a JavaScript-based tunnel using either HTTP or WebSocket, and a client
                implementation which supports the Guacamole protocol and renders the remote display
                when combined with a Guacamole protocol stream from the tunnel.</para>
            <para>It provides cross-browser mouse and keyboard events, an XML-driven on-screen
                keyboard, and synchronized nestable layers with hardware-accelerated compositing.
                Projects that wish to provide remote desktop support over HTML5 can leverage the
                years of research and development that went into Guacamole by incorporating the API
                into their application or service.</para>
        </simplesect>
        <simplesect xml:id="access-from-anywhere" xmlns:xl="http://www.w3.org/1999/xlink">
            <title>Why use Guacamole?</title>
            <para>The principle reason to use Guacamole is constant, world-wide, unfettered access
                to your computers.</para>
            <para>Guacamole allows access one or more desktops from anywhere remotely, without
                having to install a client, particularly when installing a client is not possible.
                By setting up a Guacamole server, you can provide access to any other computer on
                the network from virtually any other computer on the internet, anywhere in the
                world. Even mobile phones or tablets can be used, without having to install
                anything.</para>
            <para>As a true web application whose communication is over HTTP or HTTPS only,
                Guacamole allows you to access your machines from anywhere without violating the
                policy of your workplace, and without requiring the installation of special clients.
                The presence of a proxy or corporate firewall does not prevent Guacamole use.</para>
        </simplesect>
        <simplesect xml:id="access-from-anything" xmlns:xl="http://www.w3.org/1999/xlink">
            <title>Access your computers from any device</title>
            <para>As Guacamole requires only a reasonably-fast, standards-compliant browser,
                Guacamole will run on many devices, including mobile phones and tablets.</para>
            <para>Guacamole is specifically designed to not care whether you have a mouse, keyboard,
                touchscreen, or any combination of those.</para>
            <para>One of the major design philosophies behind Guacamole is that it should never
                assume you have a particular device (ie: a mobile phone) just because your browser
                has or is missing a specific feature (ie: touch events or a smallish screen).
                Guacamole's codebase provides support for both mouse and touch events
                simultaneously, without choosing one over the other, while the interface is intended
                to be usable regardless of screen size.</para>
            <para>Barring bugs, you should be able to use Guacamole on just about any modern device
                with a web browser.</para>
        </simplesect>
        <simplesect xml:id="non-physical-computer" xmlns:xl="http://www.w3.org/1999/xlink">
            <title>Keep a computer in the "cloud"</title>
            <para>Ignoring the buzzword, it's often useful to have a computer that has no dedicated
                physical hardware, where its processing and storage power are handled transparently
                by redundant systems in some remote datacenter.</para>
            <para>Computers hosted on virtualized hardware are more resilient to failures, and with
                so many companies now offering on-demand computing resources, Guacamole is a perfect
                way to access several machines that are only accessible over the internet.</para>
            <para>In fact, all Guacamole development is done on computers like this. This is partly
                because we like the mobility, and partly because we want to ensure Guacamole is
                always performant enough for daily use.</para>
        </simplesect>
        <simplesect xml:id="group-access" xmlns:xl="http://www.w3.org/1999/xlink">
            <title>Provide easy access to a group</title>
            <para>Guacamole allows you to centralize access to a large group of machines, and
                specify on a per-user basis which machines are accessible. Rather than remember a
                list of machines and credentials, users need only log into a central server and
                click on one of the connections listed.</para>
            <para>If you have multiple computers which you would like to access remotely, or you are
                part of a group where each person has a set of machines that they need remote access
                to, Guacamole is a good way to provide that access while also ensuring that access
                is available from anywhere.</para>
        </simplesect>
        <simplesect xml:id="adding-remote-access" xmlns:xl="http://www.w3.org/1999/xlink">
            <title>Adding HTML5 remote access to your existing infrastructure</title>
            <para>As Guacamole is an API, not just a web application, the core components and
                libraries provided by the Guacamole project can be used to add HTML5 remote access
                features to an existing application. You need not use the main Guacamole web
                application; you can write (or integrate with) your own rather easily.</para>
            <para>If you host an on-demand computing service, adding HTML5-based remote access
                allows users of your service more broad access; users need nothing more than a web
                browser to see their computers' screens.</para>
        </simplesect>
    </preface>
    <part xml:id="users-guide">
        <title>User's Guide</title>
        <xi:include href="chapters/architecture.xml"/>
        <xi:include href="chapters/installing.xml"/>
        <xi:include href="chapters/docker.xml"/>
        <xi:include href="chapters/reverse-proxy.xml"/>
        <xi:include href="chapters/configuring.xml"/>
        <xi:include href="chapters/jdbc-auth.xml"/>
        <xi:include href="chapters/ldap-auth.xml"/>
        <xi:include href="chapters/duo-auth.xml"/>
        <xi:include href="chapters/totp-auth.xml"/>
        <xi:include href="chapters/header-auth.xml"/>
        <xi:include href="chapters/cas-auth.xml"/>
        <xi:include href="chapters/openid-auth.xml"/>
        <xi:include href="chapters/radius-auth.xml"/>
        <xi:include href="chapters/adhoc-connections.xml"/>
        <xi:include href="chapters/using.xml"/>
        <xi:include href="chapters/administration.xml"/>
        <xi:include href="chapters/troubleshooting.xml"/>
    </part>
    <part xml:id="developers-guide">
        <title>Developer's Guide</title>
        <xi:include href="chapters/protocol.xml"/>
        <xi:include href="chapters/libguac.xml"/>
        <xi:include href="chapters/guacamole-common.xml"/>
        <xi:include href="chapters/guacamole-common-js.xml"/>
        <xi:include href="chapters/guacamole-ext.xml"/>
        <xi:include href="chapters/adding-protocol.xml"/>
        <xi:include href="chapters/custom-auth.xml"/>
        <xi:include href="chapters/event-listeners.xml"/>
        <xi:include href="chapters/yourown.xml"/>
    </part>
    <part xml:id="appendices">
        <title>Appendices</title>
        <xi:include href="appendices/faq.xml"/>
        <xi:include href="references/protocol.xml"/>
        <index xml:id="book-index"/>
    </part>
</book>