Skip to content

Guacamole on Ubuntu

Updated: 20 January 2024

Getting started

To connect to the Guacamole web console:

  1. Connect to https://[instance url/ip]/guacamole
  2. The default administrator credentials are:
    • Login: guacadmin
    • Password: guacadmin

How to add an SSH connection?

  1. Connect to https://[instance url/ip]/guacamole
  2. Go to Settings > Connections
  3. Click “New Connection”
  4. Fill the details of the connection. For example: Alt text Alt text Alt text

(*) ${HISTORY_PATH}/\${HISTORY_UUID}

  1. Click "Save"

How to add an RDP connection?

  1. Connect to https://[instance url/ip]/guacamole
  2. Go to Settings > Connections
  3. Click “New Connection”
  4. Fill the details of the connection. For example: Alt text Alt text Alt text

(*) ${HISTORY_PATH}/\${HISTORY_UUID}

  1. Click "Save"

Security

Authentication

TOTP MFA

Prerequisites: To use TOTP as authentication, the user needs to have an App like Google Authenticator, or Microsoft Authenticator on their mobile (alternatively, but not recommended, a web browser App like “Proton Pass” can be used).

To enable built-in TOTP on Guacamole:

  1. SSH to the Guacamole instance

  2. Publish the extension to Guacamole:

    $ sudo ln -s /etc/guacamole/available-extensions/guacamole-auth-totp-1.5.4.jar /etc/guacamole/extensions/

  3. Restart the tomcat service:

    $ sudo systemctl restart tomcat9

HTTS / TLS: replacing the TLS certificate

It is recommended to replace the installed default certificate.

By default, the private key and the certificate are stored in /opt/tomcat/ssl/keyStore.p12

It has no password.

Ideally, you generate a new key and certificate pair with your PKI and replace the p12 file with yours.

Ensure that tomcat own the p12 file.

If a password is set on the p12 file, you have to specify it in the tomcat configuration:

  • File: /etc/tomcat9/server.xml

  • Value: keystorePass

Alternatively, you can generate a new self signed certificate with the following commands:

  1. SSH to the Guacamole instance

  2. Change of folder:

    $ cd /opt/tomcat/ssl

  3. Generate the key pair and the self-signed certificate:

    $ sudo openssl req -x509 -newkey rsa:4096 -keyout myNewKey.pem -out newCert.pem -days 365 -nodes

  4. Put the private key and the certificate in a p12:

    $ sudo openssl pkcs12 -export -out keyStore.p12 -inkey myNewKey.pem -in newCert.pem -passout pass:

  5. Ensure that the owner of the p12 is tomcat:

    $ sudo chown tomcat:tomcat keyStore.p12

  6. Restart tomcat:

    $ sudo systemctl restart tomcat9

Session recordings

How to enable session recording?

Session recording is enabled on connection basis.

To enable session recording on a connection:

  1. Connect the the Guacamole web console: https://[instance url/ip]/guacamole

  2. Authenticate as an administrator (ex: guacadmin).

  3. Go to Settings > Connections

  4. Click on the connection on which you want to activate the recording.

  5. In the “Screen Recording” section, set:

    • Recording path: ${HISTORY_PATH}/${HISTORY_UUID}

    • Automatically create recording path: X

  6. Save the configuration update

Alt text

How to view recordings?

When this connection will be used, you will be able to view the recording in Settings > History.

Alt text

Where are the recordings on the instance?

On the instance, recordings are saved in the /opt/guacamole/recordings/ folder.

Warning

You should monitor closely used space on your instance, to avoid a denial of service by lack of free space.

Logs

You can find the logs there:

  • /var/log/tomcat9/catalina.out
  • /var/log/syslog