# AWS EC2 Discovery
## Overview
Keeper Connection Manager integrates with Amazon AWS to perform automatic discovery and connection to EC2 instances. This makes it fast and easy to connect to any EC2 instance in your cloud environment without having to manually configure anything. Like other connections, the EC2 instance connections are privileged, which means that the end-user does not have access to the underlying credentials.
Once activated, the EC2 instances will appear on the home screen of Keeper Connection Manager as seen below.
### Features of the Integration
* Instant discovery of EC2 instances in your AWS environment
* Restrict permissions to a defined User Group
* PEM files can be managed either on the filesystem or Keeper Vault
## AWS Setup
In order to integrate Keeper Connection Manager with Amazon AWS, you'll need to create a user and assign a role policy that has permission to read instance information. A sample policy with minimal permissions is below:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ec2:DescribeImages",
"ec2:GetPasswordData",
"ec2:DescribeInstances",
"ec2:DescribeInstanceStatus"
],
"Resource": "*"
}
]
}
```
Assign the permission to a user and then create access keys.
## Installation
### Create Group
Before configuring the environment, ensure that you have a Group called "AWS EC2 Administrators" that are assigned to the users who will have access to discovered instances. The group name can also be customized through the AWS\_DISCOVERY\_ADMIN\_GROUP environmental variable.
### Auto Docker Method
To update your Keeper Connection Manager environment to support this feature, you'll need to edit the Docker Compose file located at `/etc/kcm-setup/docker-compose.yml`
#### **(1) Stop the Containers**
Before making changes on the local instance, it is a good idea to stop the containers.
```
sudo ./kcm-setup.run stop
```
#### **(2) Edit the Docker Compose**
Now, edit the docker compose file `/etc/kcm-setup/docker-compose.yml` and add the necessary required environmental variables and volume property. For example, see below.
```
guacamole:
image: keeper/guacamole:2
environment:
....
....
AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
AWS_DISCOVERY_REGIONS: us-east-1
AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
volumes:
....
- "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"
```
#### Store Credentials in the Keeper Vault (optional)
If you are using the Secrets Manager Vault connection with KCM, pem files or private keys can be pulled in dynamically from the Keeper Vault. *If using this method, a volume mount for pem files does not need to be created.* See the [EC2 Cloud Connector documentation](https://docs.keeper.io/kcm-linux-rpm-method/vault-integration/ec2-cloud-connector) for more details.
**Environmental Variables**
`AWS_DISCOVERY_ACCESS_KEY_ID`
The access key ID for the AWS account that should be used to authenticate with AWS (Required).
`AWS_DISCOVERY_SECRET_KEY`
The secret key associated with the access key (Required).
`AWS_DISCOVERY_REGIONS`
Comma-separated list of regions to query for EC2 instances, such as `us-west-1,us-east-1` (Required).
`AWS_DISCOVERY_INSTANCE_BASE_PATH`
The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).
`AWS_DISCOVERY_ADMIN_GROUP`
The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.
`AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT`
If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "`kcm:record`" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.
`AWS_DISCOVERY_KSM_CONFIG`
This Keeper Secrets Manager configuration provides integration with the Keeper vault to store PEM files. See the [EC2 Cloud Connector documentation](https://docs.keeper.io/kcm-linux-rpm-method/vault-integration/ec2-cloud-connector) for more details.
#### **(3) Copy .pem files into the guac\_keys folder**
In the Docker Compose example, you can see a volume mapping in the local file location `/var/lib/guac_keys/`. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.
See the [Key File Permissions](#docker-file-permissions) section below to review the file permissions and ensure that the key files are readable by the container.
{% hint style="info" %}
If you are using the Secrets Manager Vault connection with KCM, pem files or private keys can be pulled in dynamically from the Keeper Vault. See the [EC2 Cloud Connector documentation](https://docs.keeper.io/kcm-linux-rpm-method/vault-integration/ec2-cloud-connector) for more details.
{% endhint %}
#### (4) Upgrade the Container
To update all of the underlying software when using the Docker Automated Install method, run the below command:
```
sudo ./kcm-setup.run upgrade
```
This should automatically start the containers after the update.
### Docker Compose Method
To update your Keeper Connection Manager environment to support this feature, you'll need to edit the "guacamole" section of your custom Docker Compose file.
**(1) Stop the Containers**
Before making changes on the local instance, it is a good idea to stop the containers, as you normally would do with docker-compose.
```
sudo docker-compose stop
```
#### **(2) Edit the Docker Compose**
Now, edit your docker compose file and add the necessary required environmental variables and volume property to the `guacamole` section. For example, see below.
```
guacamole:
image: keeper/guacamole:2
environment:
....
....
AWS_DISCOVERY_ACCESS_KEY_ID: XXXXXXXXXXXXXXX
AWS_DISCOVERY_SECRET_KEY: XXXXXXXXXXXXXXXXXXXXXXX
AWS_DISCOVERY_REGIONS: us-east-1
AWS_DISCOVERY_ADMIN_GROUP: MyDevOpsGroup
AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT: "true"
volumes:
....
- "/var/lib/guac_keys/:/etc/guacamole/cloud-connector-secrets/aws/:ro"
```
**Environmental Variables**
`AWS_DISCOVERY_ACCESS_KEY_ID`
The access key ID for the AWS account that should be used to authenticate with AWS (Required).
`AWS_DISCOVERY_SECRET_KEY`
The secret key associated with the access key (Required).
`AWS_DISCOVERY_REGIONS`
Comma-separated list of regions to query for EC2 instances, such as `us-west-1,us-east-1` (Required).
`AWS_DISCOVERY_INSTANCE_BASE_PATH`
The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).
`AWS_DISCOVERY_ADMIN_GROUP`
The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations.
`AWS_DISCOVERY_RECORD_CONNECTIONS_BY_DEFAULT`
If set to "true", screen recording will be enabled by default on all connections. Connection session recording can also be set at an individual machine level using the "`kcm:record`" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.
#### **(3) Copy .pem files into the guac\_keys folder**
In the Docker Compose example, you can see a volume mapping in the local file location `/var/lib/guac_keys/`. This is the folder in the KCM host where you must place all of the SSH key files required to establish a connection to the target instances. Windows instances must also copy the .pem file which is used to decrypt the Administrator password. KCM will select the proper file for establishing a connection based on the EC2 instance metadata.
See the [Key File Permissions](#docker-file-permissions) section below to review the file permissions and ensure that the key files are readable by the container.
#### (4) Upgrade the Container
To update all of the underlying software when using the Custom Docker Install method, upgrade your containers (assuming docker-compose.yml is in the current directory):
```
sudo docker-compose up -d
```
This should automatically start the containers after the update.
### Advanced Linux Method
If you have installed Keeper Connection Manager using the Advanced Linux Install method, follow the steps below to activate the AWS EC2 discovery feature.
**(1) Install the KCM Cloud Connector package**
If you are using the Advanced Linux Install method, you can use yum install to install the KCM Cloud Connector package:
```
sudo yum install kcm-cloud-connector-aws
```
**(2) Edit the Guacamole Properties File**
Edit `/etc/guacamole/guacamole.properties` to include the mandatory and optional properties for the AWS Cloud Connector feature.
**Available Properties**
`aws-discovery-access-key-id`
The access key ID for the AWS account that should be used to authenticate with AWS (**Required**).
`aws-discovery-secret-key`
The secret key associated with the access key (**Required**).
`aws-discovery-regions`
Comma-separated list of regions to query for EC2 instances, such as `us-west-1,us-east-1` (**Required**).
`aws-discovery-instance-base-path`
The name of the organizational connection group that should be used to house the EC2 instances for convenience. By default, this will be “Amazon EC2“ (Optional).
`aws-discovery-admin-group`
The name of the User Group in Keeper Connection Manager to require for any user to see the discovered EC2 instances. By default, this will be a group called “AWS EC2 Administrators". This can also be assigned to a Group that has been provisioned from Azure AD or other directory integrations (Optional).
`aws-discovery-record-connections-by-default`
If this property is set to "true", screen recording will be enabled by default on all connections (Optional).
Connection session recording can also be set at an individual machine level using the "`kcm:record`" EC2 instance tag, which can be set to "true" or "false" to explicitly enable or disable connection recording.
#### **(3) Copy .pem files into the guac\_keys folder**
Add any required PEM files for private keys used to access Linux instances or decrypt Windows passwords to `/etc/guacamole/cloud-connector-secrets/aws/`
**(4) Restart the Guacamole service**
The new package will not take effect until the web application is restarted.
```
sudo systemctl restart guacamole
```
## Instance Configuration with Tags
Connections can be configured using AWS EC2 tags assigned to each instance, in order to override and customize defaults and metadata.
### Available Tags
**`kcm:username`**
The username that should be used when connecting to that instance.
This tag defines the login username for the instance, such as "centos" or "ec2-user". KCM attempts to select the correct username based on the AMI of the instance, but this can be used to correct a wrong assumption.
#### `kcm:organize`
The full path of the connection groups that should be used to organize the instance among other connections.
This tag Allows EC2 instances to be further organized beyond the connection group containing all instances. By default, all discovered instances will be placed within one top-level group of connections called "Amazon EC2", but will not be further organized. For example, if you set `kcm:organize` to something like "Databases", that instance will be located within a "Databases" connection group beneath "Amazon EC2". If you set `kcm:organize` to "Databases/MySQL", that instance will be within a "MySQL" connection group beneath "Databases", which itself would be beneath the main "Amazon EC2" group.
These connection groups do *not* need to already exist, and they actually exist only in memory (dynamically maintained by the EC2 support).
#### `kcm:record`
Flag to indicate if the instance connection sessions should be recorded.
This tag will override the default screen recording configuration of the KCM environment property `aws-discovery-record-connections-by-default` . If this tag exists with the value "true", the connection will be recorded, if "false", the connection will not be recorded. If the tag does not exist, or is set to any other value, the configured default recording behavior will be used.
## Key File Permissions
### Filename
* The key files must be named exactly as referenced in the EC2 console, e.g. MyServer
* The key files must be named with a **.pem** file extension, for example **MyServer.pem**
### Permissions
The service in the "guacamole" docker container is run by the "guacamole" user. File permissions must be configured properly in the volume mount to ensure that the "guacamole" user has read access to the shared key files.
Example: On the host under `/var/lib/guac_keys/` the files may be owned by ec2-user or whatever you have set up.
```
[root@xxx guac_keys]# ls -l
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:31 kcmdemo.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 ec2-user ec2-user 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 ec2-user ec2-user 1678 Jul 29 18:30 KCMKaliLinux.pem
```
In the container the files may show owned by "1000" or some other user ID.
```
[root@1dd8996db434 aws]# ls -l
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoMac.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoUbuntu.pem
-rw------- 1 1000 1000 1674 Jul 29 18:30 KCMDemoWindows.pem
-rw------- 1 1000 1000 1678 Jul 29 18:30 KCMKaliLinux.pem
-rw------- 1 1000 1000 1678 Jul 29 18:31 kcmdemo.pem
```
There are two ways of solving the file permissions between the host and the guacamole container.
**(1)** You may use the environmental variables GUACAMOLE\_UID and GUACAMOLE\_GID in the guacamole docker definition to map the permission.
```
GUACAMOLE_UID: 1000
GUACAMOLE_GID: 1000
```
This change has the following result:
* Updates the ownerships of existing files from the old UID of the `guacamole` user to the specified value.
* Updates the UID of the `guacamole` user in the container to match that value.
**(2)** You can set wider group or world read permissions on the files from the host, but this is a decision based on your environment and security settings.
{% hint style="info" %}
Ensure that you upgrade the containers for the change to take effect.
(`kcm-setup.run upgrade` or `docker-compose up -d`)
{% endhint %}
### Key Files with Passphrases
If the .pem key is encrypted with a passphrase, you will be prompted for this when establishing the connection to the target.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.keeper.io/en/keeper-connection-manager/using-keeper-connection-manager/aws-ec2-discovery.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.