Today we are going to look at how to install Apache Guacamole on a Raspberry Pi.
Apache Guacamole is a clientless remote desktop gateway that runs in your browser. In summary, you’re able to RDP, VNC, or SSH into devices on your network through a web browser. You can also setup Telnet and Kubernetes, but we won’t be going over that in this tutorial. The tool works very well and allows you to manage all your connections in a centralized location accessible by a web browser.
It is my recommendation that you use a Raspberry Pi 4 when using Guacamole since it supports gigabit ethernet. This will work on all Raspberry Pi devices, but the network bandwidth is what will ultimately limit you when using older devices.
We will set this up by using Docker and Portainer, so if you haven’t set that up yet, please check out my tutorial here.
If you’d like to learn about the Apache Guacamole Docker container or install it without using Portainer, you can find the github page here.
1. Instructions – Raspberry Pi Apache Guacamole
1. First, we are going to create a volume in Portainer. Open Portainer and select Volumes. Then, select Add Volume.
2. Enter the name as Guacamole and then create the volume.
3. Go to Containers and Add Container.
4. Enter the name as Guacamole and under image, enter oznu/guacamole:armhf. Select Publish a new network port and enter 8080 for both the host and container. NOTE: If you are using port 8080 for anything else, you can use a different port.
5. At the bottom, select Volumes and then map additional volume with the path as /config and the volume that we created earlier. Select Restart Policy and change the restart policy to Always. You can then deploy the container!
6. The image will now download and then install. You will need to give this upwards of 5-10 minutes for the entire process to finish. When it does, you can navigate to Apache Guacamole by your Raspberry Pi’s IP address and port 8080.
http://[RASPBERRY_PI_IP]:[PORT]
7. When you access the landing page, log in with the username guacadmin and password guacadmin.
8. The first thing we will do is create a new username and delete guacadmin. In the top right, select guacadmin and then settings. Select Users and then New User.
9. Create a new user and save. NOTE: There are a bunch of different options here that you can tinker with if you’d like.
10. Logout and then log in with your newly created user. Navigate to the settings and then delete the guacadmin user.
11. The setup process is now complete!
2. Remote Connection Setup
Setting up a remote connection is super simple. The key is to ensure that the destination device (Windows, Mac, Linux PC) is configured properly. Generally, you will be using RDP or VNC sessions if you’d like to view the desktop of a destination PC and SSH if you’d like to connect to the terminal. I’m not going to go over each example, but I will go over the general way of adding a new group and connection.
2.1 How to Create a Connection Group
Groups give you an easy way of structuring your machines. This will need to be created based on your requirements, but I generally split my machines up by category (Windows, Linux).
1. Navigate to the settings and select Connections, then New Group.
2. Give your group a name, modify any settings you’d like, and select Save.
2.2 How to Create a New Connection
Connections are what you’ll use to connect to your machines. I am not going to give specific examples but will show you how you can create RDP, VNC, or SSH connections.
1. Navigate to the settings and select Connections, then New Connection.
2. Enter a Name and then select Location to pick a group. Under Protocol, select RDP, VNC, or SSH.
3. There are a ton of settings here, but simply entering the information in the Parameters section will allow you to connect. Add your Hostname and port (3389 for RDP, 5900 for VNC, 22 for SSH). Then add your Username and Password to the destination device and save the connection. There are a ton of other options that can be changed, but in general, these are the most important.
2.3 Multi-Factor Authentication
There are many reasons why someone would want to expose Apache Guacamole to the outside internet. Generally, it’s suggested that rather than exposing the service, you use a VPN to tunnel back to your home network. However, if you want to expose this to the internet, you can use Nginx Proxy Manager, set up an SSL certificate, and enable two-factor authentication on Guacamole. To enable two-factor authentication, follow these steps.
1. Open Portainer, navigate to the container, and select Duplicate/Edit.
2. At the bottom, select Env and add an environment variable.
3. Enter EXTENSIONS in the name and auth-totp in the value.
4. Select Deploy the container. The container will now redeploy and when you login, you will be asked to set up two-factor authentication!
3. Conclusion – Raspberry Pi Apache Guacamole
Apache Guacamole is an awesome little tool and it’s super easy to setup on a Raspberry Pi. It’s very nice to be able to manage remote connections in a central location and it’s great that it works on all devices with a web browser! I’ve always used remote desktop connection tools but it was an entire setup every time I’d like to implement it on a new device. This is an easy way to hit all of your devices at the same time!
If you have any questions, please leave them in the comments. Thanks for reading!
