Skip to main content

Guacamole integration details

Bravura Privilege can provide access to remote systems using access disclosure plugins for Guacamole. Guacamole is a third-party remote desktop gateway that supports standard protocols including RDP, SSH, VNC, and Telnet. It is clientless, which means there are no additional software or drivers needed to view the access disclosure plugins on your workstation; all that is required is a dedicated Linux-based system to act as the Guacamole remote desktop gateway. The access disclosure plugins can then displayed on an HTML5-supported web browser.

There are two main pieces of software that run on the Guacamole gateway:

  • The guacd service, which is a server package that acts as a proxy that connects to the managed system;

  • The guacamole package, a Java web applet that runs on Apache Tomcat,

    • guacamole acts as client to the guacd service and as server to the user's browser

    • It also acts as client to the Bravura Privilege sessmonc CGI to which it sends session monitoring data if that feature is configured.

Guacamole access disclosure plugins have similar functionality as the native access disclosure plugins, but instead of having to manage a diverse set of local programs for remote access to target systems, provides a convenient, centrally-configured thin client. It also completely hides the password from the target system administrators (unlike native disclosures, which normally provide the password in plain text on the command line which is captured in the admin's workstation Task Manager process and in the Windows Event log.)

The plugin controls contain default attributes to customize behavior, and are compatible with session recording.

The only drawback of the Guacamole disclosures is the need to install and maintain the third-party Guacamole services on Linux proxy systems, and to calculate how many such systems are required for the amount of users who can disclose access at the same time.

How it works

  1. A user checks out a single account or account set and accesses a Guacamole disclosure plugin. This redirects the user to a specific URL on the Guacamole gateway.

  2. The URL opens a browser window that contains specific information about the managed account checked out, including the checkout ID, account ID, and the type of access disclosure plugin requested.

  3. The Guacamole gateway contacts the Bravura Privilege server using the CheckoutStatusGet and CheckoutParamsGet API calls to get information about the status and validity of the account checked out.

  4. If the check-out is deemed valid, the Guacamole gateway initiates the disclosure session to the managed system and shows the resulting screen in the browser window.

  5. The user can now interact with the managed system from that browser window.

  6. The Guacamole gateway contacts the Bravura Privilege server using the CheckoutStatusGet API call periodically until the checkout is no longer valid or until the user closes the disclosure session.

There is greater flexibility when using Guacamole access disclosure plugins. It can be viewed on commonly used browsers such as Google Chrome, Mozilla Firefox and Microsoft Edge. Unlike native access disclosure plugins which are limited to Windows, you can view Guacamole access disclosure plugins on other operating systems such as Linux, provided that it has a HTML5-compatible browser. Guacamole access disclosure plugins can also be viewed on mobile devices such as smart phones and tablets.

Guacamole access disclosure plugins have similar functionality as the native access disclosure plugins. The controls contain default attributes to customize behavior, and are compatible with session recording.

Prepare for Guacamole setup

This section outlines the steps for setting up Guacamole. In sequence, you will need to:

  1. Decide which CentOS/RHEL version will be used as the Guacamole server.

    • The following versions are supported:

      • Centos 8 Stream / RHEL 8 64-bit

      • Centos 9 Stream / RHEL 9 64-bit

  2. View the Guacamole benchmarking metrics to determine the optimal system requirements for the Guacamole server.

  3. Configure proxy server settings for the Guacamole server. To do this, edit the /etc/profile file (as root user):

    vi /etc/profile

    For example, add the following lines to the bottom of the file:

    PROXY_URL="http://<proxyaddress>:<port>/"

export http_proxy="$PROXY_URL"
export https_proxy="$PROXY_URL"
export ftp_proxy="$PROXY_URL"
export no_proxy="127.0.0.1,localhost"
         
# For curl

export HTTP_PROXY="$PROXY_URL"
export HTTPS_PROXY="$PROXY_URL"
export FTP_PROXY="$PROXY_URL"
export NO_PROXY="127.0.0.1,localhost"

    Replace <proxyaddress> and <port> with the IP address and port number of the proxy server, respectively. Note that this is based on a proxy server using HTTP protocol; further modifications are required if the proxy server uses HTTPS.

    Save the file.

  4. Source the file to start using the proxy settings:

    source /etc/profile

  5. Ensure the Guacamole server is up to date.

    For Centos 8 / RHEL 8 or newer:

    dnf update

  6. Configure Guacamole remote desktop gateway

  7. Configure Guacamole access disclosure plugins

  8. (Optional) Secure Guacamole connections using SSL

Important

  • It is highly recommended that you follow the above steps in sequence, otherwise you may encounter configuration issues.

  • Before editing any file mentioned in this documentation, it is recommended to make a backup of that file first.

  • If you encounter issues at any point, check out the Troubleshoot configuration problems section.

Configure Guacamole remote desktop gateway

There are a couple methods of installing the Guacamole remote desktop gateway:

  • Using Docker : Docker is a daemon that runs applications with all of the required dependencies and libraries that are bundled into one package, or ”container”. Docker is open-source and can be installed on many platforms including Windows, Linux and Mac OS.

  • Using Podman : As of CentOS 8/RHEL 8, Docker support has been dropped in favor of a similar container engine called Podman. Podman is daemonless and can run multiple containers by combining them into “pods”.

Install Guacamole using Docker

The following steps are based on a CentOS 7 64-bit distribution. All steps performed on the Guacamole server should be performed as root user.

Obtain the idmunix-rhel-el8.x64.tar.gz or idmunix-rhel-el9.x64.tar.gz file from <instancedir>\addon\idmunix on the Bravura Privilege server and copy it into the Guacamole server under the /root directory.

  1. Navigate to the root directory:

    cd /root

  2. Unzip the idmunix-rhel-el8.x64.tar.gz file:

    tar -xf idmunix-rhel-el8.x64.tar.gz

  3. If the Guacamole server will use a proxy server, update the Dockerfile for the guacamole container.

    1. Navigate to the idmunix-rhel-el8.x64/docker/guacamole directory:

      cd /root/idmunix-rhel-el8.x64/docker/guacamole

    2. Modify the DockerFile by uncommenting one of the following lines according to your configuration:

      For HTTPS proxy only:

      ENV CATALINA_OPTS -Dhttps.proxyHost=<proxyhost> -Dhttps.proxyPort=<proxyport> -Dhttps.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      For HTTP proxy only:

      ENV CATALINA_OPTS -Dhttp.proxyHost=<proxyhost> -Dhttp.proxyPort=<proxyport> -Dhttp.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      For both HTTP and HTTPS proxy :

      ENV CATALINA_OPTS -Dhttps.proxyHost=<proxyhost> -Dhttps.proxyPort=<proxyport> -Dhttps.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\" -Dhttp.proxyHost=<proxyhost> -Dhttp.proxyPort=<proxyport> -Dhttp.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      Replace <proxyhost> and <proxyport> with the IP address and port number of the proxy server, respectively.

    3. Save the file.

  4. Navigate to the idmunix-rhel-el8.x64/docker directory:

    cd /root/idmunix-rhel-el8.x64/docker/

  5. Build the Docker image:

    docker compose build

  6. Create and start the Docker container:

    docker compose up -d

    If using Version 1 of the Docker Compose repository, the command is docker-compose.

  7. Open a browser window on a server or workstation that can access the Guacamole server using port 8080, and provide the following URL:

    http://<DNSName-of-guacamole-server>:8080/pam-guacamole

    A black screen with the following message will be displayed, however this is expected at the setup stage:

    Configuring guacamole using docker-compose-error.png

Stopping the container

To stop the Docker container run:

docker compose down

Starting the container

To start the Docker container; for example, after restarting the Guacamole server, run:

docker compose up -d

Running the Docker container as a service

Docker containers can be controlled using systemd . This is useful when you want to start Guacamole automatically upon reboot of the Guacamole server.

  1. Create a service called guacamole.service:

    sudo nano /etc/systemd/system/guacamole.service

  2. In Edit mode, insert the following into guacamole.service:

    [Unit]
Description=Guacamole service
Requires=docker.service
After=network.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/bin/docker-compose -f /root/idmunix-rhel-el8.x64/docker/docker-compose.yml
            up -d
         
ExecStop=/usr/local/bin/docker-compose -f /root/idmunix-rhel-el8.x64/docker/docker-compose.yml
            down
         
[Install]
WantedBy=multi-user.target

    Modify the path to the docker-compose.yml file should you move this to a different directory.

  3. Save the file.

  4. Reload systemd files:

    systemctl daemon-reload

  5. Enable guacamole.service to run at boot:

    systemctl enable guacamole.service

  6. Ensure no errors are returned. If so, view the status of the service by running:

    systemctl status guacamole.service

Start the Guacamole service by running:

systemctl start guacamole.service

Stop the Guacamole service by running:

systemctl stop guacamole.service

Logging

Tail the logs for the running containers with the following commands:

docker logs -f guacd
docker logs -f guacamole
Install Guacamole using Podman

The following steps are based on a CentOS 8 and Centos 9 Stream 64-bit distribution. All steps performed on the Guacamole server should be performed as root user.

  1. Install the EPEL repo.

    dnf -y install epel-release

  2. Install podman-compose.

    dnf -y install podman-compose

  3. Obtain the idmunix-rhel-el8.tar.gz or idmunix-rhel-el9.x64.tar.gz file from <instancedir>\addon\idmunix on the Bravura Privilege server and copy it into the Guacamole server under the /root directory.

  4. Navigate to the root directory:

    cd /root

  5. Unzip the idmunix-rhel-el8.x64.tar.gz file:

    tar -xf idmunix-rhel-el8.x64.tar.gz

  6. If the Guacamole server will use a proxy server, update the Dockerfile for the guacamole container.

    1. Navigate to the idmunix-rhel-el8.x64/docker/guacamole directory:

      cd /root/idmunix-rhel-el8.x64/docker/guacamole

    2. Modify the DockerFile by uncommenting one of the following lines according to your configuration:

      For HTTPS proxy only:

      ENV CATALINA_OPTS -Dhttps.proxyHost=<proxyhost> -Dhttps.proxyPort=<proxyport> -Dhttps.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      For HTTP proxy only:

      ENV CATALINA_OPTS -Dhttp.proxyHost=<proxyhost> -Dhttp.proxyPort=<proxyport> -Dhttp.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      For both HTTP and HTTPS proxy :

      ENV CATALINA_OPTS -Dhttps.proxyHost=<proxyhost> -Dhttps.proxyPort=<proxyport> -Dhttps.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"
                  -Dhttp.proxyHost=<proxyhost> -Dhttp.proxyPort=<proxyport> -Dhttp.nonProxyHosts=\"localhost|127.0.0.1|192.168.0.1\"

      Replace <proxyhost> and <proxyport> with the IP address and port number of the proxy server, respectively.

    3. Save the file.

  7. Navigate to the idmunix-rhel-el8.x64/docker directory:

    cd /root/idmunix-rhel-el8.x64/docker/

  8. Build the Docker image using podman-compose:

    podman-compose build

  9. Create and start the Docker container:

    podman-compose up -d

    When prompted to select an image, choose docker.io/guacamole/guacd:1.5.3

  10. Open a browser window on a server or workstation that can access the Guacamole server using port 8080, and provide the following URL:

    http://<DNSName-of-guacamole-server>:8080/pam-guacamole

    A black screen with the following message will be displayed, however this is expected at the setup stage:

    Configuring guacamole using docker-compose-error.png

Stopping the container

To stop the Docker container run:

podman-compose down

Starting the container

  1. Navigate to the idmunix-rhel-el8.x64/docker directory:

    cd /root/idmunix-rhel-el8.x64/docker/

  2. Start the Docker container using podman-compose:

    podman-compose up -d

Running the Docker container as a service

Docker containers can be controlled using systemd . This is useful when you want to start Guacamole automatically upon reboot of the Guacamole server.

  1. Create a service called guacamole.service:

    sudo nano /etc/systemd/system/guacamole.service

  2. In Edit mode, insert the following into guacamole.service:

    [Unit]
Description=Guacamole service
Requires=podman.socket
After=network.target
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=podman-compose -f /root/idmunix-rhel-el8.x64/docker/docker-compose.yml up
            -d
         
ExecStop=podman-compose -f /root/idmunix-rhel-el8.x64/docker/docker-compose.yml down
[Install]
WantedBy=multi-user.target

    Modify the path to the docker-compose.yml file should you move this to a different directory.

  3. Save the file.

  4. Reload systemd files:

    systemctl daemon-reload

  5. Enable guacamole.service to run at boot:

    systemctl enable guacamole.service

  6. Ensure no errors are returned. If so, view the status of the service by running:

    systemctl status guacamole.service

Start the Guacamole service by running:

systemctl start guacamole.service

Stop the Guacamole service by running:

systemctl stop guacamole.service

Logging

Tail the logs for the running containers with the following commands:

podman logs -f guacd
podman logs -f guacamole

Configure Guacamole access disclosure plugins

At a minimum, to use Guacamole access disclosure plugins, the URL of the Guacamole service must be set. To do this:

  1. Log in to the Bravura Privilege instance as superuser.

  2. Click Manage the system > Privileged access > Access disclosure plugins.

  3. Select a Guacamole access disclosure plugin. See Types of access disclosure plugins for a list of available plugins.

  4. Set guacamole-url. It must be set using the following format: <address>:<port>/<webappname>

    • address: The IP address or server name of the Guacamole remote desktop gateway. This must begin with http:// or https://, depending on your configuration.

    • port: The port number the Guacamole service is listening on. This should either be set to 8080 or 8443, depending on your configuration.

    • webappname: The web application name. This should be set to pam-guacamole .

    • For example:

      • http://linux1.bravura1.corp:8080/pam-guacamole

      • https://linux1.bravura1.corp:8443/pam-guacamole

  5. Click Update.

  6. Update the guacamole-url for each In-Browser disclosure plugin you wish to use.

  7. Click Next.

  8. Click Finish.

Secure Guacamole connections using SSL

In order to secure Guacamole connections using SSL, please ensure the following have been created before proceeding:

  • An SSL certificate for the Bravura Fabric server (we will use bravuracert.cer as an example)

  • An SSL certificate for the Guacamole server (we will use guacamole.cer as an example)

  • A keystore for guacamole.cer on the Guacamole server (we will use keystore.jks as an example)

It is assumed the reader knows how to generate these items, otherwise contact support@bravurasecurity.com for assistance.

Note

keytool is a certificate management utility will be used to import the Bravura Fabric server SSL certificate into a truststore. If your version of CentOS/RHEL does not have this installed, you need to install java. For example as root user, run yum install java or dnf install java depending on your CentOS/RHEL version.

  1. On the Guacamole server, navigate to the /root directory:

    cd /root

  2. Create a new directory called certificates :

    mkdir certificates

  3. Place keystore.jks into the certificates directory.

  4. Copy bravuracert.cer from the Bravura Security Fabric server to the Guacamole server and place it in the certificates directory.

  5. Navigate to the certificates directory.

    cd /root/certificates

  6. Run keytool to import the bravuracert.cer certificate to a truststore:

    keytool -import -v -trustcacerts -alias <alias> -file bravuracert.cer -keystore truststore.jks

    Replace <alias> with a unique ID (ie. bravurainst)

    It will ask for a truststore password, and prompt you to trust the certificate:

    [root@bravura-guacamole certificates]# keytool -import -v -trustcacerts -alias bravurainst
            -file bravuracert.cer -keystore truststore.jks 
         
Enter keystore password: 
Re-enter new password: 
Owner: CN=fabric-svr1.bravura1.corp 
Issuer: CN=fabric-svr1.bravura1.corp 
Serial number: 16c6fd2eaee998ac4d24e204b4e035ee 
Valid from: Fri Feb 10 16:32:44 MST 2023 until: Sat Feb 10 16:52:44 MST 2024 
Certificate fingerprints: 
         SHA1: E8:F4:C7:BC:CE:05:BD:B1:A3:B6:9D:33:28:B8:D6:41:5B:AC:F0:D4 
         SHA256: 6F:C7:29:03:7B:24:2E:98:E1:B4:4A:E8:9C:C7:A7:86:16:87:D6:71:98:23:22:32:30:2F:83:6C:E5:BC:92:AD
            
         
Signature algorithm name: SHA256withRSA 
Subject Public Key Algorithm: 2048-bit RSA key 
Version: 3 
 
Extensions: 
 
#1: ObjectId: 2.5.29.37 Criticality=false 
ExtendedKeyUsages [ 
  clientAuth 
  serverAuth 
] 
 
#2: ObjectId: 2.5.29.15 Criticality=true 
KeyUsage [ 
  DigitalSignature 
  Key_Encipherment 
] 
#3: ObjectId: 2.5.29.17 Criticality=false 
SubjectAlternativeName [ 
  DNSName: fabric-svr1.bravura1.corp 
] 
#4: ObjectId: 2.5.29.14 Criticality=false 
SubjectKeyIdentifier [ 
KeyIdentifier [ 
0000: E0 94 85 4D C7 03 D4 E5   95 EC 11 8F 7B D5 4A CB  ...M..........J. 
0010: 0E A4 77 99                                        ..w. 
] 
] 
Trust this certificate? [no]:  y 
Certificate was added to keystore 
[Storing truststore.jks]

Next steps

Self-signed certificates

If you are using self-signed SSL certificates for the Guacamole server, you will need to deploy these certificates on any system that will be used to launch Guacamole sessions. If not installed, web browsers will return a ERR_CERT_AUTHORITY_INVALID error message because it cannot validate the site’s SSL certificate.

Perform the following steps as a user with administrative permissions, for each system that will be used to launch Guacamole sessions. This is based on a Windows environment.

  1. For each system that will be used to launch Guacamole sessions, create a new directory to store the Guacamole certificate. (ie. C:\guacamole_certificates)

  2. Copy over the guacamole.cer file from the Guacamole server to the directory specified in the previous step.

  3. Close any open web browser windows.

  4. From the directory where the guacamole.cer certificate is located, double click on the file.

  5. Click Install Certificate…

  6. Choose the Store Location (default Current User)

    It is recommended that the store location be set to Local Machine, otherwise each individual user on the system will need to install the certificate.

  7. Click Next

  8. Select Place all certificates in the following store

  9. Click Browse…

  10. Select Trusted Root Certification Authorities.

  11. Click OK.

  12. Click Next.

  13. Click Finish.

  14. Click Yes to accept the security warning.

  15. Click OK to close the import wizard.

  16. Open a web browser, and specify the DNS name of the Guacamole server in the address bar:

    https://<DNSName-of-guacamole-server>

    You should no longer see the ERR_CERT_AUTHORITY_INVALID error message.

Configure Guacamole with SSL using Docker

The following steps are based on a Guacamole installation using Docker . All steps performed on the Guacamole server will be done as root user.

  1. Navigate to the idmunix-rhel-el8.x64/docker or idmunix-rhel-el9.x64/docker directory.

    cd /root/idmunix-rhel-el8.x64/docker/

  2. Start the Docker container if not already done so:

    docker compose up -d

  3. From the same directory, modify docker-compose.yml , by adding port 8443 to the list of ports. The file should look like this:

    version: "3" 
services: 
  guacd: 
    build: 
      context: ./guacd 
    image: guacd 
    container_name: guacd 
    deploy: 
      replicas: 1 
      restart_policy: 
        condition: on-failure 
    networks: 
      - guac 
  guacamole: 
    build: 
      context: ./guacamole 
    image: guacamole 
    container_name: guacamole 
    deploy: 
      replicas: 1 
      restart_policy: 
        condition: on-failure 
    ports: 
      - "8080:8080" 
      - "8443:8443" 
    networks: 
      - guac 
networks: 
  guac:

     

    Save the file.

  4. From the docker directory, navigate to the guacamole directory.

    cd /root/idmunix-rhel-el8.x64/docker/guacamole

  5. Modify Dockerfile , by exposing port 8443. The file should look like this:

    # Use args for Tomcat image label to allow image builder to choose alternatives 
# such as `--build-arg TOMCAT_JRE=jre8-alpine` 
# 
ARG TOMCAT_VERSION=9 
ARG TOMCAT_JRE=jre8 
 
FROM tomcat:${TOMCAT_VERSION}-${TOMCAT_JRE} 
 
COPY . / 
 
EXPOSE 8080 
EXPOSE 8443 
 
ENV GUACAMOLE_HOME /etc/guacamole/ 
CMD ["catalina.sh", "run"]

    Save the file.

  6. Navigate to the idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat directory:

    cd /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat

  7. Create 2 directories called conf and ssl :

    mkdir conf
mkdir ssl

  8. Copy over keystore.jks and truststore.jks to the ssl directory.

    cp /root/certificates/truststore.jks /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/ssl/
cp /root/certificates/keystore.jks /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/ssl/

  9. From the tomcat directory, navigate to the bin directory.

    cd /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/bin

  10. Modify setenv.sh , by adding a line to include a line to the path of the truststore file and password:

    export JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=/usr/local/tomcat/ssl/truststore.jks
            -Djavax.net.ssl.trustStorePassword=<password>"

    trustStore is the full path to the truststore.jks file

    trustStorePassword is the password you provided for the truststore.jks file. (replace <password>)

    Save the file.

  11. Enter the guacamole container context:

    docker exec -it guacamole /bin/bash

    To confirm that you are in the guacamole container context, you will see:

    root@<containerid>:/usr/local/tomcat#

    Where <containerid> is the Guacamole container ID.

  12. You will need to install a text editor to be able to edit the file from within the container; for example nano :

    apt-get update 
apt-get install nano

  13. Open server.xml in the conf directory using nano :

    nano conf/server.xml

  14. Modify server.xml, by adding the connector definition for enabling SSL protocol; for example:

    <Connector 
   protocol="org.apache.coyote.http11.Http11NioProtocol" 
   port="8443" maxThreads="200" 
   scheme="https" secure="true" SSLEnabled="true" 
   keystoreFile="ssl/keystore.jks" keystorePass="<password>" 
   clientAuth="false" sslProtocol="TLS"/>

    keystoreFile is the location of the keystore.jks file within the guacamole container context.

    keystorePass is the password you provided for the keystore.jks file (replace <password> )

    The file should look something like this:

    ...
    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" /> 
    <!-- A "Connector" using the shared thread pool--> 
    <!-- 
    <Connector executor="tomcatThreadPool" 
               port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" /> 
    -->
    <!-- Define an SSL/TLS HTTP/1.1 Connector on port 8443 
         This connector uses the NIO implementation. The default 
         SSLImplementation will depend on the presence of the APR/native 
         library and the useOpenSSL attribute of the AprLifecycleListener. 
         Either JSSE or OpenSSL style configuration may be used regardless of 
         the SSLImplementation selected. JSSE style configuration is used below. 
    --> 
    <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 
                port="8443" maxThreads="200" 
                scheme="https" secure="true" SSLEnabled="true" 
                keystoreFile="ssl/keystore.jks" keystorePass="password123" 
                clientAuth="false" sslProtocol="TLS"/> 
    <!-- 
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" 
               maxThreads="150" SSLEnabled="true"> 
        <SSLHostConfig> 
            <Certificate certificateKeystoreFile="conf/localhost-rsa.jks" 
                         type="RSA" /> 
        </SSLHostConfig> 
    </Connector> 
    --> 
...

    Save the file.

  15. Type exit to leave the guacamole container context.

  16. Navigate to the idmunix-rhel-el8.x64/docker directory.

    cd /root/idmunix-rhel-el8.x64/docker/

  17. Copy server.xml from the guacamole container. This will prevent the file from being overwritten every time the guacamole container is built:

    docker cp guacamole:/usr/local/tomcat/conf/server.xml guacamole/usr/local/tomcat/conf/

    For future updates to the server.xml file, edit the file from guacamole/usr/local/tomcat/conf/ instead of going into the container context. The latter will be overwritten should you rebuild the guacamole container.

  18. Stop the Docker container.

    docker-compose down

  19. Rebuild the Docker containers and image.

    docker-compose up --force-recreate --build -d

  20. Open a browser window on a system where the Guacamole server SSL certificate is installed, and access the Guacamole server using https and port 8443; for example:

    https://<DNSName-of-guacamole-server>:8443/pam-guacamole

  21. Confirm that the Guacamole server is secured, as indicated by the lock on the address bar.

    A black screen with the following message will be displayed, however this is expected at the setup stage:

    Configuring guacamole using docker-compose-error.png

  22. Update the guacamole-url for Guacamole access disclosure plugins to use port 8443.

Configure Guacamole with SSL using Podman

The following steps are based on a Guacamole installation using Podman . All steps performed on the Guacamole server will be done as root user.

  1. Navigate to theidmunix-rhel-el8.x64/docker or idmunix-rhel-el9.x64/docker directory.

    cd /root/idmunix-rhel-el8.x64/docker/

  2. Start the Docker container if not already done so:

    podman-compose up -d

  3. From the same directory, modify docker-compose.yml, by adding port 8443 to the list of ports. The file should look like this:

    version: "3" 
services: 
  guacd: 
    build: 
      context: ./guacd 
    image: guacd 
    container_name: guacd 
    deploy: 
      replicas: 1 
      restart_policy: 
        condition: on-failure 
    networks: 
      - guac 
  guacamole: 
    build: 
      context: ./guacamole 
    image: guacamole 
    container_name: guacamole 
    deploy: 
      replicas: 1 
      restart_policy: 
        condition: on-failure 
    ports: 
      - "8080:8080" 
      - "8443:8443" 
    networks: 
      - guac 
networks: 
  guac:

    Save the file.

  4. From the docker directory, navigate to the guacamole directory.

    cd /root/idmunix-rhel-el8.x64/docker/guacamole

  5. Modify Dockerfile, by exposing port 8443. The file should look like this:

    # Use args for Tomcat image label to allow image builder to choose alternatives 
# such as `--build-arg TOMCAT_JRE=jre8-alpine` 
# 
ARG TOMCAT_VERSION=9 
ARG TOMCAT_JRE=jre8 
 
FROM tomcat:${TOMCAT_VERSION}-${TOMCAT_JRE} 
 
COPY . / 
 
EXPOSE 8080 
EXPOSE 8443 
 
ENV GUACAMOLE_HOME /etc/guacamole/ 
CMD ["catalina.sh", "run"]

    Save the file.

  6. Navigate to the idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat directory:

    cd /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat

  7. Create two directories called conf and ssl :

    mkdir conf
mkdir ssl

  8. Copy over keystore.jks and truststore.jks to the ssl directory.

    cp /root/certificates/truststore.jks /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/ssl/
cp /root/certificates/keystore.jks /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/ssl/

  9. From the tomcat directory, navigate to the bin directory.

    cd /root/idmunix-rhel-el8.x64/docker/guacamole/usr/local/tomcat/bin

  10. Modify setenv.sh by adding a line to include a line to the path of the truststore file and password:

    export JAVA_OPTS="$JAVA_OPTS -Djavax.net.ssl.trustStore=/usr/local/tomcat/ssl/truststore.jks -Djavax.net.ssl.trustStorePassword=<password>"

    trustStore is the full path to the truststore.jks file

    trustStorePassword is the password you provided for the truststore.jks file. (replace <password> )

    Save the file.

  11. Enter the guacamole container context:

    podman exec -it guacamole /bin/bash

    To confirm that you are in the guacamole container context, you will see:

    root@guac:/usr/local/tomcat#

  12. You will need to install a text editor to be able to edit the file from within the container; for example nano :

    apt-get update
apt-get install nano

  13. Open server.xml in the conf directory using nano :

    nano conf/server.xml

  14. Modify server.xml by adding the connector definition for enabling SSL protocol; for example:

    <Connector 
   protocol="org.apache.coyote.http11.Http11NioProtocol" 
   port="8443" maxThreads="200" 
   scheme="https" secure="true" SSLEnabled="true" 
   keystoreFile="ssl/keystore.jks" keystorePass="<password>" 
   clientAuth="false" sslProtocol="TLS"/>

    keystoreFile is the location of the keystore.jks file within the guacamole container context.

    keystorePass is the password you provided for the keystore.jks file (replace <password> )

    The file should look something like this:

    ...
    <Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" /> 
    <!-- A "Connector" using the shared thread pool--> 
    <!-- 
    <Connector executor="tomcatThreadPool" 
               port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" /> 
    -->
    <!-- Define an SSL/TLS HTTP/1.1 Connector on port 8443 
         This connector uses the NIO implementation. The default 
         SSLImplementation will depend on the presence of the APR/native 
         library and the useOpenSSL attribute of the AprLifecycleListener. 
         Either JSSE or OpenSSL style configuration may be used regardless of 
         the SSLImplementation selected. JSSE style configuration is used below. 
    --> 
    <Connector protocol="org.apache.coyote.http11.Http11NioProtocol" 
                port="8443" maxThreads="200" 
                scheme="https" secure="true" SSLEnabled="true" 
                keystoreFile="ssl/keystore.jks" keystorePass="password123" 
                clientAuth="false" sslProtocol="TLS"/> 
    <!-- 
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" 
               maxThreads="150" SSLEnabled="true"> 
        <SSLHostConfig> 
            <Certificate certificateKeystoreFile="conf/localhost-rsa.jks" 
                         type="RSA" /> 
        </SSLHostConfig> 
    </Connector> 
    --> 
...

    Save the file.

  15. Type exit to leave the guacamole container context.

  16. Copy server.xml from the guacamole container. This will prevent the file from being overwritten every time the guacamole container is built:

    podman cp guacamole:/usr/local/tomcat/conf/server.xml guacamole/usr/local/tomcat/conf/

    For future updates to the server.xml file, edit the file located at guacamole/usr/local/tomcat/conf/ instead of accessing the container context. The latter will be overwritten should you rebuild the guacamole container.

  17. Stop the Docker container.

    podman-compose down

  18. Rebuild the Docker containers and image.

    podman-compose up --force-recreate --build -d

  19. Open a browser window on a system where the Guacamole server SSL certificate is installed, and access the Guacamole server using https and port 8443, for example:

    https://<DNSName-of-guacamole-server>:8443/pam-guacamole

  20. Confirm that the Guacamole server is secured, as indicated by the lock on the address bar.

    A black screen with the following message will be displayed, however this is expected at the setup stage:

    Configuring guacamole using docker-compose-error.png

  21. Update the guacamole-url for Guacamole access disclosure plugins to use port 8443.

Troubleshoot configuration problems

General installation issues

  • If you cannot download packages, try restarting the network or restarting the system.

  • If you are unable to install any of the RPMs and/or their dependencies, run the following command and try to install the RPMs again.

    yum clean all

  • If the Guacamole gateway is behind a firewall and cannot install packages using yum due to connection issues, add the proxy to the yum config file. To do this, edit the yum.conf file:

    vi /etc/yum.conf

    Add a new line at the bottom of the file with the proxy address:

    proxy=<proxy address>
General configuration issues

  • If you are launching a Guacamole disclosure plugin but it gives a connection error:

    • Ensure that the guacd proxy and web application service are running.

      • Test the connection from within the Guacamole server:

        Using curl:

        curl -L --noproxy '*' localhost:<port>/pam-guacamole | less

        Using wget:

        wget --no-proxy localhost:<port>/pam-guacamole

    • Ensure the firewall on the Guacamole server is not blocking port 8080 (or 8443 for SSL connections)

    • Ensure that the Guacamole gateway can ping the Bravura Privilege server and managed systems prior to connecting via access disclosure plugin, using the IP address, then the hostname. If the systems can be reached by IP address but not the hostname, add the hostname and corresponding IP address to the /etc/hosts file. If using Docker or Podman, you may need to add a hostname mapping to the docker-compose file.

    • Ensure that the Guacamole gateway can reach the Bravura Privilege server using port 80 (or 443 for SSL connections)

    • For In-Browser RDP, ensure that the managed account that is used to launch the Guacamole session has remote access to the managed system. This can be verified by manually opening up a Remote Desktop Connection session, or by using Remote Desktop disclosure (pswxtsvc) and logging in as the managed account.

    • Ensure that the security protocol is correct for the managed system you are trying to connect to. As of Guacamole 1.3, ‘any’ should automatically choose the correct protocol.

  • If you’re trying to connect to a Windows system older than Windows 10, ensure that the proper lines are uncommented in the guacd 's Dockerfile. Refer back to installation steps for Docker or Podman

  • If text is not displayed properly using Telnet or SSH, install a monospace font package for Telnet and SSH such as gnu-free-mono-fonts.

  • If clipboard capture is not working for session monitoring, a required dependency may be missing. Ensure that freerdp-plugins is installed.

  • You may find logging to be helpful in diagnosing Guacamole connection problems.

    • Log files on a Docker-installed environment can be viewed by running:

      docker logs guacd
docker logs guacamole

    • Log files on a Podman-installed environment can be viewed by running:

      podman logs guacd
podman logs guacamole

    • Log files on a CentOS/RHEL environment where Guacamole RPM packages are installed manually are located in:

      /var/log/tomcat
/var/log/messages
Podman configuration issues

  • You may encounter the following error, despite connecting with the correct security type:

Configuring guacamole using docker-compose-error.png

This could be the result of connecting to a managed system that does not require a proxy. If a proxy is not required to access the managed system, modify the no_proxy list in /etc/profile to include the managed system. You will need to source the file again or log off and log back in to the Guacamole server for the proxy changes to take effect. Alternatively, add --http-proxy=false to the podman run commands. For example:

podman run -d --pod guac --name guacd --http-proxy=false guacd
podman run -d --pod guac --name guacamole --http-proxy=false guacamole
SSL configuration issues

  • Ensure that the /bin/ setenv.sh file contains the correct truststore, path and password.

  • Ensure that the /conf/ server.xml file contains the correct keystore, path and password.

  • Ensure that the passwords for the keystore.jks and truststore.jks files are correct.

    keytool -list -v -keystore <pathOfStoreFile>/<storeFileName>.jks

  • If you update /conf/ server.xml from within the guacamole container context, ensure that you copied it outside of the container or you will lose your changes if you rebuild the container.

  • You must access the instance using the DNS name you provided in the SSL certificates. Accessing it using localhost, or an IP address will result in warnings.

  • Ensure that the guacamole-url for the Guacamole access disclosure plugin contains the exact DNS name you provided for the Guacamole server SSL certificate.

  • If you continue to receive security warnings when accessing the Guacamole server, ensure that you have installed the SSL certificate in the correct location (Trusted Root Certification Authorities).

  • If you are using self-signed certificates, ensure that it is deployed on the system that will launch Guacamole sessions .

  • For self-signed certificates, you may need to update the Guacamole access disclosure plugins to ignore the SSL certificate. (set the ignore-cert disclosure attribute to True)

Benchmarking metrics for Guacamole

Several factors can affect the reliability of Guacamole. One of the major factors is memory usage on the Guacamole server. However, it can be challenging to determine the amount of memory Guacamole consumes. A single Guacamole session can initiate multiple guacd threads; each thread using varying amounts of memory. Plus, the amount of memory initially consumed by a Guacamole session will gradually increase as the session persists. Additionally, the tasks performed on the remote desktop screen can also impact memory consumption, as well as the display settings for the remote desktop screen. Furthermore, RDP sessions consume more memory than SSH sessions.

The following shows how to determine:

  • To determine the maximum number of concurrent Guacamole sessions based on the amount of memory (RAM) allocated on the Guacamole gateway in the worst case.

  • To determine the amount of memory (RAM) to be allocated on the Guacamole gateway for a given number of concurrent Guacamole sessions in the worst case.

Test methodology

To make things simple and consistent, 40 concurrent In-Browser RDP sessions will be launched. Each session will RDP to the same managed system using the same managed account, with the default display resolution of 1024x768 at 96 DPI (dots per inch), and will open a command line window upon login that covers most of the Remote Desktop screen, which will ping 3 reachable IP addresses every 2 seconds. This will simulate constant movement on the screen, which ideally would result in a more realistic worst-case scenario. It is assumed that in a normal case, users will periodically use Guacamole sessions throughout the checkout duration, rather than regularly.

The terms “memory” and “RAM” will be used interchangeably.

To get an idea of how much memory is consumed per Guacamole session, you need to determine the following metrics at each stage:

  1. The total RAM used on the Guacamole server before starting Guacamole

  2. The total RAM used on the Guacamole server after starting Guacamole

  3. The total RAM used on the Guacamole server after initiating a single Guacamole session and leave it running for at least 15-20 minutes – the longer the duration, the better

  4. The total RAM used on the Guacamole server after ending the active Guacamole session (this number will be different than stage 2)

The memory allocated when launching the initial Guacamole session is typically larger than subsequent Guacamole sessions. This is because some guacd processes will remain active even if all Guacamole sessions have terminated. Thus, the total RAM used at Stage 4 will differ from Stage 2. However, the memory consumed upon launching subsequent Guacamole sessions will be relatively consistent.

A useful tool to measure this information is htop , which can be installed on the Guacamole server using dnf install htop (or yum install htop). You can find more info at https://htop.dev

A minimum 4 core processor is recommended for the Guacamole server. On htop , you can determine the CPU usage based on the “Load average” metric. There are 3 values: the first value is the per minute average; the second value is the 5 minute average; and the third value is the 15 minute average. A value of 4.0 for a 4-core CPU would mean 100% utilization. If the Load Average consistently exceeds this number, it is an indication that additional cores need to be allocated to the Guacamole server based on the load.

Test exclusions

Session monitoring is not included in this test. Based on Guacamole benchmarking tests conducted previously, there does not appear to be any noticeable increase in memory usage when Session Monitor is enabled (screenshots, keystrokes and clipboard capture)

Other Guacamole disclosure plugins such as In-Browser SSH, In-Browser VNC, In-Browser RemoteApp and In-Browser Telnet will not be included in this test. In-Browser VNC and In-Browser Remote App should have similar memory requirements as In-Browser RDP; and In-Browser SSH and In-Browser Telnet should both be comparable but use considerably less memory than In-Browser RDP.

Test environment

  • Guacamole server

    • OS: CentOS 8 Stream 64-bit (virtual machine)

    • Internal memory: 6 GB RAM (recognized on system as 5.41 GB)

    • Processor: Intel Core i7-4790 @3.60GHz (4 processors)

    • Hard Drive: 12 GB

    • Guacamole version: 1.3

      • Installed using podman

      • SSL enabled

  • Bravura Privilege instance server

    • OS: Windows 2022 64-bit (virtual machine)

    • Internal Memory: 5GB RAM

    • Processor: Intel Core i7-4790 @3.60GHz (2 processors)

    • Hard Drive: 50 GB

    • Privilege version: 12.3.5 (build 32487)

  • Managed system

    • OS: Windows 2022 64-bit (virtual machine)

    • Internal Memory: 6 GB RAM

    • Processor: Intel Core i7-4790 @3.60GHz (4 processors)

    • Hard Drive: 50 GB

    • Remote Desktop Services (Terminal Services) installed

      • Remote Desktop session host configured to allow an unlimited number of concurrent connections

      • At least one user is part of the Remote Desktop Users group

Test results

The following test was performed:

  • 40 concurrent Guacamole In-Browser RDP sessions were launched

  • Each RDP session runs the same scheduled task upon login to the managed system

    • A scheduled task opens a command line window, set to the following:

      • Font : Size: 28 ; Font: MS Gothic

      • Layout : Screen Buffer Size: 65x9001 ; Window Size: 65x24 ; Window Position: 10x10

      • Colors (Screen Background): Selected Color Values: Red: 242 ; Green: 242 ; Blue: 242; Opacity: 86%

      • The scheduled task executes a batch script that pings 3 different IP addresses; 1 IP address is pinged every 2 seconds

  • The Guacamole sessions were left running for an 12 hour period, to ensure that no Guacamole sessions unexpectedly terminated based on the environment specifications given

  • The total memory usage for 40 Guacamole sessions was obtained after the 12 hour period had elapsed

  • The memory usage per Guacamole session is based on the difference of the total memory usage before a Guacamole session is closed and after the Guacamole session is closed

Table 1. Observed memory usage

Stage

Description

Total Memory Usage (GB)

Total Memory Usage (MB)

1

The total RAM used on the Guacamole server before starting Guacamole

0.557

557

2

The total RAM used on the Guacamole server after starting Guacamole

0.677

677

The difference in total RAM used between Stage 1 and Stage 2

0.12

120

3

The total RAM used on the Guacamole server after initiating a single Guacamole session and leave it running for 15-20 minutes

0.926

926

4

The total RAM used on the Guacamole server after ending the initial Guacamole session

0.81

810

The difference between the total RAM used after initiating and terminating the initial Guacamole session (Stage 4) and starting the Guacamole service (Stage 2)

0.249

249



The total memory usage was gathered after all 40 sessions were initiated and left running for more than 12 hours. One-by-one, each Guacamole session was terminated, and the updated total memory usage per x number of sessions was obtained. This is a more accurate measure of memory usage per Guacamole session instead of obtaining it immediately after the Guacamole session is launched because the memory usage can still fluctuate as time goes on.

Average memory usage per Guacamole session (GB)

Minimum memory usage per Guacamole session (GB)

Maximum memory usage per Guacamole session (GB)

0.0975

0.074

0.116

Average memory usage per Guacamole session (MB)

Minimum memory usage per Guacamole session (MB)

Maximum memory usage per Guacamole session (MB)

97.5

74

116

The maximum memory usage for a Guacamole session will be used to calculate the worst case, in this case, 116 MB.

Formula

To get the minimum amount of RAM in GB for y number of sessions:

z = (557 + 249 + xy) * 0.01

Where :

x = Amount of memory per Guacamole session (MB)

y = Total amount of sessions

z = Total memory (GB)

  • 557: The total RAM (MB) used in megabytes before starting Guacamole on the Guacamole server

  • 249: The additional RAM (MB) needed to start the Guacamole service and the memory that remains after terminating the initial Guacamole session (difference between Stage 4 and Stage 2)

  • xy: The amount of RAM allocated per Guacamole session, multiplied by the number of active sessions

  • 1GB = 1000 MB

Examples

For 10 Guacamole sessions:

z = (557 + 249 + 116x) * 0.01 
z = (806 + 116(10)) * 0.01 
z = (806 + 1160)) * 0.01 
z = 1966  * 0.01 
z = 1.97 GB

For 50 Guacamole sessions:

z = (557 + 249 + 116x) * 0.01
z = (806 + 116(50)) * 0.01
z = (806 + 5800)) * 0.01
z = 6606 * 0.01
z = 6.61 GB

For 100 Guacamole sessions:

z = (557 + 249 + 116x) * 0.01
z = (806 + 116(100)) * 0.01
z = (806 + 11600)) * 0.01
z = 12406 * 0.01
z = 12.41 GB

For 200 Guacamole sessions:

z = (557 + 249 + 116x) * 0.01
z = (806 + 116(200)) * 0.01
z = (806 + 23200)) * 0.01
z = 24006 * 0.01
z = 24.01 GB

To get the maximum number of Guacamole sessions for y GB of RAM allocated to the Guacamole server:

x = floor((y – 557 – 249) / z)

Where :

x = Total amount of sessions

y = Free memory (GB)

z = Amount of memory per Guacamole session (MB)

  • 1GB = 1000 MB

Examples

For 5GB of memory:

x = floor((y - 557 - 249) / 116))
x = floor((y - 308) / 116)
x = floor((5000 - 308) / 116)
x = floor(4692 / 116)
x = 40.44 sessions or 40 sessions.

For 12 GB of memory:

x = floor((y - 557 - 249) / 116)
x = floor((y - 308) / 116)
x = floor((12000 - 308) / 116)
x = floor(11898 / 116)
x = 102.57 sessions or 102 sessions.

For 20 GB of memory:

x = floor((y - 557 - 249) / 116)
x = floor((y - 308) / 116)
x = floor((20000 - 308) / 116)
x = floor(19692 / 116)
x = 169.76 sessions or 169 sessions.
Other factors to consider

  • Network latency : Depending on the network connection, it’s possible that sessions may terminate if the network is extremely slow (ie. latency is greater than 3000ms)

  • CPU : It is best to continuously monitor the CPU usage on the Guacamole server. If you periodically notice some sessions terminating unexpectedly, especially when there is a lot of active Guacamole sessions, ensure that the Load average has not been exceeded based on the number of CPU cores allocated for the Guacamole server.

  • Screen resolution size : Setting a larger display resolution size for the Guacamole window will increase the memory usage, especially when work is being performed on the majority of the remote desktop screen.

  • By default, Microsoft Edge Chromium, Google Chrome and Mozilla Firefox automatically puts idle browser tabs to sleep to reduce memory usage. If a Guacamole session terminates unexpectedly, it may be because the browser itself has not replied back to the Guacamole server in a sufficient amount of time.

In this section: