Guacamole Bastion Host Cluster

The cluster deployment provides high availability to the operation of the Guacamole Bastion Host.

The cluster is deployed using a CloudFormation template. The template will provide the following resources:

Application Load Balancer

Terminates the TLS connection and forwards the connection to the EC2 instances
Auto Scaling Group

Launches the Guacamole EC2 instances, monitors their health and replaces them as needed.

Prerequisites

The following resources are required to exist before the template can be deployed:

VPC

A VPC with at least two subnet. The Guacamole instances need to be launched into subnets that have access to the internet or have a CloudFormation VPC Endpoint configured. The VPC also needs to provide a security group that can be attached to the Guacamole EC2 instances for access to the database.
ACM Certificate

The ACM Certificate is required for the Application Load Balancer to terminate the TLS connection. Please follow this guide on how to create an ACM Certificate or this guide on how to import an existing private key and certificate.
MySQL Server

A MySQL compatible server (Aurora, MySQL, MariaDB) is required and not deployed by the CloudFormation stack. The MySQL server needs to be reachable from the EC2 instances.
MySQL User and Database

The MySQL server needs to have a database, user and schema deployed before the cluster can be launched. Please follow the steps below.

Setup Instructions

Step 1: Prepare MySQL Server

Create a new database and user on the MySQL server. Connect to your MySQL server and execute the following command. It is recommended to change the default password in the first line to something more secure.
```
CREATE USER 'guacamole'@'%' IDENTIFIED BY 'guacamole';
GRANT DELETE,UPDATE,INSERT,SELECT ON guacamole.* TO 'guacamole'@'%';
```
If you have an existing Guacamole instance and want to migrate, go to Step 2.
Download and import guaws.sql. Execute the following command. Replace the host parameter with your MySQL server and the user with your administrative user on the server that has permissions to create tables and databases.
```
 mysql --host mysqlserver --user=root --password < guaws.sql
```

Step 2 (optional): Migrate Database

If you are migrating from a single instance deployment to the cluster deployment you will want to move existing users and connections to the new environment.

Connect to your existing Guacamole instance through SSH with the ec2-user user.

Run the following command to create a dump of your MySQL database to a file

 mysqldump --protocol=TCP --skip-lock-tables --add-drop-table --user=guacamole --password=guacamole --databases guacamole > backup.sql

Import the dump into your new MySQL server. Replace the host parameter with your MySQL server and the user with your administrative user on the server that has permissions to create tables and databases.
```
 mysql --host mysqlserver --user=root --password < backup.sql
```

Step 3 (optional): Create Security Group

The Guacamole EC2 instances must be able to connect to the database server. If your database already allows incoming connections from within the VPC then this step is optional.

To create a new security group using the console

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/v2/home#SecurityGroups.
Choose Create Security Group.
Specify a name and description for the security group.
For VPC, choose the ID of the VPC.
On the Outbound tab, edit the first rule, set Type to MySQL/Aurora and set the Destination to the security group of your database server.

Additionally, the security group of your database server needs to be configured to allow incoming requests from the security group that you just created.

Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/v2/home#SecurityGroups.
Select your database security group.
On the Inbound tab, click Edit.
In the dialog, set Type to MySQL/Aurora and set the Source to the security group that you just created.

Step 4: Launch Stack

The stack can be launched by clicking on the button below. You can also download the CloudFormation template and deploy it manually.

Please ensure that the subnets for the EC2 instances (InstanceSubnets) have internet access or a CloudFormation VPC Endpoint configured. Otherwise the EC2 instance cannot signal the CloudFormation stack of their successful deployment.

If you want Guacamole to be accessible from the internet, make sure that the subnets (LoadBalancerSubnets) are internet facing (sometimes referred to as public subnets).

If the stack fails to enter the CREATE_COMPLETE state within 10 minutes the deployment has most likely failed. In that case, please double check that instances within the InstanceSubnets can reach the CloudFormation API endpoint.

Step 5: Access the Load Balancer

Wait until the stack is in the CREATE_COMPLETE state. Open the Output tab of the CloudFormation stack that was deployed in Step 2. Copy and paste the LoadBalancerDNSName value into your browser. You should see the login screen. The username is guacadmin and the password is guacamole. Please change the password after login by accessing the account settings in the upper right menu.

If you see a blank page instead, the database connection settings might be wrong or the EC2 instance has no network connectivity to the database server. Please make sure that the security groups attached to the EC2 instances have sufficient permissions to access the database server.

Step 6 (optional): Assign DNS Record

Follow the guide on Routing Traffic to an ELB Load Balancer to associate a custom domain name with the load balancer. Make sure that the domain name matches the ACM certificate to prevent certificate warnings in the browser.

Apache Guacamole, Guacamole, Apache, the Apache feather logo, and the Apache Guacamole project logo are trademarks of The Apache Software Foundation.