Setup Guacamole Remote Desktop Gateway on Ubuntu with one script

How to replace RDP, SSH and TeamViewer with free open source web-based client-less remote desktop gateway.

I recently learned about Guacamole and found that the setup is quite easy. I had been looking for a way to access all of my virtual and physical machine desktops remotely but didn’t want to rely upon, or trust TeamViewer eternally. Guacamole is open source software that provides you a way to run a tomcat/apache/mysql server suite that sets up and connects remote desktop connections via a web browser very similar to Teamviewer. It allows you to connect to any number of different desktops with just an html5 web browser, and a single open port on your firewall. You can use Google Authenticator 2FA to log into a console that has access to all your desktops, without having to install or configure remote clients such as putty, RDP and VPN. Although, if you’re attempting to use VNC, there will be some initial configuration of the VNC server on the client side – I found that UltraVNC server works best with Guacamole, more on that later.

The installation documentation on the official site is comprehensive but I was able to set up the system fast thanks to Chase Wright’s post here. To be clear, this is not “my script”, but I’ve written this article as a tutorial/guide.

First, you’ll want a standard Ubuntu server or virtual machine installed and running. I installed guacamole on Ubuntu Server 16.10 LTS.

Second, open an ssh connection to your server and run the following commands:

sudo su -
wget https://raw.githubusercontent.com/MysticRyuujin/guac-install/master/guac-install.sh
chmod +x guac-install.sh
./guac-install.sh

The installation will take a little while to download and install, and should only prompt you to provide a mysql database password.

For me, that was pretty much it for the initial setup. Next, I went to a different computer and connected to the guacamole gateway at the following default website:

http://serverIPaddress:8080/guacamole (replace serverIPaddress with your ubuntu server’s IP)

Login with the default guacamole username/password: guacadmin/guacadmin

The initial interface is a little sparse, but to create an RDP connection do the following:

  1. Create a new user first before you create a connection because, by default, it will launch a desktop session the next time you log in. If there’s a problem with the connection you may get stuck. This happened to me and I was stuck on the error:
    “Connection Error: An internal error with Guacamole server, and the connection has been terminated”

    It took a little digging but essentially the server console is up and running, but it is hidden by the black screen/pop-up and you can get back into the settings by going to the url: http://serverIPaddress:8080/guacamole/#/settings/sessions

  2. Create the user first by going to the menu in the upper right-hand corner and choose Settings:
  3.  
  4. Next, click the Users tab and then New User:
  5. Next, provide a username, password (x2), and give this new user all permissions and hit save at the bottom:
  6. With this new user created, you will now want to log in as this new user and change the guacadmin account password.
  7. Now we can create our first connection. Before you create your first RDP connection, be sure to test RDP account credentials from a different computer to ensure you can connect successfully.
  8. Click on the Connections tab and then New Connection. The only things I had to set up to get to my workstation RDP connection working were the following:            
  9.  
  10. Hit Save at the bottom. There are many additional settings available but this should get you up and connected.
  11. Now we want to assign this connection to a user. Do that by going into the Users tab again, find the user you want to assign and the connection:
  12. Now go to a different computer from the one you want to connect to, go to http://serverIPaddress:8080/guacamole site, login as the user with the connection assigned to it and you should be greeted with the RDP console of the remote computer.
  13. To setup an ssh connection it’s even easier. Again, first create a new user with the same name as the ssh server you want to connect into (I named my user HN-DHCP01). Then create a new connection and name it the same as your server. Below are the guacamole ssh connection settings I used to connect to my DHCP01 server:
  14. Under the Authentication setting, provide a valid ssh user’s credentials on the server you’ll be connecting into.
  15. Hit save at the bottom. Go back into the User tab, then select the new user (HN-DHCP01 user) and assign the connection to the user at the bottom and hit save.
  16. Log out of guacamole, then log in as the new user (HN-DHCP01) this will instantly log you into an ssh session that you can see in the screenshot below runs right in the browser!
  17. Guacamole also supports Two-Factor Authentication as well as a multitude of additional setups and configurations. It’s wise to setup 2FA prior to opening any firewall ports into your local network from the internet, as well as make sure that you follow all security precautions and test everything thoroughly.
  18. When configuring VNC for use as a remote support with Guacamole, I’ve found UltraVNC Server works best for Windows Clients. It’s a little tricky to setup on the client side and get it to run consistently across all flavors of Windows 7, and Windows 10 feature releases. 
  19. Enjoy your guacamole and let me know in the comments if I’ve missed anything.