You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@guacamole.apache.org by mj...@apache.org on 2016/04/24 03:02:16 UTC
[02/58] [abbrv] [partial] incubator-guacamole-website git commit: Add
doc/ and pub/ directories from old site. Remove Piwik tracking.
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/f9d5dedf/doc/0.8.3/gug/mysql-auth.html
----------------------------------------------------------------------
diff --git a/doc/0.8.3/gug/mysql-auth.html b/doc/0.8.3/gug/mysql-auth.html
new file mode 100644
index 0000000..94ba59e
--- /dev/null
+++ b/doc/0.8.3/gug/mysql-auth.html
@@ -0,0 +1,521 @@
+<?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 4. MySQL authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.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="configuring-guacamole.html" title="Chapter 3. Configuring Guacamole" /><link rel="next" href="ldap-auth.html" title="Chapter 5. LDAP 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 4. MySQL authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configuring-guacamole.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="ldap-auth.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter 4. MySQL authentication" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="mysql-auth"></a>Chapter 4. MySQL authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="mysql-auth.html#installing-mysql-auth">Installing MySQL authentication</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-auth.html#idp740928">Creating a database and user</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp757744
">Running the SQL scripts</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp772704">Configuring Guacamole</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp773024">Logging in</a></span></dt></dl></dd><dt><span class="section"><a href="mysql-auth.html#mysql-auth-schema">Modifying data manually</a></span></dt><dd><dl><dt><span class="section"><a href="mysql-auth.html#idp793152">Users</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp812144">Connections and parameters</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp858096">Connections groups</a></span></dt><dt><span class="section"><a href="mysql-auth.html#idp878096">Permissions</a></span></dt></dl></dd></dl></div>
+
+ <a id="idp715184" class="indexterm"></a>
+ <a id="idp716128" class="indexterm"></a>
+ <p>Guacamole supports MySQL authentication through an extension available from the project
+ website. This extension allows users and connections to be managed from within the web
+ application. Unlike the default, XML-driven authentication module, all changes to users and
+ connections take effect immediately; users need not logout and back in in order to see new
+ connections.</p>
+ <p>The official MySQL authentication also supports load balancing through the use of
+ "balancing groups". When a balancing group is created, it can be used like any other
+ connection, but will use the least used of its underlying connections, spreading load evenly
+ across any connections contained within.</p>
+ <div class="section" title="Installing MySQL authentication"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-mysql-auth"></a>Installing MySQL authentication</h2></div></div></div>
+
+ <p>The MySQL authentication module is not included in the main Guacamole bundle nor is it
+ enabled by default. You must use the download link provided in the downloads section of
+ the main Guacamole site.</p>
+ <p>The downloaded <code class="filename">.tar.gz</code> file will contain several
+ directories:</p>
+ <div class="variablelist"><dl><dt><span class="term"><code class="filename">lib/</code></span></dt><dd>
+ <p>Contains all <code class="filename">.jar</code> files required for the MySQL
+ authentication module to work, including the module itself. <span class="emphasis"><em>The
+ MySQL JDBC connector is not included.</em></span></p>
+ </dd><dt><span class="term"><code class="filename">schema/</code></span></dt><dd>
+ <p>Contains all SQL scripts required to set up the MySQL database.</p>
+ </dd></dl></div>
+ <p>The contents of <code class="filename">lib/</code> must be copied into the classpath of
+ Guacamole, which is the directory specified by the <span class="property">lib-directory</span>
+ property in <code class="filename">guacamole.properties</code>. If this property is not
+ specified, simply add it. On Linux servers,
+ <code class="filename">/var/lib/guacamole/classpath</code> is a good choice, but it can be
+ whatever you like.</p>
+ <p>In addition to the files from <code class="filename">lib/</code>, you must also copy
+ <code class="filename">.jar</code> file from the MySQL "Connector-J" JDBC archive. The
+ archive containing this <code class="filename">.jar</code> can be downloaded from <a class="ulink" href="http://dev.mysql.com/downloads/connector/j/" target="_top">MySQL's
+ website</a>.</p>
+ <p>After copying the files in place, check to make sure everything looks sane. The
+ contents should match at least the files shown here:</p>
+ <div class="informalexample">
+ <pre class="screen"><code class="prompt">$</code> ls <em class="replaceable"><code>/var/lib/guacamole/classpath</code></em>
+<code class="computeroutput">aopalliance-1.0.jar javax.inject-1.jar
+commons-logging-1.1.1.jar mybatis-3.1.1.jar
+google-collections-1.0.jar mybatis-guice-3.2.jar
+guacamole-auth-mysql-0.8.0.jar mysql-connector-java-5.1.23-bin.jar
+guice-3.0.jar slf4j-api-1.6.1.jar
+guice-multibindings-3.0.jar slf4j-jcl-1.6.1.jar</code>
+<code class="prompt">$</code></pre>
+ </div>
+ <p>Each of the <code class="filename">.jar</code> files above is either the MySQL authentication
+ module itself (<code class="filename">guacamole-auth-mysql-0.8.0.jar</code>) or a dependency.
+ They must all be placed in Guacamole's lib-directory for the MySQL authentication to
+ work.</p>
+ <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+ <p>If you do not see <code class="filename">mysql-connector-java-5.1.23-bin.jar</code> (or a
+ similar file with a different version) present in the same directory as the other
+ <code class="filename">.jar</code> files, then you have not copied MySQL Connector-J
+ properly.</p>
+ <p>Be sure to download MySQL Connector-J from the <a class="ulink" href="http://dev.mysql.com/downloads/connector/j/" target="_top">MySQL website</a>.
+ Extract the downloaded archive, and copy the <code class="filename">.jar</code> file into the
+ same directory as shown above. <span class="emphasis"><em>If this is not done, MySQL authentication
+ will not work.</em></span> Guacamole will be unable to connect to your MySQL
+ database.</p>
+ </div>
+ <div class="section" title="Creating a database and user"><div class="titlepage"><div><div><h3 class="title"><a id="idp740928"></a>Creating a database and user</h3></div></div></div>
+
+ <a id="idp741776" class="indexterm"></a>
+ <p>The MySQL authentication module will need a database to store all authentication
+ data and a user to use only for data access and manipulation. You could use an
+ existing database and existing user, but for the sake of simplicity and security,
+ these instructions assume you will be creating a new database and new user that will
+ be used only by Guacamole and only for this authentication module.</p>
+ <p>At this point, you need MySQL installed and the root MySQL user configured. If
+ this is not the case, install MySQL now. Most distributions will provide a
+ convenient MySQL package which will set up everything for you, including the root
+ user. After MySQL is installed, create the new database and user:</p>
+ <div class="informalexample">
+ <pre class="screen"><code class="prompt">$</code> mysql -u root -p
+<code class="prompt">Enter password:</code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong>
+<code class="computeroutput">Welcome to the MySQL monitor. Commands end with ; or \g.
+Your MySQL connection id is 233
+Server version: 5.5.29-0ubuntu0.12.10.1 (Ubuntu)
+
+Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
+
+Oracle is a registered trademark of Oracle Corporation and/or its
+affiliates. Other names may be trademarks of their respective
+owners.
+
+Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
+</code>
+<code class="prompt">mysql></code> <strong class="userinput"><code>CREATE DATABASE <em class="replaceable"><code>guacamole</code></em>;</code></strong>
+<code class="computeroutput">Query OK, 1 row affected (0.00 sec)</code>
+
+<code class="prompt">mysql></code> <strong class="userinput"><code>CREATE USER '<em class="replaceable"><code>guacamole'</code></em>@'localhost' IDENTIFIED BY '<em class="replaceable"><code>some_password</code></em>';</code></strong>
+<code class="computeroutput">Query OK, 0 rows affected (0.00 sec)</code>
+
+<code class="prompt">mysql></code> <strong class="userinput"><code>GRANT SELECT,INSERT,UPDATE,DELETE ON <em class="replaceable"><code>guacamole</code></em>.* TO '<em class="replaceable"><code>guacamole'</code></em>@'localhost';</code></strong>
+<code class="computeroutput">Query OK, 0 rows affected (0.00 sec)</code>
+
+<code class="prompt">mysql></code> <strong class="userinput"><code>FLUSH PRIVILEGES;</code></strong>
+<code class="computeroutput">Query OK, 0 rows affected (0.02 sec)</code>
+
+<code class="prompt">mysql></code> <strong class="userinput"><code>quit</code></strong>
+<code class="computeroutput">Bye</code>
+<code class="prompt">$</code></pre>
+ </div>
+ <p>The database and user can be named whatever you like, but these instructions will
+ refer to both as "guacamole". Naturally, you should choose a real password for your
+ user rather than the string "some_password" shown above.</p>
+ </div>
+ <div class="section" title="Running the SQL scripts"><div class="titlepage"><div><div><h3 class="title"><a id="idp757744"></a>Running the SQL scripts</h3></div></div></div>
+
+ <a id="idp758560" class="indexterm"></a>
+ <p>The SQL scripts that create the database schema and default administrator user are
+ included in the archive you downloaded within the <code class="filename">schema/</code>
+ directory. They are named such that they can be run in order with one
+ command:</p>
+ <div class="informalexample">
+ <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ls schema/</code></strong>
+<code class="computeroutput">001-create-schema.sql 002-create-admin-user.sql upgrade</code>
+<code class="prompt">$</code> <strong class="userinput"><code>cat schema/*.sql | mysql -u root -p <em class="replaceable"><code>guacamole</code></em></code></strong>
+<code class="computeroutput"><code class="prompt">Enter password:</code></code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong>
+<code class="prompt">$</code></pre>
+ </div>
+ <p>If the operation is successful, all tables have been created successfully, and the
+ database is now ready for use. All that is left now is to configure Guacamole to use
+ the database we've created.</p>
+ <div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3>
+ <p>If you are upgrading from an older version that lacked support for connection
+ groups, you should instead run the upgrade script located within the
+ <code class="filename">upgrade/</code> directory:</p>
+ <div class="informalexample">
+ <pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>ls schema/upgrade/</code></strong>
+<code class="computeroutput">upgrade-pre-0.8.2.sql</code>
+<code class="prompt">$</code> <strong class="userinput"><code>mysql -u root -p <em class="replaceable"><code>guacamole</code></em> < schema/upgrade/upgrade-pre-0.8.2.sql</code></strong>
+<code class="computeroutput"><code class="prompt">Enter password:</code></code> <strong class="userinput"><code><em class="replaceable"><code>password</code></em></code></strong>
+<code class="prompt">$</code></pre>
+ </div>
+ </div>
+ </div>
+ <div class="section" title="Configuring Guacamole"><div class="titlepage"><div><div><h3 class="title"><a id="idp772704"></a>Configuring Guacamole</h3></div></div></div>
+
+ <a id="idp773680" class="indexterm"></a>
+ <p>Now that the database and user is created, and the SQL scripts have been run, we
+ need to add a few properties to <code class="filename">guacamole.properties</code> such that
+ Guacamole can connect to MySQL when authenticating users:</p>
+ <div class="informalexample">
+ <pre class="programlisting"># Auth provider class
+auth-provider: net.sourceforge.guacamole.net.auth.mysql.MySQLAuthenticationProvider
+
+# MySQL properties
+mysql-hostname: localhost
+mysql-port: 3306
+mysql-database: <em class="replaceable"><code>guacamole</code></em>
+mysql-username: <em class="replaceable"><code>guacamole</code></em>
+mysql-password: <em class="replaceable"><code>some_password</code></em></pre>
+ </div>
+ <a id="idp778064" class="indexterm"></a>
+ <p>Be sure to specify the correct password for the MySQL user you created, and
+ specify the correct database and username if you didn't use "guacamole". If you wish
+ to only allow one user at a time to access any single connection, you can also limit
+ concurrent access to connections:</p>
+ <div class="informalexample">
+ <pre class="programlisting">mysql-disallow-simultaneous-connections: true</pre>
+ </div>
+ <p>This is not required, but with the above property in place, users attempting to
+ use a connection that is currently in use by another user will be denied access. By
+ default, concurrent access is allowed.</p>
+ <p>You can also limit whether a single user is allowed to connect to the same
+ connection or group concurrently. By default, this is enabled, as it has security
+ implications when balancing groups are used, but you can explicitly disable this if
+ you want to allow duplicate connections:</p>
+ <div class="informalexample">
+ <pre class="programlisting">mysql-disallow-duplicate-connections: false</pre>
+ </div>
+ <p>Now just restart Tomcat (or whatever servlet container you are using) and
+ authentication will use MySQL.</p>
+ </div>
+ <div class="section" title="Logging in"><div class="titlepage"><div><div><h3 class="title"><a id="idp773024"></a>Logging in</h3></div></div></div>
+
+ <a id="idp784336" class="indexterm"></a>
+ <a id="idp785104" class="indexterm"></a>
+ <p>After the MySQL authentication module is installed, you need to log in and change
+ your password, and add whatever connections and additional users you need.</p>
+ <p>The default user is "<span class="token">guacadmin</span>", with the default password of
+ "<span class="token">guacadmin</span>". You can change your password by editing your own
+ user in the administration screen.</p>
+ <p>More detailed instructions for managing users and connections is given in <a class="xref" href="using-guacamole.html" title="Chapter 7. Using Guacamole">Chapter 7, <em>Using Guacamole</em></a> in <a class="xref" href="using-guacamole.html#guacamole-admin-ui" title="Administration">the section called “Administration”</a>.</p>
+ </div>
+ </div>
+ <div class="section" title="Modifying data manually"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="mysql-auth-schema"></a>Modifying data manually</h2></div></div></div>
+
+ <a id="idp790784" class="indexterm"></a>
+ <p>If necessary, it is possible to modify the data backing the MySQL authentication
+ module manually by executing SQL statements against the database. In general use, this
+ will not be common, but if you need to bulk-insert a large number of users or
+ connections, or you wish to translate an existing configuration automatically, you will
+ need to know how everything is laid out at a high level.</p>
+ <p>This section assumes knowledge of SQL and MySQL, and that whatever you need to do can
+ be accomplished if only you had high-level information about Guacamole's SQL
+ schema.</p>
+ <div class="section" title="Users"><div class="titlepage"><div><div><h3 class="title"><a id="idp793152"></a>Users</h3></div></div></div>
+
+ <a id="idp794000" class="indexterm"></a>
+ <p>Every user has a corresponding entry in the <code class="classname">guacamole_user</code>
+ table. Each user has a corresponding unique username and salted password. The salted
+ password is split into two columns: one containing the salt, and the other
+ containing the password hashed with SHA-256.</p>
+ <p>The <code class="classname">guacamole_user</code> table contains the following
+ columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The unique integer associated with each user. This value is generated
+ automatically when a new entry is inserted into the
+ <code class="classname">guacamole_user</code> table.</p>
+ </dd><dt><span class="term"><span class="property">username</span></span></dt><dd>
+ <p>The unique name associated with each user. This value must be
+ specified manually, and must be different from any existing username in
+ the table. References to users in other tables use the value from
+ <span class="property">user_id</span>, not
+ <span class="property">username</span>.</p>
+ </dd><dt><span class="term"><span class="property">password_hash</span></span></dt><dd>
+ <p>The result of hashing the user's password concatenated with the
+ contents of <span class="property">password_salt</span> using SHA-256. The salt
+ is appended to the password prior to hashing.</p>
+ </dd><dt><span class="term"><span class="property">password_salt</span></span></dt><dd>
+ <p>A 32-byte random value. When a new user is created from the web
+ interface, this value is randomly generated using a
+ cryptographically-secure random number generator.</p>
+ </dd></dl></div>
+ <p>If creating a user manually, the main complication is the salt, which must be
+ determined before the <span class="command"><strong>INSERT</strong></span> statement can be constructed, but
+ this can be dealt with using variables:</p>
+ <div class="informalexample">
+ <pre class="programlisting">-- Generate salt
+SET @salt = UNHEX(SHA2(UUID(), 256));
+
+-- Create user and hash password with salt
+INSERT INTO guacamole_user (username, password_salt, password_hash)
+ VALUES ('myuser', @salt, UNHEX(SHA2(CONCAT('mypassword', HEX(@salt)), 256)));</pre>
+ </div>
+ <p>This sort of statement is useful for both creating new users or for changing
+ passwords, especially if all administrators have forgotten theirs.</p>
+ <p>Note that versions of MySQL earlier than 5.5.5 do not have the
+ <code class="methodname">SHA2</code> function. If you are using one of these versions,
+ you will need to calculate the SHA-256 value manually (by using the
+ <span class="command"><strong>sha256sum</strong></span> command, for example).</p>
+ </div>
+ <div class="section" title="Connections and parameters"><div class="titlepage"><div><div><h3 class="title"><a id="idp812144"></a>Connections and parameters</h3></div></div></div>
+
+ <a id="idp813312" class="indexterm"></a>
+ <a id="idp813744" class="indexterm"></a>
+ <p>Each connection has an entry in the <code class="classname">guacamole_connection</code>
+ table, with a one-to-many relationship to parameters, stored as name/value pairs in
+ the <code class="classname">guacamole_connection_parameter</code> table.</p>
+ <p>The <code class="classname">guacamole_connection</code> table is simply a pairing of a
+ unique and descriptive name with the protocol to be used for the connection. It
+ contains the following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">connection_id</span></span></dt><dd>
+ <p>The unique integer associated with each connection. This value is
+ generated automatically when a new entry is inserted into the
+ <code class="classname">guacamole_connection</code> table.</p>
+ </dd><dt><span class="term"><span class="property">connection_name</span></span></dt><dd>
+ <p>The unique name associated with each connection. This value must be
+ specified manually, and must be different from any existing connection
+ name in the same connection group. References to connections in other
+ tables use the value from <span class="property">connection_id</span>, not
+ <span class="property">connection_name</span>.</p>
+ </dd><dt><span class="term"><span class="property">protocol</span></span></dt><dd>
+ <p>The protocol to use with this connection. This is the name of the
+ protocol that should be sent to guacd when connecting, for example "vnc"
+ or "rdp".</p>
+ </dd><dt><span class="term"><span class="property">parent_id</span></span></dt><dd>
+ <p>The unique integer associated with the connection group containing
+ this connection, or <code class="constant">NULL</code> if this connection is
+ within the root group.</p>
+ </dd></dl></div>
+ <p>As there are potentially multiple parameters per connection, where the names of
+ each parameter are completely arbitrary and determined only by the protocol in use,
+ every parameter for a given connection has an entry in table
+ <code class="classname">guacamole_connection_parameter</code> table associated with its
+ corresponding connection. This table contains the following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">connection_id</span></span></dt><dd>
+ <p>The <span class="property">connection_id</span> value from the connection this
+ parameter is for.</p>
+ </dd><dt><span class="term"><span class="property">parameter_name</span></span></dt><dd>
+ <p>The name of the parameter to set. This is the name listed in the
+ documentation for the protocol specified in the associated
+ connection.</p>
+ </dd><dt><span class="term"><span class="property">parameter_value</span></span></dt><dd>
+ <p>The value to assign to the parameter named. While this value is an
+ arbitrary string, it must conform to the requirements of the protocol as
+ documented for the connection to be successful.</p>
+ </dd></dl></div>
+ <p>Adding a connection and corresponding parameters is relatively easy compared to
+ adding a user as there is no salt to generate nor password to hash:</p>
+ <div class="informalexample">
+ <pre class="programlisting">-- Create connection
+INSERT INTO guacamole_connection (connection_name, protocol) VALUES ('<em class="replaceable"><code>test</code></em>', '<em class="replaceable"><code>vnc</code></em>');
+SET @id = LAST_INSERT_ID();
+
+-- Add parameters
+INSERT INTO guacamole_connection_parameter VALUES (@id, 'hostname', '<em class="replaceable"><code>localhost</code></em>');
+INSERT INTO guacamole_connection_parameter VALUES (@id, 'port', '<em class="replaceable"><code>5901</code></em>');</pre>
+ </div>
+ <div class="section" title="Usage history"><div class="titlepage"><div><div><h4 class="title"><a id="idp840752"></a>Usage history</h4></div></div></div>
+
+ <a id="idp841696" class="indexterm"></a>
+ <p>When a connection is initiated or terminated, a corresponding entry in the
+ <code class="classname">guacamole_connection_history</code> table is created or
+ updated respectively. Each entry is associated with the user using the
+ connection, the connection itself, and the time the connection started. If the
+ connection has ended, the end time is also stored.</p>
+ <p>It is very unlikely that a user will need to update this table, but knowing
+ the structure is potentially useful if you wish to generate a report of
+ Guacamole usage. The <code class="classname">guacamole_connection_history</code> table
+ has the following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">history_id</span></span></dt><dd>
+ <p>The unique integer associated with each history record. This value
+ is generated automatically when a new entry is inserted into the
+ <code class="classname">guacamole_connection_history</code>
+ table.</p>
+ </dd><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> from the entry in
+ <code class="classname">guacamole_user</code> associated with the user
+ using the connection.</p>
+ </dd><dt><span class="term"><span class="property">connection_id</span></span></dt><dd>
+ <p>The value of the <span class="property">connection_id</span> from the entry
+ in <code class="classname">guacamole_connection</code> associated the
+ connection being used.</p>
+ </dd><dt><span class="term"><span class="property">start_date</span></span></dt><dd>
+ <p>The time at which the connection was started by the user
+ specified. Despite its name, this column also stores time
+ information in addition to the date.</p>
+ </dd><dt><span class="term"><span class="property">end_date</span></span></dt><dd>
+ <p>The time at which the connection ended. If the connection is still
+ active, the value in this column will be <code class="constant">NULL</code>.
+ Despite its name, this column also stores time information in
+ addition to the date.</p>
+ </dd></dl></div>
+ </div>
+ </div>
+ <div class="section" title="Connections groups"><div class="titlepage"><div><div><h3 class="title"><a id="idp858096"></a>Connections groups</h3></div></div></div>
+
+ <a id="idp859904" class="indexterm"></a>
+ <p>Each connection group has an entry in the
+ <code class="classname">guacamole_connection_group</code> table, with a one-to-many
+ relationship to other groups and connections.</p>
+ <p>The <code class="classname">guacamole_connection_group</code> table is simply a pairing of
+ a unique and descriptive name with a group type, which can be either
+ <span class="type">ORGANIZATIONAL</span> or <span class="type">BALANCING</span>. It contains the following
+ columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">connection_group_id</span></span></dt><dd>
+ <p>The unique integer associated with each connection group. This value
+ is generated automatically when a new entry is inserted into the
+ <code class="classname">guacamole_connection_group</code> table.</p>
+ </dd><dt><span class="term"><span class="property">connection_group_name</span></span></dt><dd>
+ <p>The unique name associated with each connection group. This value must
+ be specified manually, and must be different from any existing
+ connection group name in the same connection group. References to
+ connections in other tables use the value from
+ <span class="property">connection_group_id</span>, not
+ <span class="property">connection_group_name</span>.</p>
+ </dd><dt><span class="term"><span class="property">type</span></span></dt><dd>
+ <p>The type of this connection group. This can be either
+ <span class="type">ORGANIZATIONAL</span> or <span class="type">BALANCING</span>.</p>
+ </dd><dt><span class="term"><span class="property">parent_id</span></span></dt><dd>
+ <p>The unique integer associated with the connection group containing
+ this connection group, or <code class="constant">NULL</code> if this connection
+ group is within the root group.</p>
+ </dd></dl></div>
+ <p>Adding a connection group is even simpler than adding a new connection as there
+ are no associated parameters stored in a separate table:</p>
+ <div class="informalexample">
+ <pre class="programlisting">-- Create connection group
+INSERT INTO guacamole_connection_group (connection_group_name, type) VALUES ('<em class="replaceable"><code>test</code></em>', '<em class="replaceable"><code>ORGANIZATIONAL</code></em>');</pre>
+ </div>
+ </div>
+ <div class="section" title="Permissions"><div class="titlepage"><div><div><h3 class="title"><a id="idp878096"></a>Permissions</h3></div></div></div>
+
+ <p>There are three permissions tables in the schema which correspond to the three
+ types of permissions in Guacamole's authentication model: system permissions, which
+ control operations that affect the system as a whole, and user and connection
+ permissions, which control operations that affect specific, existing users or
+ connections respectively.</p>
+ <div class="section" title="System permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp879856"></a>System permissions</h4></div></div></div>
+
+ <a id="idp880672" class="indexterm"></a>
+ <p>System permissions are defined by entries in the
+ <code class="classname">guacamole_system_permission</code> table. Each entry grants
+ permission for a specific user to perform a specific system operation.</p>
+ <p>The <code class="classname">guacamole_system_permission</code> table contains the
+ following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> column of the entry
+ associated with the user owning this permission.</p>
+ </dd><dt><span class="term"><span class="property">permission</span></span></dt><dd>
+ <p>The permission being granted. This column can have one of three
+ possible values: <code class="constant">ADMINISTER</code>, which grants the
+ ability to administer the entire system (essentially a wildcard
+ permission), <code class="constant">CREATE_CONNECTION</code>, which grants
+ the ability to create connections,
+ <code class="constant">CREATE_CONNECTION_GROUP</code>, which grants the
+ ability to create connections groups, or
+ <code class="constant">CREATE_USER</code>, which grants the ability to
+ create users.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="User permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp891296"></a>User permissions</h4></div></div></div>
+
+ <a id="idp892112" class="indexterm"></a>
+ <p>User permissions are defined by entries in the
+ <code class="classname">guacamole_user_permission</code> table. Each entry grants
+ permission for a specific user to perform a specific operation on another
+ existing user.</p>
+ <p>The <code class="classname">guacamole_user_permission</code> table contains the
+ following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> column of the entry
+ associated with the user owning this permission.</p>
+ </dd><dt><span class="term"><span class="property">affected_user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> column of the entry
+ associated with the user <span class="emphasis"><em>affected</em></span> by this
+ permission. This is the user that would be the object of the
+ operation represented by this permission.</p>
+ </dd><dt><span class="term"><span class="property">permission</span></span></dt><dd>
+ <p>The permission being granted. This column can have one of four
+ possible values: <code class="constant">ADMINISTER</code>, which grants the
+ ability to add or remove permissions which affect the user,
+ <code class="constant">READ</code>, which grants the ability to read data
+ associated with the user, <code class="constant">UPDATE</code>, which grants
+ the ability to update data associated with the user, or
+ <code class="constant">DELETE</code>, which grants the ability to delete
+ the user.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="Connection permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp905760"></a>Connection permissions</h4></div></div></div>
+
+ <a id="idp906576" class="indexterm"></a>
+ <p>Connection permissions are defined by entries in the
+ <code class="classname">guacamole_connection_permission</code> table. Each entry
+ grants permission for a specific user to perform a specific operation on an
+ existing connection.</p>
+ <p>The <code class="classname">guacamole_connection_permission</code> table contains the
+ following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> column of the entry
+ associated with the user owning this permission.</p>
+ </dd><dt><span class="term"><span class="property">connection_id</span></span></dt><dd>
+ <p>The value of the <span class="property">connection_id</span> column of the
+ entry associated with the connection affected by this permission.
+ This is the connection that would be the object of the operation
+ represented by this permission.</p>
+ </dd><dt><span class="term"><span class="property">permission</span></span></dt><dd>
+ <p>The permission being granted. This column can have one of four
+ possible values: <code class="constant">ADMINISTER</code>, which grants the
+ ability to add or remove permissions which affect the connection,
+ <code class="constant">READ</code>, which grants the ability to read data
+ associated with the connection (a prerequisite for connecting),
+ <code class="constant">UPDATE</code>, which grants the ability to update
+ data associated with the connection, or <code class="constant">DELETE</code>,
+ which grants the ability to delete the connection.</p>
+ </dd></dl></div>
+ </div>
+ <div class="section" title="Connection group permissions"><div class="titlepage"><div><div><h4 class="title"><a id="idp919728"></a>Connection group permissions</h4></div></div></div>
+
+ <a id="idp920544" class="indexterm"></a>
+ <p>Connection group permissions are defined by entries in the
+ <code class="classname">guacamole_connection_group_permission</code> table. Each
+ entry grants permission for a specific user to perform a specific operation on
+ an existing connection group.</p>
+ <p>The <code class="classname">guacamole_connection_group_permission</code> table
+ contains the following columns:</p>
+ <div class="variablelist"><dl><dt><span class="term"><span class="property">user_id</span></span></dt><dd>
+ <p>The value of the <span class="property">user_id</span> column of the entry
+ associated with the user owning this permission.</p>
+ </dd><dt><span class="term"><span class="property">connection_group_id</span></span></dt><dd>
+ <p>The value of the <span class="property">connection_group_id</span> column
+ of the entry associated with the connection group affected by this
+ permission. This is the connection group that would be the object of
+ the operation represented by this permission.</p>
+ </dd><dt><span class="term"><span class="property">permission</span></span></dt><dd>
+ <p>The permission being granted. This column can have one of four
+ possible values: <code class="constant">ADMINISTER</code>, which grants the
+ ability to add or remove permissions which affect the connection
+ group, <code class="constant">READ</code>, which grants the ability to read
+ data associated with the connection group,
+ <code class="constant">UPDATE</code>, which grants the ability to update
+ data associated with the connection group, or
+ <code class="constant">DELETE</code>, which grants the ability to delete
+ the connection group (and implicitly its contents).</p>
+ </dd></dl></div>
+ </div>
+ </div>
+ </div>
+</div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-guacamole.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="ldap-auth.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 3. Configuring Guacamole </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 5. LDAP 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>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/f9d5dedf/doc/0.8.3/gug/noauth.html
----------------------------------------------------------------------
diff --git a/doc/0.8.3/gug/noauth.html b/doc/0.8.3/gug/noauth.html
new file mode 100644
index 0000000..1ccf924
--- /dev/null
+++ b/doc/0.8.3/gug/noauth.html
@@ -0,0 +1,131 @@
+<?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 6. Disabling authentication</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.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 5. LDAP authentication" /><link rel="next" href="using-guacamole.html" title="Chapter 7. Using Guacamole" />
+ <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 6. Disabling 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="using-guacamole.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" title="Chapter 6. Disabling authentication" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="noauth"></a>Chapter 6. Disabling authentication</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl><dt><span class="section"><a href="noauth.html#installing-noauth">Installing the "noauth" extension</a></span></dt><dd><dl><dt><span class="section"><a href="noauth.html#idp1039904">Configuring Guacamole</a></span></dt></dl></dd><dt><span class="section"><a href="noauth.html#noauth-configurat
ion">Adding connections</a></span></dt></dl></div>
+
+ <a id="idp1020784" class="indexterm"></a>
+ <a id="idp1021760" class="indexterm"></a>
+ <p>Guacamole normally enforces authentication, requiring all users to have a corresponding
+ set of credentials. If you would rather just type in your server's URL and gain access to
+ your computer, you can do this with the "noauth" extension.</p>
+ <p>guacamole-auth-noauth removes all authentication, giving anyone that visits your server
+ access to the same set of connections dictated by an XML configuration file. It is an
+ authentication implementation in its own right, and thus doesn't truly "disable"
+ authentication per se. Instead, it grants anyone access without requiring a username or
+ password.</p>
+ <p>The security implications of this should be obvious - anyone with access to your Guacamole
+ instance will have access to your remote desktops.</p>
+ <div class="section" title="Installing the "noauth" extension"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="installing-noauth"></a>Installing the "noauth" extension</h2></div></div></div>
+
+ <p>The "noauth" authentication module is not included in the main Guacamole bundle nor is
+ it enabled by default. You must use the download link provided in the downloads section
+ of the main Guacamole site.</p>
+ <p>The downloaded <code class="filename">.tar.gz</code> file will contain several
+ directories:</p>
+ <div class="variablelist"><dl><dt><span class="term"><code class="filename">lib/</code></span></dt><dd>
+ <p>Contains all <code class="filename">.jar</code> files required for the "noauth"
+ authentication module to work, including the module itself.</p>
+ </dd><dt><span class="term"><code class="filename">example/</code></span></dt><dd>
+ <p>Contains an example configuration file:
+ <code class="filename">noauth-config.xml</code>.</p>
+ </dd></dl></div>
+ <p>The contents of <code class="filename">lib/</code> must be copied into the classpath of
+ Guacamole, which is the directory specified by the <span class="property">lib-directory</span>
+ property in <code class="filename">guacamole.properties</code>. If this property is not
+ specified, simply add it. On Linux servers,
+ <code class="filename">/var/lib/guacamole/classpath</code> is a good choice, but it can be
+ whatever you like.</p>
+ <p>The "noauth" extension is very simple and does not require any external libraries to
+ function. The contents of the <code class="filename">lib/</code> directory should be simply the
+ extension itself. After copying this file in place, check that the contents match the
+ listing shown here:</p>
+ <pre class="screen"><code class="prompt">$</code> ls <em class="replaceable"><code>/var/lib/guacamole/classpath</code></em>
+<code class="computeroutput">guacamole-auth-noauth-0.8.0.jar</code>
+<code class="prompt">$</code></pre>
+ <p>If there are other <code class="filename">.jar</code> files present beyond the "noauth"
+ authentication module itself (<code class="filename">guacamole-auth-noauth-0.8.0.jar</code>), it
+ should still work. You would only have problems if two different versions of "noauth"
+ were present.</p>
+ <div class="section" title="Configuring Guacamole"><div class="titlepage"><div><div><h3 class="title"><a id="idp1039904"></a>Configuring Guacamole</h3></div></div></div>
+
+ <p>A few properties must be added to <code class="filename">guacamole.properties</code> such
+ that Guacamole will load the "noauth" extension and locate its configuration
+ file:</p>
+ <pre class="programlisting"># Auth provider class
+auth-provider: net.sourceforge.guacamole.net.auth.noauth.NoAuthenticationProvider
+
+# NoAuth properties
+noauth-config: <em class="replaceable"><code>/etc/guacamole/noauth-config.xml</code></em></pre>
+ <p>The <span class="property">auth-provider</span> property above is a standard Guacamole
+ property and tells Guacamole which authentication provider to use when
+ authenticating requests.</p>
+ <p>The <span class="property">noauth-config</span> property defines where the XML
+ configuration file (documented below) is located. This file describes the
+ connections available to any user of your Guacamole instance and can be placed
+ anywhere so long as its location is given in
+ <code class="filename">guacamole.properties</code>. On Linux servers,
+ <code class="filename">/etc/guacamole</code> is a good location for Guacamole
+ configuration files, including the configuration file used by "noauth".</p>
+ <p>Now just restart Tomcat (or whatever servlet container you are using) and
+ authentication will be effectively disabled.</p>
+ </div>
+ </div>
+ <div class="section" title="Adding connections"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="noauth-configuration"></a>Adding connections</h2></div></div></div>
+
+ <a id="idp1047808" class="indexterm"></a>
+ <p>Although the "noauth" extension does not check credentials, it still requires a
+ configuration file describing which connections are available and the protocols to use.
+ This configuration is an XML file, typically called
+ <code class="filename">noauth-config.xml</code>.</p>
+ <p>An example <code class="filename">noauth-config.xml</code> file is provided in the
+ <code class="filename">example/</code> directory of the <code class="filename">.tar.gz</code> file
+ downloadable from the Guacamole site. The format is fairly straightforward, and it
+ consists only of a list of connections (configurations) and parameters:</p>
+ <div class="informalexample">
+ <pre class="programlisting"><configs>
+ <config name="myconfig" protocol="rdp">
+ <param name="hostname" value="rdp-server" />
+ <param name="port" value="3389" />
+ </config>
+</configs></pre>
+ <p>The file consists of a single <code class="code"><configs></code> tag that contains any
+ number of <code class="code"><config></code> tags, each representing a distinct connection
+ available for use.</p>
+ <p>Each <code class="code"><config></code> tag has a corresponding <code class="code">name</code> and
+ <code class="code">protocol</code>. The <code class="code">name</code> attribute defines a unique
+ identifier for the connection and tells Guacamole what text should be displayed when
+ identifying the connection. The <code class="code">protocol</code> attribute defines the standard
+ remote desktop protocol to use, such as VNC, RDP, or SSH. These protocols must be
+ specified as lowercase due to the naming convention used by the libraries providing
+ protocol support. If the wrong case is used, Guacamole will be unable to load the
+ corresponding protocol support and the connection will fail.</p>
+ <p>The <param> tags are placed within <config> tags, describing a parameter
+ name/value pair. The parameters available, their names, and their allowed values are
+ protocol-specific and documented in <a class="xref" href="configuring-guacamole.html" title="Chapter 3. Configuring Guacamole">Chapter 3, <em>Configuring Guacamole</em></a>.</p>
+ <p>The example above creates a new connection called "myconfig" that uses RDP to
+ connect to the server at rdp-server on port 3389.</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="using-guacamole.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 5. 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 7. Using Guacamole</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>
+<!-- End Google Analytics -->
+ </body></html>
http://git-wip-us.apache.org/repos/asf/incubator-guacamole-website/blob/f9d5dedf/doc/0.8.3/gug/preface.html
----------------------------------------------------------------------
diff --git a/doc/0.8.3/gug/preface.html b/doc/0.8.3/gug/preface.html
new file mode 100644
index 0000000..5d80146
--- /dev/null
+++ b/doc/0.8.3/gug/preface.html
@@ -0,0 +1,147 @@
+<?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>Introduction</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="index.html" title="Guacamole Manual" /><link rel="prev" href="index.html" title="Guacamole Manual" /><link rel="next" href="users-guide.html" title="Part I. User's Guide" />
+ <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">Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="users-guide.html">Next</a></td></tr></table><hr /></div><div class="preface" title="Introduction"><div class="titlepage"><div><div><h2 class="title"><a id="preface"></a>Introduction</h2></div></div></div>
+
+ <p>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 <a class="ulink" href="http://guac-dev.org/" target="_top">http://guac-dev.org/</a>. It is a work in
+ progress which will be continuously updated as Guacamole changes with each
+ release.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>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.</p>
+ <p>This particular edition of the <em class="citetitle">Guacamole Manual</em> covers
+ Guacamole version 0.8.3. 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.</p>
+ <a id="idp5920" class="indexterm"></a>
+ <div class="simplesect" title="What is Guacamole?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="idp63376"></a>What is Guacamole?</h2></div></div></div>
+
+ <a id="idp6304" class="indexterm"></a>
+ <p>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.</p>
+ <p>"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.</p>
+ <a id="idp66608" class="indexterm"></a>
+ <p>Historically, Guacamole was an HTML5 VNC client, and before that, a JavaScript
+ Telnet client called <span class="application"><a class="application" href="http://sourceforge.net/projects/realmint" target="_top">RealMint</a></span>
+ ("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.</p>
+ <p>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.</p>
+ <p>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.</p>
+ </div>
+ <div class="simplesect" title="Why use Guacamole?"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="access-from-anywhere"></a>Why use Guacamole?</h2></div></div></div>
+
+ <p>The principle reason to use Guacamole is constant, world-wide, unfettered access
+ to your computers.</p>
+ <p>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.</p>
+ <p>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.</p>
+ </div>
+ <div class="simplesect" title="Access your computers from any device"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="access-from-anything"></a>Access your computers from any device</h2></div></div></div>
+
+ <p>As Guacamole requires only a reasonably-fast, standards-compliant browser,
+ Guacamole will run on many devices, including mobile phones and tablets.</p>
+ <p>Guacamole is specifically designed to not care whether you have a mouse, keyboard,
+ touchscreen, or any combination of those.</p>
+ <p>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.</p>
+ <p>Barring bugs, you should be able to use Guacamole on just about any modern device
+ with a web browser.</p>
+ </div>
+ <div class="simplesect" title="Keep a computer in the "cloud""><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="non-physical-computer"></a>Keep a computer in the "cloud"</h2></div></div></div>
+
+ <p>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.</p>
+ <p>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.</p>
+ <p>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.</p>
+ </div>
+ <div class="simplesect" title="Provide easy access to a group"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="group-access"></a>Provide easy access to a group</h2></div></div></div>
+
+ <p>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.</p>
+ <p>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.</p>
+ </div>
+ <div class="simplesect" title="Adding HTML5 remote access to your existing infrastructure"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="adding-remote-access"></a>Adding HTML5 remote access to your existing infrastructure</h2></div></div></div>
+
+ <p>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.</p>
+ <p>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.</p>
+ </div>
+ </div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="users-guide.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Guacamole Manual </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Part I. User's Guide</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>
+<!-- End Google Analytics -->
+ </body></html>