Guacamole is a browser based remote access tool that provides easy access to hosts in your VPC. Both Windows desktops (RDP) and Linux terminals (SSH) are supported. No client software needs to be installed, an HTML5 capable web browser is all you need. This also enables administrators in corporate environments behind restrictive proxies to access remote servers on AWS.
This product ships with version 1.1.0 of the popular open-source HTML5 RDP and SSH client Apache Guacamole (http://guacamole.apache.org/) and GuAWS, an agent that queries your AWS environment to automatically discover running instances. GuAWS is continuously scanning your VPC for new instances using the AWS API. Your servers are organized by security groups which makes it easy to find the right instance and manage access. Additionally, connections opened by users are logged to CloudWatch logs.
This cluster configuration provides a highly available deployment of the Guacamole Bastion Host through the use of Auto Scaling Groups and the Application Load Balancer. The cluster is deployed using CloudFormation and is ready to go within 5 minutes after launch.
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.
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.
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
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.
ec2-user user. 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
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.
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.
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.
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.