| <?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>0.9.14</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 0.9.14. 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/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> |