Troubleshooting

Should an issue or error occur with the Apache Guacamole installation script itself the following troubleshooting steps, tips and known issues may help resolve many problems.

Considerations

1. Be sure you have meet all of the criteria in Requirements. Ex: You are running a supported OS, like RHEL/CentOS 7.x.
2. Ensure you have downloaded the latest version of this Guacamole install script direct from the offical source on Github at https://github.com/Zer0CoolX/guacamole-install-rhel/blob/master/guac-install.sh
3. Review the Issues section of the repo, both closed and open, to make sure the issue has not already been addressed.
4. Make sure to set the guac-install.sh script to be executable as per the directions in the README. If not do so.
5. The server you are installing on has an internet connection. If not this is required for the script to work.
6. The server is running a fresh install of RHEL/CentOS and does not perform other roles, does not have other software (used by Guacamole or not) installed and has not had a previously failed attempt of this or other scripts run on it. This script is meant to install Apache Guacamole and its dependent programs for the first time on a "fresh" system. Attempting to use the script on a previously used or configured system is not supported.

Helpful Steps to Gather Information

1. If there was an error message on screen, take note of it. It should provide the line in the script that failed and exit code.
2. Check the generated log file. Typically the last recorded information in the log was the problem. Work from the bottom of the log up and look for problems.
3. Verify the parameters in etc/guacamole/guacamole.properties. This will contain the settings for primary and secondary authentication methods.
4. Verify the parameters in /etc/nginx/conf.d/guacamole.conf and /etc/nginx/conf.d/guacamole_ssl.conf. These files store Nginx parameters and will cause problems if incorrect.
5. The log at /var/log/messages may provide information about issues with Guacamole and the software it uses.
6. Consider checking journalctl or systemctl for further information.

Common Issues

1. The most frequent issues are errors/typos in the manually entered parameters by the user in response to the menus. The best way to prevent these issues is to be prepared. Collect and verify all the information required for the choices/parameters you plan to use with Guacamole. This could include information such as: credentials, names, IP/domains, and other parameters. Be sure to configure networking and other equipment to support the chosen options desired in Guacamole. This may include steps like: creating LDAPS certificate, opening/forwarding ports on a hardware firewall, setting up a public domain to point to the proper WAN IP, etc.
2. If the guac-install.sh file is set to use a line ending other than Unix Line Endings (LF), then the script will not run and instead an error like ": No such file or directory" will be displayed when trying to run it. Change the line endings in the script to Unix (LF) from Windows (CR LF) or Macintosh (CR), save the script and re-try running the script. This change is generally a toggle in most editors not a change you have to make to the contents of the file manually.
3. If setup the script finishes without errors on screen or in the log but the login screen for the web client is blank, then it is likely a configuration issue. Typical culprits are authentication settings (like improper LDAP entries), MariaDB or Nginx config issues. A good method for resolving this can be to run tail -f /var/log/messages and then try to load the web GUI again. This will display the log in real time and you will be able to see if accessing the site generates any output.

If you are unable to resolve an issue yourself, consider submitting an issue report via the Issues tab here in the Github repo. Before doing so, check the How to Report Bugs and Issues page for guidance on the best way to submit requests for help.