| <?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> |