| <?xml version="1.0" encoding="UTF-8"?> |
| |
| <chapter xml:id="adhoc-connections" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" |
| xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink"> |
| <title>Ad-hoc Connections</title> |
| <indexterm> |
| <primary>connections</primary> |
| <secondary>adhoc</secondary> |
| </indexterm> |
| <indexterm> |
| <primary>adhoc</primary> |
| </indexterm> |
| <indexterm> |
| <primary>quickconnect</primary> |
| </indexterm> |
| <para>The quickconnect extension provides a connection bar on the Guacamole Client home page |
| that allows users to type in the URI of a server to which they want to connect and the client |
| will parse the URI and immediately establish the connection. The purpose of the extension is |
| to allow situations where administrators want to allow users the flexibility of establishing |
| their own connections without having to grant them access to edit connections or even to have |
| to create the connections at all, aside from typing the URI.</para> |
| <important> |
| <para>There are several implications of using this extension that should be well-understood |
| by administrators prior to implementing it:</para> |
| <itemizedlist> |
| <listitem><para>Connections established with this extension are created in-memory |
| and only persist until the Guacamole session ends.</para></listitem> |
| <listitem><para>Connections created with this extension are not accessible to other users, and |
| cannot be shared with other users.</para></listitem> |
| <listitem><para>This extension provides no functionality for authenticating users - it does |
| not allow anonymous logins, and requires that users are successfully authenticated |
| by another authentication module before it can be used.</para></listitem> |
| <listitem><para>The extension provides users the ability not only to establish connections, but |
| also to set any of the parameters for a connection. There are security implications for |
| this - for example, RDP file sharing can be used to pass through any directory available |
| on the server running guacd to the remote desktop. This should be taken into consideration |
| when enabling this extension and making sure that guacd is configured in a way that |
| does not compromise sensitive system files by allowing access to them.</para></listitem> |
| </itemizedlist> |
| </important> |
| <section xml:id="quickconnect-downloading"> |
| <title>Downloading the quickconnect extension</title> |
| <para>The quickconnect extension is available separately from the main |
| <filename>guacamole.war</filename>. The link for this and all other |
| officially-supported and compatible extensions for a particular version of Guacamole are |
| provided in the release notes for that version. You can find the release notes for |
| current versions of Guacamole here: <link |
| xlink:href="http://guacamole.apache.org/releases/" |
| >http://guacamole.apache.org/releases/</link>.</para> |
| <para>The quickconnect extension is packaged as a <filename>.tar.gz</filename> file containing |
| only the extension itself, <filename>guacamole-auth-quickconnect-1.2.0.jar</filename>, which must |
| ultimately be placed in <filename>GUACAMOLE_HOME/extensions</filename>.</para> |
| </section> |
| <section xml:id="installing-quickconnect"> |
| <title>Installing the quickconnect extension</title> |
| <para>Guacamole extensions are self-contained <filename>.jar</filename> files which are |
| located within the <filename>GUACAMOLE_HOME/extensions</filename> directory. |
| <emphasis>If you are unsure where <varname>GUACAMOLE_HOME</varname> is located on |
| your system, please consult <xref linkend="configuring-guacamole"/> before |
| proceeding.</emphasis></para> |
| <para>To install the extension, you must:</para> |
| <procedure> |
| <step> |
| <para>Create the <filename>GUACAMOLE_HOME/extensions</filename> directory, if it |
| does not already exist.</para> |
| </step> |
| <step> |
| <para>Place the <filename>guacamole-auth-quickconnect-1.2.0.jar</filename> file in |
| the <filename>GUACAMOLE_HOME/extensions</filename> directory.</para> |
| </step> |
| </procedure> |
| <section xml:id="guac-quickconnect-config"> |
| <title>Configuring Guacamole for the quickconnect extension</title> |
| <indexterm> |
| <primary>configuring quickconnect</primary> |
| </indexterm> |
| <para>This module has no configuration options.</para> |
| </section> |
| <section xml:id="completing-quickconnect-install"> |
| <title>Completing the installation</title> |
| <para>Guacamole will only load newly-installed extensions during startup, so your |
| servlet container will need to be restarted before the quickconnect extension |
| can be used. <emphasis>Doing this will disconnect all active users, so be sure |
| that it is safe to do so prior to attempting installation.</emphasis> |
| When ready, restart your servlet container and give the extension a try.</para> |
| </section> |
| </section> |
| <section xml:id="using-quickconnect"> |
| <title>Using the quickconnect extension</title> |
| <para>The quickconnect extension provides a field on the home page that allows you to enter |
| a Uniform Resource Identifier (URI) to create a connection. A URI is in the form:</para> |
| <informalexample> |
| <para><uri><replaceable>protocol</replaceable>://<replaceable>username</replaceable>:<replaceable>password</replaceable>@<replaceable>host</replaceable>:<replaceable>port</replaceable>/?<replaceable>parameters</replaceable></uri></para> |
| </informalexample> |
| <para>The <replaceable>protocol</replaceable> field can have any of the protocols supported |
| by Guacamole, as documented in <xref linkend="configuring-guacamole"/>. Many of the |
| protocols define a default <replaceable>port</replaceable> value, with the exception of |
| VNC. The <replaceable>parameters</replaceable> field can specify any of the |
| protocol-specific parameters as documented on the configuration page.</para> |
| <para>To establish a connection, simply type in a valid URI and either press "Enter" or |
| click the connect button. This extension will parse the URI and create a new connection, |
| and immediately start that connection in the current browser.</para> |
| <para>Here are a few examples of URIs:</para> |
| <itemizedlist> |
| <listitem> |
| <informalexample> |
| <para><uri>ssh://linux1.example.com/</uri></para> |
| </informalexample> |
| <para>Connect to the server linux1.example.com using the SSH protocol on the default |
| SSH port (22). This will result in prompting for both username and |
| password.</para> |
| </listitem> |
| <listitem> |
| <informalexample> |
| <para><uri>vnc://linux1.example.com:5900/</uri></para> |
| </informalexample> |
| <para>Connect to the server linux1.example.com using the VNC protocol and specifying |
| the port as 5900.</para> |
| </listitem> |
| <listitem> |
| <informalexample> |
| <para><uri> |
| rdp://localuser@windows1.example.com/?security=rdp&ignore-cert=true&disable-audio=true&enable-drive=true&drive-path=/mnt/usb |
| </uri></para> |
| </informalexample> |
| <para>Connect to the server windows1.example.com using the RDP protocol and the user |
| "localuser". This URI also specifies several RDP-specific parameters on the |
| connection, including forcing security mode to RDP (security=rdp), ignoring any |
| certificate errors (ignore-cert=true), disabling audio pass-through |
| (disable-audio=true), and enabling filesystem redirection (enable-drive=true) to |
| the /mnt/usb folder on the system running guacd (drive-path=/mnt/usb).</para> |
| </listitem> |
| </itemizedlist> |
| </section> |
| </chapter> |