Step by Step Installation Guide

Notice: (7/18/2019) This page of the wiki may be out-of-date at this time. It is the last page in the wiki I need to update after making major changes to the flow of how the script works and presents menus. It should still be viable as a generalized guide but specific menus/features may be different, removed or new. I hope to have this updated within a couple weeks. Once complete this message will be gone. Thanks!

Installing Apache Guacamole

This page will provide a step-by-step directions along with screenshots and/or gifs when appropriate demonstrating usage of the Apache Guacamole installation script. Be sure to read and review all the documentation in the repo prior to attempting to use the script. Its especially important to have read and reviewed the Warnings, Variables and Requirements among other documentation. The README also provides some important information.

WARNING: It is highly recommended to test this script in a dev/test environment prior to using it in a production setting!

Preface

The script presents options in sets, which I will refer to as "menu(s)". There are two (2) basic types of menus within the script:

1. Options Menu's (or just menu). These are the menus we see first when running the script and their purpose is to take user input for given options.
2. Summary Menu's. These menus are visible after completing the option style menus. The purpose of which is to review selections, make changes and run, restart or cancel the script.

When an option/prompt displays a default value, for ex:

Enter the Guacamole DB name (default guac_db)

Pressing Enter without typing a response to the prompt will use the default value. In the above example, pressing enter at the empty prompt will use the value guac_db as if it was typed in as a response.

Regardless, all of the menus share common headers/titles:

• The first 2 lines at the top are always used as a title of sorts to represent that what is being run is the "Guacamole Installation Script" and the subtitle which reads "Guacamole Remote Desktop Gateway"
• The next line is a dynamic title letting the user know what menu we are currently on. This may state something like "Database and JKS Menu" to represent that the current menu is related to database and Java Keystroe options. It may instead read "Database Summary", in which case its a menu summarizing choices previously made in related to the database, along with an option to make changes to those options.
• Following is a line automatically populated with the OS name, major version and arch. This may state something like "CentOS 7 x86_64".
• The last line typically displays the source of the Guacamole installation, either stable release or git. The exception to this is explained in step 3 below.

Once the option to run the script is selected, information will be displayed on screen to give an idea of progress and what stage the script is currently on. There are two (2) possible points within this period in which human input is required.

• Java Keystore setup. This is always required regardless of options selected. More details on this specific step can be found below.
• Self-signed cert Wizard. This is only displayed/required when selecting a self-signed cert. More details provided below.

When complete, Apache Guacamole should be ready to use. I would recommend doing a quick check by loading the web page, logging in and verifying selected options. I would highly recommend rebooting the Guacamole server to ensure that all required services start as expected and that any updates applied by the script are complete.

Downloading the Apache Guacamole Install Script

Download the guac-install.sh script from this repo using the command:

wget https://raw.githubusercontent.com/Zer0CoolX/guacamole-install-rhel/master/guac-install.sh

If installing a custom Guacamole extension (.jar file), download it as well and take note of its file name and full path. For example the custom extension for Customizing Guacamole's Login Screen

Make the guac-install.sh script executable:

chmod +x guac-install.sh

If planning to use LDAPS via the Guacamole LDAP extension, also download/copy the certificate file (.cer type) from the AD/LDAP server and take note of its file name and full path. Further directions on how to configure LDAPS can be found on the LDAP or LDAPS wiki page.

Run the Apache Guacamole Install Script

Run the script as sudo/root from the directory it is in:

sudo ./guac-install.sh

Options Menus

1. Source Menu

The script is able to install from a stable release version or direct from the Apache Guacamole git repo. The "Source Menu" displays the current stable version (dictated by a static variable set in the script) and the current git version (pulled from the git repo automatically). The "stable" version should always be selected unless attempting to test new features in the git version of Guacamole which are untested for use with the script and may not work. Note: I am unable to support issues/problems when using the script with git as the source.

2. Database and JKS Menu

The menu presents 3 prompts explained below:

1. "Enter the Guacamole DB name". The name of the database in mariaDB used to store all the information Guacamole needs. It could be named virtually anything, but I would recommend giving it a name that clearly represents what it is. Generally speaking, the default value should accomplish this.
2. "Enter the Guacamole DB username". The name of the user whom will have access assigned to utilize the database above on Guacamole's behalf.
3. "Enter the Java KeyStore key-size to use". This is the size in bits to use for the JKS keystore related to Guacamole. The default is 4096 (bit) and should provide a high level of security. 2048 (bit) is likely secure enough. I would not recommend anything lower than 2048 and have not tested with anything greater than 4096.

3. Passwords Menu

This menu is used to set passwords for the Database and JKS from the prior menu.

1. "Enter the root password for mariaDB". This is used to set the root password for mariaDB itself. While not needed on a regular basis, its likely a good idea to set this to something that will be remembered should it ever be required later on.
2. "Enter the Guacamole DB password". Sets the password for the database named in step 1 of the prior menu. While not needed on a regular basis, its likely a good idea to set this to something that will be remembered should it ever be required later on.
3. "Enter the Guacamole Java KeyStore password". Sets the password to the Java Keystore used by Guacamole. While not needed on a regular basis, its likely a good idea to set this to something that will be remembered should it ever be required later on.

4. SSL Certificate Type Menu

Options in this menu determine what type of SSL certificate is used, if any. The following 3 options are provided. To select an option in the prompt, enter the number of the option and press enter.

1. "LetsEncrypt". Selecting this option will proceed to the "LetsEncrypt Menu" which is detailed below under heading 4.1. This option should be used when wanting to acquire a new SSL cert from Let's Encrypt and under the assumption that you have a public domain already configured to direct through networking equipment to the Guacamole server thus making the Guacamole server accessible from the internet.
2. "Self-signed". This option will proceed to the "Self-signed SSL Certificate Menu" which is detailed below under heading 4.2. This option will use openssl to generate a self-signed SSL cert. This option can be used with a public domain already configured to direct through networking equipment to the Guacamole server thus making the Guacamole server accessible from the internet, but I would not recommend it. It should be acceptable for use across a local network or for testing.
3. "None". This option will skip the Let's Encrypt and Self-signed cert. It will make Guacamole accessible via HTTP only (instead of forcing it to use HTTPS), and comment out parameters in the /etc/nginx.conf.d/guacamole.conf and /etc/nginx.conf.d/guacamole_ssl.conf files related to SSL certs. The only reason to use this option is to configure SSL manually, if for example using a cert other than one from Let's Encrypt or self-signed. This should only be used if you know what you are doing and intend to configure HTTPS/SSL yourself.

4.1 LetsEncrypt Menu

The "LetsEncrypt Menu" is a conditional menu only displayed if the "LetsEncrypt" (1) option from the prior menu (4) was selected. It is used to set the parameters used by the script to generate a valid SSL cert using LetsEncrypt/certbot. The following options are presented by this menu:

1. "Enter a valid e-mail address for a Let's Encrypt SSL certificate". This is an email address Let's Encrypt will use to send important account notifications like if a certificate is about to expire.
2. "Enter the Let's Encrypt key-size to use". This is the key-size of the SSL certificate provided by Let's Encrypt. The default for this script is set to 4096 (bit) which should be very secure. 2048 (bit) should provide reasonable security for most use cases. I would not recommend lower than 2048 and have not tested higher than 4096 bit. If unsure leave at the default.
3. "Use OCSP Stapling". Determines if OCSP stapling is set on the certificate and in the Nginx configurations. I highly recommend using this unless you have a specific reason not to.

4.2 Self-signed SSL Certificate Menu

The "Self-signed SSL Certificate Menu" is a conditional menu only displayed if the "Self-signed" (2) option from the prior menu (4) was selected. It is used to set the parameters used by the script to generate a self-signed SSL cert using openssl. A single parameter is presented in this menu:

1. "Enter the Self-Signed SSL key-size to use". The key-size of the self-signed SSL certificate generated by openssl. The default of 4096 (bit) should be reasonable for most uses. 2048 (bit) should be relatively strong as well. As the self-signed cert option should not be used for publicly facing Guacamole implementations, the key-size used is of less importance here than with the equivalent Let's Encrypt option. Even if it was used across the internet, the certificate would not be trusted by clients. I would, however, still recommend using the default value or no lower than 2048.

5. Nginx Menu

The Nginx menu presents a few important but not necessarily intuitive options to set. The options are as follows (NOTE: the gif has not yet been updated to reflect option 1 for the LAN IP):

1. "Enter the LAN IP of this server". Displays the Guacamole servers LAN IP as the default option. For systems with multiple NIC's, this option provides the ability to manually determine which LAN IP to use for Guacamole. This is NOT the WAN IP. It is the a LAN IP used by Guacamole, Tomcat and Nginx to communicate "internally". If not using multiple NIC's, just use the default value provided(hit enter or type the default in as its displayed and hit enter). man hostname, describes that hostname -I, Do not make any assumptions about the order of the output. As I have implemented the command, I only pull the first IP address provided by the command. On multi-NIC systems this may not produce the desired IP hence the addition of this option.
2. "Enter a valid hostname or public domain name such as mydomain.com". What gets entered here depends on if the Guacamole server will use a public domain or only be accessible on the local network. If using a public domain, for ex: mydomain.com then that should be entered here (notice there is no "http://" preceding the domain). If this is being used locally the default value of localhost should typically be used. Alternatives may be the IP address of the Guacamole server or its LAN hostname. I recommend sticking with localhost if not using a public domain.
3. "Enter the URI path, starting and ending with / for example /guacamole/". To overly simplify, the URI path is the part of the URL to open the Guacamole web site after the domain name. The default (typically used by Guacamole) for example would be something like https://mydomain.com/guacamole/. If you instead want it to just be https://mydomain.com then you would enter / as the URI path. If you wanted to customize the URI to be https://mydomain.com/customuri/ then you would set this to /customuri/. / is the default set in this script.
4. "Use only >= 256-bit SSL ciphers (More secure, less compatible. default: no)". This option allows using more secure, 256-bit or greater ciphers only, at the expense of compatibility with older OS's and browsers. For more details see the wiki page on Nginx Configuration. I would recommend using "yes" only if you know all clients connecting are using "modern" OS's and browsers. If compatibility is a concern stick with "no".
5. "Use Content-Security-Policy [CSP] (More secure, less compatible. default: no)". Adds Content Security Policy (CSP) to the SSL configuration. CSP is an HTTP response header which helps reduce XSS risks in modern browsers by declaring which dynamic resources are allowed to load. For more details see the CSP wiki page. This option should increase security but may cause reduced compatibility.

6. Standard Guacamole Extensions

Provides the option to install/configure standard Guacamole extensions or not. If "yes" is selected, the menu displays options for what standard extensions to use/configure. Otherwise the menu for (7) below is displayed.

Guacamole extensions can be selected from this menu by their number. This menu works as a toggle. A selected extension will display a + between the number and ")". To toggle an extension enter its number in the menu and press enter. Multiple extensions can be selected. When all desired extensions are selected, do not enter a number and hit enter while the response to the prompt is blank. Doing so will then lead to a submenu for each extension.

At present the only Guacamole extension the script is able to setup and configure is the LDAP extension. All others are placeholders until I am able to add them to the script and test them properly. Please see the Other Extensions wiki page for details.

The options are as follows:

1. LDAP
2. TOTP
3. Duo
4. RADIUS
5. CAS
6. OpenID

Of the above, all are used as a means of authentication except TOTP (2) and Duo (3), which are used for two-factor authentication, sometimes referred to as 2FA.

6.1 LDAP

See the wiki page LDAP or LDAPS Authentication for details on the prompts and info about configuration.

7. Custom Extension Menu

Prompts if a custom extension should be installed and if so provides options for using it. I have only tested this with my Apache Guacamole Login Screen Customization extension. This option allows adding a local .jar Guacamole extension file from the script to setup. The Apache Guacamole install script will move the .jar extension to the proper folder for Guacamole to use it and set the proper SEL context for it. If the custom extension requires parameters to be configured this would need to be done manually before or after running the script with this option.

The initial prompt states "Would you like to install a custom Guacamole extensions from a local file", with valid answers being yes/no. If "yes" is selected then further prompts are displayed (detailed below), otherwise the next menu is displayed.

If "yes" was selected then the following choices are present:

1. "Enter a valid filename of the .jar extension file (Ex: myextension.jar)". The file name of the extension would be entered here. For example, if the extensions file name was myextension.jar then that is what you would enter for this prompt.
2. "Enter the full path of the dir containing the .jar extension file (must end with / Ex: /home/me/)". This is the local path on the server we are running the install script on that contains the above file, excluding the file name. If the myextension.jar file was in /home/me/ then we would enter that path for this prompt.

Note: If the filename and/or path given are not correct the script will prompt again for it. Be sure prior to running the script that you know the correct file name and full path.

Summary Menus

The "Summary Menu" is the main menu for the summary menus. Each category of menus from the "Options" menus is listed here. This menu serves 2 purposes:

• Allowing review and modification of choices made before running the script.
• Providing a way to run, start from the beginning of the prompts or to cancel the script.

I recommend carefully reviewing the choices made prior to running the script. This is important not only to make sure choices are accurate/correct, but in case one needs to record information like credentials, database names, etc. for safe keeping.

WARNING Be aware that most categories offer options to change the entries, plural. If for example, you wanted to change the database username, electing to make changes to the "Database and JKS" selections would result in ALL settings within this menu being erased and requiring them to be re-entered. In other words, its not possible to alter a single parameter within a menu, only selections made on a per menu category basis.

1. Database

Provides a summary of all the choices made from the "Database and JKS" menu. The only prompt provided asks if the user wants to change the displayed parameters. The default answer is "no" and will return to the main Summary Menu. Pressing "yes" will proceed to the "Database and JKS" options menu to re-select the desired parameters and then return to the Summary Menu (main menu).

2. Passwords

Summarizes the passwords entered in the "Passwords" menu. The only prompt provided asks if the user wants to change the displayed parameters. The default answer is "no" and will return to the main Summary Menu. Pressing "yes" will proceed to the "Passwords" options menu to re-select the desired parameters and then return to the Summary Menu (main menu).

3. SSL Certificate

Displays the type of certificate previously selected and the parameters entered for it. The only prompt provided asks if the user wants to change the displayed parameters. The default answer is "no" and will return to the main Summary Menu. Pressing "yes" will proceed to the "SSL Certificates Type" options menu to re-select the desired SSL certificate type followed by the applicable sub menu for that certificate types parameters and then return to the Summary Menu (main menu).

4. Nginx

Lists the parameters selected from the "Nginx" menu. The only prompt provided asks if the user wants to change the displayed parameters. The default answer is "no" and will return to the main Summary Menu. Pressing "yes" will proceed to the "Passwords" options menu to re-select the desired parameters and then return to the Summary Menu (main menu).

5. Standard Extensions

This summary menu is used to view if standard extensions where elected to be installed followed by three (3) options as follows:

1. "View/change selected extensions and their settings". This will display a sub menu listing a count of the standard extensions selected followed by a list of options for only the extensions previously selected. It is from this option that a user can review what extensions are set to be used, their parameters and the ability to make changes to the configuration on a per extension basis.
2. "Change if extensions are installed and if so which". Provides a mechanism to elect to install no standard extensions or to select/re-select which to install. Be aware that using this option to add/remove extensions from the existing selections will require re-selecting AND re-configuring all of the desired extensions. So if, for example, you had previously selected the LDAP extension and entered its parameters and then chose this option to add another extension as well, you will need to select LDAP and re-enter all of its configuration information again.
3. "Return to the Summary menu". Simply returns to the main Summary menu.

5.1 View/change selected extensions and their settings

To further explain how this sub menu works, if a user previously selected to install "LADP", "Duo" and "RADIUS" extensions then this menu would display numbered options for each. It will not display extensions that had not been selected via the "Standard Guacamole Extensions" options menu.

These menus will only allow altering parameters for previously selected extensions and does not provide the means to include additional extensions, exclude specific previously selected extensions nor decline installing standard extensions altogether. To do so would require using the second (2) option from the "Standard Extensions" summary menu (5).

Each entry for an extension will display a summary menu for the parameters of that extension and the option to return to this menu (5.1) or like previous summary menus, the ability to change configuration options for the given extension. This will not affect any other extensions/parameters outside of those for a given extension. If electing to change the parameters for an extension (entering "yes"), the menu will proceed to the applicable extension menu and then return to the "Standard Extensions" summary menu. If entering "no" then the user is returned to the "View/change selected extensions and their settings" submenu (5.1).

The last option listed will read "Return to Standard Extension Summary" which will return to the "Standard Extensions" summary menu (5).

5.2 Change if extensions are installed and if so which

To elaborate on this option, it is meant to provide a means to change the election to install any standard extensions and/or to change which standard extensions to include.

WARNING This option will erase the inclusion of AND parameters for ALL standard extensions. Long story short, if you previously selected 3 extensions and use this option to add a 4th, you will need to also include the previous 3 in the selection of extensions AND configure all extensions.

Selecting this menu entry will go to the "Standard Guacamole Extensions" options menu, prompting if standard extensions should be installed or not. Selecting "no" will return to the Summary Menu (main menu). Selecting "yes" will proceed to the list of extensions to chose from, followed by the applicable menus for each extensions parameters and then return to the Summary Menu (main menu).

6. Custom Extension

Displays if installing a custom extension was elected. If so, it displays the parameters for the custom extension. The only prompt provided asks if the user wants to change the displayed parameters. The default answer is "no" and will return to the main Summary Menu. Pressing "yes" will proceed to the "Custom Extension" options menu to re-select if a custom extension is to be install, entering the desired parameters (if "yes") and then return to the Summary Menu (main menu).

7. Accept and Run Installation

This option is used to run the Apache Guacamole install script after all choices have been made and reviewed. The point of no return...

8. Cancel and Start Over

This option allows starting the script all over, fresh, from the first prompt. This is useful if you want to change the source of the install (stable vs git) or feel that starting with a clean slate would be faster then using the summary menus to correct entries. Of course in using this option, all previously entered choices are lost.

9. Cancel and Exit Script

Provides a means to stop and exit the script without making any changes to the server. This is the most graceful way to exit the script without it committing any changes to the machine. Of course in using this option, all previously entered choices are lost. The script can be manually ran again by starting with the command to run the script.

Completion

After using "Accept and Run Install" (7), the script will run. During this time it will provide a summary of the steps and activities it is currently going through. As mentioned in the Preface section of this page, there is at least one point (and potentially a second when specific selections are made) that will require human input to proceed.

This output is not a complete dump of everything occurring, but instead a curated summary of events. This makes it easy to tell that the script is running/working and should it fail to generally give an idea at which stage it stopped.

When run successfully and finished, a series of completion messages are displayed to make it clear the process is complete. This includes important information like:

• Path and name of the log file created by the script.
• What URL to open/manage Apache Guacamole from.
• Recommendations to update the default admin account and reboot the server.
• Point of contact information (based on the ADM_POC variable) in case the person running the script was not the person who acquired/customized it for use, should anything go wrong.

In line with the recommendation messages, the first thing to do is check the URL and ensure the login page loads. If it does not work review and work from the information in the wiki pages Troubleshooting, Known-Issues and How to Report Issues.

First, ensure that the server is available via its public domain, hostname or IP based on what selections you made in the script. Verify that infrastructure is properly setup to support the configuration (for example ports forwarded, public domain points to the correct public/WAN IP, etc.) and that the configuration itself is correct in both the information and syntax required.

Presuming the login page loads, login with the default credentials and immediately add a new user with a secure password and admin rights. If using LDAP/LDAPS, follow these Important Manual Steps for setting up an AD/LDAP user with admin rights. After creating a new admin user (and confirming the account works), I recommend either disabling or deleting the default admin account. If you intend to keep it active, change the default password at least.

I would recommend before investing time to setup user permissions, connections, etc. to confirm that all selections are functioning as expected. Extensions, authentication, HTTPS/SSL, etc. Once satisfied these work I highly recommend rebooting the server before setting up Guacamole for use.

At this stage hopefully Apache Guacamole is up and running according to the choices made when running the script. The script itself can be deleted from the server. The log file generated by the script can/should be kept only until the point that one is confident the install was successful. The log may contain sensitive information regarding the configuration of the Apache Guacamole server. I would recommend deleting it or storing it on another server/location that is secure temporarily.