HowTo Setup Guacamole

Overview

Apache's guacamole provides a "proxy" mechanism allowing users to make SSH, Telnet, VNC and RDP connections from the comfort of their web browser. For example:

• A Windows user can use IE to ssh into a NST system (no native software required).
• A Mac user can open up a Windows desktop using Chrome (probably Safari as well).
• A Chromebook user can click on links to open up a Linux VNC desktops or shared Windows Desktops.

Set Up

Setting up guacamole on a NST (or Fedora) based system is not difficult, but it is a non-trivial process and involves several supporting packages.

• You need to have a back-end guacamole server (guacd) that provides the native connections to the services (SSH, Telnet, VNC and RDP).
• You need to have a front-end guacamole server (guacamole) that provides the HTML 5 pages and Web Socket connections to web based clients.
• You need an authentication management system (database).

The installation directions found here are a concise version aimed at a NST (or Fedora) based system. Refer to the guacamole web site for full details and the most recent changes.

Set Up Overview

• Install docker.
• Create and start a docker machine to run the guacamole back-end.
• Create a docker machine to run the guacamole front-end.
• Create and initialize a PostgreSQL database for guacamole.
• Start the guacamole front-end.
• Log into the guacamole and change the default administrative password.

The sections below provide the commands that can be run on an NST system.

Install Docker

Run the following commands as the root user to install, enable and start docker:

dnf install docker
systemctl enable docker
systemctl start docker

During this set up, everything is done as the root user. If you want to experiment with running docker as a non-root user, refer to the Getting started with Docker page at the Fedora developer wiki.

Set Variables

In order to provide some consistency as well as the ability to customize the examples shown here, we will define some variables for our examples.

# Name of docker container for the guacamole back-end (guacd)
declare guacBack="guac-back";

# Name of docker container for the guacamole front-end (guacemole interface)
declare guacFront="guac-front";

# Database settings
declare DB="guacamole";
declare DB_HOST="255.255.255.255";
declare DB_USER="guacamole_user";
declare DB_PASS="YOUR_PWD";
# For Fedora 
declare PG_HBA="/var/lib/pgsql/data/pg_hba.conf";
# For NST
declare PG_HBA="/var/nst/var/lib/pgsql/data/pg_hba.conf";

If you copy/paste the above into your terminal window, you should be able to up arrow and then adjust values you would like to change before proceeding with the rest of the installation steps. You MUST change DB_HOST to the IPv4 address of your system (you can use getipaddr --default-address on a NST system). You SHOULD change DB_PASS to a unique password.

Start guacamole Containers

Use the following commands to initialize your guacamole docker containers:

docker run --name ${guacBack} -d guacamole/guacd;
docker run --name ${guacFront} \
    --link ${guacBack}:guacd \
    -d -p 8080:8080 guacamole/guacamole;

docker image ls
docker container ls

Setup/Start Up PostgreSQL

Use NST web interface to setup PostgreSQL server by selecting Database | PostgreSQL | PostgreSQL Database Management from the web interface. Adjust the following settings:

• Enable TCP/IP connections from 127.0.0.1/32.
• Change the administrative password to something you can remember.
• Optionally include the "-d" option under the "Additional PostgreSQL Setup Options" if you want to completely clear out all databases and start over fresh (WARNING THIS REMOVES ALL DATABASES).

Add and Initialize the guacamole Database

Use the following command to generate the initial SQL for the guacamole database:

Next we will create the database for guacamole;

psql -U postgres -c "CREATE DATABASE ${DB}"

We can now run a command within a docker container to generate the necessary SQL to initialize the new database and apply it with the psql command:

docker run --rm guacamole/guacamole /opt/guacamole/bin/initdb.sh --postgres > initdb.sql
psql -U postgres ${DB} -f initdb.sql

Now create the guacamole database user and give that user to the guacamole database.

echo -e "CREATE USER ${DB_USER} WITH PASSWORD '${DB_PASS}';
GRANT SELECT,INSERT,UPDATE,DELETE ON ALL TABLES IN SCHEMA public TO ${DB_USER};
GRANT SELECT,USAGE ON ALL SEQUENCES IN SCHEMA public TO ${DB_USER};" | \
 psql -U postgres ${DB};

Now that the tables are set up, we need to allow our docker container access to the PostgreSQL server. This is done by modifying the appropriate pg_hba.conf file and then restarting the postgresql service. The following assumes that the docker container that will have a IPv4 address somewhere in the 172.17.0.0/16 range (you may need to adjust this if your container has a different address).

echo "host    ${DB}  ${DB_USER}  172.17.0.0/16 md5" >> ${PG_HBA};
systemctl restart postgresql;

Start the guacamole Front-End

Now that the database is ready, we need to start the docker container that runs the guacamole front-end. We will first attempt to stop and remove any existing instances (in case it was running) and then start it using the following commands:

docker stop ${guacFront};
docker rm ${guacFront};
docker run --name ${guacFront} \
   --link ${guacBack}:guacd \
   -e POSTGRES_DATABASE="${DB}" \
   -e POSTGRES_HOSTNAME="${DB_HOST}" \
   -e POSTGRES_PORT=5432 \
   -e POSTGRES_USER="${DB_USER}" \
   -e POSTGRES_PASSWORD="${DB_PASS}" \
   -d -p 8080:8080 guacamole/guacamole;

Next lets verify that our docker container is running and that port 8080 has been exposed on our system.

 docker ps -a
 netstat -tnap | grep 8080

We can also do a preliminary check on the guacamole front-end error log using the following command:

 docker logs ${guacFront} | less

Initial Configuration

At this point we should have guacamole up and running. The first thing we should do is change the password for the guacadmin account.

• Point your web browser at: http://127.0.0.1:8080/guacamole/
• Log in as guacadmin with the initial password of guacadmin.
• Immediately got to Settings | Preferences and change the administrative password.

You should now be able to use the guacamole web interface to configure user accounts and connections so that your users can connect to various hosts.

Securing Tomcat

Unfortunately, the guacamole/guacamole image expose the tomcat web interface if you point your browser at port 8080. The welcome page provides some security notes and by default it does not appear that there are any accounts configured to allow access to the management features.

Based on suggestions from https://www.cb-net.co.uk/linux/running-guacamole-from-a-docker-container-on-ubuntu-16-04-lts-16-10/ and https://www.owasp.org/index.php/Securing_tomcat, you can completely remove the Tomcat management features by running the following:

docker exec -it ${guacFront} /bin/bash

sed -i 's/redirectPort="8443"/redirectPort="8443" server="" secure="true"/g' /usr/local/tomcat/conf/server.xml

sed -i 's/<Server port="8005" shutdown="SHUTDOWN">/<Server port="-1" shutdown="SHUTDOWN">/g' /usr/local/tomcat/conf/server.xml
 
rm -Rf /usr/local/tomcat/webapps/docs/
rm -Rf /usr/local/tomcat/webapps/examples/
rm -Rf /usr/local/tomcat/webapps/manager/
rm -Rf /usr/local/tomcat/webapps/host-manager/
 
chmod -R 400 /usr/local/tomcat/conf
exit

SSL Protection

You will not want to leave port 8080 open to the outside world as connections are not encrypted. On an NST system, you can configure the httpd service so that external users can access guacamole over an encrypted SSL connection. You should be able to start with a /etc/httpd/conf.d/guacamole.conf like the following:

Alias /guacamole "/guacamole/"

<Location /guacamole/>
    Order allow,deny
    Allow from all
    ProxyPass http://127.0.0.1:8080/guacamole/ flushpackets=on
    ProxyPassReverse http://127.0.0.1:8080/guacamole/
</Location>

<Location /guacamole/websocket-tunnel>
    Order allow,deny
    Allow from all
    ProxyPass ws://127.0.0.1:8080/guacamole/websocket-tunnel
    ProxyPassReverse ws://127.0.0.1:8080/guacamole/websocket-tunnel
</Location>

After creating the file, you will need to enable and start (or restart) the httpd service.

 systemctl enable httpd
 systemctl stop httpd
 systemctl start httpd

After making the above changes, verify that you can reach the guacamole web interface using a SSL connection using a URL like:

https://PUBLIC_ADDR/guacamole/

NOTE: Change PUBLIC_ADDR shown above to the IPv4 address or host name of the system running the httpd service.

Manage

Shell Prompt

Use the following command to open a shell prompt to a docker container:

docker exec -it ${guacFront} /bin/bash

Status

You can use the following commands to verify that PostgreSQL and your docker containers are running:

docker ps -a
systemctl status postgresql.service

Stopping

You can use the following commands to stop PostgreSQL and your docker containers:

docker stop ${guacFront}
docker stop ${guacBack}
systemctl stop postgresql.service

Starting

You can use the following commands to start PostgreSQL and your docker containers:

systemctl start postgresql.service
docker start ${guacBack}
docker start ${guacFront}

Docker Logs (Troubleshooting)

You can review the logs for your your docker containers when troubleshooting problems:

docker logs ${guacFront}
docker logs ${guacBack}

Removal

You can use the following commands to completely remove the docker containers and images.

docker stop ${guacFront}
docker stop ${guacBack}
docker rmi ${guacFront}
docker rmi ${guacBack}