Troubleshooting

Common troubleshooting and log inspection

---

RBI issues with version 2.20.0 or newer

If RBI sessions are showing as black screens or throwing errors, you may need to upgrade the AppArmor and Seccomp file configuration.

Version 2.20.0 and newer updates have mandatory changes to support Remote Browser Isolation (RBI). The instructions are posted on the 2.20.0 release notes page.

---

Check the Logs

If things are not behaving as expected, a good first step is always to check the logs. There may be messages logged by Guacamole or guacd which describe exactly what is failing, or which will at least point you in the right direction toward resolving a problem.

Auto Docker Install method

If you installed Keeper Connection Manager using the Auto Docker Install method, you can use the kcm-setup.run script to check log files.

To see all recent logs across all containers:

sudo ./kcm-setup.run logs

To tail the logs in real time, use the -f flag

sudo ./kcm-setup.run logs -f

Container-specific logs can be monitored to troubleshoot specific issues, as outlined below.

guacd Logs

• Command: sudo ./kcm-setup.run logs guacd

• Use When:

  • Troubleshooting connection issues

  • Debugging protocol-specific errors (RDP, VNC, SSH)

  • Analyzing session details and performance metrics

  • Investigating connection attempts and results

  • Viewing errors and stack traces related to guacd

guacamole Logs

• Command: sudo ./kcm-setup.run logs guacamole

• Use When:

  • Debugging user authentication issues

  • Monitoring user session activities

  • Troubleshooting web request handling and responses

  • Investigating configuration loading and parsing results

  • Viewing errors and stack traces related to the web application

  • Checking HTTP request and response logs

db Logs

• Command: sudo ./kcm-setup.run logs db

• Use When:

  • Troubleshooting database connection issues

  • Debugging query execution problems

  • Monitoring transaction management

  • Investigating database startup and shutdown logs

  • Viewing user authentication results for the database

  • Analyzing performance metrics

  • Checking backup and restore operations

  • Viewing errors and stack traces related to the database

ssl Logs

• Command: sudo ./kcm-setup.run logs ssl

• Use When:

  • Troubleshooting SSL/TLS connection issues

  • Debugging SSL certificate loading and verification

  • Investigating secure connection establishment and termination

  • Checking HTTP to HTTPS redirection logs

  • Viewing handshake and encryption details

  • Viewing errors and stack traces related to SSL/TLS

  • Analyzing configuration results

  • Checking client and server connection details

To look at individual log files, you can specify the type of log output:

sudo ./kcm-setup.run logs guacd
sudo ./kcm-setup.run logs guacamole
sudo ./kcm-setup.run logs db
sudo ./kcm-setup.run logs ssl

If you want to start digging around the Docker images, the below commands will get you started:

sudo docker-compose -p "kcm" -f /etc/kcm-setup/docker-compose.yml ps
sudo docker ps
sudo docker exec -it <container ID> /bin/bash
etc...

Custom Docker Install method

When you have installed using the Custom Docker Install method, you can use the built-in docker and docker-compose logging commands.

For example, when using docker-compose:

sudo docker-compose logs guacd
sudo docker-compose logs guacamole
sudo docker-compose logs db
sudo docker-compose logs ssl

Using the regular docker command, locate the container ID through either "docker ps":

sudo docker ps

CONTAINER ID   IMAGE ...
2aca97c20f5c   keeper/guacamole-ssl-nginx ...
73538e4af0b7   keeper/guacamole-db-mysql ...
44ab1b150bc9   keeper/guacd ...
85e79b62f058   keeper/guacamole ...

Then you can reference the specific container to get the logs:

sudo docker logs 44ab1b150bc9
sudo docker logs 85e79b62f058
sudo docker logs 73538e4af0b7
sudo docker logs 2aca97c20f5c

Connection Issues

If Keeper Connection Manager is hanging during startup, or unable to connect to any hosts, one thing to quickly check is if the Linux machine is capable of generating enough entropy for random number generation. To resolve this, we recommend installing the haveged package.

These packages can be installed using the commands below (CentOS / RHEL):

sudo yum install epel-release
sudo yum install haveged
sudo systemctl start haveged
sudo systemctl enable haveged

Auto Docker Install Debug

The kcm-setup.run script now supports a KCM_SETUP_DEBUG environment variable that causes the script to run in verbose mode, printing out all commands run and all output from those commands. This debug output can be sent directly to the terminal or to a file depending on the value of KCM_SETUP_DEBUG.

export KCM_SETUP_DEBUG=/path/to/file
sudo -E ./kcm-setup.run

Verbose Logging

LOG_LEVEL

This variable is optional and specifies the lowest level of log message that should be displayed. In order of increasing verbosity, valid values are: "error", "warn", "info", "debug", "trace".

The default log level is "info".

Administration

LDAP users are not listed when integrating LDAP with a database

Check that your (administrative) Keeper Connection Manager user account has permission to list LDAP users

Keeper's LDAP support will not bypass the permissions enforced by your LDAP directory. This means that your Keeper Connection Manager user will only be able to see LDAP users within Keeper Connection Manager's admin interface if your corresponding LDAP user has this permission to list these users, regardless of whether Keeper's "search" LDAP user has permission and regardless of whether your database user has general permission to manage users.

If unsure whether your user has permission, a good way to check is to execute an LDAP query against your directory, binding using the DN and password associated with your LDAP account. The "ldapsearch" utility is a standard tool which can perform such a search:

$ ldapsearch -x -LLL -H ldap://YOUR_LDAP_SERVER -D "YOUR_LDAP_DN" -W -b USER_BASE_DN "(objectClass=*)"

where YOUR_LDAP_SERVER is the hostname or IP address of your LDAP server, YOUR_LDAP_DN is the full DN of your account within LDAP, and USER_BASE_DN is the base DN of all relevant users within your LDAP directory (as specified with the LDAP_USER_BASE_DN property of the docker-compose.yml file, or inside the container as ldap-user-base-dn property in /etc/guacamole/guacamole.properties).

Check that you are using LDAP credentials to sign in to Keeper Connection Manager, not database credentials.

If your user account within the database has an associated password, and you specify that password instead of the password associated with your LDAP account, you will successfully authenticate against the database only. This is a valid authentication result, but means that your session will lack access to LDAP objects. To be able to access objects within LDAP, including users, you must authenticate with credentials that your LDAP directory will accept.

Check for trailing whitespace after LDAP-related properties

While the Java .properties files do not assign meaning to whitespace that occurs before a property value, everything after the first non-whitespace character of a property value is part of the property value, including further whitespace. If you are confident that all LDAP-related properties within the docker compose file (hence the /etc/guacamole/guacamole.properties file inside the container) look correct, check that you have not accidentally inserted whitespace at the end of what otherwise appears to be a correct value. The presence of whitespace at the end of LDAP-related properties may result in queries failing and may cause Guacamole to incorrectly interpret the results of queries that appear to succeed.

The password for "guacadmin" (or the current user) cannot be changed

Use the "Preferences" interface for changing your own password, not the administrative user editor

Keeper Connection Manager has two mechanisms available for changing a user's password: the user editor, for changing the passwords of other users (without having to know their current passwords), and the "Preferences" screen, for changing your own password after verifying that you know your current password. As only the "Preferences" screen verifies that you know your current password, this is the only mechanism which Keeper will allow if you are making changes to your own user. If you attempt to change your own password using the user editor, permission will be denied. For administrators, the "Preferences" screen can be accessed by going to "Settings" and then selecting "Preferences".

Check that the user in question has permission to change their own password

User accounts defined within the Keeper Connection Manager database do not necessarily have permission to change their own passwords. Permission to update your own password must be explicitly granted by the administrator. If you are an administrator and you want a newly-created user to be able to change their own password, check the box next to the "Change own password" permission within the user editor.

Remote desktop reachability and behavior

Cannot connect to Windows using RDP

Try explicitly specifying the security method

Recent versions of Windows require NLA (Network Level Authentication) by default, an RDP-specific security method which uses higher-grade encryption and which enforces authentication before allocating desktop session resources. If connections to your Windows RDP servers are failing, try selecting the "NLA" or "TLS" security mode within the failing connection(s) parameters. If you do not also specify the username, password, and (if applicable) domain, Keeper will prompt you for these details upon connecting.

Similarly, older versions of Windows may not support NLA or TLS by default, and Keeper's initial security negotiation may fail unless the older "RDP" security method is explicitly selected.

Try disabling validation of the RDP server certificate

Both the NLA (Network Level Authentication) and TLS security modes involve client verification of the RDP server's certificate. In the case of most Windows servers, this certificate will be self-signed and cannot be verified. Lacking the ability to verify the certificate against a known certificate authority, Keeper will refuse to complete the RDP connection. Individual RDP connections can be configured to bypass this verification by checking the "Ignore server certificate" option within the connection parameters.

Check whether Windows firewall rules are blocking RDP connections from guacd

The Windows firewall may be configured to block inbound RDP connections, either locally or through GPOs. If the Windows machine in question has historically been accessed using RDP, it may still be the case that RDP access is blocked for all but a specific subnet in which the Keeper Connection Manager server does not reside. If this is the case, the Windows firewall should be reconfigured to allow the Keeper Connection Manager server (or its subnet) to connect via RDP. The Windows server does not need to be publicly accessible.

File transfer using RDP drive redirection is not working

Check that the drive path points to a directory that is writable by the "guacd" user or group

The Keeper Connection Manager packages create a "guacd" user and group for controlling access to files that should be accessible only by guacd. If you are configuring RDP drive redirection, and this user (or group) is not given write access to the directory chosen as the RDP drive path, guacd will not be able to read/write files within that directory as it emulates the redirected drive. Appropriate permissions and ownership should be assigned to any directory intended for use as an RDP connection's drive path:

$ sudo chown -R root:guacd /path/to/directory
$ sudo chmod 770 /path/to/directory

Issues Connecting to Keeper Secrets Manager (KSM) when Using HTTP Proxy

See CATALINA_OPTS