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 -
chmod +x 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:
- 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
- Create the user first by going to the menu in the upper right-hand corner and choose Settings:
- Next, click the Users tab and then New User:
- Next, provide a username, password (x2), and give this new user all permissions and hit save at the bottom:
- With this new user created, you will now want to log in as this new user and change the guacadmin account password.
- 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.
- 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:
- Hit Save at the bottom. There are many additional settings available but this should get you up and connected.
- 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:
- 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.
- 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:
- Under the Authentication setting, provide a valid ssh user’s credentials on the server you’ll be connecting into.
- 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.
- 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!
- 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.
- 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.
- Enjoy your guacamole and let me know in the comments if I’ve missed anything.
21 thoughts on “Setup Guacamole Remote Desktop Gateway on Ubuntu with one script”
Do you have a guide for adding AD/LDAP authentication for this?
Sorry, no. Let me know if you find something.
A big Thanks… This script saved my day…
One question.. do you have any idea how I can configure Nginx reverse proxy after using your script to install Guacamole?
Also I need to change the url path in the address bar from
to something like
To change the /guacamole just rename at /var/lib/tomcat8/webapps
Remember, if update in future, need to bring back the name before doing it.
Hi, thnx for the tutorial it worked for me until when I try to connect to desktop. What is the parameters for the network, Your is 10.0.10.51 is that your machine internal ip
10.0.10.51 is the internal IP of the ubuntu server that runs guacamole. 10.0.10.182 is one of the computers that I want to connect to remotely from the outside going through 10.0.10.51.
I have followed your tutorial and it works a treat.
However, since I reach it from the Internet, I would like to protect the connexion using SSL. Do you have a simple tutorial for that?
Keep up the good work!
Since Guacamole does not provide SSL itself, you need to put a reverse proxy like Nginx in front of it, to secure connection.
Check out here: https://kifarunix.com/configure-guacamole-ssl-tls-with-nginx-reverse-proxy/
Hello loved the tutorial,
can you share how i would get to guacamole through the web to my classroom Computers
You would have to port forward on your firewall to a single IP on your LAN that is the server which is running guacamole right?
Thanks for this tutorial. I have it set up and was able to RDP into my desktop successfully. However, there is a log of lag when I try to scroll or drag anything on the desktop. It can’t seem to render scrolling/dragging correctly. Any advice on how I can fix this? When I connect with the native windows RDP application everything works fine.
Yes I’ve seen this to a limited degree. Sorry no advice on resolving the lag issue. Maybe something to bring up with the guac devs at their help site here: https://sourceforge.net/p/guacamole/discussion/
I have followed the same steps,but it says invalid login
having trouble in connecting RDP and SSH,Please help
hi, good script. is it possible for the login page to be custom?
For example, can the logo be changed?
How to disable the two factor authentication !?
Go to etc/guacamole/extension/ remove the file guacamole-auth-totp.1.0.0.jar and restart the Tomcat server and restart guacd
How to install open ID and Configure in Guacamole.
Used your script and it worked for the most part, but it failed on creating the guacamole_user MySQL user. I created it manually and granted all permissions. However, the login page is still blank. Ever encountered this before or heard of the fix? Their mailing list archive isn’t any help.
I want to integrate with AWS Cognito for Open ID connect so that Cognito users can login to Guacamole with their credentials. How can I acheive it?
Was following the steps listed above. All was going well. I am stuck at signing into the apache gaucamole log on page. Went back an verified the user name and password. Cannot get logged on. What should I look at to troubleshot this issue?