http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/duo-auth.html ---------------------------------------------------------------------- diff --git a/doc/0.9.11-incubating/gug/duo-auth.html b/doc/0.9.11-incubating/gug/duo-auth.html new file mode 100644 index 0000000..d85f9c7 --- /dev/null +++ b/doc/0.9.11-incubating/gug/duo-auth.html @@ -0,0 +1,101 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 8. Duo two-factor authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="ldap-auth.html" title="Chapter 7. LDAP authentication" /><link rel="next" href="noauth.html" title="Chapter 9. Disabling authentication" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> + </head><body> + <!-- CONTENT --> + + <div id="page"><div id="content"> + <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Duo two-factor authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ldap-auth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="noauth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="duo-auth"></a>Chapter 8. Duo two-factor authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="duo-auth.html#duo-architecture">How Duo works with Guacamole</a></span></dt><dt><span class="section"><a href="duo-auth.html#duo-downloading">Downloading the Duo extension</a></span></dt><dt><span class="section"><a href="duo-auth.html#installing-duo-auth">Installing Duo authentication</a ></span></dt><dd><dl><dt><span class="section"><a >href="duo-auth.html#idm140352911249696">Adding Guacamole to >Duo</a></span></dt><dt><span class="section"><a >href="duo-auth.html#guac-duo-config">Configuring Guacamole for >Duo</a></span></dt><dt><span class="section"><a >href="duo-auth.html#completing-duo-install">Completing the >installation</a></span></dt></dl></dd></dl></div><a id="idm140352911488960" >class="indexterm"></a><p>Guacamole supports Duo as a second authentication >factor, layered on top of any other + authentication extension, including those available from the main project website. The Duo + authentication extension allows users to be additionally verified against the Duo service + before the authentication process is allowed to succeed.</p><div class="important"><h3 class="title">Important</h3><p>This chapter involves modifying the contents of <code class="varname">GUACAMOLE_HOME</code> - + the Guacamole configuration directory. If you are unsure where + <code class="varname">GUACAMOLE_HOME</code> is located on your system, please consult <a class="xref" href="configuring-guacamole.html" title="Chapter 5. Configuring Guacamole">Chapter 5, <em>Configuring Guacamole</em></a> before proceeding.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="duo-architecture"></a>How Duo works with Guacamole</h2></div></div></div><p>Guacamole provides support for Duo as a second authentication factor. To make use of + the Duo authentication extension, some other authentication mechanism will need be + configured, as well. When a user attempts to log into Guacamole, other installed + authentication methods will be queried first:</p><div class="informalfigure"><div class="mediaobject"><img src="images/duo-auth-factor-1.png" width="180" /></div></div><p>Only after authentication has succeeded with one of those methods will Guacamole reach + out to Duo to obtain additional verification of user identity:</p><div class="informalfigure"><div class="mediaobject"><img src="images/duo-auth-factor-2.png" width="360" /></div></div><p>If both the initial authentication attempt and verification through Duo succeed, the + user will be allowed in. If either mechanism fails, access to Guacamole is + denied.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="duo-downloading"></a>Downloading the Duo extension</h2></div></div></div><p>The Duo authentication extension is available separately from the main + <code class="filename">guacamole.war</code>. The link for this and all other + officially-supported and compatible extensions for a particular version of Guacamole are + provided on the release notes for that version. You can find the release notes for + current versions of Guacamole here: <a class="link" href="http://guacamole.incubator.apache.org/releases/"; target="_top">http://guacamole.incubator.apache.org/releases/</a>.</p><p>The Duo authentication extension is packaged as a <code class="filename">.tar.gz</code> file + containing only the extension itself, + <code class="filename">guacamole-auth-duo-0.9.11-incubating.jar</code>, which must ultimately + be placed in <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-duo-auth"></a>Installing Duo authentication</h2></div></div></div><p>Guacamole extensions are self-contained <code class="filename">.jar</code> files which are + located within the <code class="filename">GUACAMOLE_HOME/extensions</code> directory. To install + the Duo authentication extension, you must:</p><div class="procedure"><ol class="procedure" type="1"><li class="step"><p>Create the <code class="filename">GUACAMOLE_HOME/extensions</code> directory, if it + does not already exist.</p></li><li class="step"><p>Copy <code class="filename">guacamole-auth-duo-0.9.11-incubating.jar</code> within + <code class="filename">GUACAMOLE_HOME/extensions</code>.</p></li><li class="step"><p>Configure Guacamole to use Duo authentication, as described below.</p></li></ol></div><div class="important"><h3 class="title">Important</h3><p>You will need to restart Guacamole by restarting your servlet container in order + to complete the installation. Doing this will disconnect all active users, so be + sure that it is safe to do so prior to attempting installation. If you do not + configure the Duo authentication properly, Guacamole will not start up again until + the configuration is fixed.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idm140352911249696"></a>Adding Guacamole to Duo</h3></div></div></div><p>Duo does not provide a specific integration option for Guacamole, but Guacamole's + Duo extension uses Duo's generic authentication API. To use Guacamole with Duo, you + will need to add it as a new "Auth API" application from within the "Applications" + tab of the admin panel of your Duo account:</p><div class="informalfigure"><div class="mediaobject"><img src="images/duo-add-guacamole.png" width="540" /></div></div><p>Within the settings of the newly-added application, rename the application to + something more representative than "Auth API". This application name is what will be + presented to your users when they are prompted by Duo for additional + authentication:</p><div class="informalfigure"><div class="mediaobject"><img src="images/duo-rename-guacamole.png" width="540" /></div></div><p>Once you've finished adding Guacamole as an "Auth API" application, the + configuration information required to configure Guacamole is listed within the + application's "Details" section. You will need to copy the integration key, secret + key, and API hostname - they will later be specified within + <code class="filename">guacamole.properties</code>:</p><div class="informalfigure"><div class="mediaobject"><img src="images/duo-copy-details.png" width="540" /></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guac-duo-config"></a>Configuring Guacamole for Duo</h3></div></div></div><a id="idm140352911076848" class="indexterm"></a><a id="idm140352911075024" class="indexterm"></a><p>The application-specific configuration information retrieved from Duo must be + added to <code class="filename">guacamole.properties</code> to describe how Guacamole should + connect to the Duo service:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">duo-api-hostname</span></span></dt><dd><p>The hostname of the Duo API endpoint to be used to verify user + identities. This will usually be in the form + "<code class="uri">api-<em class="replaceable"><code>XXXXXXXX</code></em>.duosecurity.com</code>", + where "<em class="replaceable"><code>XXXXXXXX</code></em>" is some arbitrary + alphanumeric value assigned by Duo. This value will have been generated + by Duo when you added Guacamole as an "Auth API" application, and can be + found within the application details in the "API hostname" field. + <span class="emphasis"><em>This value is required.</em></span></p></dd><dt><span class="term"><span class="property">duo-integration-key</span></span></dt><dd><p>The integration key provided for Guacamole by Duo. This value will + have been generated by Duo when you added Guacamole as an "Auth API" + application, and can be found within the application details in the + "Integration key" field. <span class="emphasis"><em>This value is required and must be + EXACTLY 20 characters.</em></span></p></dd><dt><span class="term"><span class="property">duo-secret-key</span></span></dt><dd><p>The secret key provided for Guacamole by Duo. This value will have + been generated by Duo when you added Guacamole as an "Auth API" + application, and can be found within the application details in the + "Secret key" field. <span class="emphasis"><em>This value is required and must be EXACTLY + 20 characters.</em></span></p></dd></dl></div><p>In addition to the above, <span class="emphasis"><em>you must also manually generate an + "application key"</em></span>. The application key is required by Duo's + authentication API, but is not provided by Duo. It is an arbitrary value meant to be + unique to each deployment of an application using their API.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="property">duo-application-key</span></span></dt><dd><p>An arbitrary, random key which you manually generated for Guacamole. + <span class="emphasis"><em>This value is required and must be AT LEAST 40 + characters.</em></span></p></dd></dl></div><p>The application key can be generated with any method as long as it is sufficiently + random. There exist utilities which will do this for you, like + <span class="command"><strong>pwgen</strong></span>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>pwgen 40 1</code></strong> +<code class="computeroutput">em1io4zievohneeseiwah0zie2raQuoo2ci5oBoo</code> +<code class="prompt">$</code></pre></div><p>Alternatively, one quick and fairly portable way to do this is to use the + <span class="command"><strong>dd</strong></span> utility to copy random bytes from the secure random device + <code class="filename">/dev/random</code>, sending the data through a cryptographic hash + tool with a sufficiently-long result, like <span class="command"><strong>sha256sum</strong></span>:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>dd if=/dev/random count=1 | sha256sum</code></strong> +<code class="computeroutput">5d16d6bb86da73e7d1abd3286b21dcf3b3e707532e64ceebc7a008350d0d485d -</code> +<code class="prompt">$</code></pre></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="completing-duo-install"></a>Completing the installation</h3></div></div></div><p>Guacamole will only reread <code class="filename">guacamole.properties</code> and load + newly-installed extensions during startup, so your servlet container will need to be + restarted before Duo authentication will take effect. Restart your servlet container + and give the new authentication a try.</p><p> + </p><div class="important"><h3 class="title">Important</h3><p>You only need to restart your servlet container. <span class="emphasis"><em>You do not need + to restart <span class="package">guacd</span></em></span>.</p><p><span class="package">guacd</span> is completely independent of the web application + and does not deal with <code class="filename">guacamole.properties</code> or the + authentication system in any way. Since you are already restarting the + servlet container, restarting <span class="package">guacd</span> as well technically + won't hurt anything, but doing so is completely pointless.</p></div><p> + </p><p>If Guacamole does not come back online after restarting your servlet container, + check the logs. Problems in the configuration of the Duo extension may prevent + Guacamole from starting up, and any such errors will be recorded in the logs of your + servlet container.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ldap-auth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="noauth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. LDAP authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 9. Disabling authentication</td></tr></table></div> + + </div></div> + <!-- Google Analytics --> + <script type="text/javascript"> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-75289145-1', 'auto'); + ga('send', 'pageview'); + </script> + </body></html> \ No newline at end of file
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/faq.html ---------------------------------------------------------------------- diff --git a/doc/0.9.11-incubating/gug/faq.html b/doc/0.9.11-incubating/gug/faq.html new file mode 100644 index 0000000..32866d7 --- /dev/null +++ b/doc/0.9.11-incubating/gug/faq.html @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Appendix A. FAQ</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="appendices.html" title="Part III. Appendices" /><link rel="prev" href="appendices.html" title="Part III. Appendices" /><link rel="next" href="protocol-reference.html" title="Appendix B. Guacamole protocol reference" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> + </head><body> + <!-- CONTENT --> + + <div id="page"><div id="content"> + <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Appendix A. FAQ</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendices.html">Prev</a> </td><th width="60%" align="center">Part III. Appendices</th><td width="20%" align="right"> <a accesskey="n" href="protocol-reference.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="appendix" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="faq"></a>Appendix A. FAQ</h2></div></div></div><div class="qandaset"><a id="idm140352909882320"></a><dl><dt>A.1. <a href="faq.html#idm140352909882032">Where does the name "Guacamole" come from? </a></dt><dt>A.2. <a href="faq.html#idm140352909752720">What does "clientless" mean? </a></dt><dt>A.3. <a href="faq.html#idm140352907862816">Does Guacamole use WebSocket? </a></dt><dt>A.4. <a href="faq.html#idm140352907833232">I have Tomcat (or some other servlet container) set up behind a p roxy (like + mod_proxy) and cannot connect to Guacamole. Why? How do I solve this? </a></dt><dt>A.5. <a href="faq.html#idm140352907885440">I connect to the internet through a web proxy, and cannot connect to + Guacamole. I cannot reconfigure the proxy. How do I solve this? </a></dt><dt>A.6. <a href="faq.html#idm140352907853840">Can I buy special licensing of the Guacamole code base, such that I can use it + in my own product, without providing the source to my users, without + contributing back, and without acknowledging the project? </a></dt><dt>A.7. <a href="faq.html#idm140352908241984">Can I pay for custom Guacamole work, or for help integrating Guacamole into my + product, if the open source nature and licenses are preserved?</a></dt><dt>A.8. <a href="faq.html#idm140352907616336">How can I contribute to the project? </a></dt><dt>A.9. <a href="faq.html#idm140352907857168">How can I become an official member of the project? </a></dt><dt>A.10. <a href="faq.html#idm140352907732384">I think I've found a bug. How do I report it? </a></dt><dt>A.11. <a href="faq.html#idm140352907320320">I need help! Where can I find some? </a></dt></dl><table border="0" style="width: 100%;"><colgroup><col align="left" width="1%" /><col /></colgroup><tbody><tr class="question"><td align="left" valign="top"><a id="idm140352909882032"></a><a id="idm140352909881744"></a><p><strong>A.1.</strong></p></td><td align="left" valign="top"><p>Where does the name "Guacamole" come from? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The name was chosen arbitrarily from a random utterance in a conversation wi th + a member of the project. </p><p>When the project reached the point where it was growing out of the + proof-of-concept phase, and needed a real home on the internet, we needed to + think of a name to register the project under. </p><p>Several acronyms were toyed with and discarded. We tried anagrams, but all + were too wordy and complex. We considered naming the project after a fish or an + animal, and after suggesting the guanaco, James Muehlner, a developer of the + project, suggested (randomly): "guacamole". </p><p>The name had a nice ring, we weren't embarrassed to use it, and it stuck. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352909752720"></a><a id="idm140352907628640"></a><p><strong>A.2.</strong></p></td><td align="left" valign="top"><p>What does "clientless" mean? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The term "clientless" means that no specific client is needed. A Guacamole + user needs only have an HTML5 web browser installed, which is exceedingly + common; virtually all modern computers and mobile devices have such a browser + installed by default. </p><p>In this sense, Guacamole is "clientless" in that it does not require any + additional software to be installed beyond what is considered standard for any + computer. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907862816"></a><a id="idm140352907862528"></a><p><strong>A.3.</strong></p></td><td align="left" valign="top"><p>Does Guacamole use WebSocket? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>Guacamole uses either WebSocket or plain HTTP, whichever is supported by both + the browser and your servlet container. If WebSocket cannot be used for any + reason, Guacamole will fall back to using HTTP.</p><p>Historically, Guacamole had no WebSocket support at all. This was due to a + lack of browser support and lack of a true standard. Overall, it didn't matter + as there really wasn't any need: the tunnel used by Guacamole when WebSocket is + not available is largely equivalent to WebSocket in terms of efficiency and + latency, and is more compatible with proxies and existing browsers.</p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907833232"></a><a id="idm140352907832944"></a><p><strong>A.4.</strong></p></td><td align="left" valign="top"><p>I have Tomcat (or some other servlet container) set up behind a proxy (like + mod_proxy) and cannot connect to Guacamole. Why? How do I solve this? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>You need to enable automatic flushing of the proxy's buffer as it receives + packets. </p><p>Most proxies, including mod_proxy, buffer data received from the server, and + will not flush this data in real-time. Each proxy has an option to force + flushing of each packet automatically, as this is necessary for streaming + applications like Guacamole, but this is usually not enabled by default. </p><p>Because Guacamole depends on streaming to function, a proxy configured to not + automatically flush packets will disrupt the stream to the point that the + connection seems unreasonably slow, or just fails to establish altogether. </p><p>In the case of mod_proxy, this option is <code class="code">flushpackets=on</code>. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907885440"></a><a id="idm140352907885152"></a><p><strong>A.5.</strong></p></td><td align="left" valign="top"><p>I connect to the internet through a web proxy, and cannot connect to + Guacamole. I cannot reconfigure the proxy. How do I solve this? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>You need to enable automatic flushing of your proxy's buffer to avoid + disrupting the stream used by Guacamole. </p><p>If you cannot change the settings of your proxy, using HTTPS instead of HTTP + should solve the problem. Proxies are required to stream HTTPS because of the + nature of SSL. Using HTTPS will allow Guacamole traffic to stream through + proxies unencumbered, even if you cannot access the proxy settings directly. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907853840"></a><a id="idm140352907853552"></a><p><strong>A.6.</strong></p></td><td align="left" valign="top"><p>Can I buy special licensing of the Guacamole code base, such that I can use it + in my own product, without providing the source to my users, without + contributing back, and without acknowledging the project? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>Usually, no. Previous requests for such licensing have been very one-sided and + there would be no direct or indirect benefit to the community and the project. + That said, we handle requests for licensing on a case-by-case basis. In general, + any special licensing has to somehow provide for the community and the + open-source project.</p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352908241984"></a><a id="idm140352908241696"></a><p><strong>A.7.</strong></p></td><td align="left" valign="top"><p>Can I pay for custom Guacamole work, or for help integrating Guacamole into my + product, if the open source nature and licenses are preserved?</p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>Yes. We love to be paid to work on Guacamole, especially if that work remains + open source. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907616336"></a><a id="idm140352907616048"></a><p><strong>A.8.</strong></p></td><td align="left" valign="top"><p>How can I contribute to the project? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>If you are a programmer and want to contribute code, Guacamole is open-source + and you are welcome to do so! Just send us your patches. There is no guarantee + that your patch will be added to the upstream source, and all changes are + carefully reviewed. </p><p>If you are not a programmer, but want to help out, feel free to look through + the documentation or try installing Guacamole and test it out. General editing, + documentation contributions, and testing are always helpful. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907857168"></a><a id="idm140352907856880"></a><p><strong>A.9.</strong></p></td><td align="left" valign="top"><p>How can I become an official member of the project? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The short answer is: "by being asked." </p><p>People are only added as official members of the Guacamole project after their + work has been proven. This usually means you will have contributed code in the + form of patches before, or we know you from extensive testing work, or you + frequently help with documentation, and we are impressed enough that we want you + as part of the project. </p><p>All that said, you do not need to be a member of the project to help out. Feel + free to contribute anything. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907732384"></a><a id="idm140352907732096"></a><p><strong>A.10.</strong></p></td><td align="left" valign="top"><p>I think I've found a bug. How do I report it? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>The project tracks in-progress tasks and bugs via the JIRA instance hosted by + the Apache Software Foundation:</p><p><a class="link" href="https://issues.apache.org/jira/browse/GUACAMOLE/"; target="_top"><code class="uri">https://issues.apache.org/jira/browse/GUACAMOLE/</code></a></p><p>All bugs should be reported there as new issues. This is also where you would + request a new feature. If the bug you found is security-related, we would prefer + to be contacted personally via email, such that the bug can be fixed before + becoming dangerously widely known. </p></td></tr><tr class="question"><td align="left" valign="top"><a id="idm140352907320320"></a><a id="idm140352907867856"></a><p><strong>A.11.</strong></p></td><td align="left" valign="top"><p>I need help! Where can I find some? </p></td></tr><tr class="answer"><td align="left" valign="top"></td><td align="left" valign="top"><p>If you would like help with Apache Guacamole, or wish to help others, we + highly recommend sending an email to the one of the projectâs <a class="link" href="http://guacamole.incubator.apache.org/support/#mailing-lists"; target="_top">mailing lists</a>. <span class="emphasis"><em>You will need to subscribe prior to sending + email to any list.</em></span> All mailing lists are actively filtered for + spam, and any email not originating from a subscriber will bounce.</p><p>There are two primary mailing lists:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><a class="link" href="http://mail-archives.apache.org/mod_mbox/incubator-guacamole-user/"; target="_top"><code class="email"><<a class="email" href="mailto:[email protected]";>[email protected]</a>></code></a></span></dt><dd><p>The user list is intended for general questions and discussions + which do not necessarily pertain to development. This list replaces + the old <a class="link" href="https://sourceforge.net/p/guacamole/discussion/"; target="_top">SourceForge forums</a> used by Guacamole prior to its + acceptance into the Apache Incubator.</p><p><span class="emphasis"><em>If you're not sure which mailing list to use, the user + list is probably the correct choice.</em></span></p></dd><dt><span class="term"><a class="link" href="http://mail-archives.apache.org/mod_mbox/incubator-guacamole-dev/"; target="_top"><code class="email"><<a class="email" href="mailto:[email protected]";>[email protected]</a>></code></a></span></dt><dd><p>The development list is for development-related discussion + involving people who are contributors to the Apache Guacamole + project (or who wish to become contributors).</p></dd></dl></div></td></tr></tbody></table></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendices.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendices.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="protocol-reference.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part III. Appendices </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Appendix B. Guacamole protocol reference</td></tr></table></div> + + </div></div> + <!-- Google Analytics --> + <script type="text/javascript"> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-75289145-1', 'auto'); + ga('send', 'pageview'); + </script> + </body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/guacamole-architecture.html ---------------------------------------------------------------------- diff --git a/doc/0.9.11-incubating/gug/guacamole-architecture.html b/doc/0.9.11-incubating/gug/guacamole-architecture.html new file mode 100644 index 0000000..a8e42d4 --- /dev/null +++ b/doc/0.9.11-incubating/gug/guacamole-architecture.html @@ -0,0 +1,83 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 1. Implementation and architecture</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="users-guide.html" title="Part I. User's Guide" /><link rel="next" href="installing-guacamole.html" title="Chapter 2. Installing Guacamole natively" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> + </head><body> + <!-- CONTENT --> + + <div id="page"><div id="content"> + <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 1. Implementation and architecture</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="users-guide.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="installing-guacamole.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-architecture"></a>Chapter 1. Implementation and architecture</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="guacamole-architecture.html#guacamole-protocol-architecture">The Guacamole protocol </a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#guacd">guacd</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#w eb-application">The web application</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#realmint">RealMint</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#vnc-client">VNC Client</a></span></dt><dt><span class="section"><a href="guacamole-architecture.html#gateway">Remote Desktop Gateway</a></span></dt></dl></div><a id="idm140352911492688" class="indexterm"></a><a id="idm140352911395680" class="indexterm"></a><a id="idm140352911394912" class="indexterm"></a><p>Guacamole is not a self-contained web application and is made up of many parts. The web + application is actually intended to be simple and minimal, with the majority of the + gruntwork performed by lower-level components.</p><div class="informalfigure"><div class="mediaobject"><img src="images/guac-arch.png" width="225" /></div></div><p>Users connect to a Guacamole server with their web browser. The Guacamole client, written + in JavaScript, is served to users by a webserver within the Guacamole server. Once loaded, + this client connects back to the server over HTTP using the Guacamole protocol.</p><p>The web application deployed to the Guacamole server reads the Guacamole protocol and + forwards it to guacd, the native Guacamole proxy. This proxy actually interprets the + contents of the Guacamole protocol, connecting to any number of remote desktop servers on + behalf of the user.</p><p>The Guacamole protocol combined with guacd provide protocol agnosticism: neither the + Guacamole client nor the web application need to be aware of what remote desktop protocol is + actually being used.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-protocol-architecture"></a>The Guacamole protocol </h2></div></div></div><a id="idm140352911483424" class="indexterm"></a><a id="idm140352911482656" class="indexterm"></a><p>The web application does not understand any remote desktop protocol at all. It does + not contain support for VNC or RDP or any other protocol supported by the Guacamole + stack. It actually only understands the Guacamole protocol, which is a protocol for + remote display rendering and event transport. While a protocol with those properties + would naturally have the same abilities as a remote desktop protocol, the design + principles behind a remote desktop protocol and the Guacamole protocol are different: + the Guacamole protocol is not intended to implement the features of a specific desktop + environment.</p><p>As a remote display and interaction protocol, Guacamole implements a superset of + existing remote desktop protocols. Adding support for a particular remote desktop + protocol (like RDP) to Guacamole thus involves writing a middle layer which "translates" + between the remote desktop protocol and the Guacamole protocol. Implementing such a + translation is no different than implementing any native client, except that this + particular implementation renders to a remote display rather than a local one.</p><p>The middle layer that handles this translation is guacd.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacd"></a>guacd</h2></div></div></div><a id="idm140352911478384" class="indexterm"></a><a id="idm140352911477616" class="indexterm"></a><p>guacd is the heart of Guacamole which dynamically loads support for remote desktop + protocols (called "client plugins") and connects them to remote desktops based on + instructions received from the web application.</p><p>guacd is a daemon process which is installed along with Guacamole and runs in the + background, listening for TCP connections from the web application. guacd also does not + understand any specific remote desktop protocol, but rather implements just enough of + the Guacamole protocol to determine which protocol support needs to be loaded and what + arguments must be passed to it. Once a client plugin is loaded, it runs independently of + guacd and has full control of the communication between itself and the web application + until the client plugin terminates.</p><a id="idm140352911475184" class="indexterm"></a><p>guacd and all client plugins depend on a common library, libguac, which makes + communication via the Guacamole protocol easier and a bit more abstract.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="web-application"></a>The web application</h2></div></div></div><a id="idm140352911472016" class="indexterm"></a><p>The part of Guacamole that a user actually interacts with is the web + application.</p><p>The web application, as mentioned before, does not implement any remote desktop + protocol. It relies on guacd, and implements nothing more than a spiffy web interface + and authentication layer.</p><p>We chose to implement the server side of the web application in Java, but there's no + reason that it can't be written in a different language. In fact, because Guacamole is + intended be an API, we encourage this.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="realmint"></a>RealMint</h2></div></div></div><a id="idm140352911468432" class="indexterm"></a><p>Guacamole is now a generalized remote desktop gateway, but this was not always the + case. Guacamole began as a purely text-based Telnet client written in JavaScript called + <span class="application"><a class="application" href="http://sourceforge.net/projects/realmint"; target="_top">RealMint</a></span> ("RealMint" is an anagram for "terminal"). It was written + mainly as a demonstration and, while intended to be useful, its main claim to fame was + only that it was pure JavaScript.</p><p>The tunnel used by RealMint was written in PHP. In contrast to Guacamole's HTTP + tunnel, RealMint's tunnel used only simple long-polling and was inefficient. RealMint + had a decent keyboard implementation which lives on now in parts of Guacamole's keyboard + code, but this was really the extent of RealMint's features and usability.</p><p>Given that it was just an implementation of a legacy protocol, and that several other + JavaScript terminal emulators exist, most of which well-established and stable, the + project was dropped.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="vnc-client"></a>VNC Client</h2></div></div></div><p>Once the developers learned of the HTML5 canvas tag, and saw that it was already + implemented in Firefox and Chrome, work started instead on a proof-of-concept JavaScript + VNC client.</p><p>This client was purely JavaScript with a Java server component, and worked by + translating VNC into an XML-based version of the same. Its development was naturally + driven by VNC's features, and its scope was limited to forwarding a single connection to + a set of users. Although relatively slow, the proof-of-concept worked well enough that + the project needed an online place to live, and was registered with SourceForge as + "Guacamole" - an HTML5 VNC client.</p><p>As Guacamole grew and became more than a proof-of-concept, the need for speed + increased, and the old RealMint-style long polling was dropped, as was the use of + XML.</p><p>As WebSocket could not be trusted to be supported at the time, and Java had no + WebSocket standard for servlets, an equivalent HTTP-based tunnel was developed. This + tunnel is still used today if WebSocket cannot be used for any reason.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="gateway"></a>Remote Desktop Gateway</h2></div></div></div><p>A faster text-based protocol was developed which could present the features of + multiple remote desktop protocols, not just VNC. The entire system was rearchitected + into a standard daemon, guacd, and a common library, libguac, which drove both the + daemon and protocol support, which became extendable.</p><p>The scope of the project expanded from an adequate VNC client to a performant HTML5 + remote desktop gateway and general API. In its current state, Guacamole can be used as a + central gateway to access any number of machines running different remote desktop + servers. It provides extendable authentication, and in the case you need something more + specialized, a general API for HTML5-based remote access.</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="users-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="installing-guacamole.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Part I. User's Guide </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 2. Installing Guacamole natively</td></tr></table></div> + + </div></div> + <!-- Google Analytics --> + <script type="text/javascript"> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-75289145-1', 'auto'); + ga('send', 'pageview'); + </script> + </body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/guacamole-common-js.html ---------------------------------------------------------------------- diff --git a/doc/0.9.11-incubating/gug/guacamole-common-js.html b/doc/0.9.11-incubating/gug/guacamole-common-js.html new file mode 100644 index 0000000..dd6ae4a --- /dev/null +++ b/doc/0.9.11-incubating/gug/guacamole-common-js.html @@ -0,0 +1,263 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 16. guacamole-common-js</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part II. Developer's Guide" /><link rel="prev" href="guacamole-common.html" title="Chapter 15. guacamole-common" /><link rel="next" href="guacamole-ext.html" title="Chapter 17. guacamole-ext" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> + </head><body> + <!-- CONTENT --> + + <div id="page"><div id="content"> + <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 16. guacamole-common-js</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="guacamole-common.html">Prev</a> </td><th width="60%" align="center">Part II. Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="guacamole-ext.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-common-js"></a>Chapter 16. guacamole-common-js</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="guacamole-common-js.html#guacamole-client">Guacamole client</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#input-abstraction">Input abstraction</a>< /span></dt><dd><dl><dt><span class="section"><a href="guacamole-common-js.html#guacamole-mouse">Mouse</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#guacamole-touch">Touch</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#guacamole-keyboard">Keyboard</a></span></dt></dl></dd><dt><span class="section"><a href="guacamole-common-js.html#on-screen-keyboard">On-screen keyboard</a></span></dt><dd><dl><dt><span class="section"><a href="guacamole-common-js.html#keyboard-layouts">Keyboard layouts</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#displaying-osk">Displaying the keyboard</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#styling-the-keyboard">Styling the keyboard</a></span></dt><dt><span class="section"><a href="guacamole-common-js.html#osk-event-handling">Handling key events</a></span></dt></dl></dd></dl></div><a id="idm140352908244720" class="indexterm"></a><a id="idm14035290 8037008" class="indexterm"></a><p>The Guacamole project provides a JavaScript API for interfacing with + other components that conform to the design of Guacamole, such as + projects using libguac or guacamole-common. This API is called + guacamole-common-js.</p><p>guacamole-common-js provides a JavaScript implementation of a + Guacamole client, as well as tunneling mechanisms for getting protocol + data out of JavaScript and into guacd or the server side of a web + application.</p><p>For convenience, it also provides mouse and keyboard abstraction objects that translate + JavaScript mouse, touch, and keyboard events into consistent data that Guacamole can more + easily digest. The extendable on-screen keyboard that was developed for the Guacamole web + application is also included.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="guacamole-client"></a>Guacamole client</h2></div></div></div><p>The main benefit to using the JavaScript API is the full Guacamole + client implementation, which implements all Guacamole instructions, + and makes use of the tunnel implementations provided by both the + JavaScript and Java APIs.</p><p>Using the Guacamole client is straightforward. The client, like + all other objects within the JavaScript API, is within the + <code class="code">Guacamole</code> namespace. It is instantiated given an + existing, unconnected tunnel:</p><div class="informalexample"><pre class="programlisting">var client = new Guacamole.Client(tunnel);</pre></div><p>Once you have the client, it won't immediately appear within the + DOM. You need to add its display element manually:</p><div class="informalexample"><pre class="programlisting">document.body.appendChild(client.getDisplay().getElement());</pre></div><p>At this point, the client will be visible, rendering all updates + as soon as they are received through the tunnel.</p><div class="informalexample"><pre class="programlisting">client.connect();</pre></div><p>It is possible to pass arbitrary data to the tunnel during + connection which can be used for authentication or for choosing a + particular connection. When the <code class="methodname">connect()</code> + function of the Guacamole client is called, it in turn calls the + <code class="methodname">connect()</code> function of the tunnel + originally given to the client, establishing a connection.</p><div class="important"><h3 class="title">Important</h3><p>When creating the <code class="classname">Guacamole.Client</code>, the + tunnel used must not already be connected. The + <code class="classname">Guacamole.Client</code> will call the + <code class="methodname">connect()</code> function for you when its + own <code class="methodname">connect()</code> function is invoked. If + the tunnel is already connected when it is given to the + <code class="classname">Guacamole.Client</code>, connection may not + work at all.</p></div><p>In general, all instructions available within the Guacamole + protocol are automatically handled by the Guacamole client, + including instructions related to audio and video. The only + instructions which you must handle yourself are "name" (used to name + the connection), "clipboard" (used to update clipboard data on the + client side), and "error" (used when something goes wrong + server-side). Each of these instructions has a corresponding event + handler; you need only supply functions to handle these events. If + any of these event handlers are left unset, the corresponding + instructions are simply ignored.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="http-tunnel"></a>HTTP tunnel</h2></div></div></div><p>Both the Java and JavaScript API implement corresponding ends of + an HTTP tunnel, based on + <code class="classname">XMLHttpRequest</code>.</p><p>The tunnel is a true stream - there is no polling. An initial + request is made from the JavaScript side, and this request is + handled on the Java side. While this request is open, data is + streamed along the connection, and instructions within this stream + are handled as soon as they are received by the client.</p><p>While data is being streamed along this existing connection, a + second connection attempt is made. Data continues to be streamed + along the original connection until the server receives and handles + the second request, at which point the original connection closes + and the stream is transferred to the new connection.</p><p>This process repeats, alternating between active streams, thus + creating an unbroken sequence of instructions, while also allowing + JavaScript to free any memory used by the previously active + connection.</p><p>The tunnel is created by supplying the relative URL to the + server-side tunnel servlet:</p><div class="informalexample"><pre class="programlisting">var tunnel = new Guacamole.Tunnel("tunnel");</pre></div><p>Once created, the tunnel can be passed to a + <code class="classname">Guacamole.Client</code> for use in a Guacamole + connection.</p><p>The tunnel actually takes care of the Guacamole protocol parsing + on behalf of the client, triggering "oninstruction" events for every + instruction received, splitting each element into elements of an + array so that the client doesn't have to.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="input-abstraction"></a>Input abstraction</h2></div></div></div><p>Browsers can be rather finicky when it comes to keyboard and mouse + input, not to mention touch events. There is little agreement on + which keyboard events get fired when, and what detail about the + event is made available to JavaScript. Touch and mouse events can + also cause confusion, as most browsers will generate + <span class="emphasis"><em>both</em></span> events when the user touches the + screen (for compatibility with JavaScript code that only handles + mouse events), making it more difficult for applications to support + both mouse and touch independently.</p><p>The Guacamole JavaScript API abstracts mouse, keyboard, and touch + interaction, providing several helper objects which act as an + abstract interface between you and the browser events.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-mouse"></a>Mouse</h3></div></div></div><p>Mouse event abstraction is provided by the + <code class="classname">Guacamole.Mouse</code> object. Given an + arbitrary DOM element, <code class="classname">Guacamole.Mouse</code> + triggers <span class="property">onmousedown</span>, + <span class="property">onmousemove</span>, and + <span class="property">onmouseup</span> events which are consistent + across browsers. This object only response. to true mouse + events. Mouse events which are actually the result of touch + events are ignored.</p><div class="informalexample"><pre class="programlisting">var element = document.getElementById("some-arbitrary-id"); +var mouse = new Guacamole.Mouse(element); + +mouse.onmousedown = +mouse.onmousemove = +mouse.onmouseup = function(state) { + + // Do something with the mouse state received ... + +};</pre></div><p>The handles of each event are given an instance of + <code class="classname">Guacamole.Mouse.State</code> which + represents the current state of the mouse, containing the state + of each button (including the scroll wheel) as well as the X and + Y coordinates of the pointer in pixels.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-touch"></a>Touch</h3></div></div></div><p>Touch event abstraction is provided by either + <code class="classname">Guacamole.Touchpad</code> (emulates a + touchpad to generate artificial mouse events) or + <code class="classname">Guacamole.Touchscreen</code> (emulates a + touchscreen, again generating artificial mouse events). + Guacamole uses the touchpad emulation, as this provides the most + flexibility and mouse-like features, including scrollwheel and + clicking with different buttons, but your preferences may + differ.</p><div class="informalexample"><pre class="programlisting">var element = document.getElementById("some-arbitrary-id"); +var touch = new Guacamole.Touchpad(element); // or Guacamole.Touchscreen + +touch.onmousedown = +touch.onmousemove = +touch.onmouseup = function(state) { + + // Do something with the mouse state received ... + +};</pre></div><p>Note that even though these objects are touch-specific, they + still provide mouse events. The state object given to the event + handlers of each event is still an instance of + <code class="classname">Guacamole.Mouse.State</code>.</p><p>Ultimately, you could assign the same event handler to all the + events of both an instance of + <code class="classname">Guacamole.Mouse</code> as well as + <code class="classname">Guacamole.Touchscreen</code> or + <code class="classname">Guacamole.Touchpad</code>, and you would + magically gain mouse and touch support. This support, being + driven by the needs of remote desktop, is naturally geared + around the mouse and providing a reasonable means of interacting + with it. For an actual mouse, events are translated simply and + literally, while touch events go through additional emulation + and heuristics. From the perspective of the user and the code, + this is all transparent.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-keyboard"></a>Keyboard</h3></div></div></div><p>Keyboard events in Guacamole are abstracted with the + <code class="classname">Guacamole.Keyboard</code> object as only + keyup and keydown events; there is no keypress like there is in + JavaScript. Further, all the craziness of keycodes vs. scancodes + vs. key identifiers normally present across browsers is + abstracted away. All your event handlers will see is an X11 + keysym, which represent every key unambiguously. Conveniently, + X11 keysyms are also what the Guacamole protocol requires, so if + you want to use <code class="classname">Guacamole.Keyboard</code> to + drive key events sent over the Guacamole protocol, everything + can be connected directly.</p><p>Just like the other input abstraction objects, + <code class="classname">Guacamole.Keyboard</code> requires a DOM + element as an event target. Only key events directed at this + element will be handled.</p><div class="informalexample"><pre class="programlisting">var keyboard = new Guacamole.Keyboard(document); + +keyboard.onkeydown = function(keysym) { + // Do something ... +}; + +keyboard.onkeyup = function(keysym) { + // Do something ... +};</pre></div><p>In this case, we are using <code class="classname">document</code> as + the event target, thus receiving all key events while the + browser window (or tab) has focus.</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="on-screen-keyboard"></a>On-screen keyboard</h2></div></div></div><p>The Guacamole JavaScript API also provides an extendable on-screen + keyboard, <code class="classname">Guacamole.OnScreenKeyboard</code>, which + requires the URL of an XML file describing the keyboard layout. The + on-screen keyboard object provides no hard-coded layout information; + the keyboard layout is described entirely within the XML layout + file.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="keyboard-layouts"></a>Keyboard layouts</h3></div></div></div><p>The keyboard layout XML included in the Guacamole web + application would be a good place to start regarding how these + layout files are written, but in general, the keyboard is simply + a set of rows or columns, denoted with <code class="code"><row></code> and + <code class="code"><column></code> tags respectively, where each can + be nested within the other as desired.</p><p>Each key is represented with a <code class="code"><key></code> tag, but + this is not what the user sees, nor what generates the key + event. Each key contains any number of <code class="code"><cap></code> + tags, which represent the visible part of the key. The cap + describes which X11 keysym will be sent when the key is pressed. + Each cap can be associated with any combination of arbitrary + modifier flags which dictate when that cap is active.</p><p>For example:</p><div class="informalexample"><pre class="programlisting"><keyboard lang="en_US" layout="example" size="5"> + <row> + <key size="4"> + <cap modifier="shift" keysym="0xFFE1">Shift</cap> + </key> + <key> + <cap>a</cap> + <cap if="shift">A</cap> + </key> + </row> +</keyboard></pre></div><p>Here we have a very simple keyboard which defines only two + keys: "shift" (a modifier) and the letter "a". When "shift" is + pressed, it sets the "shift" modifier, affecting other keys in + the keyboard. The "a" key has two caps: one lowercase (the + default) and one uppercase (which requires the shift modifier to + be active).</p><p>Notice that the shift key needed the keysym explicitly + specified, while the "a" key did not. This is because the + on-screen keyboard will automatically derive the correct keysym + from the text of the key cap if the text contains only a single + character.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="displaying-osk"></a>Displaying the keyboard</h3></div></div></div><p>Once you have a keyboard layout available, adding an on-screen + keyboard to your application is simple:</p><div class="informalexample"><pre class="programlisting">// Add keyboard to body +var keyboard = new Guacamole.OnScreenKeyboard("path/to/layout.xml"); +document.body.appendChild(keyboard.getElement()); + +// Set size of keyboard to 100 pixels +keyboard.resize(100);</pre></div><p>Here, we have explicitly specified the width of the keyboard + as 100 pixels. Normally, you would determine this by inspecting + the width of the containing component, or by deciding on a + reasonable width beforehand. Once the width is given, the height + of the keyboard is determined based on the arrangement of each + row.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="styling-the-keyboard"></a>Styling the keyboard</h3></div></div></div><p>While the <code class="classname">Guacamole.OnScreenKeyboard</code> + object will handle most of the layout, you will still need to + style everything yourself with CSS to get the elements to render + properly and the keys to change state when clicked or activated. + It defines several CSS classes, which you will need to manually + style to get things looking as desired:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="classname">guac-keyboard</code></span></dt><dd><p>This class is assigned to the root element + containing the entire keyboard, returned by + <code class="methodname">getElement()</code>,</p></dd><dt><span class="term"><code class="classname">guac-keyboard-row</code></span></dt><dd><p>Assigned to the <code class="code">div</code> elements which + contain each row.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-column</code></span></dt><dd><p>Assigned to the <code class="code">div</code> elements which + contain each column.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-gap</code></span></dt><dd><p>Assigned to any <code class="code">div</code> elements created + as a result of <code class="code"><gap></code> tags in the + keyboard layout. <code class="code"><gap></code> tags are + intended to behave as keys with no visible styling + or caps.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-key-container</code></span></dt><dd><p>Assigned to the <code class="code">div</code> element which + contains a key, and provides that key with its + required dimensions. It is this element that will be + scaled relative to the size specified in the layout + XML and the size given to the <code class="code">resize()</code> + function.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-key</code></span></dt><dd><p>Assigned to the <code class="code">div</code> element which + represents the actual key, not the cap. This element + will not directly contain text, but it will contain + all caps that this key can have. With clever CSS + rules, you can take advantage of this and cause + inactive caps to appear on the key in a corner (for + example), or hide them entirely.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-cap</code></span></dt><dd><p>Assigned to the <code class="code">div</code> element + representing a key cap. Each cap is a child of its + corresponding key, and it is up to the author of the + CSS rules to hide or show or reposition each cap + appropriately. Each cap will contain the display + text defined within the <code class="code"><cap></code> + element in the layout XML.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-requires-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd><p>Added to the cap element when that cap requires a + specific modifier.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-uses-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd><p>Added to the key element when any cap contained + within it requires a specific modifier.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-modifier-<em class="replaceable"><code>MODIFIER</code></em></code></span></dt><dd><p>Added to and removed from the root keyboard + element when a modifier key is activated or + deactivated respectively.</p></dd><dt><span class="term"><code class="classname">guac-keyboard-pressed</code></span></dt><dd><p>Added to and removed from any key element as it is + pressed and released respectively.</p></dd></dl></div><div class="important"><h3 class="title">Important</h3><p>The CSS rules required for the on-screen keyboard to work + as expected can be quite complex. Looking over the CSS rules + used by the on-screen keyboard in the Guacamole web + application would be a good place to start to see how the + appearance of each key can be driven through the simple + class changes described above.</p><p>Inspecting the elements of an active on-screen keyboard + within the Guacamole web application with the developer + tools of your favorite browser is also a good idea.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="osk-event-handling"></a>Handling key events</h3></div></div></div><p>Key events generated by the on-screen keyboard are identical + to those of <code class="classname">Guacamole.Keyboard</code> in that + they consist only of a single X11 keysym. Only keyup and keydown + events exist, as before; there is no keypress event.</p><div class="informalexample"><pre class="programlisting">// Assuming we have an instance of Guacamole.OnScreenKeyboard already +// called "keyboard" + +keyboard.onkeydown = function(keysym) { + // Do something ... +}; + +keyboard.onkeyup = function(keysym) { + // Do something ... +};</pre></div></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="guacamole-common.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="guacamole-ext.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 15. <span class="package">guacamole-common</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 17. guacamole-ext</td></tr></table></div> + + </div></div> + <!-- Google Analytics --> + <script type="text/javascript"> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-75289145-1', 'auto'); + ga('send', 'pageview'); + </script> + </body></html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/2441fd18/doc/0.9.11-incubating/gug/guacamole-common.html ---------------------------------------------------------------------- diff --git a/doc/0.9.11-incubating/gug/guacamole-common.html b/doc/0.9.11-incubating/gug/guacamole-common.html new file mode 100644 index 0000000..e325511 --- /dev/null +++ b/doc/0.9.11-incubating/gug/guacamole-common.html @@ -0,0 +1,141 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 15. guacamole-common</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="developers-guide.html" title="Part II. Developer's Guide" /><link rel="prev" href="libguac.html" title="Chapter 14. libguac" /><link rel="next" href="guacamole-common-js.html" title="Chapter 16. guacamole-common-js" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> + </head><body> + <!-- CONTENT --> + + <div id="page"><div id="content"> + <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 15. <span class="package">guacamole-common</span></th></tr><tr><td width="20%" align="left"><a accesskey="p" href="libguac.html">Prev</a> </td><th width="60%" align="center">Part II. Developer's Guide</th><td width="20%" align="right"> <a accesskey="n" href="guacamole-common-js.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="guacamole-common"></a>Chapter 15. <span class="package">guacamole-common</span></h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="guacamole-common.html#java-http-tunnel">HTTP tunnel</a></span></dt><dt><span class="section"><a href="guacamole-common.html#java-protocol-usage">Using the Guacamole protocol</a></span></dt><dd><dl><dt><span class="section"><a href ="guacamole-common.html#java-reading-protocol"><code class="classname">GuacamoleReader</code></a></span></dt><dt><span class="section"><a href="guacamole-common.html#java-writing-protocol"><code class="classname">GuacamoleWriter</code></a></span></dt></dl></dd></dl></div><a id="idm140352908228032" class="indexterm"></a><a id="idm140352908246976" class="indexterm"></a><p>The Java API provided by the Guacamole project is called guacamole-common. It provides a + basic means of tunneling data between the JavaScript client provided by guacamole-common-js + and the native proxy daemon, guacd, and for dealing with the Guacamole protocol. The purpose + of this library is to facilitate the creation of custom tunnels between the JavaScript + client and guacd, allowing your Guacamole-driven web application to enforce its own security + model, if any, and dictate exactly what connections are established.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="java-http-tunnel"></a>HTTP tunnel</h2></div></div></div><p>The Guacamole Java API implements the HTTP tunnel using a servlet + called <code class="classname">GuacamoleHTTPTunnelServlet</code>. This + servlet handles all requests coming to it over HTTP from the + JavaScript client, and translated them into connect, read, or write + requests, which each get dispatched to the + <code class="methodname">doConnect()</code>, + <code class="methodname">doRead()</code>, and + <code class="methodname">doWrite()</code> functions accordingly.</p><p>Normally, you wouldn't touch the <code class="methodname">doRead()</code> + and <code class="methodname">doWrite()</code> functions, as these have + already been written to properly handle the requests of the + JavaScript tunnel, and if you feel the need to touch these + functions, you are probably better off writing your own tunnel + implementation, although such a thing is difficult to do in a + performant way.</p><p>When developing an application based on the Guacamole API, you + should use <code class="classname">GuacamoleHTTPTunnelServlet</code> by + extending it, implementing your own version of + <code class="methodname">doConnect()</code>, which is the only abstract + function it defines. The tutorial later in this book demonstrating + how to write a Guacamole-based web application shows the basics of + doing this, but generally, <code class="methodname">doConnect()</code> is + an excellent place for authentication or other validation, as it is + the responsibility of <code class="methodname">doConnect()</code> to create + (or not create) the actual tunnel. If + <code class="methodname">doConnect()</code> does not create the tunnel, + communication between the JavaScript client and guacd cannot take + place, which is an ideal power to have as an authenticator.</p><p>The <code class="methodname">doConnect()</code> function is expected to return a new + <code class="classname">GuacamoleTunnel</code>, but it is completely up to the + implementation to decide how that tunnel is to be created. The already-implemented parts + of <code class="classname">GuacamoleHTTPTunnelServlet</code> then return the unique identifier + of this tunnel to the JavaScript client, allowing its own tunnel implementation to + continue to communicate with the tunnel existing on the Java side.</p><p>Instances of <code class="classname">GuacamoleTunnel</code> are created associated with a + <code class="classname">GuacamoleSocket</code>, which is the abstract interface surrounding + the low-level connection to guacd. Overall, there is a socket + (<code class="classname">GuacamoleSocket</code>) which provides a TCP connection to guacd. + This socket is exposed to <code class="classname">GuacamoleTunnel</code>, which provides + abstract protocol access around what is actually (but secretly, through the abstraction + of the API) a TCP socket.</p><p>The Guacamole web application extends this tunnel servlet in order + to implement authentication at the lowest possible level, + effectively prohibiting communication between the client and any + remote desktops unless they have properly authenticated. Your own + implementation can be considerably simpler, especially if you don't + need authentication:</p><div class="informalexample"><pre class="programlisting">public class MyGuacamoleTunnelServlet + extends GuacamoleHTTPTunnelServlet { + + @Override + protected GuacamoleTunnel doConnect(HttpServletRequest request) + throws GuacamoleException { + + // Connect to guacd here (this is a STUB) + GuacamoleSocket socket; + + // Return a new tunnel which uses the connected socket + return new SimpleGuacamoleTunnel(socket); + + } + +}</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="java-protocol-usage"></a>Using the Guacamole protocol</h2></div></div></div><p>guacamole-common provides basic low-level support for the + Guacamole protocol. This low-level support is leveraged by the HTTP + tunnel implementation to satisfy the requirements of the JavaScript + client implementation, as the JavaScript client expects the + handshake procedure to have already taken place. This support exists + through the <code class="classname">GuacamoleReader</code> and + <code class="classname">GuacamoleWriter</code> classes, which are + similar to Java's <code class="classname">Reader</code> and + <code class="classname">Writer</code> classes, except that they deal + with the Guacamole protocol specifically, and thus have slightly + different contracts.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="java-reading-protocol"></a><code class="classname">GuacamoleReader</code></h3></div></div></div><p><code class="classname">GuacamoleReader</code> provides a very basic + <code class="methodname">read()</code> function which is required + to return one or more complete instructions in a + <span class="type">char</span> array. It also provides the typical + <code class="methodname">available()</code> function, which informs + you whether <code class="methodname">read()</code> is likely to block + the next time it is called, and an even more abstract version of + <code class="methodname">read()</code> called + <code class="methodname">readInstruction()</code> which returns one + instruction at a time, wrapped within a + <code class="classname">GuacamoleInstruction</code> instance.</p><p>Normally, you would not need to use this class yourself. It is + used by <code class="classname">ConfiguredGuacamoleSocket</code> to + complete the Guacamole protocol handshake procedure, and it is + used by <code class="classname">GuacamoleHTTPTunnelServlet</code> within + <code class="methodname">doRead()</code> to implement the reading + half of the tunnel.</p><p>The only concrete implementation of + <code class="classname">GuacamoleReader</code> is + <code class="classname">ReaderGuacamoleReader</code>, which wraps a + Java <code class="classname">Reader</code>, using that as the source for + data to parse into Guacamole instructions. Again, you would not + normally directly use this class, nor instantiate it yourself. A + working, concrete instance of + <code class="classname">GuacamoleReader</code> can be retrieved from + any <code class="classname">GuacamoleSocket</code> or + <code class="classname">GuacamoleTunnel</code>.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="java-writing-protocol"></a><code class="classname">GuacamoleWriter</code></h3></div></div></div><p><code class="classname">GuacamoleWriter</code> provides a very basic + <code class="methodname">write()</code> function and a more + abstract version called + <code class="methodname">writeInstruction()</code> which writes + instances of <code class="classname">GuacamoleInstruction</code>. These + functions are analogous to the <code class="methodname">read()</code> + and <code class="methodname">readInstruction()</code> functions + provided by <code class="classname">GuacamoleReader</code>, and have + similar restrictions: the contract imposed by + <code class="methodname">write()</code> requires that written + instructions be complete</p><p>The only concrete implementation of + <code class="classname">GuacamoleWriter</code> is + <code class="classname">WriterGuacamoleWriter</code>, which wraps a + Java <code class="classname">Writer</code>, using that as the + destination for Guacamole instruction data, but you would not + normally directly use this class, nor instantiate it yourself. + It is used by <code class="classname">ConfiguredGuacamoleSocket</code> + to complete the Guacamole protocol handshake procedure, and it + is used by <code class="classname">GuacamoleHTTPTunnelServlet</code> + within <code class="methodname">doWrite()</code> to implement the + writing half of the tunnel.</p><p>If necessary, a <code class="classname">GuacamoleWriter</code> can be + retrieved from any <code class="classname">GuacamoleSocket</code> or + <code class="classname">GuacamoleTunnel</code>, but in most cases, + the classes provided by the Guacamole Java API which already use + <code class="classname">GuacamoleWriter</code> will be + sufficient.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libguac.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="developers-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="guacamole-common-js.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 14. libguac </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 16. guacamole-common-js</td></tr></table></div> + + </div></div> + <!-- Google Analytics --> + <script type="text/javascript"> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-75289145-1', 'auto'); + ga('send', 'pageview'); + </script> + </body></html> \ No newline at end of file
