Logs & Error Handling

The Apache Guacamole installation script generates a log of its activites and also has error handling built in to help troubleshoot any issues that may arise when running the script.

If you do run into an issue with the script, its critical to include the error message displayed by the script in any submitted issue. Its also important to include any other errors from the log in an issue. Be sure to remove any sensitive information like public IP, password(s), public domain, AD/LDAP info, etc.

Log

The Guacamole install script generates a log file based on the variable FILENAME which is stored in the same directory the script is run from. The file name including the .log file extension is stored i nthe variable logfile.

The file name is formated as:

guacamole-${GUAC_VER}_dd-yy-mm.log

Ex:

guacamole-1.0.0_16-2019-7.log

The log file will contain all of the output seen on the screen while the script is running as well as basically all stdout and stderr generated by the commands used by the script. The log file is much more complete then the cleaned up output seen on screen while the script is running.

The script does not log the responses to the menus at the start of the script, however those responses are stored in variables passed to commands logged by the script and may end up in the log as part of those commands in plain text. Once the script has run and the server has been tested to satisfaction, the log file should be moved off the system or deleted.

Error Handler

The Apache Guacamole script will prodcue a detailed and noticable error message on screen should there be an issue while the script is running. This error message will also appear within the log file generated by the Guacamole script.

If an error is encountered, the script will immediatly abort running.

An error message will look similar to the following example:

ERROR (Script Failed) | Line 1058 | Command: mkdir -v /etc/guacamole | Exit code: 1

The message will provide 3 key peices of information to help a user resolve the problem (or report it).

1. The exact line of the script that failed.
2. The specific command on that line that failed.
3. The exit code of the failed command.

Additionally, checking the log file and reviewing the lines immediatly above the error message in the log may provide further details. For example the failed command may have additional error output via stderr not displayed by the error message displayed to the user.

The error handling uses a temporary file stored in the same directory the script is run from, called guac_tmp_vars. A variable called DEL_TMP_VAR controls if this file is automatically deleted by the script or not on a successful run. The default is set to true.

This temporary text file stores only 2 things:

1. Line 1 contains a numeric integer representing the PID of the last background process run or -1 if the the last command run was not a background process.
2. Line 2 contains a true or false entry based on if the error handler was already triggered. This simply prevents the error handler from displaying output two times if a background process failed, for the foreground process and background process. Instead it displays a single message for the failed background process.

As the error handler displays the full command used, this can include passwords or other sensitive options set by a user via the menus. Since the error message is also recorded in the log file, it should be deleted when no longer needed.

If you find what you feel to be a failure during installation not captured by the error handling please file a bug report as per the directions for How to Report Issues