Apache Guacamole on Podman

Apache Guacamole is the Swiss Army Knife of remote desktop tools. It offers a WebUI that allows users to access remote hosts on RDP, VNC, and SSH. The good people at the Apache Project call Guacamole clientless since it does not require any additional software on the host-end aside from the servers powering RDP, VNC, or SSH. The full-install guide looks intimidating, however, a container-runtime like Podman makes install a snap. This guide will demonstrate how to install the Podman container-runtime on RHEL and CentOS, pull and start a Guacamole container, and finally, how to create a user-scoped systemd service so that the container can be managed with systemctl.

Installing Podman


yum module install container-tools


subscription-manager repos --enable=rhel-7-server-extras-rpms
yum install podman


yum install podman

Pull and Start the Guacamole Container

The Apache official Guacamole container image requires a separate container for SQL. Thankfully, Docker community contributor, Oznu, built a self-contained container which bundles everything Guacamole needs to function. Pull the container image with the command:

podman pull docker.io/oznu/guacamole

Now to start the container image, you’ll first want to consider a few things. First, consider which port will you use to access Guacamole’s WebUI. Oznu-Guacamole defaults to 8080, so I just pipe my server’s port 8080 to the container. If you’re using 8080 for something else, you’ll need to select a different port. Ports numbered 1024 and below are known as privileged-ports, so choose a port above 1024 so that you can run your Guacamole container as a regular user rather than as root.

Second, consider what location will you use to store any data Guacamole creates, such as settings, so that they persist after the container terminates. Container people call this the ‘Writable Layer’. Creating a writable layer is optional but doing it is a great help since getting your user settings just right in Guacamole’s WebUI may take some effort. Saving these settings means only needing to do this once.

Create a location to preserve your container’s writable layer in your home directory:

mkdir ~/guacamole

Start the container with podman:

podman run -d --name guac -p 8080:8080 -v /home/<username>/guacamole:/config:Z docker.io/oznu/guacamole

Options Explained:

podman run [runs the container]

-d [detached, rather than interactive]

–name guac [name of the container, you may choose whatever name you like]

-p 8080:8080 [map local port 8080 : to container port 8080]

-v [mount the container’s writeable layer “/config” on local directory “/home/<username>/guacamole”. The :Z will set the correct selinux contexts on /home/<username>/guacamole. Substitute your own username for <username>.

Configure Firewall

For the webUI to be accessible to other hosts on our network we’ll need to open up port 8080/tcp (or the port you chose in the previous step) on the firewall.

sudo firewall-cmd --perm --add-port 8080/tcp && sudo firewall-cmd reload

Open the WebUI

If everything went right, you should now be able to open a browser on <hostname or IP>:8080 and see Guacamole’s webUI login:

The default username/password combo is: guacadmin/guacadmin. Login and change this ASAP.

Create User Scoped Systemd Service for Guacamole:

In order to have a user-scoped systemd service that continues to run after you’ve logged out you’ll need to set the linger property via the loginctl command:

sudo loginctl enable-linger <username>

Verify your loginctl settings with:

sudo loginctl show-user <username>

Make a directory to hold your user-scoped systemd service file in ~/.config:

mkdir -p /home/<username>/.config/systemd/user

And change working directory into this directory:

cd ~/home/<username>/.config/systemd/user

Use this podman command to create the systemd .service file:

podman generate systemd --name guacamole --files guac

This will generate a file named container-guacamole.service in your ~/.config/systemd/user directory.

Next, use podman to stop your running Guacamole container, and restart it with systemctl:

podman stop guac

systemctl --user enable container-guacamole.service

systemctl --user start container-guacamole.service

Finally, check the status of your user-scoped service:

systemctl --user status container-guacamole.service

That’s all folks. You can now open a web browser on your host at port 8080 and begin setting up connections to remote Linux and Windows hosts via SSH, VNC, or RDP. The user-scoped systemd service will keep your Guacamole container running after you log out and restart it if the system is rebooted. You can control the state of the container via systemctl --user [stop/start/restart].



Update: 2022/8/15 – Reader Felix points out that oznu/guacamole hasn’t received an update in some time. A quick check of docker hub reveals that it hasn’t received any love in the last 5 years, poor little pod. Several, more recently updated container images exist, including abesnier/guacamole which can be found by searching docker hub here.

2 thoughts on “Apache Guacamole on Podman

  1. Felix Fischer says:

    As oznu/guacamole seems to not be maintained anymore, I used abesnier/guacamole, which is a fork of oznu’s version. Would be nice if you could update the article.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.