Using Atmosphere "New Web Desktop/Shell" (Apache Guacamole)

Owned by Former user (Deleted)
Last updated: Nov 20, 2017 by Former user (Deleted)
4 min read

This is a guide to using Guacamole VNC and Guacamole SSH on Atmosphere. From Apache Guacamole:

"Apache Guacamole is a clientless remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH. We call it clientless because no plugins or client software are required. Thanks to HTML5, once Guacamole is installed on a server, all you need to access your desktops is a web browser."

The official user guide for Guacamole can be found here, but please note that not all features are available in Guacamole on Atmosphere.

Using Guacamole:

Press CTRL+ALT+SHIFT to access settings menu. The settings menu has options for Input method, Mouse emulation mode, and Display. At the top of the menu is a drop-down with additional options: logout, disconnect, settings. The additional settings menu will have the same options in addition to language preferences.

 

 

 

 

 

 

 

 

 

Guacamole Desktop

  • Uses VNC protocol
  •  Connect using the "Open New Web Desktop (beta)" button

Guacamole Shell

  • Uses SSH protocol
  • Connect using the "Open New Web Shell (beta)" button and entering password
  • Also connects SFTP and supports drag-and-drop file transfers

Copy/Paste

You can copy/paste text using the menu (CTRL+ALT+SHIFT). Text pasted in the box can then be pasted in the SSH or VNC session. Text that is copied from the SSH/VNC session will appear in the text box where it can be grabbed on the local system. On SSH connections, copy/paste functionalities are engaged with a right click or by just highlighting text. On VNC, you can copy/paste text from the box using the normal method of right click then select copy or paste.

 

 

 

 

 

 

 

Persisting your Session in Guacamole Shell

When you close a Guacamole Shell (Web Shell) window, your shell session ends and is not preserved. You may wish to make your shell session persistent, so that you can disconnect from it and reconnect later. For this, we recommend using either tmux or screen on your instance. Both of these should already be installed, and both can be used to keep your shell session active, and connect to it later, even if your browser disconnects.

tmux Crash Course

Create a new tmux session and activate it:

tmux

Now you can do your work inside tmux, and your session will be preserved even if you get disconnected.

You can explicitly "detach" from your tmux session by pressing Ctrl-b, followed by the 'd' key – though this is not necessary when disconnecting Guacamole Shell. You can just close the browser and your tmux session will stay active.

When you re-connect to Guacamole shell, you can re-attach to the first available tmux session (i.e. the one that you opened earlier) with:

tmux a

This should bring you back to the same shell, exactly where you were earlier! # It's possible to have more than one tmux session open, and this may cause confusion. You can list all active tmux sessions with:

tmux ls

If you see multiple sessions listed, you can connect to a named session (e.g. session 0) with

tmux a -t 0

For more information on using tmux, please see tmux documentation (e.g. man tmux) and other articles on the web (e.g. A Gentle Introduction to tmux).

Common Errors (and some solutions)

Connection Error - closed the connection

This means that you were successfully authenticated by the Guacamole server, but it was unable to connect to your instance. This could be an issue with the instance, or perhaps with the Guacamole server. If it continues to happen after a few tries, contact support. The most likely problem is the VNC server closed.

Connection Error - do not have permission

Similar to the 403 Error, this means you are not authenticated for that connection. However, since you made it past the 403 Error, you have been authenticated by Guacamole but the instance you are trying to connect to is not your own. If you encounter this error, contact support.

Connection Error -  failed to login

This error occurs on SSH connections when the user mistypes the password. Simply retry.

403 Error

When authentication fails, the authentication extension presents you with a normal-looking error page. This means that the Guacamole server did not accept authentication. This error has nothing to do with your instance. If this still happens after trying a few times, contact support so we can fix the Guacamole server.

Unable to render {include} The included page could not be found.