University of California at Berkeley
           Department of Electrical Engineering & Computer Sciences
                          Instructional Support Group

/share/b/pub/guacamole.help

						  (last updated September 2024)

CONTENTS:
	Introduction
	Using Apache Guacamole


Introduction
------------

Apache Guacamole is a web-based remote desktop that is the primary way of using
graphical applications remotely on our Linux machines.  It's faster and easier
to use than X11 forwarding over SSH, and replaces X2Go (which is obsolete) as
our main remote desktop solution for Linux.

The following machines are available to all users via Guacamole remote desktop:

    eda-1.eecs .. eda-4.eecs (RHEL Linux servers)

Other machines may be available to you depending on what courses you are taking
-- check with your instructors to be sure.


Using Apache Guacamole
----------------------

To use Guacamole to connect to an instructional Linux machine, start by
visiting

    https://instrdp.eecs.berkeley.edu

in your browser (we recommend Chrome or Microsoft Edge -- Safari and Firefox
users, see below).  You do not have to connect to the campus VPN first, even if
you are off-campus.  You may be asked to log in through CalNet -- if prompted,
enter your CalNet ID and passphrase.

Once you're logged in, you'll see a list of groups of machines -- click the +
next to the group to show the list of machines in the group, then click the
name of the machine to connect to it.  (Note that you may see groups of
machines that you are not allowed to log in to -- if you try to use those
machines, you will receive an error when you attempt to log in.)

When you connect, you should see a dialog box asking for a username and
password -- enter the username and password for your instructional account (not
your CalNet ID and passphrase), then press Enter or click OK to log in.

You should now be able to use the remote desktop normally.  Some hints and
tips:

* Copying and pasting between the remote desktop and your local applications
  works as normal in Chrome and Microsoft Edge, provided you accept the request
  for clipboard permissions from the Guacamole webapp.  In Safari and in
  Firefox 127 or later, you may see "Paste" popups when clicking into the
  Guacamole desktop -- these are clipboard synchronization requests, and if you
  don't accept them, pasting content from local applications into your
  Guacamole remote session will not work.
* Pressing Ctrl-Alt-Shift (on Mac, Control-Command ⌘-Shift) will bring up a
  menu on the left side of the screen.  From here, you can click on your CalNet
  username to bring up a menu allowing you to disconnect from your remote
  desktop without logging out of the machine -- this is useful if you want to
  leave and come back to your work later.  (Note that you will be logged out
  automatically after a period of inactivity -- 5 days on the eda-* machines,
  shorter on others.)  Press Ctrl-Alt-Shift (or Control-Command ⌘-Shift) again
  to dismiss the menu.
* Certain key combinations (like the one to close your current browser tab or
  window) are interpreted by your browser rather than the remote desktop.  If
  you need to use one of these key combinations, bring up the Ctrl-Alt-Shift
  menu and then choose "On-screen keyboard" from under "Input method", then
  click in the on-screen keyboard to enter the key combination you need.
* On touchscreen devices, swipe in from the left edge of the screen to bring up
  the menu.  If you don't have a physical keyboard attached, select one of the
  two input method modes ("Text input" or "On-screen keyboard") so that you can
  enter text.  You can also change the mouse emulation mode for touchscreens
  here, as well as adjust the display zoom.  Swipe out towards the left of the
  screen to dismiss the menu.