Apache Guacamole is for remote professionals who want to get work done, PERIOD.

NOTE: This article is a large overview with some key specifics. If you'd like to see this broken into several smaller parts with step-by-step instructions let us know in the comments section. If you like this content, kindly consider donating to keep this website free to all, never with ads.


Mainstream Remote Options (pretty much suck)

Mainstream Remote Options

We've tried the typical "top 10" remote tools including but not limited to: Logmein, NoMachine, Splashtop, TeamViewer and Zoho Assist. They are all meant for the Windows world and they have zero Linux support and if they do, are really poorly implemented. They all have finicky clients and outrageously over-priced subscription models. Don't get us started on the privacy issues.

Logmein = $$$$$

Lets talk about the elephant in the room: Logmein. For the Linux user there isn't a client beyond basic shell (hahaha). However, it is arguably the most popular service when it comes remote access systems for check-writers and the Microsoft desktop.


Joking aside, there are costs to every decision despite any hands-off posturing. Not all costs are directly financial. There are costs in terms ease-of-use and performance-per-dollar.

Logmein works but in our experience it just doesn't feel like a good value. For example even when both remote and local computers are using 100mps+ connections (Comcast Business 😡) we are left with a bad aftertaste from the DSL era in terms of performance. One must remember that upload speeds are typically 1/10 of any download speed your ISP will provide to you so YMMV significantly (one of many bottlenecks). Using the Logmein client, especially going more than one machine deep, the experience often lags. Working with 15 fps is just unusable and the recommended in-browser variant is laughably terrible. Multiple monitor support is pretty awful too. For the price, this is just unforgivable (and no Linux!).

Circling back to actual dollars, the graphic below taken directly from Logmein plan options (https://www.logmein.com/buy) in 2021 shows the pricing tiers. Apache Guacamole presents a potential and substantial savings and performance increase over the so called industry best.

LogmeIn pricing as of 2021.

Savings Example

The cheapest option, 2 computers for ~$350 a year could probably be run off a Raspberry Pi tucked into a empty shelf somewhere for about $100 for a full 8GB kit, plus a yearly fee of ~$120 with a 2GB reverse proxy host. Likely that set-up could easily handle up to 4-8 users at any given moment. Subtract Logmein's tier of $840 for a total savings of ~73.8%(!). Each year after this would reduce to 85% savings (more if Logmein continues to raise prices as they have done for several years starting circa 2018). Of course there is administration costs but for argument's sake these would likely be similar once set in an automated manner. User support and admin of machines is likely to be a push in terms of cost. The CFO and bean counters would likely push for a substantial savings and so too the penny-pincher.

Practicing the Faith

The best tools are mostly invisible, do a few things right and then get the hell out of your way. This is the Unix[-like] philosophy as stated by Doug Mclroy in the Bell System Tech Journey in 1978: "Make each program do one thing well. To do a new job, build afresh rather than complicate old programs..."

Apache Guacamole does it's "one thing" fantastically but it can be challenging to set-up for the un-initiated, or even using a docker container (hence why this overview and editorial exists). It took us three attempts and it was only the last one that worked easily and without headaches - or as older Linux critics joke, spend "writing drivers and configurations for days on end."

The Solution

Apache Guacamole

Runs on Ubuntu 20.04.


Nginx logo.

Guac Installation

The FASTEST and EASIEST method to install Apache Guacamole clientless remote desktop gateway (using VNC, RDP, and SSH) is to simply use this awesomely powerful and dead simple script by MysticRyuujin on github.

Operating System

We used Ubuntu 20.04 within a virtual machine hosted on a pre-existing remote business network. The server itself was hosted inside a VMware ESXI environment. This included reserving and then setting a static IP for the Ubuntu server within that environment. For the noob, be very careful with proper spacing in any Ubuntu netplan static IP config file.

Ultimately it won't matter how you host your Ubuntu server as long as you can control its IP address and available resource pool. So run MysticRyuujin's script following his directions inside your Ubuntu 20.04 server. That's the easy part.

Domain and Web Server

You'll need to have a working domain running Nginx. We are using a 2GB droplet on Digital Ocean which hosts several low-traffic websites along with a testing environment. So this tutorial not only shows you how to install and use Apache Gucamole but also use a reverse Nginx proxy within a multi-site virtual hosts Nginx situation.

For future scalability we'd recommend not doing that if you plan to have dozens or hundreds of remote users - but all situations are unique and its up to you to decide. One could always increase resources if remote users complain about bandwidth.

You'll need to create your own specific Nginx configuration file to set up your domain as a reverse proxy to your actual remote machine. This assumes you already have a working domain and that you know how to set up the appropriate A-record.


Below, an example of an Canonical-Name record at domain registrar GoDaddy. This might look a bit different depending on what registrar you use for your domain. Using the CNAME record easily allows use of a word for the sub-domain without having to specify an IP like you would with an A-record.

We simply used "guac" as our sub-domain. It will function as the user login location for the Guacamole system.

CNAME example.

The next requirement is to either create or update your SSL cert from LetsEncrypt. They (along with EFF) have made it super easy to get free and secure certs using open-source software. We won't get into all of the details on how to set up your first cert but we are assuming you have some experience in doing so.

Creating an SSL Cert

Here is an example of the cerbot command below that we used to update our own cert. Simply change the "YOUR-DOMAIN.com" to your actual domain name. If you are not using "guac" as the sub-domain, change that also to your desired sub-domain. You'll notice this includes the "--dry-run" flag, so its just a test. If it passes on your server, remove the flag to actually apply the changes and generate a new certificate.

./certbot-auto -d YOUR-DOMAIN.com -d www.YOUR-DOMAIN.com -d guac.YOUR-DOMAIN.com -d www.guac.YOUR-DOMAIN.com --dry-run

Nginx config

The Nginx configuration below can be copied and pasted into your virtual hosts file but you'll need to change the "YOUR-DOMAIN.com" with your own domain details. You'll also need append or change the SSL certificate information you created earlier. Since we had a shared SSL cert for the domain we wanted to create a new cert specifically for the guac sub-domain. We had to manually edit the location for the fullchain.pem and privkey.epm file location (otherwise it'd just point to the old cert). LetsEncrypt is likely to mod the file for you if you use that option when creating the cert the very first time. You will likely have to create the log file locations else this will trigger an error.


server {
listen 80; server_name guac.YOUR-DOMAIN.com www.guac.YOUR-DOMAIN.com;
return 301 https://$host$request_uri; }

server {
listen 443 ssl;
server_name guac.YOUR-DOMAIN.com www.guac.YOUR-DOMAIN.com;

add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
add_header X-XSS-Protection "1; mode=block";

client_max_body_size 15M;

ssl_certificate /etc/letsencrypt/live/YOUR-DOMAIN.com/fullchain.pem; # managed by Certbot
ssl_certificate_key /etc/letsencrypt/live/YOUR-DOMAIN.com/privkey.pem; # managed by Certbot
include /etc/letsencrypt/options-ssl-Nginx.conf; # managed by Certbot
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
ssl_session_cache shared:SSL:50m;

access_log /var/log/Nginx/guac/access.log;
error_log /var/log/Nginx/guac/error.log;

location / {
proxy_pass http://YOUR-INTERNAL-IP:8080/guacamole/;
proxy_buffering off;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
access_log off;


File Transfer Size

You may notice the line that is marked # LIMITS FILE TRANSFER SIZE THROUGH GUACAMOLE REMOTE/LOCAL in the config above.

You are likely to want to transfer files back and forth between your remote computer and any local computer you are using. This line assures that you can move files up to 15 megabytes in size. You can change this amount to suit your specific needs.

For very large transfers, we recommend increasing this rule to complete the tasks then limiting it back down. Many users transferring large files could overwhelm your server's bandwidth or ability to maintain connections if you have a particularly busy server. Large file transfers aren't a big deal on a quiet instance or alternatively use a file sharing service. For a corporate environment this is likely OneDrive or for the education space Google Drive.

We highly recommend if you do allow file transfers through Guacamole set a cron job to periodically clear out the server's download location every 5 or 10 minutes. More on that in a moment in the remote configuration example.

Login and Hardening

At this point you should be able to login to your Apache Guacamole instance at: guac.YOUR-DOMAIN.com and your website should be SSL encrypted.

You'll use your default administrator username and password that you defined with the install script (inside of Ubuntu server).

You will be presented with a QR code the very first time you login, if you correctly elected to use time-based OTP secondary authentication (do this, seriously).

Log in

Combined with your reverse proxy a 3rd party won't be able to easily read any data to and fro your remote and local machines. However, this is only the first step in securing your Apache Guacamole installation.

Other security measures should be put into place including but not limited to, in no particular order:

1) always set-up OTP time factor login for the Apache Guacamole during installation
2) setting firewalls properly between your internal systems and gateways
3) whitelisting your reverse-proxy web server to be the only appropriate access point into Apache Guacamole, deny all others
4) whitelisting the user's specific IP addresses only, deny the rest
5) utilize SSH tunneling between remote and local machines
6) use Fail2Ban to stop brute login attempts
7) lock the remote machines based upon local time (during sleeping hours)
8) others not covered here (leave your ideas in the comments section)
9) keep all machines updated in near real-time with latest service packs and security updates
10) close any and all ports not in use
11) have a back-up plan in place using the "the rule of three"

Remember, even though your browser is translating RDP or VNC into Javascript via the browser the security considerations are serious!

Connection Settings

Although the official Apache Guacamole documentation and manual is very detailed, we can at times find it hard to follow. The docs are better once you get into Chapter 17: Administration.

We wanted to include a singular minimum configuration example to get connected to a remote machine. This example is a Windows 10 workstation that is authenticated behind Microsoft Active Directory.

Why Windows on a Linux blog? This is numerically the most common remote machine desktop and often the most finicky character, sitting in Redmond-land. Apache Guacamole in our minds is the perfect replacement for Logmein (which again has no Linux support in the first place - but Guac certainly does).

It should be trivial to set up a Linux desktop or even other operating systems once you have a singular machine up and running in your Apache Guacamole server. If there is demand, we can always update this article or create another in the future but the basic process will be the same.

Apache Guacamole
Image manipulated for privacy. Actual image of a physical Windows 10 remote desktop via Apache Guacamole service via Firefox, on Ubuntu MATE 20.04.

Window Remote Tweaks

There are a few things that must be done on the Windows side to make this more manageable so access feels less like a remote session and more of an in-person experience. So yes brave reader, we have to modify a Windows system option item on the remote, yay!

Utilizing RDP protocol, Windows will kill off your session after a set time, regardless if you are the only user (or not) and shutdown programs (even though it claims it won't). You must "enable" the non-service - its important to change the default session timeout to "never" using this path:

On the Windows remote PC:

1. Open gpedit.msc
2. Browse to Computer Configuration --> Administrative Templates --> Windows Components --> Remote Desktop Services --> Remote Desktop Session Host --> Session Time Limits. 3. Enable the "Set time limit for disconnected sessions" and set it to Never

RDP Session Time Out Limits

Basically with this change Windows won't treat every single RDP session as a different event, rather a continuation of a previous event. You'll be able to work, leave programs open without fear of loosing data until a forced Windows Update restart or one you actually trigger yourself. We would recommend the remote machine reboot every evening at a set time and lock immediately after a short period of inactivity. It goes without saying if you are using RDP (as our example will) the remote machine must have RDP enabled.

Now that we have a machine that is more or less ready to be used let's get to the bare-bones configuration of the machine within Apache Guacamole itself. It can be quite easy to get up and running. Your environment might be substantially different.

Connections in Apache Guacamole

The section on connections is pretty good in the Guacamole manual but it helps to have labeled images, so we've included both the input fields along with images below each written section.

EDIT CONNECTION: This area is mostly labeling but contains what method of connection to use, eg, RDP, VNC, SSH etc. This example uses RDP.

Name: Remote PC name (arbitrary)
Location: Group name (set up first in admin, works like a folder)
Protocol: RDP (don't forget to enable RDP on the remote machine).

PARAMETERS: This area passes information from your local machine through your remote so you can access the remote as if your browser was the remote itself.

Hostname: This is the name or the IP of the remote machine.
Port: If using RDP, the default should be 3389.

Username: enter the remote machine profile username
Password: enter the remote machine profile password
Domain: enter the domain name of your remote network (do not use .com).
Security Mode: NLA if using Active Directory (as this example).
Disable Authentication: leave unchecked
Ignore Server Certification: if using a self-sign cert, check this option.

DISPLAY: This area can be safely ignored or tweaked to your liking but if you are on a decent network connection, use True Color and Display Update for the Resize Method.

DEVICE REDIRECTION: This section controls audio and is up to you to use (or not) but most likely there's no need to play audio from the remote into your local machine. It can be safely disabled to save some bandwidth, especially if there are multi-users. Be sure to also mute your remote machines as well so users won't blare audio into remote locations and disturb those spaces.

Enable Drive: this permits you to share files between your remote and local device and in our opinion should always be checked.
Drive Name: Label the virtual drive anything you wish.
Drive Path: This is where files will be dropped to transfer between remote and local machines. We would recommend setting up a cron job to purge this directory every 5 mins because users will tend to fill up your server with files rather than use online file sharing services like OneDrive or GoogleDrive because its easier to use the build-in transfer. In case you missed it in the manual pressing CTRL+ALT+SHIFT on your local machine will reveal the Guacamole user control panel to logout, share keyboards and transfer files.
Automatically Create Drive: check this for simple functionality, un-check if you have a pre-established shared location.

The final bit which is quite important is the Guacamole Menu. As per manual this is where you will find the hidden sidebar within your browser that is invoked with the keyboard combination: CTRL+ALT+SHIFT.

The chapter for the menu is pretty great and there's no real need to replicate that content here but we will provide a summary as follows:

The menu allows you to navigate back to the home screen, share content between the local machine and the remote screen including the clipboard and file transfers as previously mentioned. There are also options for controlling pointer devices and keyboard input as well as zoom controls. Lastly, the menu provides an explicit session sub-menu to end a session and log out of Guacamole entirely. We advise to always using the logout option when you are done using your remote machine to be sure the connection is closed gracefully.

Results and Final Thoughts

We've been testing this exact set-up for over 4 weeks (at the time this article was written) and we have to say the results are pretty fantastic when compared to our old or other tested remote investigations. The remote machine is used daily during normal business hours.

Apache Guacamole is really, blazing fast; its faster than Logmein and gives us better local access over any sort of VPN solution without the headaches. The file transfer tool along with the minute keyboard control types are easy to use and fast.

The screen automatically resizes as we use our browser so we never have to deal with multiple monitors or changing the views like you would with Logmein, TeamViewer or a VNC program. Our remote machine uses three separate monitors of varying resolution while our local machine uses one single large screen (a 4K 48" TV). Its as if the the remote computer is using our local screen which is a huge boon considering window placement and easy accessibility are issues constantly referenced in complaints by Logmein and remote users in general.

And of course, the real beauty of Apache Guacamole (aside from its cost savings), it uses the browser as its access method. You are freed from the OS wars including mobile OS which are compatible; if it has a browser you can use it to access any other machine, and get what you need to do, done. Did I mention it uses and runs on Linux? ❤️

Thanks for being here!

If you've made it this far, thanks for sticking it out with us in this rather large overview. We'd love to hear your comments and experiences in the comment section below. And if you want step-by-step instructions with every detail that can happen if enough of you voice the demand.

If you are interested in creating an Apache Guacamole installation for your home or business we are happy to offer our services including up to 1 hour free consultation. To get things started, please contact us, voicemail at (559) 242-6647, or send a SMS. We are here to help!

About the Writer
Chris Lessley
Author: Chris Lessley
A server admin, dev ops warrior and website designer since 2002, Chris is a lover of all things Linux and open-source! Each blog topic has been tested by fire in the real world and shared with the hope to help others. Need more help? Hire me! Chris' other interests include fine art and the humanities in the classical tradition and can be found writing for our friends over at gripfastart.works. If you like this content, kindly consider donating to keep this website free to all, without ads.

Comments powered by CComment

Member of The Internet Defense LeagueOpen Source Initiative