someorg/Easy-Guacamole-Installer
1
0
Fork 0
mirror of https://github.com/itiligent/Easy-Guacamole-Installer.git synced 2025-12-12 17:32:32 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

updated various comments and notes

Browse source
This commit is contained in:
Itiligent 2024-05-12 08:27:59 +10:00
parent a2276cf542
commit ce7fe28b06
7 changed files with 51 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
1-setup.sh
View file

@ -96,7 +96,7 @@ GUAC_SOURCE_LINK="http://apache.org/dyn/closer.cgi?action=download&filename=guac
MYSQL_VERSION=""
MARIADB_LINK="https://downloads.mariadb.com/MariaDB/mariadb_repo_setup"
# Guacamole default install URL
# Reverse proxy uses this URL:
GUAC_URL=http://localhost:8080/guacamole/
# Get the default route interface IP. Manually update for multi homed systems or where cloud images may use 127.0.x.x
@ -125,7 +125,7 @@ INSTALL_LDAP="" # Add Active Directory extension (true/false)
INSTALL_QCONNECT="" # Add Guacamole console quick connect feature (true/false)
INSTALL_HISTREC="" # Add Guacamole history recording storage feature (true/false)
HISTREC_PATH="" # If blank sets Apache default /var/lib/guacamole/recordings
GUAC_URL_REDIR="" # Add auto redirect from http://xxx:8080 root to http://xxx:8080/guacamole)
GUAC_URL_REDIR="" # Add auto redirect of site root http://xxx:8080 to http://xxx:8080/guacamole
INSTALL_NGINX="" # Install and configure Nginx and reverse proxy Guacamole (via http port 80 only, true/false)
PROXY_SITE="" # Local DNS name for reverse proxy site and/or self signed TLS certificates
SELF_SIGN="" # Add self signed TLS support to Nginx (Let's Encrypt not available with this option, true/false)
@ -252,13 +252,13 @@ fi
# Uncomment here to force a specific Tomcat version.
# TOMCAT_VERSION="tomcat9"
# Workaround for issue #31
# Workaround for 1.5.4 specific bug, see issue #31. This was fixed in 1.5.5
if [[ "${OS_NAME,,}" = "debian" && "${OS_CODENAME,,}" = *"bullseye"* ]] || [[ "${OS_NAME,,}" = "ubuntu" && "${OS_CODENAME,,}" = *"focal"* ]]; then
IFS='.' read -ra guac_version_parts <<< "${GUAC_VERSION}"
major="${guac_version_parts[0]}"
minor="${guac_version_parts[1]}"
patch="${guac_version_parts[2]}"
# Assume this will be correctly fixed in 1.5.5 and is a 1.5.4 specific bug. Uncomment 2nd line if issue persists >=1.5.4 (See https://issues.apache.org/jira/browse/GUACAMOLE-1892))
# Uncomment 2nd line and comment first line if issue returns >=1.5.4 (See https://issues.apache.org/jira/browse/GUACAMOLE-1892))
if (( major == 1 && minor == 5 && patch == 4 )); then
#if (( major > 1 || (major == 1 && minor > 5) || ( major == 1 && minor == 5 && patch >= 4 ) )); then
export LDFLAGS="-lrt"

3
2-install-guacamole.sh
View file

@ -544,7 +544,8 @@ ALTER USER 'root'@'localhost' IDENTIFIED BY '$MYSQL_ROOT_PWD';"
echo
fi
# Find the location of the MySQL or MariaDB config files. (Add more potential config file candidates here.)
# A simple method to find the correct file containing the default MySQL timezone setting from a potential list of candidates.
# Add to this array if your distro uses a different path to the .cnf containing the default_time_zone value.
for x in /etc/mysql/mariadb.conf.d/50-server.cnf \
/etc/mysql/mysql.conf.d/mysqld.cnf \
/etc/mysql/my.cnf; do

36
ACTIVE-DIRECTORY-HOW-TO.md
View file

@ -41,19 +41,13 @@ mysql-auto-create-accounts: true
ldap-max-search-results:200
```
- **_Important note on `ldap-user-base-dn:`_** This value sets a position in the directory as a relative root to search within. All Guacamole users to be authenticated by Active Directory must be placed in a lower position within the directory tree than this value. This line can be added multiple times to more efficiently search across multiple branches of a directory tree.
- **Important note on `ldap-user-base-dn:`** This value sets a position in the directory as a relative root to search within. All Guacamole users to be authenticated by Active Directory must be placed in a lower position within the directory tree than this value. This line can be added multiple times to more efficiently search across multiple branches of a directory tree.
- **_Important note on `ldap-max-search-results:`_** Yes, there is no space before the `:200` value. In larger environments managing the directory efficiently requires that we don't query every object in the tree for every user lookup. You may need to adjust this number depending on the number of objects in your tree.
- **Important note on `ldap-max-search-results:`** Yes, there is no space before the default `:200` value. In larger environments managing the directory efficiently requires that we don't query every object in the tree for every user lookup. You may need to adjust this number depending on the number of objects in the above relative root search path.
- **_Important note on `mysql-auto-create-accounts:`_** This line is optional and can be deleted. This line ensures that all Active Directory user accounts will have a matching user account created in the Guacamole db at thier first Guacmaole logon with thier AD accout. All users who need MFA must have a local Guacamole account which is where this setting will be most useful. Local Guacamole db accounts are not needed for access to Guacamole and if not using MFA any regular Domain user can be provisioned access to Guacamole connections without this extra step.
- **Important note on `mysql-auto-create-accounts:`** This line is optional and can be deleted if using Active Directory authentication without Guacamole's implementation of MFA. This line ensures that all Active Directory user accounts will have a matching user account created in the Guacamole database at thier first Guacmaole logon with thier AD accout. Only if Gucamole's MFA feature is to be provisioned is a local Guacamole account required, and automating this step can aid MFA deployment. If you want to provision Guacamole MFA access to just a limited selection of Active Diretory users, you may remove this line and manually create the passwordless Guacamole database local account pairings as needed. [See below for more.](https://github.com/itiligent/Guacamole-Install/blob/main/ACTIVE-DIRECTORY-HOW-TO.md#busts_in_silhouette-manually-creating-and-configuring-new-guacamole-users-for-active-directory-authentication-with-mfa)
### :computer: **Step 4: Run the (now customised) LDAP configuration script**
```shell
sudo $USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh
```
### If you use TLS with your AD implementation, there is an extra step... For more info see [#18](https://github.com/itiligent/Guacamole-Install/issues/18)
#### If your AD has TLS implemented via a self signed certificate you must also apply the 5 steps below, else skip... For more info see [#18](https://github.com/itiligent/Guacamole-Install/issues/18)
1. Adjust this line in the above template for add-ldap-auth-guacamole.sh (Values can be none, ssl or stattls)
```
@ -67,9 +61,9 @@ openssl s_client -connect X.X.X.X:389 \
openssl x509 -text | \
sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'
```
3. Copy the certificate contents from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- and paste this into a file
3. Copy the certificate contents from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE----- and paste this into a file (e.g. adcert.pem as per below)
```
sudo nano /etc/ssl/certs/adcert.pem
sudo nano /etc/ssl/certs/adcert.pem # then paste certificate output
```
4. Now import the AD cert file into the Java keystore
@ -85,19 +79,27 @@ sudo keytool -importcert -alias adcert \
systemctl restart tomcat9
````
### :door: **Step 5: Logging on to Guacamole with the new guacbind-ad account**
### :computer: **Step 4: Run the (now customised) LDAP configuration script**
```shell
sudo $USER_HOME_DIR/guac-setup/add-ldap-auth-guacamole.sh
```
### :door: **Step 5: Log on to Guacamole with the new guacbind-ad account**
- When logging in to Guacamole as the new Active Directory account and password created above, that domain user is passed through to Guacamole as both a Guacamole admin and a Domain User. If all is working correctly, all the users located below the directory tree position set in **ldap-user-base-dn** will be listed under **Settings | Users** of the Guacamole management console.
### :busts_in_silhouette: **Step 6: Manually creating and configuring new Guacamole users for Active Directory authentication**
### :busts_in_silhouette: **Manually creating and configuring new Guacamole users for Active Directory authentication with MFA.**
- If not using the **mysql-auto-create-accounts** directive, manually re-create the exact user account names in Guacamole as those in the directory that you wish to give specific local adminstrative permissions or access to Guacamole. **DO NOT configure a Guacamole password for any users that will be exclusively authenticating via Active directory**. If AD users need MFA, better to implement MFA via AD globally rather via the Guacamole application. Guacamole local user accounts without a password are first given an MFA challenge by the local Guacamole application (if Guacamole's MFA is configured for that user locally) and then will be brokered to Active Directory for their Kerberos authentication challenge. Guacamole local user accounts that are given passwords in Guacamole will always refer to the local db for authentication, never Active Directory. This design allows for a matrix of local, domain, MFA & non-MFA access use cases to be deployed.
- If not using the **mysql-auto-create-accounts** directive, manually re-create the exact user account names in Guacamole as those in the directory that you wish to give specific local adminstrative permissions and/or provision Guacamole's MFA access. **DO NOT configure a Guacamole password for any users that will be exclusively authenticating via Active directory**. Guacamole database local user accounts without a password are first given an MFA challenge by the local Guacamole application (Only where the local passwordless Guacamole account is configured for MFA) and then will be brokered to Active Directory for their Kerberos authentication challenge. Guacamole database local user accounts that are given passwords in Guacamole will always refer to the local database account for authentication, never Active Directory. This design allows for a matrix of local, domain, MFA & non-MFA access use cases to be deployed.
### :key: **Step 7: Logging on using either the local vs. the domain guacbind-ad account**
### :key: **Logging using Gucamole local vs. domain guacbind-ad account**
- As described above, logging on with the Guacamole admin user password will authenticate with the local Guacamole admin account, conversely if the Guacamole admin domain account password is given, the domain account is authenticated via Active Directory and then passed through as authorized to administer Guacamole. It may sometimes be necessary to log on with the local Guacamole admin account to manage some application functions, but be aware that when doing so you will not be able to view and search the user list from Active Directory. Only when logged on with the domain version of the Guacamole admin account can domain user permissions to various Guacamole sessions and objects be delegated and managed.
### :gear: **Step 8: Creating a quasi Single Sign-On user experience for Windows RDP access**
### :gear: **Creating a quasi Single Sign-On user experience for Windows RDP access**
- Create a Global Security domain group (e.g., Guac_Users) and populate it with selected domain users as required.
- Now add this new security group to the built-in “Remote Desktop Users” domain group.

19
README.md
View file

@ -19,7 +19,7 @@ wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.
<img src="https://github.githubassets.com/images/icons/emoji/lock.png" width="23"> **Before diving in, make sure you have:**
- **A compatible OS:**
- **A compatible OS (with sudo & wget packages installed):**
- **Debian 12, 11 or 10**
- **Ubuntu 23.04, 22.04, 20.04**
- **Raspbian Buster or Bullseye**
@ -28,13 +28,14 @@ wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.
- **1 CPU core + 2GB RAM for every 25 users (plus minimum RAM & disk space for your selected OS).**
- **Open TCP ports: 22, 80, and 443 (no other services using 80, 8080 & 443)**
- **If selecting either of the TLS reverse proxy options, you must create an internal DNS record for the internal proxy site, and an additional public DNS record if using the LetsEncypt option.**
- **The username running the 1-setup.sh script must have sudo permissions (script is not run as sudo, it will prompt for sudo)**
## Setup Script Menu
<img src="https://github.githubassets.com/images/icons/emoji/wrench.png" width="23"> **The main 1-setup.sh script guides you through the installation options in the following steps:**
1. Setup the system hostname and local DNS name. (Must be consistent with DNS records for TLS proxy)
2. Choose either a fresh local MySQL install or use a pre-existing remote MySQL instance.
2. Choose either a fresh local MySQL install or use a pre-existing local or remote MySQL instance.
3. Pick an authentication extension: DUO, TOTP, LDAP/Active Directory, or none.
4. Select optional console features: Quick Connect & History Recorded Storage UI integrations.
5. Decide on the Guacamole front end: Nginx reverse proxy (http or https) or keep the native Guacamole interface on port 8080
@ -55,7 +56,7 @@ wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.
- **Caution: Be aware that running the auto-installer link again re-downloads the suite of scripts and will overwrite all script edits. You must run setup locally after editing the setup script.** If any other scripts are edited, their corresponding download links in the setup script must also be commented out in the main setup script else these will be overwritten even when setup is run locally. There should be no reason to edit any script other than the main `1-setup.sh`
- Many of the scripts in the suite are **automatically adjusted with your chosen installation settings at 1st install** to form a matched set. This allows you to upgrade Guacamole or add extra features after the original installation without any configuration mismatches or errors. Editing any scripts other than the main setup may break this function.
- Nginx is automatically configured to default to at least TLS 1.2, therefore ancient browsers or API connections using TLS 1.1 will not work out of the box. This can be reverted via the the `/etc/nginx/nginx.conf` file.
- Nginx is automatically configured to default to at least TLS 1.2, therefore ancient browsers or API connections using TLS 1.1 will not work out of the box. To revert this see commented sections of the `/etc/nginx/nginx.conf` file.
- A daily MySQL backup job will be automatically configured under the script owner's crontab.
- **Security note:** The Quick Connect option brings a few extra security implications; so be aware of potential risks in your particular environment.
@ -68,7 +69,7 @@ wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.
## Customise & Brand Your Guacamole Theme
<img src="https://github.githubassets.com/images/icons/emoji/art.png" width="23"> **Want to give Guacamole your personal touch? Follow the theme and branding instructions** [here](https://github.com/itiligent/Guacamole-Install/tree/main/guac-custom-theme-builder). To revert to the Guacamole default theme, simply delete the branding.jar file from /etc/guacamole/extensions then `TOMCAT=$(ls /etc/ | grep tomcat) && sudo systemctl restart ${TOMCAT} && sudo systemctl restart guacd && sudo systemctl restart nginx` and don't forget to clear your web browser cache.
<img src="https://github.githubassets.com/images/icons/emoji/art.png" width="23"> **Want to give Guacamole your personal touch? Follow the theme and branding instructions** [here](https://github.com/itiligent/Guacamole-Install/tree/main/guac-custom-theme-builder). To revert to the Guacamole default theme, simply delete the branding.jar file from /etc/guacamole/extensions, run `TOMCAT=$(ls /etc/ | grep tomcat) && sudo systemctl restart ${TOMCAT} && sudo systemctl restart guacd && sudo systemctl restart nginx`, then clear your browser's cache.
## Managing self signed TLS certs with Nginx (the easy way!)
@ -81,17 +82,17 @@ wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.
## Upgrading Guacamole
<img src="https://github.githubassets.com/images/icons/emoji/globe_with_meridians.png" width="23"> To upgrade Guacamole, edit `upgrade-guac.sh` to relfect the latest versions of Guacamole and MySQL connector/J before running it. This script will automatically update the installed extensions too.
<img src="https://github.githubassets.com/images/icons/emoji/globe_with_meridians.png" width="23"> To upgrade, edit `upgrade-guac.sh` to relfect the latest versions of Guacamole, MySQL connector/J before running. This script will also automatically update any optional pre-existing extensions if present (TOTP, DUO, LDAP, Quick Connect and History Recorded Storage.)
## High Availability Deployment
<img src="https://github.githubassets.com/images/icons/emoji/unicode/1f454.png" width="23"> Did you know that Guacamole can run in a load balanced farm with layered physical/virutual separation between the web front end, application and database layers? To achieve this, the MySQL, Guacamole and Nginx front end components are typically split into 3 systems (or containers). VLANs & firewalls between these layers help greatly with defence in depth security concepts too.
<img src="https://github.githubassets.com/images/icons/emoji/unicode/1f454.png" width="23"> Did you know that Guacamole can run in a load balanced farm with layered physical / virtual separation between the web front end, application and database layers? To achieve this, the MySQL, Guacamole and Nginx front end components are typically split into 3 systems (or containers). VLANs & firewalls between these layers help greatly with defence in depth security concepts too.
A simple benefit of using a separate MySQL backend server or MYSQL container means you can upgrade and test whilst keeping all your data and connection profiles intact. Just point this installer to your MySQL instance and immediately all your connection profiles and settings are right there!
Separating the MySQL layer allows for more granular delegation of datasbase admin tasks (least priviledge) and staged upgrades or application scale out without taking Guacamole offline. (Simply by pointing the installer to your shared backend MySQL instance, all exisiting connection profiles and settings will be immediately available to the new Guacamole instance).
- **For the DATABASE layer:** Find the included `install-mysql-backend-only.sh` [here](https://github.com/itiligent/Guacamole-Install/tree/main/guac-enterprise-build) to install a standalone instance of the Guacamole MySQL database for your backend.
- **For the APPLICATION layer:** You can use the main setup script to build as many application servers as you like. Simply run the main installer to point new installations to a separate remote backend database, just make sure to say **no** to both the "Install MySQL locally" option and any other reverse proxy install options.
- **For the Front end**: There are so many choices available that are already very well documented. You could even use the Nginx scripts to build a separate TLS front end layer. Be aware that [HA Proxy](https://www.haproxy.org/) generally provides far superior session persistence/affinity under load balanced conditions [when compared to Open Source Nginx](https://www.nginx.com/products/nginx/compare-models/) as only Nginx Plus subscribers get all the proper load balancing stuff!
- **For the APPLICATION layer:** You can use the main setup script to build as many application servers as you like. Simply run the main installer to point new installations to a separate remote backend database, just make sure to say **no** to the "Install MySQL locally" option. Also consider saying **no** to any other local reverse proxy install options depending on your plan for load balancing the web front end.
- **For the Front end**: There are so many choices available that are already very well documented. You could even use the included Nginx scripts to build the basis of a separate TLS front end layer, and then add your preferred Nginx load balancing techniques to this config. Be aware that [HA Proxy](https://www.haproxy.org/) generally provides far superior session persistence / affinity under load balanced conditions [when compared to Open Source Nginx](https://www.nginx.com/products/nginx/compare-models/) as only Nginx Plus subscribers get all the proper load balancing stuff! How far you go with load balancing / session affinity will be determined by how seamless you wish to make the user experience when reconnecting to interrupted sessions.
### Installer script download manifest

11
guac-enterprise-build/install-mysql-backend-only.sh
View file

@ -54,7 +54,7 @@ mkdir -p $DOWNLOAD_DIR
chown -R $SUDO_USER:root $DOWNLOAD_DIR
# Version of Guacamole auth jdbc database schema to use
GUAC_VERSION="1.5.3"
GUAC_VERSION="1.5.5"
# Set preferred Apache CDN download link)
GUAC_SOURCE_LINK="http://apache.org/dyn/closer.cgi?action=download&filename=guacamole/${GUAC_VERSION}"
@ -85,6 +85,7 @@ GUAC_USER="guacamole_user" # Default is guacamole_user
GUAC_PWD="test" # Requires an entry
MYSQL_ROOT_PWD="test" # Requires an entry.
DB_TZ=$(cat /etc/timezone) # Typically system default (cat /etc/timezone) or change to "UTC" if required.
MYSQL_VERSION="" # Blank "" will use distro default MySQL packages. Enter a specific MySQL version for official Maria repo eg. 11.1.2. See https://mariadb.org/mariadb/all-releases/ for available versions.
# For a remotely accessed back end DB instance, keep this script set to BACKEND_MYSQL="true".
# Other options are fairly straight forward. For a typical back end server only the $FRONTEND_NET and $MYSQL_BIND_ADDR
@ -98,8 +99,7 @@ DB_TZ=$(cat /etc/timezone) # Typically system default (cat /etc/timezone) or cha
# Start install actions ##############################################################################################
#######################################################################################################################
# Choose a specific MySQL version e.g. 11.1.2 See https://mariadb.org/mariadb/all-releases/ for available versions.
MYSQL_VERSION="" # Blank "" forces distro default MySQL packages.
# Standardise on a lexicon for the different MySQL package options
if [[ -z "${MYSQL_VERSION}" ]]; then
# Use Linux distro default version.
MYSQLPKG="default-mysql-server default-mysql-client mysql-common"
@ -155,7 +155,7 @@ else
echo
fi
# Set the root password without a reliance on debconf.
# Set the MySQL root password without a reliance on debconf (may not be present in all distros).
echo -e "${GREY}Setting MySQL root password..."
SQLCODE="
FLUSH PRIVILEGES;
@ -169,7 +169,8 @@ else
echo
fi
# Find the location of the MySQL or MariaDB config files. (Add to this list for more potential candidates.)
# A simple method to find the correct file containing the default MySQL timezone setting from a potential list of candidates.
# and then update that timzone value. Add to this array if your distro uses a different path to the .cnf contaiing the default_time_zone value.
for x in /etc/mysql/mariadb.conf.d/50-server.cnf \
/etc/mysql/mysql.conf.d/mysqld.cnf \
/etc/mysql/my.cnf; do

13
guac-enterprise-build/upgrade-mysql-backend-only.sh
View file

@ -6,8 +6,12 @@
# April 2023
#######################################################################################################################
# The Guacamole schema have not been updated since late 2021, suggesting that its now quite mature and there will be
# little need to use this, but just in case. Update the database packages separately via apt.
### IMPORTANT ###
# Update you MySQL database packages separately first via your package manager first
# You only need to run this script if the Guacamole schema have changed between versions (this has not been updated since late 2021 with 1.0, suggesting
# that Guacamole is now quite mature and changes may be rare in future.
# To acertain if there are schema changes required for an upgraded version, check inside the guacamole-auth-jdbc-GUAC_VERSION.tar.gz
# file under /mysql/schema/upgrade/ to find any relevant updates. Only run this script if there are.
#######################################################################################################################
# Script pre-flight checks and settings ###############################################################################
@ -52,10 +56,10 @@ mkdir -p $DOWNLOAD_DIR
chown -R $SUDO_USER:root $DOWNLOAD_DIR
# Version of Guacamole to upgrade to. See https://guacamole.apache.org/releases/ for latest version info.
NEW_GUAC_VERSION="1.5.3"
NEW_GUAC_VERSION="1.5.5"
# The currently installed Guacamole schema version is needed to evaluate the required schema upgrades.
OLD_GUAC_VERSION="1.5.0"
OLD_GUAC_VERSION="1.5.4"
# Set preferred Apache CDN download link)
GUAC_SOURCE_LINK="http://apache.org/dyn/closer.cgi?action=download&filename=guacamole/${NEW_GUAC_VERSION}"
@ -80,6 +84,7 @@ echo
# Start install actions ##############################################################################################
#######################################################################################################################
# Download and extract the Guacamole SQL authentication extension containing the database schema
wget -q --show-progress -O guacamole-auth-jdbc-${NEW_GUAC_VERSION}.tar.gz ${GUAC_SOURCE_LINK}/binary/guacamole-auth-jdbc-${NEW_GUAC_VERSION}.tar.gz
if [[ $? -ne 0 ]]; then

4
guac-optional-features/add-smtp-relay-o365.sh
View file

@ -6,12 +6,10 @@
# April 2023
#######################################################################################################################
# If run as standalone and not from the main installer script, check the below variables are correct.
# Prerequisites:
# An office 365 account with a mailbox (NON ADMIN!!)
# An app password created for the above office 365 user at https://mysignins.microsoft.com/security-info
# SMTP Auth enabled for that user under "manage mail apps in the Office365 admin centre
# SMTP Auth enabled for that user under "manage mail apps" in the Office365 admin centre.
# Prepare text output colours
GREY='\033[0;37m'