src/chapters/using.xml - guacamole-manual - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <chapter xml:id="using-guacamole"
     xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
     xmlns:xi="http://www.w3.org/2001/XInclude">

     <title>Using Guacamole</title>

     <section xml:id="logging-into-guacamole">
         <title>Logging in</title>
         <indexterm>
             <primary>logging in</primary>
         </indexterm>
         <para>When you visit a Guacamole instance for the first time, you will see the login screen.
             This screen authenticates you with Guacamole, allowing you to use Guacamole to interact
             with one or more remote desktops. </para>
         <para>Enter your username and password and click "login". You will then be given a list of
             available remote desktop connections to choose from. If you have used Guacamole in that
             specific web browser before, you will also see thumbnails of the screens of recently
             used connections. </para>
         <para>Keep in mind this is the login for Guacamole, and not necessarily the login for the
             remote desktop you wish to connect to. The username and password you give Guacamole
             grants you access to the Guacamole system only. The usernames and passwords required for
             the remote desktops you have access to through Guacamole are independent. </para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="../images/login.png" format="PNG" contentwidth="4in"/>
                 </imageobject>
                 <caption>
                     <para> The Guacamole login screen. </para>
                 </caption>
             </mediaobject>
         </informalfigure>
     </section>

     <section xml:id="selecting-a-connection">
         <title>Selecting a connection</title>
         <indexterm>
             <primary>connecting</primary>
         </indexterm>
         <para>Once logged in, you will be presented with a list of connections. Selecting a
             connection from this list will open that connection in a new window or tab. The
             connection list interface will remain open and running in the previous window or tab, as
             it is the only access point for other connections, the clipboard, and settings.</para>
         <para>Multiple connections can be used simultaneously. </para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="../images/connection-list.png" format="PNG"
                         contentwidth="4in"/>
                 </imageobject>
                 <caption>
                     <para> List of available connections. </para>
                 </caption>
             </mediaobject>
         </informalfigure>
         <para>If you don't wish to connect to any desktops, you can also logout from this screen by
             clicking the "logout" button. Beware that this will disconnect you from any of your open
             desktops, if you have any. </para>
     </section>

     <section xml:id="interacting-with-the-desktop">
         <title>Interacting with the remote desktop</title>
         <indexterm>
             <primary>interacting</primary>
         </indexterm>
         <para>Once you open a connection, you will see an image of a desktop. You can interact with
             this image just as you would your normal desktop, or any remote desktop client. </para>
         <para>Clicking on parts of the image will affect the remote desktop as if you were clicking
             on the desktop directly. Typing causes keys to be typed remotely as if you were using a
             keyboard connected directly to the remote machine. </para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="../images/vnc.png" format="PNG" contentwidth="4in"/>
                 </imageobject>
                 <caption>
                     <para> An active remote desktop. </para>
                 </caption>
             </mediaobject>
         </informalfigure>
         <section xml:id="using-the-clipboard">
             <title>Using the clipboard</title>
             <indexterm>
                 <primary>clipboard</primary>
             </indexterm>
             <para>The clipboard can be manipulated using the clipboard editor accessible near the
                 bottom of the connection list interface.</para>
             <para>Web browsers don't provide access to clipboard data, thus true synchronization
                 between your local clipboard and the remote clipboard is impossible. Instead, the
                 clipboard editor acts as an intermediary. You can paste text from your clipboard
                 into the editor, and it will be sent to the remote clipboard. If you cut or copy
                 text remotely, that text will be visible in the clipboard editor locally, where you
                 can then select and copy it.</para>
             <para>All open Guacamole connections use this common clipboard, thus copying and pasting
                 between connections is seamless; you do not need to visit the clipboard editor to
                 copy and paste from one connection to another.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/clipboard.png" format="PNG" contentwidth="3in"
                         />
                     </imageobject>
                     <caption>
                         <para> The editable clipboard contents, accessible from the connection list
                             interface. </para>
                     </caption>
                 </mediaobject>
             </informalfigure>
         </section>
         <section xml:id="using-the-osk">
             <title>Typing with special keys</title>
             <indexterm xmlns:xl="http://www.w3.org/1999/xlink">
                 <primary>on-screen keyboard</primary>
             </indexterm>
             <para>Certain key combinations are impossible to press within a web application like
                 Guacamole because they are reserved by the operating system (Ctrl-Alt-Del or
                 Alt-Tab, for example) or by the web browser. If you press one of these reserved
                 combinations, the effect will be observed locally, not remotely, and the remote
                 desktop will receive only some of the keys. </para>
             <para>Guacamole provides an on-screen keyboard such that key events can be sent to the
                 remote machine without affecting the local browser. You can show the on-screen
                 keyboard by pressing Ctrl-Alt-Shift. Pressing the Ctrl-Alt-Shift again will hide the
                 on-screen keyboard.</para>
             <para>Clicking on the buttons of the on-screen keyboard has the same effect as pressing
                 the same buttons on a real keyboard, except that the operating system and browser
                 will not intercept these keypresses; they will only be sent remotely. </para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/osk.png" format="PNG" contentwidth="4in"/>
                     </imageobject>
                     <caption>
                         <para> The on-screen keyboard. </para>
                     </caption>
                 </mediaobject>
             </informalfigure>
         </section>
         <section xml:id="logging-out-of-guacamole">
             <title>Logging out</title>
             <indexterm>
                 <primary>logging out</primary>
             </indexterm>
             <para>When you are done and wish to logout of Guacamole completely, find the original
                 connection interface tab and click the "logout" button. Beware that this will close
                 all current connections and end your Guacamole session. </para>
             <para>Note that this is not the same as disconnecting from a single connection. To
                 disconnect, simply close the tab or window with the remote desktop in it. Closing a
                 tab or window automatically disconnects from the associated remote desktop without
                 logging you out of Guacamole completely. </para>
             <para>If you logout of Guacamole, all active connections are closed, and can only be
                 accessed by logging in again and reconnecting.</para>
         </section>
     </section>

     <section xml:id="using-touch-devices">
         <title>Using touch devices</title>
         <indexterm xmlns:xl="http://www.w3.org/1999/xlink">
             <primary>touch devices</primary>
         </indexterm>
         <para>Guacamole can be used on devices that have touchscreens, even when
             those touchscreens are the sole means of input, such as most tablets
             and mobile phones.</para>
         <section xml:id="using-mouse">
             <title>Moving the mouse</title>
             <indexterm>
                 <primary>mouse</primary>
             </indexterm>
             <para>As a finger makes for a very inaccurate pointing device,
                 especially for mouse-driven applications designed for precise
                 input, the default mode for touch-based mouse input in Guacamole
                 is touchpad emulation.</para>
             <para>Guacamole's touchpad emulation is similar in behavior to the
                 touchpad present on most modern laptops. Drag your finger across
                 the display to move the mouse pointer, and tap the display to
                 left-click. Right-clicking is accomplished with a two-finger
                 tap, and middle-clicking with a three-finger tap.</para>
             <para>Click-and-drag by tapping the screen and then quickly placing
                 your finger back down. This gesture only causes the mouse button
                 to press down, but does not release it again until you lift your
                 finger back up.</para>
             <para>The mouse scroll wheel can be operated by dragging two fingers
                 up or down.</para>
         </section>
         <section xml:id="zooming">
             <title>Zooming in</title>
             <indexterm>
                 <primary>zoom</primary>
             </indexterm>
             <para>Many touch-enabled devices have small screens, which makes the
                 larger screens of a typical remote desktop hard to see and
                 interact with. If you want to temporarily zoom in, long-press on
                 the display. This will reveal a rectangular magnifier that can
                 be dragged around the screen, revealing detail below it at full
                 resolution.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/android-magnifier.png" format="PNG"
                             contentwidth="4in"/>
                     </imageobject>
                     <caption>
                         <para>The magnifier tool in use</para>
                     </caption>
                 </mediaobject>
             </informalfigure>
             <para>Tapping outside this magnifier closes the magnifier, while
                 tapping inside engages a typing mode.</para>
         </section>
         <section xml:id="typing">
             <title>Typing</title>
             <indexterm>
                 <primary>typing</primary>
             </indexterm>
             <para>In most cases, if your device has a hardware keyboard or you
                 use a bluetooth keyboard, you will not need to do anything
                 special in order to type; you can just press keys and expect the
                 same effect you would have on a desktop.</para>
             <para>For devices that lack a hardware keyboard, you need to bring
                 Guacamole into "typing mode" by long-pressing on the display to
                 bring up the magnifier. Tap on the magnifier to bring up your
                 device's on-screen keyboard.</para>
         </section>
         <section xml:id="panning">
             <title>Panning</title>
             <indexterm>
                 <primary>panning</primary>
             </indexterm>
             <para>Because Guacamole uses all touch events to drive mouse input,
                 the normal gestures for scrolling the screen will not work.
                 Depending on how big your screen is, and whether the display is
                 currently zoomed, you have three options for panning the screen:<orderedlist>
                     <listitem>
                         <para>Move the mouse</para>
                         <para>Moving the mouse beyond the bounds of the screen
                             of the device will cause the display to
                             automatically scroll until the mouse pointer is in
                             view again. This will only work if the screen is not
                             already fully visible.</para>
                     </listitem>
                     <listitem>
                         <para>Long-press to bring up panning mode</para>
                         <para>If the remote display is already fully visible,
                             long-pressing will not bring up the magnifier, but
                             will instead put Guacamole in a panning mode. Arrows
                             will appear at the sides of the screen, and you can
                             drag around the screen as normal. Tapping on the
                             screen will put Guacamole in typing mode, allowing
                             you to type and use your native on-screen keyboard
                             (if any).</para>
                         <informalfigure>
                             <mediaobject>
                                 <imageobject>
                                     <imagedata fileref="../images/android-panning.png" format="PNG"
                                         contentwidth="4in"/>
                                 </imageobject>
                                 <caption>
                                     <para>Panning mode</para>
                                 </caption>
                             </mediaobject>
                         </informalfigure>
                     </listitem>
                     <listitem>
                         <para>Bring up the magnifier, tap to put Guacamole in
                             typing/panning mode, and then drag the screen</para>
                         <para>When in typing mode, dragging your finger on the
                             screen will cause the screen to pan as it normally
                             would. This is useful while typing, especially if
                             what you're typing starts to run off the visible
                             area of your device's screen.</para>
                     </listitem>
                 </orderedlist></para>
         </section>
     </section>
     <section xml:id="changing-settings">
         <title>Changing settings</title>
         <indexterm>
             <primary>settings</primary>
         </indexterm>
         <para>Guacamole's settings section is located within the connection interface, and affects
             the behavior of all active and future Guacamole connections. Unless specified otherwise,
             changing a setting affects current Guacamole connections immediately.</para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="../images/settings.png" format="PNG" contentwidth="3in"/>
                 </imageobject>
                 <caption>
                     <para>Guacamole settings, accessible from the connection list interface. </para>
                 </caption>
             </mediaobject>
         </informalfigure>
         <section xml:id="disabling-sound">
             <title>Disabling sound</title>
             <indexterm>
                 <primary>audio</primary>
                 <secondary>disabling</secondary>
             </indexterm>
             <indexterm>
                 <primary>sound</primary>
                 <secondary>disabling</secondary>
             </indexterm>
             <indexterm>
                 <primary>disabling sound</primary>
             </indexterm>
             <para>Sound can sometimes cause problems if your browser is too slow or if you lack
                 sufficient network bandwidth. In some cases, browsers do not actually support sound,
                 but misreport that they do to Guacamole, causing wasted bandwidth when Guacamole
                 sends audio data that can't actually be played.</para>
             <para>To disable sound, check the "Disable sound" checkbox in the settings
                 section.</para>
         </section>
         <section xml:id="disabling-auto-fit">
             <title>Disabling auto-fit of the display</title>
             <indexterm>
                 <primary>auto-fit</primary>
                 <secondary>disabling</secondary>
             </indexterm>
             <indexterm>
                 <primary>disabling auto-fit</primary>
             </indexterm>
             <para>Normally, scrolling around the screen is troublesome and distracting if the remote
                 display you're using is larger than the display of your device. Because of this, the
                 remote display will automatically fit itself to the available space by default. If
                 this is undesirable, you can manually disable this on a per-browser basis in the
                 settings section.</para>
             <para>To disable auto-fit, uncheck the "Auto-fit display to browser window" checkbox in
                 the settings section.</para>
         </section>
     </section>
     <section xml:id="guacamole-admin-ui">
         <title>Administration</title>
         <indexterm>
             <primary>administration</primary>
         </indexterm>
         <para>Users and connections can be administered from within the web interface if the
             underlying authentication module supports this. The only officially-supported
             authentication module supporting this is the MySQL authentication provider, which is
             documented in a different chapter.</para>
         <para>If you are using the default authentication mechanism, this
             section does not apply to you, and the Guacamole web interface will
             appear as it did in past releases. If, on the other hand, you are
             using the MySQL authentication provider, and you are logged in as an
             administrator, you will see a "Manage" button next to the "Logout"
             button at the top of the screen.</para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="../images/manage-button.png" format="PNG" contentwidth="3in"
                     />
                 </imageobject>
                 <caption>
                     <para>The "Manage" button</para>
                 </caption>
             </mediaobject>
         </informalfigure>
         <para>Clicking this button takes you to an administration screen where
             you can add or manipulate users and connections, depending on your
             permissions.</para>
         <section>
             <title>Managing users</title>
             <indexterm>
                 <primary>user management</primary>
             </indexterm>
             <para>Once at the administration screen, you will see two sections
                 displaying all visible users and connections. The visibility of
                 these sections depends on your user's permissions. If you lack
                 permission to manage users, the user management section will not
                 display. The same goes for management of connections.</para>
             <para>To add a new user, type the username of the new user within
                 the text box inside the user management section, and click the
                 "Add" button. The new user will be added and made available. The
                 new user will have no access to any existing connections, no
                 administrative privileges, and no password, and will not be able
                 to login. You will need to set the user's password first in
                 order to allow login.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/manage-users.png" format="PNG"
                             contentwidth="3in"/>
                     </imageobject>
                     <caption>
                         <para>User management interface</para>
                     </caption>
                 </mediaobject>
             </informalfigure>
             <para>To edit a user, just click on the user you wish to edit. A small dialog will
                 display allowing you to change the user's password, add or remove administrative
                 permissions, and add or remove access to specific connections or groups.</para>
             <para>If you have delete permission on the user, you will also see a
                 "Delete" button. Clicking this button will permanently delete
                 the user.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/edit-user.png" format="PNG" contentwidth="2in"
                         />
                     </imageobject>
                     <caption>
                         <para>Editing a user</para>
                     </caption>
                 </mediaobject>
             </informalfigure>
         </section>
         <section>
             <title>Managing connections</title>
             <indexterm>
                 <primary>connection management</primary>
             </indexterm>
             <para>To add a new connection, click the "New Connection" button. A connection creation
                 dialog will appear, allowing you to enter the details of the connection, such as its
                 location, parameters, and name. This name should be descriptive, but must also be
                 unique.</para>
             <para>Once you click "Save", the new connection will be added, but will initially only
                 be usable by administrators and your current user. To add access to the new
                 connection to another existing user, you must edit that user, checking the box
                 corresponding to the new connection.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/manage-connections.png" format="PNG"
                             contentwidth="3in"/>
                     </imageobject>
                     <caption>
                         <para>Connection management interface</para>
                     </caption>
                 </mediaobject>
             </informalfigure>
             <para>Editing a connection works identically to editing a user.
                 Click on the connection you wish to edit. A dialog will pop up
                 displaying all parameters associated with the connection,
                 allowing you to change the protocol, associated parameters, and
                 to view the connection history.</para>
             <para>Connections can also be renamed or moved by altering the contents of the "Name" or
                 "Location" fields.</para>
             <para>If you have delete permission on the connection, you will also
                 see a "Delete" button. Clicking this button will permanently
                 delete the connection.</para>
             <informalfigure>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="../images/edit-connection.png" format="PNG"
                             contentwidth="2in"/>
                     </imageobject>
                     <caption>
                         <para>Editing a connection</para>
                     </caption>
                 </mediaobject>
             </informalfigure>
             <section>
                 <title>Grouping connections</title>
                 <indexterm>
                     <primary>connection groups</primary>
                 </indexterm>
                 <indexterm>
                     <primary>groups</primary>
                 </indexterm>
                 <para>Connections can be placed within groups for purposes of organization or load
                     balancing. Each group is displayed in connection lists as a "+" symbol followed
                     by its name. The group can be expanded revealing any contained connections or
                     groups. If the group is a balancing group, the group can be used as a
                     connection, and the least-used contained connection will be used.</para>
                 <para>To add a new connection group, click the "New Group" button. A connection
                     group creation dialog will appear, allowing you to enter the details of the
                     group. Just as with connections, you can enter the location and name, which
                     should be descriptive and unique. Duplicate names are not allowed.</para>
                 <informalfigure>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="../images/edit-group.png" format="PNG"
                                 contentwidth="3in"/>
                         </imageobject>
                         <caption>
                             <para>Editing a connection group</para>
                         </caption>
                     </mediaobject>
                 </informalfigure>
                 <para>You can edit existing connection groups by clicking on them within the
                     administration interface, just like with users and connections. From within the
                     dialog that appears, you can rename, move, and change the properties of existing
                     connection groups.</para>
             </section>
             <section>
                 <title>Balancing vs. organizational groups</title>
                 <para>Connection groups can be either "organizational" or "balancing". Each group
                     can contain any number of other connections or groups, but the semantics of the
                     group change depending on the type.</para>
                 <para>An organizational group behaves exactly as a folder or directory in a file
                     system. It simply contains connections and other groups, but provides no other
                     behavior. Clicking on an organizational group within a connection list will
                     expand the group, revealing its contents.</para>
                 <para>A balancing group behaves as a connection. It dynamically balances load across
                     the connections it contains, choosing the connection with the fewest number of
                     active users. Unlike organizational groups, clicking on a balancing group causes
                     a new connection to be opened. The actual underlying connection used depends on
                     which connection has the least load at the time the group was clicked.</para>
             </section>
         </section>
     </section>

 </chapter>
	<?xml version="1.0" encoding="UTF-8"?>

	<chapter xml:id="using-guacamole"
	xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en"
	xmlns:xi="http://www.w3.org/2001/XInclude">

	<title>Using Guacamole</title>

	<section xml:id="logging-into-guacamole">
	<title>Logging in</title>
	<indexterm>
	<primary>logging in</primary>
	</indexterm>
	<para>When you visit a Guacamole instance for the first time, you will see the login screen.
	This screen authenticates you with Guacamole, allowing you to use Guacamole to interact
	with one or more remote desktops. </para>
	<para>Enter your username and password and click "login". You will then be given a list of
	available remote desktop connections to choose from. If you have used Guacamole in that
	specific web browser before, you will also see thumbnails of the screens of recently
	used connections. </para>
	<para>Keep in mind this is the login for Guacamole, and not necessarily the login for the
	remote desktop you wish to connect to. The username and password you give Guacamole
	grants you access to the Guacamole system only. The usernames and passwords required for
	the remote desktops you have access to through Guacamole are independent. </para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/login.png" format="PNG" contentwidth="4in"/>
	</imageobject>
	<caption>
	<para> The Guacamole login screen. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	</section>

	<section xml:id="selecting-a-connection">
	<title>Selecting a connection</title>
	<indexterm>
	<primary>connecting</primary>
	</indexterm>
	<para>Once logged in, you will be presented with a list of connections. Selecting a
	connection from this list will open that connection in a new window or tab. The
	connection list interface will remain open and running in the previous window or tab, as
	it is the only access point for other connections, the clipboard, and settings.</para>
	<para>Multiple connections can be used simultaneously. </para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/connection-list.png" format="PNG"
	contentwidth="4in"/>
	</imageobject>
	<caption>
	<para> List of available connections. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>If you don't wish to connect to any desktops, you can also logout from this screen by
	clicking the "logout" button. Beware that this will disconnect you from any of your open
	desktops, if you have any. </para>
	</section>

	<section xml:id="interacting-with-the-desktop">
	<title>Interacting with the remote desktop</title>
	<indexterm>
	<primary>interacting</primary>
	</indexterm>
	<para>Once you open a connection, you will see an image of a desktop. You can interact with
	this image just as you would your normal desktop, or any remote desktop client. </para>
	<para>Clicking on parts of the image will affect the remote desktop as if you were clicking
	on the desktop directly. Typing causes keys to be typed remotely as if you were using a
	keyboard connected directly to the remote machine. </para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/vnc.png" format="PNG" contentwidth="4in"/>
	</imageobject>
	<caption>
	<para> An active remote desktop. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	<section xml:id="using-the-clipboard">
	<title>Using the clipboard</title>
	<indexterm>
	<primary>clipboard</primary>
	</indexterm>
	<para>The clipboard can be manipulated using the clipboard editor accessible near the
	bottom of the connection list interface.</para>
	<para>Web browsers don't provide access to clipboard data, thus true synchronization
	between your local clipboard and the remote clipboard is impossible. Instead, the
	clipboard editor acts as an intermediary. You can paste text from your clipboard
	into the editor, and it will be sent to the remote clipboard. If you cut or copy
	text remotely, that text will be visible in the clipboard editor locally, where you
	can then select and copy it.</para>
	<para>All open Guacamole connections use this common clipboard, thus copying and pasting
	between connections is seamless; you do not need to visit the clipboard editor to
	copy and paste from one connection to another.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/clipboard.png" format="PNG" contentwidth="3in"
	/>
	</imageobject>
	<caption>
	<para> The editable clipboard contents, accessible from the connection list
	interface. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	</section>
	<section xml:id="using-the-osk">
	<title>Typing with special keys</title>
	<indexterm xmlns:xl="http://www.w3.org/1999/xlink">
	<primary>on-screen keyboard</primary>
	</indexterm>
	<para>Certain key combinations are impossible to press within a web application like
	Guacamole because they are reserved by the operating system (Ctrl-Alt-Del or
	Alt-Tab, for example) or by the web browser. If you press one of these reserved
	combinations, the effect will be observed locally, not remotely, and the remote
	desktop will receive only some of the keys. </para>
	<para>Guacamole provides an on-screen keyboard such that key events can be sent to the
	remote machine without affecting the local browser. You can show the on-screen
	keyboard by pressing Ctrl-Alt-Shift. Pressing the Ctrl-Alt-Shift again will hide the
	on-screen keyboard.</para>
	<para>Clicking on the buttons of the on-screen keyboard has the same effect as pressing
	the same buttons on a real keyboard, except that the operating system and browser
	will not intercept these keypresses; they will only be sent remotely. </para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/osk.png" format="PNG" contentwidth="4in"/>
	</imageobject>
	<caption>
	<para> The on-screen keyboard. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	</section>
	<section xml:id="logging-out-of-guacamole">
	<title>Logging out</title>
	<indexterm>
	<primary>logging out</primary>
	</indexterm>
	<para>When you are done and wish to logout of Guacamole completely, find the original
	connection interface tab and click the "logout" button. Beware that this will close
	all current connections and end your Guacamole session. </para>
	<para>Note that this is not the same as disconnecting from a single connection. To
	disconnect, simply close the tab or window with the remote desktop in it. Closing a
	tab or window automatically disconnects from the associated remote desktop without
	logging you out of Guacamole completely. </para>
	<para>If you logout of Guacamole, all active connections are closed, and can only be
	accessed by logging in again and reconnecting.</para>
	</section>
	</section>

	<section xml:id="using-touch-devices">
	<title>Using touch devices</title>
	<indexterm xmlns:xl="http://www.w3.org/1999/xlink">
	<primary>touch devices</primary>
	</indexterm>
	<para>Guacamole can be used on devices that have touchscreens, even when
	those touchscreens are the sole means of input, such as most tablets
	and mobile phones.</para>
	<section xml:id="using-mouse">
	<title>Moving the mouse</title>
	<indexterm>
	<primary>mouse</primary>
	</indexterm>
	<para>As a finger makes for a very inaccurate pointing device,
	especially for mouse-driven applications designed for precise
	input, the default mode for touch-based mouse input in Guacamole
	is touchpad emulation.</para>
	<para>Guacamole's touchpad emulation is similar in behavior to the
	touchpad present on most modern laptops. Drag your finger across
	the display to move the mouse pointer, and tap the display to
	left-click. Right-clicking is accomplished with a two-finger
	tap, and middle-clicking with a three-finger tap.</para>
	<para>Click-and-drag by tapping the screen and then quickly placing
	your finger back down. This gesture only causes the mouse button
	to press down, but does not release it again until you lift your
	finger back up.</para>
	<para>The mouse scroll wheel can be operated by dragging two fingers
	up or down.</para>
	</section>
	<section xml:id="zooming">
	<title>Zooming in</title>
	<indexterm>
	<primary>zoom</primary>
	</indexterm>
	<para>Many touch-enabled devices have small screens, which makes the
	larger screens of a typical remote desktop hard to see and
	interact with. If you want to temporarily zoom in, long-press on
	the display. This will reveal a rectangular magnifier that can
	be dragged around the screen, revealing detail below it at full
	resolution.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/android-magnifier.png" format="PNG"
	contentwidth="4in"/>
	</imageobject>
	<caption>
	<para>The magnifier tool in use</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>Tapping outside this magnifier closes the magnifier, while
	tapping inside engages a typing mode.</para>
	</section>
	<section xml:id="typing">
	<title>Typing</title>
	<indexterm>
	<primary>typing</primary>
	</indexterm>
	<para>In most cases, if your device has a hardware keyboard or you
	use a bluetooth keyboard, you will not need to do anything
	special in order to type; you can just press keys and expect the
	same effect you would have on a desktop.</para>
	<para>For devices that lack a hardware keyboard, you need to bring
	Guacamole into "typing mode" by long-pressing on the display to
	bring up the magnifier. Tap on the magnifier to bring up your
	device's on-screen keyboard.</para>
	</section>
	<section xml:id="panning">
	<title>Panning</title>
	<indexterm>
	<primary>panning</primary>
	</indexterm>
	<para>Because Guacamole uses all touch events to drive mouse input,
	the normal gestures for scrolling the screen will not work.
	Depending on how big your screen is, and whether the display is
	currently zoomed, you have three options for panning the screen:<orderedlist>
	<listitem>
	<para>Move the mouse</para>
	<para>Moving the mouse beyond the bounds of the screen
	of the device will cause the display to
	automatically scroll until the mouse pointer is in
	view again. This will only work if the screen is not
	already fully visible.</para>
	</listitem>
	<listitem>
	<para>Long-press to bring up panning mode</para>
	<para>If the remote display is already fully visible,
	long-pressing will not bring up the magnifier, but
	will instead put Guacamole in a panning mode. Arrows
	will appear at the sides of the screen, and you can
	drag around the screen as normal. Tapping on the
	screen will put Guacamole in typing mode, allowing
	you to type and use your native on-screen keyboard
	(if any).</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/android-panning.png" format="PNG"
	contentwidth="4in"/>
	</imageobject>
	<caption>
	<para>Panning mode</para>
	</caption>
	</mediaobject>
	</informalfigure>
	</listitem>
	<listitem>
	<para>Bring up the magnifier, tap to put Guacamole in
	typing/panning mode, and then drag the screen</para>
	<para>When in typing mode, dragging your finger on the
	screen will cause the screen to pan as it normally
	would. This is useful while typing, especially if
	what you're typing starts to run off the visible
	area of your device's screen.</para>
	</listitem>
	</orderedlist></para>
	</section>
	</section>
	<section xml:id="changing-settings">
	<title>Changing settings</title>
	<indexterm>
	<primary>settings</primary>
	</indexterm>
	<para>Guacamole's settings section is located within the connection interface, and affects
	the behavior of all active and future Guacamole connections. Unless specified otherwise,
	changing a setting affects current Guacamole connections immediately.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/settings.png" format="PNG" contentwidth="3in"/>
	</imageobject>
	<caption>
	<para>Guacamole settings, accessible from the connection list interface. </para>
	</caption>
	</mediaobject>
	</informalfigure>
	<section xml:id="disabling-sound">
	<title>Disabling sound</title>
	<indexterm>
	<primary>audio</primary>
	<secondary>disabling</secondary>
	</indexterm>
	<indexterm>
	<primary>sound</primary>
	<secondary>disabling</secondary>
	</indexterm>
	<indexterm>
	<primary>disabling sound</primary>
	</indexterm>
	<para>Sound can sometimes cause problems if your browser is too slow or if you lack
	sufficient network bandwidth. In some cases, browsers do not actually support sound,
	but misreport that they do to Guacamole, causing wasted bandwidth when Guacamole
	sends audio data that can't actually be played.</para>
	<para>To disable sound, check the "Disable sound" checkbox in the settings
	section.</para>
	</section>
	<section xml:id="disabling-auto-fit">
	<title>Disabling auto-fit of the display</title>
	<indexterm>
	<primary>auto-fit</primary>
	<secondary>disabling</secondary>
	</indexterm>
	<indexterm>
	<primary>disabling auto-fit</primary>
	</indexterm>
	<para>Normally, scrolling around the screen is troublesome and distracting if the remote
	display you're using is larger than the display of your device. Because of this, the
	remote display will automatically fit itself to the available space by default. If
	this is undesirable, you can manually disable this on a per-browser basis in the
	settings section.</para>
	<para>To disable auto-fit, uncheck the "Auto-fit display to browser window" checkbox in
	the settings section.</para>
	</section>
	</section>
	<section xml:id="guacamole-admin-ui">
	<title>Administration</title>
	<indexterm>
	<primary>administration</primary>
	</indexterm>
	<para>Users and connections can be administered from within the web interface if the
	underlying authentication module supports this. The only officially-supported
	authentication module supporting this is the MySQL authentication provider, which is
	documented in a different chapter.</para>
	<para>If you are using the default authentication mechanism, this
	section does not apply to you, and the Guacamole web interface will
	appear as it did in past releases. If, on the other hand, you are
	using the MySQL authentication provider, and you are logged in as an
	administrator, you will see a "Manage" button next to the "Logout"
	button at the top of the screen.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/manage-button.png" format="PNG" contentwidth="3in"
	/>
	</imageobject>
	<caption>
	<para>The "Manage" button</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>Clicking this button takes you to an administration screen where
	you can add or manipulate users and connections, depending on your
	permissions.</para>
	<section>
	<title>Managing users</title>
	<indexterm>
	<primary>user management</primary>
	</indexterm>
	<para>Once at the administration screen, you will see two sections
	displaying all visible users and connections. The visibility of
	these sections depends on your user's permissions. If you lack
	permission to manage users, the user management section will not
	display. The same goes for management of connections.</para>
	<para>To add a new user, type the username of the new user within
	the text box inside the user management section, and click the
	"Add" button. The new user will be added and made available. The
	new user will have no access to any existing connections, no
	administrative privileges, and no password, and will not be able
	to login. You will need to set the user's password first in
	order to allow login.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/manage-users.png" format="PNG"
	contentwidth="3in"/>
	</imageobject>
	<caption>
	<para>User management interface</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>To edit a user, just click on the user you wish to edit. A small dialog will
	display allowing you to change the user's password, add or remove administrative
	permissions, and add or remove access to specific connections or groups.</para>
	<para>If you have delete permission on the user, you will also see a
	"Delete" button. Clicking this button will permanently delete
	the user.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/edit-user.png" format="PNG" contentwidth="2in"
	/>
	</imageobject>
	<caption>
	<para>Editing a user</para>
	</caption>
	</mediaobject>
	</informalfigure>
	</section>
	<section>
	<title>Managing connections</title>
	<indexterm>
	<primary>connection management</primary>
	</indexterm>
	<para>To add a new connection, click the "New Connection" button. A connection creation
	dialog will appear, allowing you to enter the details of the connection, such as its
	location, parameters, and name. This name should be descriptive, but must also be
	unique.</para>
	<para>Once you click "Save", the new connection will be added, but will initially only
	be usable by administrators and your current user. To add access to the new
	connection to another existing user, you must edit that user, checking the box
	corresponding to the new connection.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/manage-connections.png" format="PNG"
	contentwidth="3in"/>
	</imageobject>
	<caption>
	<para>Connection management interface</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>Editing a connection works identically to editing a user.
	Click on the connection you wish to edit. A dialog will pop up
	displaying all parameters associated with the connection,
	allowing you to change the protocol, associated parameters, and
	to view the connection history.</para>
	<para>Connections can also be renamed or moved by altering the contents of the "Name" or
	"Location" fields.</para>
	<para>If you have delete permission on the connection, you will also
	see a "Delete" button. Clicking this button will permanently
	delete the connection.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/edit-connection.png" format="PNG"
	contentwidth="2in"/>
	</imageobject>
	<caption>
	<para>Editing a connection</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<section>
	<title>Grouping connections</title>
	<indexterm>
	<primary>connection groups</primary>
	</indexterm>
	<indexterm>
	<primary>groups</primary>
	</indexterm>
	<para>Connections can be placed within groups for purposes of organization or load
	balancing. Each group is displayed in connection lists as a "+" symbol followed
	by its name. The group can be expanded revealing any contained connections or
	groups. If the group is a balancing group, the group can be used as a
	connection, and the least-used contained connection will be used.</para>
	<para>To add a new connection group, click the "New Group" button. A connection
	group creation dialog will appear, allowing you to enter the details of the
	group. Just as with connections, you can enter the location and name, which
	should be descriptive and unique. Duplicate names are not allowed.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="../images/edit-group.png" format="PNG"
	contentwidth="3in"/>
	</imageobject>
	<caption>
	<para>Editing a connection group</para>
	</caption>
	</mediaobject>
	</informalfigure>
	<para>You can edit existing connection groups by clicking on them within the
	administration interface, just like with users and connections. From within the
	dialog that appears, you can rename, move, and change the properties of existing
	connection groups.</para>
	</section>
	<section>
	<title>Balancing vs. organizational groups</title>
	<para>Connection groups can be either "organizational" or "balancing". Each group
	can contain any number of other connections or groups, but the semantics of the
	group change depending on the type.</para>
	<para>An organizational group behaves exactly as a folder or directory in a file
	system. It simply contains connections and other groups, but provides no other
	behavior. Clicking on an organizational group within a connection list will
	expand the group, revealing its contents.</para>
	<para>A balancing group behaves as a connection. It dynamically balances load across
	the connections it contains, choosing the connection with the fewest number of
	active users. Unlike organizational groups, clicking on a balancing group causes
	a new connection to be opened. The actual underlying connection used depends on
	which connection has the least load at the time the group was clicked.</para>
	</section>
	</section>
	</section>

	</chapter>