Apache Guacamole is a terminal server you can run in-house to provide access to pretty much any server you are running using nothing but a web-browser. It can be installed onto a physical host or VM, or run as docker containers. Installed natively you will need at least 4Gb of memory and a couple of CPUs; installed as containers it will run happily on a host with 2Gb memory (I have run it in 1.5Gb OKwith minimal swap usage if it is dedicated to that) and a couple of virtual CPUs.
Useful for those that do not already have tools to provide the ability to SSH, VNC or RDP into remote machines; it does not yet support the spice protocol so not really suitable for KVM users unless you want to reconfigre them from the default of spice to vnc (not as simple as it sounds and if you are a Linux user which you are if using KVM you are then you already use remote-viewer that supports both spice and vnc for access to all your VM consoles).
For windows clients that may not have all the opensource tools Linux users have or those that simply like the idea of accessing everything via a web browser this is also useful.
There are lots of Videos on YouTube showing how easy Apache Guacamole is to setup and use. Interestingly none of those videos mention any of the pitfalls or issues you can expect from using it; so I will cover a few of those here.
If you have not already implemented remote access from your desktop to everything in your home lab this can be very useful, although in all honesty it is only easy to setup if you have already setup remote access to everything already. The reason I say it is easier if you already have setup remote access in other ways already is covered in the available connection types available quickly listed here
-
- Kubernetes, I have not tries to figure this one out yet
- Telnet, nobody uses that to logon anymore
- RDP access to windows machines, is obviously going to be easier if you have already configured your windows machines to accept RDP connections
- VNC access to windows machines, is obviously going to be easier if you have already configured your windows machines to accept VNC connections (I use TigerVNC to remote access my windows machines as RDP is only available in windows professional/enterprise editions not home editions)
- SSH access to remote machines, is obviously easier if you already have a existing private key on your desktop for your user that you already use to SSH into your remote machines, so you can simply add the username and paste the existing key when defining SSH sessions for your user (which is not good practice, but I have put my thoughts on that below)
- SPICE is not yet implemented, this is bad if you use KVM virtual machines as by default all console sessions for KVM instances default to SPICE [which you have of course configured to fixed ports] (and I have a few notes on that below as well)
My notes on point E SSH are that while it is probably best practice to have a private key per machine the user is likely to logon to with the public key copied to all the servers the user is likely to want to ssh to from each of those machines apart from it eventually becoming unmanageable… it does not actually work like that which is why private keys should be secured tightly, you can copy the private key to any machine and it will work.
For a home lab I will in most cases have one private key per user (not machine) and use puppet to push the public key to all the servers (and puppet to push the private key to ‘desktop’ roles the user is in) so I can change the keys in a few minutes if needed… at the *nix level; which is where applications start making it messy…
Example1: AWX (or ansible tower), as I do have a few ansible scripts I ran from the command line (ssh keys deployed by puppet of course) when I started playing with AWX I just imported the same SSH key used from the command line into AWX and it all just worked
Example2: Guacamole (this post), I just copy/pasted the private key text into each host connection entry for my username, and SSH from Guacamole just worked [so make sure for those cases no definitions are “shared” as user/key should not be shared]
Why are the examples relevant ?, because in both those examples the SSH keys are stored in databases now, not just in the users .ssh directory, using a tool like puppet or ansible to change keys globally is no longer an option. Possibly an ansible script could walk through the Guacamole SQL database searching for records containing the username and updating the key (it is in every user SSH connection definition); other scripts for every other application that wants to use SSH… becoming unmanageable again. For Guacamole you could configure user/password and set all your servers to allow password logons across SSH but passwords expire more often than keys.
My thoughts on this: Just something to be aware of… lots of youtube videos on how easy Guacamole is to setup, none on the issues you will encounter as you periodically change keys and have to update every connection entry.
My notes on point F SPICE, when using VMs under KVM the default console type is SPICE, and of course you edit your virsh definitions to use a fixed port per VM and open firewall ports to the host for the connection, so from your remote desktop when things go wrong and you cannot ssh in you can connect to the VM console from your desktop with a simple “remote-viewer spice://hostname:portnumber –display $DISPLAY” to fix the problem.
It is possible to use “virsh edit” to play with the “graphics” section to change the KVM console settings from SPICE to VNC, in which case ytou would simply change spice to vnc for remote-viewer and use “remote-viewer vnc://hostname:portnumber –display $DISPLAY” to access the console from the command line. And when it is configured for VNC Guacamole can connect to it.
However changing from SPICE to VNC gets more complicated with every update to KVM, SPICE now has a lot of hooks into USB virtual devices so it is not simple a case of changing the “graphics” section from spice to vnc anymore, and delting all the USB entries tied to SPICE devices can leave you with no mouse when you VNC into a remote Gnome session which is pretty fatal for troubleshooting. But it can be done.
My thoughts on this: VNC has been implemented which is nice, RDP has been implemented which is only available on Windows professional editions (not available on Windows Home editions) but SPICE which is the default for all KVM VMs has not been implemented and not considered a priority so while it is nice Apache Guacamole is free remember it seems targeted at large commercial users (nobody at home has Windows Professional with RDP or running kubernetes) and most Linux users use KVM and spice. For home windows users TigerVNC server installed on your windows machines will work with the VNC connection type [ without Guacamole just using the command line “vncviewer -geometry 1366×768 windows-machine-ipaddr” works to test that ]; and there are a couple of developers working on providing SPICE to Guacamole (thanks folks) so it may be available one day, but at the moment if you use KVM Guacamole is not for you it you want it for console connections to KVM.
I did mention earlier in the post it is easier to use Guacamole if you already had an environment for already remotely connection to everything. What made it easy for me to setup was my existing environment, which of course it all run from a terminal session under Gnome to provide the display; my environment is…
- All my KVM instances do not use port “auto” for consoles, but have explicit port numbers assigned (and firewall ports opened). The consoles whether spice or vnc are remotely accessable from my desktops for those occasions when the server stops accepting ssh sessions (those that are VNC can be added to Guacamole easily; those that are SPICE cannot).I just have a shell script “vmmenu” that lets me select any VM console on any of my VM hosts that I want to connect to
- I have a single private SSH key for my personal userid on my desktop(s), public key deployed to all Linux servers and VMs by puppet-ce; so I can already SSH to any server. Configuring Guacamole to SSH to the servers was simply a case of using the same userid and pasting the same private key into the connection entryI can ssh into any server without needing Guacamole
- I only have Windows Home Edition on my dual-boot laptop, Windows Home Edition does not allow RDP into it. TigerVMC however is installed on it and “vncviewer” as mentioned above can remotely control that just as well as RDP could.Note: TigerVNC allows multiple connections to the same session, noticed only when I was playing with Guacamole as I had both a Guacamole (in a web browser) and vncviewer connection active in different windows at the same time, and could see a mouse move from one interface move in the other; whether that is good or bad is up to you. You should configure each user session so each user has a different port, but you do not have to apparently :-)
So with my environment the advantages Guacamole gives me are… none. The disadvantages are that webservers (whether firefox, chrome, brave…) all chew through unreasonable amounts of real memory (and swap) on any Linux desktop.
It is also fair to say you would never open up a Guacamole server to be accesable from the internet. Maybe if you had a VPN into your environment ? (which you would need to resolve hostnames/ipaddrs anyway).
Soooo… I am not sure who all those YouTube videos on how wonderful it is are aimed at. Nor where this solution is aimed, it is not at Linux users as SPICE is needed for anyone that uses KVM, not at home users as Windows Home edition does not have RDP, not at corporate users as having ‘connection’ properties where for every connection properties are at a user level is not feasible (not that I would ever want anything to go near windows directory/ldap as that immediately breaks everything).
My thoughts: I have no idea what target this tool is being aimed at, or what problem it is trying to solve as at the moment it is partially useful for a home lab environment but it works for what has been implemented. Additional protocols and authentication methods may (probably will) be added over time but I am still unsure of the target audience [ to allow access to remote servers using only a web browser… for those clients that do not already have clients for rdp/ssh/vnc/telnet/kubernetes (I cannot think of a single client OS that does not already have a client for the protocol) ].
But it works, so lets contnue on.
Fast start setup using the container docker implementation
- Create a new VM, min 2CPU and 2Gb Memory (I used Debian as the OS)
This is not covered here as you should already know how to create VMs - Install docker
This is not covered here as you should already know how to install docker (not podman) - Install mariadb or mysql
This is not covered here, you should know how to install this from the existing repos and it is different depending on whether you are using a rhel or debian family OS - Use the provided container to generate the SQL required to create the DB, and create the DB
- Run it
- logon, (otional change admim user/password,) create a group and user, and start creating connections
-
Step D – create the mariadb/mysql database
A container is provided that generates the DB schema; generate that, use mysql to create a database and permissions and then run the generated schema.
docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --mysql > initdb.sql mysql -u root -p [reply to password prompt] CREATE DATABASE guacamole_db; CREATE USER 'guacamole_user'@'%' IDENTIFIED BY 'guacamole_pw'; GRANT SELECT,INSERT,UPDATE,DELETE ON guacamole_db.* TO 'guacamole_user'@'%'; FLUSH PRIVILEGES; USE guacamole_db; \. initdb.sql exitStep E – Run it
The only thing to note is that the “guacd” must be started first so the other container can link to it. You must also of course ensure the DB paramaters match what you created just above.
docker run --name mark-guacd -d guacamole/guacd docker run --name mark-guacamole \ --link mark-guacd:guacd \ -e REMOTE_IP_VALVE_ENABLED=TRUE \ -e MYSQL_HOSTNAME="192.168.1.189" \ -e MYSQL_PORT=3306 \ -e MYSQL_DATABASE="guacamole_db" \ -e MYSQL_USER="guacamole_user" \ -e MYSQL_PASSWORD="guacamole_pw" \ -d -p 8080:8080 guacamole/guacamoleThats it, when a “docker container list” shows they have gone from starting to started it is ready for use, simple yes ?.
Step F – Use it
Point your web-browser at your host port 8080 (remember to open ythe firewall port on your host) and you must have the guacamile/ part of the url… in the example above the URL would he http://192.168.1.189:8080/guacamole/ and logon with the defaults of user “guacadmin” with the password “guacadmin”. At that point you should create a group and your own admin user and delete the default one.
Logon, under your “name” on the right top of the window is a “settings” option, use that to start creating “connections” to your servers.
For ssh connections as I mentioned earlier I prefer to use a username and private ssh key, user/password may work instead. As I only have Windows Home edition (does not provide RDP server) I use TigerVNC server on windows machines and VNC in to port 5900 which works fine. For KVM consoles my graphics section of each KVM listens on explicit ports and ipaddrs (not “auto”) and a few I have converted from spice to VNC but the bulk of them I will wait until Guacamole supports the default KVM spice protocol and stick to remote-viewer rather than use Guacamole.
Leave settings and go back to the home screen to start using the connections.
One usage note: when you connect the browser tab is dedicated to that connection, start another tab/window to the guacamole URL to start a connection to an additional machine (repeat as needed). Then you can just switch between the tabs to switch between your active connections. On the main URL page where it shows a list of machines you are connected to… ignore that as it does not show all the active connections in the pretty picture section, you need to look at the list a little further down the page.
