src/gug.xml - guacamole-manual - Git at Google

 <?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.0</edition>
         <author>
             <personname><firstname>Michael</firstname>
                 <surname>Jumper</surname></personname>
             <email>mike.jumper@guac-dev.org</email>
         </author>
     </info>
     <preface xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="preface">
         <title>Introduction</title>
         <para>This book is the official 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://guac-dev.org/">http://guac-dev.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.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>
             <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 (which need not use 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/configuring.xml"/>
         <xi:include href="chapters/mysql-auth.xml"/>
         <xi:include href="chapters/ldap-auth.xml"/>
         <xi:include href="chapters/noauth.xml"/>
         <xi:include href="chapters/using.xml"/>
         <xi:include href="chapters/troubleshooting.xml"/>
         <!--<xi:include href="chapters/home-desktop.xml"/>-->
         <!--<xi:include href="chapters/ec2.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/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"></index>
     </part>

 </book>
	<?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.0</edition>
	<author>
	<personname><firstname>Michael</firstname>
	<surname>Jumper</surname></personname>
	<email>mike.jumper@guac-dev.org</email>
	</author>
	</info>
	<preface xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="preface">
	<title>Introduction</title>
	<para>This book is the official 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://guac-dev.org/">http://guac-dev.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.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>
	<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 (which need not use 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/configuring.xml"/>
	<xi:include href="chapters/mysql-auth.xml"/>
	<xi:include href="chapters/ldap-auth.xml"/>
	<xi:include href="chapters/noauth.xml"/>
	<xi:include href="chapters/using.xml"/>
	<xi:include href="chapters/troubleshooting.xml"/>
	<!--<xi:include href="chapters/home-desktop.xml"/>-->
	<!--<xi:include href="chapters/ec2.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/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"></index>
	</part>

	</book>