| <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Chapter 7. Using Guacamole</title><link rel="stylesheet" type="text/css" href="gug.css" /><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><link rel="home" href="index.html" title="Guacamole Manual" /><link rel="up" href="users-guide.html" title="Part I. User's Guide" /><link rel="prev" href="noauth.html" title="Chapter 6. Disabling authentication" /><link rel="next" href="administration.html" title="Chapter 8. Administration" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, user-scalable=no, target-densitydpi=device-dpi"/> |
| </head><body> |
| <!-- CONTENT --> |
| |
| <div id="page"><div id="content"> |
| <div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 7. Using Guacamole</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="noauth.html">Prev</a> </td><th width="60%" align="center">Part I. User's Guide</th><td width="20%" align="right"> <a accesskey="n" href="administration.html">Next</a></td></tr></table><hr /></div><div xml:lang="en" class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a id="using-guacamole"></a>Chapter 7. Using Guacamole</h2></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="using-guacamole.html#home-screen">Home screen</a></span></dt><dd><dl><dt><span class="section"><a href="using-guacamole.html#user-menu">User menu</a></span></dt></dl></dd><dt><span class="section"><a href="using-guacamole.html#client-screen">Client screen</a></span></dt><dd><dl><dt><span class="section"><a href="using-guacamole.html#guacamole-menu">The Guacamole menu</a></span></dt></dl></dd><dt><span class="section"><a href="using-guacamole.html#using-the-clipboard">Copying/pasting text</a></span></dt><dt><span class="section"><a href="using-guacamole.html#file-transfer">Transferring files</a></span></dt><dt><span class="section"><a href="using-guacamole.html#using-the-osk">On-screen keyboard</a></span></dt><dt><span class="section"><a href="using-guacamole.html#scaling-display">Scaling the display</a></span></dt><dt><span class="section"><a href="using-guacamole.html#touch-devices">Mobile or touch devices</a></span></dt><dd><dl><dt><span class="section"><a href="using-guacamole.html#touch-mouse">Mouse emulation</a></span></dt><dt><span class="section"><a href="using-guacamole.html#text-input">Typing without a physical keyboard</a></span></dt></dl></dd></dl></div><p><a id="idm140499501471840" class="indexterm"></a>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.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="home-screen"></a>Home screen</h2></div></div></div><p>Once you have successfully logged in, the first thing you will see is the Guacamole |
| home screen. The home screen is a list of available remote desktop connections. This |
| list contains all connections which you have been granted permission to access. If you |
| have used Guacamole in this specific web browser before, you will also see thumbnails of |
| recently used connections.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/guacamole-home-screen.png" width="450" /><div class="caption"><p>The Guacamole home screen. The user menu and several recently-used |
| connections are visible, along with one active connection.</p></div></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="user-menu"></a>User menu</h3></div></div></div><p>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:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Home</span></dt><dd><p>Navigates back to the home screen, if you are not already |
| there.</p></dd><dt><span class="term">Change password</span></dt><dd><p>Changes the password for your account. This option may not be |
| available if your user account lacks sufficient permissions, or if the |
| authentication system installed does not provide for changing |
| passwords.</p></dd><dt><span class="term">Logout</span></dt><dd><p>Logs out of Guacamole completely, closing all current connections and |
| ending the Guacamole session.</p></dd></dl></div><p>If you have administrator-level access to Guacamole, you may also see options |
| specific to managing users, connection, or sessions. These are discussed in more |
| detail in <a class="xref" href="administration.html" title="Chapter 8. Administration">Chapter 8, <em>Administration</em></a>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Users</span></dt><dd><p>Shows all other Guacamole user accounts. Depending on your access |
| level, users may be created, modified, and deleted.</p></dd><dt><span class="term">Manage connections</span></dt><dd><p>Shows available Guacamole connections and connection groups. Depending |
| on your access level, the connections displayed here may be created, |
| modified, and deleted.</p></dd><dt><span class="term">Active sessions</span></dt><dd><p>Shows all active Guacamole connections, the address from which the |
| connection originates, and when the connection began. Administrators can |
| select and kill active connections at will.</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="client-screen"></a>Client screen</h2></div></div></div><p>Once you open a connection, you will see a realtime 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.</p><div class="informalfigure"><div class="screenshot"><div class="mediaobject"><img src="images/guacamole-client-interface.png" width="540" /><div class="caption"><p>Guacamole client interface, with the Guacamole menu open.</p></div></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="guacamole-menu"></a>The Guacamole menu</h3></div></div></div><p>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 <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Shift</strong></span>. 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 <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Shift</strong></span> again or swipe left across the screen.</p><p>The Guacamole menu provides options for:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Navigating back to the home screen</p></li><li class="listitem"><p>Reading from (and writing to) the clipboard of the remote |
| desktop</p></li><li class="listitem"><p>Uploading files and monitoring file transfer progress</p></li><li class="listitem"><p>Selecting alternative methods of typing or controlling the mouse, |
| particularly for use on mobile or touchscreen devices</p></li><li class="listitem"><p>Zooming in and out of the remote display</p></li><li class="listitem"><p>Disconnecting from the current connection entirely</p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-the-clipboard"></a>Copying/pasting text</h2></div></div></div><p><a id="idm140499500236880" class="indexterm"></a>At the top of the Guacamole menu is a text area labeled "clipboard" along |
| with some basic instructions:</p><div class="blockquote"><blockquote class="blockquote"><p>Text copied/cut within Guacamole will appear here. Changes to the text below will |
| affect the remote clipboard.</p></blockquote></div><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="file-transfer"></a>Transferring files</h2></div></div></div><a id="idm140499500232512" class="indexterm"></a><p>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.</p><p>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".</p><p>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.</p><p><a id="idm140499500228880" class="indexterm"></a>To download files over SSH, you must use the <span class="command"><strong>guacctl</strong></span> |
| utility. The <span class="command"><strong>guacctl</strong></span> utility is a simple shell script that is <a class="link" href="https://raw.githubusercontent.com/glyptodon/guacamole-server/master/bin/guacctl" target="_top">included with Guacamole</a> and allows you to initiate a file download or to |
| change the directory in which uploaded files will be placed:</p><div class="informalexample"><pre class="screen"><code class="prompt">$</code> <strong class="userinput"><code>guacctl</code></strong> |
| <code class="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.</code> |
| <code class="prompt">$</code> <strong class="userinput"><code>guacctl -d <em class="replaceable"><code>FILENAME</code></em></code></strong> |
| <code class="prompt">$</code> <strong class="userinput"><code>guacctl -s <em class="replaceable"><code>DIRECTORY</code></em></code></strong> |
| $</pre></div><p>You may also create a symbolic link or alias to <span class="command"><strong>guacctl</strong></span> called |
| <span class="command"><strong>guacget</strong></span>. When run as <span class="command"><strong>guacget</strong></span>, it behaves as if |
| the <code class="option">--download</code> option was supplied and initiates a download for each |
| file specified on the command line.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="using-the-osk"></a>On-screen keyboard</h2></div></div></div><p>Certain key combinations are impossible to press within a web application like |
| Guacamole because they are reserved by the operating system (<span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Del</strong></span> or <span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>Tab</strong></span>, 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.</p><p>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 <span class="keycap"><strong>Ctrl</strong></span>, 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.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="scaling-display"></a>Scaling the display</h2></div></div></div><p><a id="idm140499500210112" class="indexterm"></a>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.</p><p>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.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="touch-devices"></a>Mobile or touch devices</h2></div></div></div><p>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.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="touch-mouse"></a>Mouse emulation</h3></div></div></div><p><a id="idm140499500204432" class="indexterm"></a>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.</p><p>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.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="absolute-mouse-emulation"></a>Absolute mode (touchscreen)</h4></div></div></div><p>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.</p><p>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.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="relative-mouse-emulation"></a>Relative mode (touchpad)</h4></div></div></div><p>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.</p><p>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.</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="text-input"></a>Typing without a physical keyboard</h3></div></div></div><p>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.</p><p>"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.</p><p><a id="idm140499500192512" class="indexterm"></a>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.</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="noauth.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="users-guide.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="administration.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Disabling authentication </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 8. Administration</td></tr></table></div> |
| |
| </div></div> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ |
| (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), |
| m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) |
| })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); |
| |
| ga('create', 'UA-75289145-1', 'auto'); |
| ga('send', 'pageview'); |
| |
| </script> |
| <!-- End Google Analytics --> |
| </body></html> |
