Easy-Guacamole-Installer/README.md

# Guacamole 1.5.3 VDI/Jump Server Appliance Build Script

<img src="https://github.githubassets.com/images/icons/emoji/sparkles.png" width="35"> This script makes setting up Guacamole 1.5.3 a breeze, with added features like TLS reverse proxy, AD integration, multi-factor authentication, Quick Connect, History Recording Storage, dark mode support, auto database backup, O365 email alerts, and enhanced security options.

## Automatic Installation

<img src="https://github.githubassets.com/images/icons/emoji/rocket.png" width="35"> To start building the Guacamole appliance, paste the below link into a terminal and follow the prompts **(no need for sudo, but the user must be a member of the sudo group)**:

```shell
wget https://raw.githubusercontent.com/itiligent/Guacamole-Install/main/1-setup.sh && chmod +x 1-setup.sh && ./1-setup.sh
```

## Prerequisites

<img src="https://github.githubassets.com/images/icons/emoji/lock.png" width="35"> **Before diving in, make sure you have:**

- A compatible OS: Ubuntu 18.04 - 22.x, Debian 11 & 10, or Raspbian Buster/Bullseye (stick to stable releases for cloud images).
- Minimum 8GB RAM and 40GB HDD.
- DNS entries matching your default route interface IP (essential for TLS).
- Open TCP ports: 22, 80, and 443.

## Installation Menu

<img src="https://github.githubassets.com/images/icons/emoji/wrench.png" width="35"> **This script guides you through the installation process in the following steps:**

1. Confirm system hostname and local DNS domain suffix.
2. Choose a MySQL instance type and set security preferences.
3. Pick an authentication extension (DUO, TOTP, LDAP, or none).
4. Select optional console features: Quick Connect and History Recorded Storage.
5. Decide on the Guacamole front end: Nginx reverse proxy (http or https) or keep the native Guacamole interface

**For the more security minded, there's several post-install hardening options available:**

- `add-fail2ban.sh`: Adds a lockdown policy for Guacamole to guard against brute force attacks.
- `add-tls-guac-daemon.sh`: Wraps internal server daemon to guac application traffic in TLS.
- `add-auth-ldap.sh`: A template script for Active Directory integration.
- `add-smtp-relay-o365.sh`: A template script for email alerts via MSO65 (BYO app password).

## Active Directory Integration

<img src="https://github.githubassets.com/images/icons/emoji/key.png" width="35"> **Need help with Active Directory authentication?** Check [here](https://github.com/itiligent/Guacamole-Install/blob/main/ACTIVE-DIRECTORY-HOW-TO.md).

## Customise and Brand Your Guacamole Theme

<img src="https://github.githubassets.com/images/icons/emoji/art.png" width="35"> **Want to give Guacamole your personal touch? Follow the theme and branding instructions** [here](https://github.com/itiligent/Guacamole-Install/tree/main/custom-theme-builder).

## Installation Notes

<img src="https://github.githubassets.com/images/icons/emoji/unicode/2699.png" width="35"> 

1. Paste and run the wget autorun link in your home directory.
2. Exit `1-setup.sh` at the first prompt. (At this point the scripts are downloaded only.)
3. Customise the huge number of installation variables available in `1-setup.sh` as required. (Certain combinations of edits will produce a fully unattended install.)
4. **Caution: If editing `1-setup.sh`, be aware that running the autorun link again re-downloads and overwrites all changes. You must run setup locally after editing.** (Also be sure to comment out the download links in the setup script to any other downloaded scripts that you may have edited. There should be little need to edit outside of the setup script's options.)
5. The **upgrade-guac.sh, add-tls-guac-daemon.sh, refresh-tls-self-signed.sh & backup-guac.sh** scripts are automatically adjusted at installation to match your chosen installation settings. These can be run after install without any modification.
6. If the self-signed TLS proxy option is selected, browser client TLS certificates will be automatically created and saved to `$DOWNLOAD_DIR/guac-setup`.
7. Nginx is automatically configured to use TLS 1.2 or above (so really old browser versions may not work.)
8. A daily MySQL backup job will be automatically configured by the installer.
9. **Security info:** The Quick Connect and History Recorded Storage options bring a few security implications; so be aware of potential risks in your particular environment.
   
## Upgrading Guacamole

<img src="https://github.githubassets.com/images/icons/emoji/globe_with_meridians.png" width="35"> To upgrade Guacamole, edit `upgrade-guac.sh` to relfect the latest available versions of Guacamole and MySQL connector/J before running it. This script will also automatically update the DUO, LDAP, TOTP, Quick Connect & History Recorded Storage extension if they are present.

## Enterprise Scale Out & High Availability 

<img src="https://github.githubassets.com/images/icons/emoji/unicode/1f454.png" width="35"> For Enterprise deployments, did you know that Guacamole can be run in a load balanced farm? To achieve this, the database, application and front end components are usually **split into a 3 layers.** (VLANs & firewalls between the layers helps with security too.)
- **For the DATABASE layer:** Find the included `install-mysql-backend-only.sh` to install just a standalone instance of the Guacamole MySQL database.
- **For the APPLICATION layer:** Simply use the main setup script on as many application servers as you like, just make sure to say no to both the Install MYSQL locally option and any Nginx front end options.
- **For the Front end**: You'll need to roll your own load balancer. **HA Proxy** provides superior session affinity under load balanced conditions when compared to Open source Nginx (Nginx Plus gives you all the good stuff.) There's too many possible ways to achieve this, and the target audience for this sort of setup likely knows how to run with whats already provided.

## Auto Download Manifest

<img src="https://github.githubassets.com/images/icons/emoji/package.png" width="35"> The autorun link downloads these repo files into `$DOWNLOAD_DIR/guac-setup`:

- `1-setup.sh`: The installation script.
- `2-install-guacamole.sh`: Guacamole main installation script.
- `3-install-nginx.sh`: Installs Nginx for reverse proxy (optional).
- `4a-install-tls-self-signed-nginx.sh`: Configures self-signed TLS for Nginx (optional).
- `4b-install-tls-letsencrypt-nginx.sh`: Installs Let's Encrypt for Nginx (optional).
- `add-auth-duo.sh`: Adds Duo MFA extension (optional).
- `add-auth-ldap.sh`: Adds Active Directory extension (optional).
- `add-auth-totp.sh`: Adds TOTP MFA extension (optional).
- `add-xtra-quickconnect.sh`: Adds Quick Connect console feature (optional).
- `add-xtra-histrecstore.sh`: Adds History Recorded Storage feature (optional).
- `add-smtp-relay-o365.sh`: Sets up SMTP auth relay with O365 for backup messages, monitoring & alerts (BYO app password).
- `add-tls-guac-daemon.sh`: Adds TLS wrapper for guacd server daemon (optional).
- `add-fail2ban.sh`: Adds a fail2ban policy for brute force protection.
- `backup-guacamole.sh`: A MySQL Guacamole backup script.
- `upgrade-guac.sh`: Upgrades Guacamole and MySQL connector.
- `refresh-tls-self-signed`: Generates and installs updated TLS certificates for Nginx.
- `branding.jar`: An example template for customising Guacamole's theme. Delete to keep the default UI.

Happy Guacamole-ing! 😄🥑