Skip to main content

Cluster Deployment

Guacamole can be operated in a highly-available manner with multiple instances serving traffic across many availability zones. This cluster deployment can also be auto-scaled to reduce cost of operation during low-traffic periods and can quickly scale up to handle increased traffic.

This guide describes a configuration provides a highly available deployment of the Guacamole Bastion Host using AWS Auto Scaling Groups and the Application Load Balancer. The cluster is deployed using CloudFormation and is ready to go within 5 minutes after launch.

Cluster Network Diagram

  • Application Load Balancer

    Terminates the TLS connection and forwards the connection to the EC2 instances running the Guacamole Bastion Host image.

  • 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

    An existing MySQL compatible server (Aurora, MySQL, MariaDB) is required and not deployed by the CloudFormation stack. The MySQL server must be able to accept connection from the EC2 instances launched by this cluster.

  • MySQL User and Database

    The MySQL server must 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​

  1. 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'@'%';

  1. If you have an existing Guacamole instance and want to migrate, go to Step 2.

  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.

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

  2. 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

  3. 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

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/v2/home#SecurityGroups.

  2. Choose Create Security Group.

  3. Specify a name and description for the security group.

  4. For VPC, choose the ID of the VPC.

  5. 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.

  1. Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/v2/home#SecurityGroups.

  2. Select your database security group.

  3. On the Inbound tab, click Edit.

  4. 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.

Launch Stack

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 GuacamoleUrl 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.