> For the complete documentation index, see [llms.txt](https://newdocs.keeper.io/kcm-linux-rpm-method/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://newdocs.keeper.io/kcm-linux-rpm-method/using-keeper-connection-manager/aws-ec2-discovery.md).
# 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.
### 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://newdocs.keeper.io/kcm-linux-rpm-method/using-keeper-connection-manager/aws-ec2-discovery.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.