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