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>
     <para><indexterm>
             <primary>interacting</primary>
         </indexterm>Guacamole provides access to much of the functionality of a desktop from within
         your web browser. Although most people use remote desktop tools only when absolutely
         necessary, we believe that Guacamole must be aimed at becoming a primary means of accessing
         desktops, and the interface is thus intended to be as seamless and unobtrusive as
         possible.</para>
     <section xml:id="home-screen">
         <title>Home screen</title>
         <para>Once you have successfully logged in, you will be taken to either the Guacamole home
             screen, where all available connections are listed, or directly to a connection, if you
             only have access to one connection.</para>
         <para>The list of connections on the home screen contains all connections for which you have
             been granted access. If you have used Guacamole in this specific web browser before, you
             will also see thumbnails of recently used connections.</para>
         <informalfigure>
             <screenshot>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="images/guacamole-home-screen.png" format="PNG"
                             contentwidth="5in"/>
                     </imageobject>
                     <caption>
                         <para>The Guacamole home screen. The user menu and several recently-used
                             connections are visible, along with one active connection.</para>
                     </caption>
                 </mediaobject>
             </screenshot>
         </informalfigure>
         <para>Clicking on any connection will open that connection within the current window or tab,
             but multiple connections can be used simultaneously. You can easily navigate back to the
             home screen without disconnecting by using your browsers back button or the "Home"
             button in the Guacamole menu. Each connection you use will remain active until
             explicitly disconnected, or until you navigate away from Guacamole entirely. Active
             connections can be seen as thumbnails updating in real-time on the home screen.</para>
         <section xml:id="user-menu">
             <title>User menu</title>
             <para>With the exception of the client screen discussed below, all Guacamole screens
                 contain a menu in the upper-right corner called the "user menu". This menu displays
                 your username and contains several options which depend on your user's level of
                 access:</para>
             <variablelist>
                 <varlistentry>
                     <term>Home</term>
                     <listitem>
                         <para>Navigates back to the home screen, if you are not already there. If
                             you only have access to one connection, this will be replaced with a
                             link to that connection.</para>
                     </listitem>
                 </varlistentry>
                 <varlistentry>
                     <term>Settings</term>
                     <listitem>
                         <para>Navigates to the settings interface, which provides access to user
                             preferences such as display language. If you have access to
                             administrative functions, those are found within the settings interface,
                             as well, and are discussed in more detail in <xref
                                 linkend="administration"/>.</para>
                     </listitem>
                 </varlistentry>
                 <varlistentry>
                     <term>Logout</term>
                     <listitem>
                         <para>Logs out of Guacamole completely, closing all current connections and
                             ending the Guacamole session.</para>
                     </listitem>
                 </varlistentry>
             </variablelist>
         </section>
     </section>
     <section xml:id="client-screen">
         <title>Client screen</title>
         <para>Once you open a connection, you will see a real-time view of the remote display. You
             can interact with this display just as you would your normal desktop. Your mouse and
             keyboard will function as if they were connected directly to the remote machine.</para>
         <informalfigure>
             <screenshot>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="images/guacamole-client-interface.png" format="PNG"
                             contentwidth="6in"/>
                     </imageobject>
                     <caption>
                         <para>Guacamole client interface, with the Guacamole menu open.</para>
                     </caption>
                 </mediaobject>
             </screenshot>
         </informalfigure>
         <para>The remote display will take up the entire browser window, with no buttons or menus to
             disturb the view. With the intent of providing a seamless experience, options specific
             to remote desktop are hidden within the Guacamole menu, which can be opened as
             needed.</para>
         <section xml:id="guacamole-menu">
             <title>The Guacamole menu</title>
             <para>The Guacamole menu is a sidebar which is hidden until explicitly shown. On a
                 desktop or other device which has a hardware keyboard, you can show this menu by
                 pressing <keycombo>
                     <keycap>Ctrl</keycap>
                     <keycap>Alt</keycap>
                     <keycap>Shift</keycap>
                 </keycombo>. If you are using a mobile or touchscreen device that lacks a keyboard,
                 you can also show the menu by swiping right from the left edge of the screen. To
                 hide the menu, you press <keycombo>
                     <keycap>Ctrl</keycap>
                     <keycap>Alt</keycap>
                     <keycap>Shift</keycap>
                 </keycombo> again or swipe left across the screen.</para>
             <para>The Guacamole menu provides options for:<itemizedlist>
                     <listitem>
                         <para>Navigating back to the home screen</para>
                     </listitem>
                     <listitem>
                         <para>Reading from (and writing to) the clipboard of the remote
                             desktop</para>
                     </listitem>
                     <listitem>
                         <para>Uploading files and monitoring file transfer progress</para>
                     </listitem>
                     <listitem>
                         <para>Selecting alternative methods of typing or controlling the mouse,
                             particularly for use on mobile or touchscreen devices</para>
                     </listitem>
                     <listitem>
                         <para>Zooming in and out of the remote display</para>
                     </listitem>
                     <listitem>
                         <para>Disconnecting from the current connection entirely</para>
                     </listitem>
                 </itemizedlist></para>
         </section>
     </section>
     <section xml:id="using-the-clipboard">
         <title>Copying/pasting text</title>
         <para><indexterm>
                 <primary>clipboard</primary>
             </indexterm>At the top of the Guacamole menu is a text area labeled "clipboard" along
             with some basic instructions:</para>
         <blockquote>
             <para>Text copied/cut within Guacamole will appear here. Changes to the text below will
                 affect the remote clipboard.</para>
         </blockquote>
         <para>The text area functions as an interface between the remote clipboard and the local
             clipboard. Text from the local clipboard can be pasted into the text area, causing that
             text to be sent to the clipboard of the remote desktop. Similarly, if you copy or cut
             text within the remote desktop, you will see that text within the text area, and can
             manually copy it into the local clipboard if desired.</para>
     </section>
     <section xml:id="client-user-menu">
         <title>Disconnecting and navigation</title>
         <para>When you are done using the current connection, or you wish to navigate elsewhere
             temporarily, options to do so are within the user menu inside the Guacamole menu:</para>
         <informalfigure>
             <mediaobject>
                 <imageobject>
                     <imagedata fileref="images/guac-menu-disconnect.png" format="PNG"
                         contentwidth="6in"/>
                 </imageobject>
                 <caption>
                     <para>The user menu within the Guacamole menu.</para>
                 </caption>
             </mediaobject>
             <para>The user menu within the Guacamole menu provides an additional "Disconnect" option
                 that allows you to explicitly close the current connection only. Clicking "Logout"
                 will also implicitly disconnect all active connections, including the current
                 connection.</para>
             <para>Navigating back to the home screen or to the settings screen will not disconnect
                 you: your connection will continue running in the background while you change
                 settings or initiate another connection, and you can resume any active connection by
                 clicking on it within the home screen.</para>
         </informalfigure>
     </section>
     <section xml:id="file-transfer">
         <title>Transferring files</title>
         <indexterm>
             <primary>file transfer</primary>
         </indexterm>
         <para>You can transfer files back and forth between your local computer and the remote
             desktop if it is supported by the underlying protocol and enabled on the connection.
             Currently, both RDP and SSH have support for file transfer, though with slightly
             different semantics. RDP provides file transfer by emulating a virtual drive, while SSH
             provides file transfer by using SFTP.</para>
         <para>To transfer files to the remote computer, drag the files into your browser window, or
             use the "Upload Files" button within the Guacamole menu. If file transfer is enabled,
             you will see a progress indicator appear within the menu. If file transfer is not
             enabled or not supported, you will instead see a notification with an error message
             describing the problem. Completed transfers can be removed from the list by clicking
             "Clear Completed Transfers".</para>
         <para>The method for downloading files from the remote computer depends on the protocol. In
             the case of RDP, you must drag, copy, move, or save the files into the special
             "Download" folder located in the virtual drive. All files dropped into this folder will
             automatically begin uploading to the client, and thus downloading through your
             browser.</para>
         <para><indexterm>
                 <primary>guacctl</primary>
             </indexterm>To download files over SSH, you must use the <command>guacctl</command>
             utility. The <command>guacctl</command> utility is a simple shell script that is <link
                 xmlns:xlink="http://www.w3.org/1999/xlink"
                 xlink:href="https://raw.githubusercontent.com/glyptodon/guacamole-server/master/bin/guacctl"
                 >included with Guacamole</link> and allows you to initiate a file download or to
             change the directory in which uploaded files will be placed:</para>
         <informalexample>
             <screen><prompt>$</prompt> <userinput>guacctl</userinput>
 <computeroutput>guacctl 0.8.0, Guacamole SSH session control utility.
 Usage: guacctl [OPTION] [FILE]...

     -d, --download         download each of the files listed.
     -s, --set-directory    set the destination directory for future uploaded
                            files.</computeroutput>
 <prompt>$</prompt> <userinput>guacctl -d <replaceable>FILENAME</replaceable></userinput>
 <prompt>$</prompt> <userinput>guacctl -s <replaceable>DIRECTORY</replaceable></userinput>
 $</screen>
         </informalexample>
         <para>You may also create a symbolic link or alias to <command>guacctl</command> called
                 <command>guacget</command>. When run as <command>guacget</command>, it behaves as if
             the <option>--download</option> option was supplied and initiates a download for each
             file specified on the command line.</para>
     </section>
     <section xml:id="using-the-osk">
         <title>On-screen keyboard</title>
         <para>Certain key combinations are impossible to press within a web application like
             Guacamole because they are reserved by the operating system (<keycombo>
                 <keycap>Ctrl</keycap>
                 <keycap>Alt</keycap>
                 <keycap>Del</keycap>
             </keycombo> or <keycombo>
                 <keycap>Alt</keycap>
                 <keycap>Tab</keycap>
             </keycombo>, 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 its own, built-in on-screen keyboard which allows keys to be sent
             to the remote desktop without affecting the local system. If the device you're using
             does not have certain keys which the remote desktop depends on, such as the arrow keys
             or <keycap>Ctrl</keycap>, you can use the on-screen keyboard for this, too. You can show
             the on-screen keyboard by selecting the "On-screen keyboard" option from the
             menu.</para>
         <para>Clicking (or tapping) 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 to the remote
             desktop.</para>
     </section>
     <section xml:id="scaling-display">
         <title>Scaling the display</title>
         <para><indexterm>
                 <primary>zoom</primary>
             </indexterm>Guacamole will default to shrinking or expanding the remote display to fit
             the browser window exactly, but this is not necessarily ideal. If the remote display is
             much larger than your local display, the screen may be impossible to see or interact
             with. This is especially true for mobile phones, whose screens need to be small enough
             to fit in the average hand.</para>
         <para>You can scale the display on touch devices by using the familiar pinch gesture. Place
             two fingers on the screen and bring them closer together to zoom out or further apart to
             zoom in.</para>
         <para>If your device lacks a touch screen, you can also control the zoom level through the
             menu. The controls for zooming in and out are located at the bottom of the menu. The
             current zoom level is displayed between two "-" and "+" buttons which control the zoom
             level in 10% increments.</para>
     </section>
     <section xml:id="touch-devices">
         <title>Mobile or touch devices</title>
         <para>Guacamole is designed to work equally well across all HTML5 browsers, including those
             of mobile devices. It will automatically handle input from a touch screen or a
             traditional mouse (or both, if you happen to have such a gifted computer), and provides
             alternative input methods for devices which lack a physical keyboard.</para>
         <section xml:id="touch-mouse">
             <title>Mouse emulation</title>
             <para><indexterm>
                     <primary>mouse</primary>
                 </indexterm>In the case that your device has a touchscreen and lacks a mouse,
                 Guacamole will emulate a mouse for the sake of interacting with remote desktops that
                 expect mouse input. By default, Guacamole uses "absolute" mouse emulation. This
                 means that the mouse pointer is positioned at the location of each tap on the
                 screen.</para>
             <para>In both absolute and relative modes, you can 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>
             <section xml:id="absolute-mouse-emulation">
                 <title>Absolute mode (touchscreen)</title>
                 <para>Absolute mouse emulation is the default as it tends to be what people expect
                     when using a touch device to interact with applications designed for mouse
                     input.</para>
                 <para>Each tap on the screen is translated into a left-click at that position.
                     Right-clicking is accomplished through pressing and holding your finger on the
                     screen. If parts of the remote display are off-screen, you can drag your finger
                     around the screen to pan the off-screen parts back into view.</para>
                 <para>Although absolute mouse emulation works generally well, a finger makes for a
                     very inaccurate pointing device. To address this, Guacamole also provides
                     "relative" mouse emulation. Relative mouse emulation provides a way to deal with
                     the need for accurate pointer control, when a true pointer device is not
                     present.</para>
                 <informalfigure>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="images/touchscreen.png" format="PNG"
                                 contentwidth="1.5in"/>
                         </imageobject>
                     </mediaobject>
                 </informalfigure>
             </section>
             <section xml:id="relative-mouse-emulation">
                 <title>Relative mode (touchpad)</title>
                 <para>Guacamole's relative mouse emulation behaves similarly to the touchpad present
                     on most modern laptops. You drag your finger across the display to move the
                     mouse pointer, and tap the display to left-click. The pointer moves relative to
                     the motion of your finger. Right-clicking is accomplished with a two-finger tap,
                     and middle-clicking with a three-finger tap. The mouse scroll wheel can be
                     operated by dragging two fingers up or down.</para>
                 <para>Because the relative mouse emulation reserves so many gestures for the
                     different mouse buttons and actions, common touch gestures like panning and
                     pinch-to-zoom will not work while relative mouse emulation is enabled. Instead,
                     the screen will automatically pan to keep the mouse pointer in view, and you can
                     zoom through the buttons in the menu.</para>
                 <informalfigure>
                     <mediaobject>
                         <imageobject>
                             <imagedata fileref="images/touchpad.png" format="PNG"
                                 contentwidth="1.5in"/>
                         </imageobject>
                     </mediaobject>
                 </informalfigure>
             </section>
         </section>
         <section xml:id="text-input">
             <title>Typing without a physical keyboard</title>
             <para>Many mobile devices lack a physical keyboard entirely, and instead provide their
                 own on-screen keyboards. As these are not true keyboards per se and do not produce
                 key presses, Guacamole's text input mode is required for typing on these
                 platforms.</para>
             <para>"Text input" allows input of keystrokes based on the input of text. Choosing "Text
                 input" tells Guacamole to infer keystrokes by tracking text entered, rather than
                 relying on actual key presses. Guacamole will instead determine the combination of
                 keypresses necessary to produce the same pattern of input, including
                 deletions.</para>
             <para><indexterm>
                     <primary>input method editors</primary>
                 </indexterm>If you wish to type via an IME (input method editor), such as those
                 required for Chinese, Japanese, or Korean, text input mode is required for this as
                 well. Such IMEs function through the explicit insertion of text and do not send
                 traditional key presses. Using text input mode within Guacamole thus allows you to
                 use a locally-installed IME, without requiring the IME to be installed on the remote
                 desktop.</para>
         </section>
     </section>
     <section xml:id="preferences">
         <title>Changing preferences</title>
         <para>User preferences can be changed within the settings screen. These preferences are
             stored locally within the browser, so if you use multiple computers to access Guacamole,
             you can have different settings for each location. The settings screen allows users to
             change the language of the Guacamole interface, to change the default input method used
             by Guacamole connections, and to change the default mouse emulation mode for if a touch
             device is used. If you have sufficient permissions, you may also change your password,
             or administer the system.</para>
         <informalfigure>
             <screenshot>
                 <mediaobject>
                     <imageobject>
                         <imagedata fileref="images/guacamole-preferences.png" format="PNG"
                             contentwidth="6in"/>
                     </imageobject>
                     <caption>
                         <para>Guacamole preferences screen.</para>
                     </caption>
                 </mediaobject>
             </screenshot>
         </informalfigure>
         <section xml:id="display-language">
             <title>Display language</title>
             <para>The Guacamole interface is currently available in English, French, and Russian. By
                 default, Guacamole will attempt to determine the appropriate display language by
                 checking the language preferences of the browser in use. If this fails, or the
                 browser is using a language not yet available within Guacamole, English will be used
                 as a fallback.</para>
             <para>If you wish to override the current display language, you can do so by selecting a
                 different language within the "Display language" field. The change will take effect
                 immediately.</para>
         </section>
         <section xml:id="changing-password">
             <title>Changing your password</title>
             <para>System administrators can restrict the ability of individual users to change their
                 own passwords, so this section may not always be available. If your account
                     <emphasis>does</emphasis> have permission, the preferences screen will contain a
                 "Change Password" section.</para>
             <para>To change your password, you must provide your current password, enter the desired
                 new password, and click "Update Password". You will remain logged in, and the change
                 will affect any future login attempt.</para>
         </section>
         <section xml:id="default-input-settings">
             <title>Default input settings</title>
             <para>Guacamole provides multiple keyboard input methods and multiple mouse emulation
                 modes. Many of these settings are specifically useful for touch devices, while
                 others are aimed mainly at traditional desktop use. By default, Guacamole will use
                 the keyboard and mouse modes most commonly preferred by users, but you can change
                 these defaults if they do not fit your tastes or your current device.</para>
             <para>The choices available mirror those within the Guacamole menu discussed earlier in
                 this chapter, and changing these settings will affect the default values selected
                 within the Guacamole menu of future connections.</para>
         </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>
	<para><indexterm>
	<primary>interacting</primary>
	</indexterm>Guacamole provides access to much of the functionality of a desktop from within
	your web browser. Although most people use remote desktop tools only when absolutely
	necessary, we believe that Guacamole must be aimed at becoming a primary means of accessing
	desktops, and the interface is thus intended to be as seamless and unobtrusive as
	possible.</para>
	<section xml:id="home-screen">
	<title>Home screen</title>
	<para>Once you have successfully logged in, you will be taken to either the Guacamole home
	screen, where all available connections are listed, or directly to a connection, if you
	only have access to one connection.</para>
	<para>The list of connections on the home screen contains all connections for which you have
	been granted access. If you have used Guacamole in this specific web browser before, you
	will also see thumbnails of recently used connections.</para>
	<informalfigure>
	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/guacamole-home-screen.png" format="PNG"
	contentwidth="5in"/>
	</imageobject>
	<caption>
	<para>The Guacamole home screen. The user menu and several recently-used
	connections are visible, along with one active connection.</para>
	</caption>
	</mediaobject>
	</screenshot>
	</informalfigure>
	<para>Clicking on any connection will open that connection within the current window or tab,
	but multiple connections can be used simultaneously. You can easily navigate back to the
	home screen without disconnecting by using your browsers back button or the "Home"
	button in the Guacamole menu. Each connection you use will remain active until
	explicitly disconnected, or until you navigate away from Guacamole entirely. Active
	connections can be seen as thumbnails updating in real-time on the home screen.</para>
	<section xml:id="user-menu">
	<title>User menu</title>
	<para>With the exception of the client screen discussed below, all Guacamole screens
	contain a menu in the upper-right corner called the "user menu". This menu displays
	your username and contains several options which depend on your user's level of
	access:</para>
	<variablelist>
	<varlistentry>
	<term>Home</term>
	<listitem>
	<para>Navigates back to the home screen, if you are not already there. If
	you only have access to one connection, this will be replaced with a
	link to that connection.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Settings</term>
	<listitem>
	<para>Navigates to the settings interface, which provides access to user
	preferences such as display language. If you have access to
	administrative functions, those are found within the settings interface,
	as well, and are discussed in more detail in <xref
	linkend="administration"/>.</para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term>Logout</term>
	<listitem>
	<para>Logs out of Guacamole completely, closing all current connections and
	ending the Guacamole session.</para>
	</listitem>
	</varlistentry>
	</variablelist>
	</section>
	</section>
	<section xml:id="client-screen">
	<title>Client screen</title>
	<para>Once you open a connection, you will see a real-time view of the remote display. You
	can interact with this display just as you would your normal desktop. Your mouse and
	keyboard will function as if they were connected directly to the remote machine.</para>
	<informalfigure>
	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/guacamole-client-interface.png" format="PNG"
	contentwidth="6in"/>
	</imageobject>
	<caption>
	<para>Guacamole client interface, with the Guacamole menu open.</para>
	</caption>
	</mediaobject>
	</screenshot>
	</informalfigure>
	<para>The remote display will take up the entire browser window, with no buttons or menus to
	disturb the view. With the intent of providing a seamless experience, options specific
	to remote desktop are hidden within the Guacamole menu, which can be opened as
	needed.</para>
	<section xml:id="guacamole-menu">
	<title>The Guacamole menu</title>
	<para>The Guacamole menu is a sidebar which is hidden until explicitly shown. On a
	desktop or other device which has a hardware keyboard, you can show this menu by
	pressing <keycombo>
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>Shift</keycap>
	</keycombo>. If you are using a mobile or touchscreen device that lacks a keyboard,
	you can also show the menu by swiping right from the left edge of the screen. To
	hide the menu, you press <keycombo>
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>Shift</keycap>
	</keycombo> again or swipe left across the screen.</para>
	<para>The Guacamole menu provides options for:<itemizedlist>
	<listitem>
	<para>Navigating back to the home screen</para>
	</listitem>
	<listitem>
	<para>Reading from (and writing to) the clipboard of the remote
	desktop</para>
	</listitem>
	<listitem>
	<para>Uploading files and monitoring file transfer progress</para>
	</listitem>
	<listitem>
	<para>Selecting alternative methods of typing or controlling the mouse,
	particularly for use on mobile or touchscreen devices</para>
	</listitem>
	<listitem>
	<para>Zooming in and out of the remote display</para>
	</listitem>
	<listitem>
	<para>Disconnecting from the current connection entirely</para>
	</listitem>
	</itemizedlist></para>
	</section>
	</section>
	<section xml:id="using-the-clipboard">
	<title>Copying/pasting text</title>
	<para><indexterm>
	<primary>clipboard</primary>
	</indexterm>At the top of the Guacamole menu is a text area labeled "clipboard" along
	with some basic instructions:</para>
	<blockquote>
	<para>Text copied/cut within Guacamole will appear here. Changes to the text below will
	affect the remote clipboard.</para>
	</blockquote>
	<para>The text area functions as an interface between the remote clipboard and the local
	clipboard. Text from the local clipboard can be pasted into the text area, causing that
	text to be sent to the clipboard of the remote desktop. Similarly, if you copy or cut
	text within the remote desktop, you will see that text within the text area, and can
	manually copy it into the local clipboard if desired.</para>
	</section>
	<section xml:id="client-user-menu">
	<title>Disconnecting and navigation</title>
	<para>When you are done using the current connection, or you wish to navigate elsewhere
	temporarily, options to do so are within the user menu inside the Guacamole menu:</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/guac-menu-disconnect.png" format="PNG"
	contentwidth="6in"/>
	</imageobject>
	<caption>
	<para>The user menu within the Guacamole menu.</para>
	</caption>
	</mediaobject>
	<para>The user menu within the Guacamole menu provides an additional "Disconnect" option
	that allows you to explicitly close the current connection only. Clicking "Logout"
	will also implicitly disconnect all active connections, including the current
	connection.</para>
	<para>Navigating back to the home screen or to the settings screen will not disconnect
	you: your connection will continue running in the background while you change
	settings or initiate another connection, and you can resume any active connection by
	clicking on it within the home screen.</para>
	</informalfigure>
	</section>
	<section xml:id="file-transfer">
	<title>Transferring files</title>
	<indexterm>
	<primary>file transfer</primary>
	</indexterm>
	<para>You can transfer files back and forth between your local computer and the remote
	desktop if it is supported by the underlying protocol and enabled on the connection.
	Currently, both RDP and SSH have support for file transfer, though with slightly
	different semantics. RDP provides file transfer by emulating a virtual drive, while SSH
	provides file transfer by using SFTP.</para>
	<para>To transfer files to the remote computer, drag the files into your browser window, or
	use the "Upload Files" button within the Guacamole menu. If file transfer is enabled,
	you will see a progress indicator appear within the menu. If file transfer is not
	enabled or not supported, you will instead see a notification with an error message
	describing the problem. Completed transfers can be removed from the list by clicking
	"Clear Completed Transfers".</para>
	<para>The method for downloading files from the remote computer depends on the protocol. In
	the case of RDP, you must drag, copy, move, or save the files into the special
	"Download" folder located in the virtual drive. All files dropped into this folder will
	automatically begin uploading to the client, and thus downloading through your
	browser.</para>
	<para><indexterm>
	<primary>guacctl</primary>
	</indexterm>To download files over SSH, you must use the <command>guacctl</command>
	utility. The <command>guacctl</command> utility is a simple shell script that is <link
	xmlns:xlink="http://www.w3.org/1999/xlink"
	xlink:href="https://raw.githubusercontent.com/glyptodon/guacamole-server/master/bin/guacctl"
	>included with Guacamole</link> and allows you to initiate a file download or to
	change the directory in which uploaded files will be placed:</para>
	<informalexample>
	<screen><prompt>$</prompt> <userinput>guacctl</userinput>
	<computeroutput>guacctl 0.8.0, Guacamole SSH session control utility.
	Usage: guacctl [OPTION] [FILE]...

	-d, --download download each of the files listed.
	-s, --set-directory set the destination directory for future uploaded
	files.</computeroutput>
	<prompt>$</prompt> <userinput>guacctl -d <replaceable>FILENAME</replaceable></userinput>
	<prompt>$</prompt> <userinput>guacctl -s <replaceable>DIRECTORY</replaceable></userinput>
	$</screen>
	</informalexample>
	<para>You may also create a symbolic link or alias to <command>guacctl</command> called
	<command>guacget</command>. When run as <command>guacget</command>, it behaves as if
	the <option>--download</option> option was supplied and initiates a download for each
	file specified on the command line.</para>
	</section>
	<section xml:id="using-the-osk">
	<title>On-screen keyboard</title>
	<para>Certain key combinations are impossible to press within a web application like
	Guacamole because they are reserved by the operating system (<keycombo>
	<keycap>Ctrl</keycap>
	<keycap>Alt</keycap>
	<keycap>Del</keycap>
	</keycombo> or <keycombo>
	<keycap>Alt</keycap>
	<keycap>Tab</keycap>
	</keycombo>, 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 its own, built-in on-screen keyboard which allows keys to be sent
	to the remote desktop without affecting the local system. If the device you're using
	does not have certain keys which the remote desktop depends on, such as the arrow keys
	or <keycap>Ctrl</keycap>, you can use the on-screen keyboard for this, too. You can show
	the on-screen keyboard by selecting the "On-screen keyboard" option from the
	menu.</para>
	<para>Clicking (or tapping) 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 to the remote
	desktop.</para>
	</section>
	<section xml:id="scaling-display">
	<title>Scaling the display</title>
	<para><indexterm>
	<primary>zoom</primary>
	</indexterm>Guacamole will default to shrinking or expanding the remote display to fit
	the browser window exactly, but this is not necessarily ideal. If the remote display is
	much larger than your local display, the screen may be impossible to see or interact
	with. This is especially true for mobile phones, whose screens need to be small enough
	to fit in the average hand.</para>
	<para>You can scale the display on touch devices by using the familiar pinch gesture. Place
	two fingers on the screen and bring them closer together to zoom out or further apart to
	zoom in.</para>
	<para>If your device lacks a touch screen, you can also control the zoom level through the
	menu. The controls for zooming in and out are located at the bottom of the menu. The
	current zoom level is displayed between two "-" and "+" buttons which control the zoom
	level in 10% increments.</para>
	</section>
	<section xml:id="touch-devices">
	<title>Mobile or touch devices</title>
	<para>Guacamole is designed to work equally well across all HTML5 browsers, including those
	of mobile devices. It will automatically handle input from a touch screen or a
	traditional mouse (or both, if you happen to have such a gifted computer), and provides
	alternative input methods for devices which lack a physical keyboard.</para>
	<section xml:id="touch-mouse">
	<title>Mouse emulation</title>
	<para><indexterm>
	<primary>mouse</primary>
	</indexterm>In the case that your device has a touchscreen and lacks a mouse,
	Guacamole will emulate a mouse for the sake of interacting with remote desktops that
	expect mouse input. By default, Guacamole uses "absolute" mouse emulation. This
	means that the mouse pointer is positioned at the location of each tap on the
	screen.</para>
	<para>In both absolute and relative modes, you can 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>
	<section xml:id="absolute-mouse-emulation">
	<title>Absolute mode (touchscreen)</title>
	<para>Absolute mouse emulation is the default as it tends to be what people expect
	when using a touch device to interact with applications designed for mouse
	input.</para>
	<para>Each tap on the screen is translated into a left-click at that position.
	Right-clicking is accomplished through pressing and holding your finger on the
	screen. If parts of the remote display are off-screen, you can drag your finger
	around the screen to pan the off-screen parts back into view.</para>
	<para>Although absolute mouse emulation works generally well, a finger makes for a
	very inaccurate pointing device. To address this, Guacamole also provides
	"relative" mouse emulation. Relative mouse emulation provides a way to deal with
	the need for accurate pointer control, when a true pointer device is not
	present.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/touchscreen.png" format="PNG"
	contentwidth="1.5in"/>
	</imageobject>
	</mediaobject>
	</informalfigure>
	</section>
	<section xml:id="relative-mouse-emulation">
	<title>Relative mode (touchpad)</title>
	<para>Guacamole's relative mouse emulation behaves similarly to the touchpad present
	on most modern laptops. You drag your finger across the display to move the
	mouse pointer, and tap the display to left-click. The pointer moves relative to
	the motion of your finger. Right-clicking is accomplished with a two-finger tap,
	and middle-clicking with a three-finger tap. The mouse scroll wheel can be
	operated by dragging two fingers up or down.</para>
	<para>Because the relative mouse emulation reserves so many gestures for the
	different mouse buttons and actions, common touch gestures like panning and
	pinch-to-zoom will not work while relative mouse emulation is enabled. Instead,
	the screen will automatically pan to keep the mouse pointer in view, and you can
	zoom through the buttons in the menu.</para>
	<informalfigure>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/touchpad.png" format="PNG"
	contentwidth="1.5in"/>
	</imageobject>
	</mediaobject>
	</informalfigure>
	</section>
	</section>
	<section xml:id="text-input">
	<title>Typing without a physical keyboard</title>
	<para>Many mobile devices lack a physical keyboard entirely, and instead provide their
	own on-screen keyboards. As these are not true keyboards per se and do not produce
	key presses, Guacamole's text input mode is required for typing on these
	platforms.</para>
	<para>"Text input" allows input of keystrokes based on the input of text. Choosing "Text
	input" tells Guacamole to infer keystrokes by tracking text entered, rather than
	relying on actual key presses. Guacamole will instead determine the combination of
	keypresses necessary to produce the same pattern of input, including
	deletions.</para>
	<para><indexterm>
	<primary>input method editors</primary>
	</indexterm>If you wish to type via an IME (input method editor), such as those
	required for Chinese, Japanese, or Korean, text input mode is required for this as
	well. Such IMEs function through the explicit insertion of text and do not send
	traditional key presses. Using text input mode within Guacamole thus allows you to
	use a locally-installed IME, without requiring the IME to be installed on the remote
	desktop.</para>
	</section>
	</section>
	<section xml:id="preferences">
	<title>Changing preferences</title>
	<para>User preferences can be changed within the settings screen. These preferences are
	stored locally within the browser, so if you use multiple computers to access Guacamole,
	you can have different settings for each location. The settings screen allows users to
	change the language of the Guacamole interface, to change the default input method used
	by Guacamole connections, and to change the default mouse emulation mode for if a touch
	device is used. If you have sufficient permissions, you may also change your password,
	or administer the system.</para>
	<informalfigure>
	<screenshot>
	<mediaobject>
	<imageobject>
	<imagedata fileref="images/guacamole-preferences.png" format="PNG"
	contentwidth="6in"/>
	</imageobject>
	<caption>
	<para>Guacamole preferences screen.</para>
	</caption>
	</mediaobject>
	</screenshot>
	</informalfigure>
	<section xml:id="display-language">
	<title>Display language</title>
	<para>The Guacamole interface is currently available in English, French, and Russian. By
	default, Guacamole will attempt to determine the appropriate display language by
	checking the language preferences of the browser in use. If this fails, or the
	browser is using a language not yet available within Guacamole, English will be used
	as a fallback.</para>
	<para>If you wish to override the current display language, you can do so by selecting a
	different language within the "Display language" field. The change will take effect
	immediately.</para>
	</section>
	<section xml:id="changing-password">
	<title>Changing your password</title>
	<para>System administrators can restrict the ability of individual users to change their
	own passwords, so this section may not always be available. If your account
	<emphasis>does</emphasis> have permission, the preferences screen will contain a
	"Change Password" section.</para>
	<para>To change your password, you must provide your current password, enter the desired
	new password, and click "Update Password". You will remain logged in, and the change
	will affect any future login attempt.</para>
	</section>
	<section xml:id="default-input-settings">
	<title>Default input settings</title>
	<para>Guacamole provides multiple keyboard input methods and multiple mouse emulation
	modes. Many of these settings are specifically useful for touch devices, while
	others are aimed mainly at traditional desktop use. By default, Guacamole will use
	the keyboard and mouse modes most commonly preferred by users, but you can change
	these defaults if they do not fit your tastes or your current device.</para>
	<para>The choices available mirror those within the Guacamole menu discussed earlier in
	this chapter, and changing these settings will affect the default values selected
	within the Guacamole menu of future connections.</para>
	</section>
	</section>

	</chapter>