Skip to main content

Setup Instructions

The instance must be launched with an IAM instance profile to retrieve running instances from the AWS API and to push the audit log to CloudWatch Logs. You can also choose to run this AMI without the instance profile applied. In that case the automatic discovery of instances and audit log will not be available.

The Guacamole web interface will only be able to discover instances it can actually open a connection to. Make sure that the Guacamole instance can establish a connection with the target instance via security group rules.

Create Instance Profile​

Using CloudFormation

Simply follow this link to launch the stack. This stack will create the required EC2 instance profile with the necessary permissions.

Launch Stack

Manually create Instance Profile

If you cannot use CloudFormation you can also create the instance profile manually by following these steps:

  1. Go to https://console.aws.amazon.com/iam/home#/policies$new?step=edit

  2. Switch to the JSON tab and paste the following policy. This policy grants the instance access to CloudWatch Logs to push the connection history and the ability to assume an IAM role in any account where you are running instances.

    {
        "Version": "2012-10-17",
        "Statement": [{
            "Action": "sts:AssumeRole",
            "Resource": "arn:aws:iam::*:role/EC2ReadOnlyAccessRole",
            "Effect": "Allow"
        }, {
            "Action": [
                "logs:CreateLogGroup",
                "logs:CreateLogStream",
                "logs:PutLogEvents",
                "logs:DescribeLogStreams"
            ],
            "Resource": "*",
            "Effect": "Allow"
        }]
    }

  3. Click on Review Policy, provide a name such as guaws and click on Create Policy

  4. Go to https://console.aws.amazon.com/iam/home#roles$new

  5. Choose EC2 under services that will use this role

  6. Select the EC2ReadOnlyAccess policy, the policy you create in the previous step and click Next

  7. Provide a role name such as "GuAWS" and click on Create Role

  8. When launching the instance pick the role from the instance profile dropdown in step 3. Configure Instance

Enable Cross-Account Access​

The Guacamole agent is able to discover instances in AWS accounts other than the AWS account it was launched in. It will query the VPC for Transit Gateway attachments and VPC Peering Connections. If the VPC is connected to a VPC in a different account, the Guacamole agent will try to assume the role EC2ReadOnlyAccessRole in the target account to discover additional EC2 instances. If this role doesn't exist, the agent will log a warning.

To enable cross-account discovery of EC2 instances, create the following IAM role, either via a CloudFormation template or manually. Allow up to five minutes for the Guacamole agent to pick up the new role. If cross-account discovery doesn't seem to work. log on to the Guacamole EC2 instance and execute guawsctl logs -f guaws to retrieve the log files of the agent. Monitor the logs for error messages.

CloudFormation Template

This stack must be deployed in the AWS account that you want to make discoverable to the Guacamole agent.

Launch Stack

Parameters:

  • Principals: Provide the AWS Account ID of the account where the Guacamole instance was launched

Manually Create IAM Role

  1. Log in to AWS account that you want to make discoverable to the Guacamole agent
  2. Go to https://console.aws.amazon.com/iam/home?#/roles$new?step=type&roleType=crossAccount
  3. Enter the AWS Account ID of the account where the Guacamole instance was launched
  4. Select the EC2ReadOnlyAccess policy, the policy you create in the previous step and click Next
  5. Provide the role name "EC2ReadOnlyAccessRole" and click on Create Role (do not change the name of the role)

Accessing the Application​

The instance should be fully booted within 5 minutes after launch. Access the application via a browser at https://[public_dns]/ (or https://[private_ip]/ if the instance was launched in a private VPC). The default user is guacadmin, the default password is the instance ID.

Most browsers will display a certificate warning. This warning is letting you know that the certificate was self-signed instead of signed by a trusted Certificate Authority. You can safely ignore the warning as it doesn't impact the security of the connection by clicking on "Continue to this webpage" (Internet Explorer) or "Advanced" and then "Proceed to website" (Chrome).

To connect to the underlying operating system of the EC2 instance connect via SSH with the username ec2-user.