# StrongDM Gateway AMI Installation Guide

### Overview

The StrongDM Gateway Amazon Machine Image (AMI) makes it easy to deploy nodes (gateways and relays) when launching Amazon EC2 instances. The AMI comes with the StrongDM package pre-installed. When you launch the EC2 instance using the correct token, the node registers in your StrongDM organization without you having to manually create it, and you are ready to connect to your resource.

This guide describes how to attach the StrongDM Gateway AMI to a new EC2 instance, set a StrongDM token, and enable the correct security settings in order to connect to EC2 through StrongDM.

{% hint style="info" %}
The AMI is provided as a courtesy. It is not maintained as regularly as the standard StrongDM gateway and relay packages. If you are unsure about whether to use a regular [Docker image](/admin/networking/gateways-and-relays/docker-nodes.md) or the AMI, we recommend using a Docker image.
{% endhint %}

### Prerequisites

Be an Administrator in StrongDM.

Decide whether you want to install a gateway or a relay. If installing a gateway, you need an admin token (`SDM_ADMIN_TOKEN`). If installing a relay, you need a relay token (`SDM_RELAY_TOKEN`).

{% hint style="info" %}
An admin token can be used on multiple machines and it is allowed to create relays and read the list of relays. A relay token can be used on only one machine, and it is only allowed to read.
{% endhint %}

### Steps

These instructions explain how to launch an EC2 instance and get a StrongDM token to configure your gateway. We recommend that you keep AWS and the StrongDM Admin UI open in separate browser tabs or windows, so you can easily switch between them.

#### Get a StrongDM token

If you are setting up a self-registering gateway, follow these steps.

1. In a new browser tab or window, log in to the Admin UI at [app.strongdm.com](https://app.strongdm.com).
2. Go to **Principals** > **Tokens**, and click **Add token**.
3. On the **Create Admin Token** page, for **Name**, enter a descriptive name (for example, “Gateway AMI Creator"), so you can remember what this token is for later.
4. Set the token's **Expiration** (1 week, 1 month, 1 year, or never).
5. Select the checkbox for **Relays**, and underneath that, select **List** and **Create**.
6. Click **Create gateway** to generate the `SDM_ADMIN_TOKEN` value.
7. **Copy** the admin token value and save it somewhere safe.

If you are setting up a relay, follow these steps.

1. In a new browser tab or window, log in to the Admin UI at [app.strongdm.com](https://app.strongdm.com).
2. Go to **Networking** > **Relays** and click **Add relay**.
3. Fill out the name of the relay and click **Create relay** to generate the `SDM_RELAY_TOKEN` value.
4. **Copy** the relay token value and save it somewhere safe.

#### Create a new EC2 instance

1. In AWS, go to the EC2 Dashboard and click **Launch instance**.
2. On the **Choose an Amazon Machine Image (AMI)** page, click **Community AMIs**.
3. Search for “StrongDM” and then choose the latest AMI available.
4. Click **Select** to attach the StrongDM Gateway AMI to your EC2 instance root device volume.
5. Choose your instance type and click **Next**.

{% hint style="info" %}
The AMI is based on Ubuntu and works on any instance type with two CPUs and four GB of memory. We recommend a t3.medium.
{% endhint %}

5. This step describes two different ways to configure user data. You can set it up with an admin token or relay token, or you can pull a password from a secrets store.

   To configure user data with an admin token or relay token, do the following:

   1. On the **Configure Instance Details** page, set all properties the way you want.
   2. Expand **Advanced Details** and configure **User data**:
   3. Select **As text**.
   4. In the **User data** box, enter the token variable and the token value in this specific format:

      If you are setting up a self-registering gateway, enter `SDM_ADMIN_TOKEN=<TOKEN>`.

      Example: `SDM_ADMIN_TOKEN=hU8sHfhdjgg6g43dgabba...7fdjjg.djs1stqjjdop90fjs946fmh`

      If you are setting up a relay, enter `SDM_RELAY_TOKEN=<TOKEN>`.

      Example: `SDM_RELAY_TOKEN=cU2sHfasj5g9g11dgambv...3fdjjg.lks1qiqjjdxy90fjs946fll`

{% hint style="info" %}
If using an admin token instead of relay token, you also have the option to set a custom listen address (the default is the AWS IP for the EC2 instance) and/or custom port (5000 by default). These can be added after the SDM\_ADMIN\_TOKEN variable by using the SDM\_RELAY\_PORT and SDM\_LISTEN\_ADDRESS variables, each separated by line breaks.
{% endhint %}

{% hint style="warning" %}
Only define the SDM environment variables in this section, in the indicated format. Any further customization or additions in the "User data" section could break the AMI installation.
{% endhint %}

To configure user data with a password from a secrets store (for example, AWS Secrets Manager) in your StrongDM Gateway AMI, you can structure your user data as follows:

````
  ```bash
  #!/usr/bin/bash

  # Do updates
  apt update -y
  
  # Install required helper apps
  apt install -y unzip awscli jq
  
  # Set the StrongDM admin token variable with key value from Secrets Manager
  # where <SECRET_ID> = ARN of the secret, <REGION> is your AWS region, and <SECRET_KEY> is the name of the key that stores the StrongDM admin token
  # Example:  aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:us-west-2:123456789012:secret:sdm/secrets-4hJMIj --region us-west-2 --query SecretString --output text| jq -r ".admintoken")
  
  ADMIN_TOKEN=$(aws secretsmanager get-secret-value --secret-id <SECRET_ID> --region <REGION> --query SecretString --output text | jq -r ".<SECRET_KEY>")
  
  # Set the StrongDM admin token variable in a way that systemctl can use it
  
  systemctl set-environment SDM_ADMIN_TOKEN="$ADMIN_TOKEN"
  
  # Restart the StrongDM gateway setup script (the script included with the StrongDM Gateway AMI)
  systemctl restart sdm-relay-setup
  
  # Unset the SDM_ADMIN_TOKEN in systemctl because sdm-proxy fails to start if it has this and SDM_RELAY_TOKEN
  systemctl unset-environment SDM_ADMIN_TOKEN
  
  # Enable and restart sdm-proxy
  systemctl enable sdm-proxy
  systemctl restart sdm-proxy
  ```
````

6\. Set up the instance the way you want on the **Add Storage** and **Add Tags** pages.

7\. On the **Configure Security Group** page, click **Add Rule** and set:

* **Type**: Custom TCP
* **Port Range**: 5000
* **Source**: Anywhere

{% hint style="info" %}
If you are setting up a gateway and you neglect the Configure Security Group step, clients are not able to connect.
{% endhint %}

8. At the bottom of the page, click **Review and Launch**.
9. On the **Review Instance Launch** page that opens, check that everything looks OK, and click **Launch**.
10. When prompted to select an existing key pair or create a new key pair, choose your key pair, check the acknowledgement box, and click **Launch Instances**.

#### Check launch status

It may take a few minutes to get your instance and gateway or relay up and running. You can check the instance’s launch status in both AWS and StrongDM.

**In AWS**

1. Check launch status by going to the **Instances** page.
2. Find the instance that you just launched. If it is up, it is shown in the **Running** state.

**In StrongDM**

If you set up a self-registering gateway:

1. Look at the **Networking** > **Gateways** page.
2. Because you gave the EC2 instance an admin token, the instance registers the StrongDM gateway when the instance comes online. You should now see a new gateway in this section. (If you do not, wait a few minutes and refresh the page.)
3. If you didn't enter a name for the new gateway, it may have been given a a less than obvious name (such as “stinky-fruit-123"). If you do not know which gateway is for EC2, you can compare the gateway’s **Listen Address** to the IP address in your EC2 instance. Once you identify the new gateway, you may want to rename it with a more descriptive name (for example, “aws-ec2-gateway”).
4. The gateway is live when its status shows that it is **online**.

If you set up a relay:

1. Look on the **Networking** > **Relays** page, which should now display your new relay.
2. It is normal for the status to be **offline** or **restarting** at first. When the state changes to **online**, your relay is ready.

Now that installation is complete, you can use StrongDM!


---

# 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.strongdm.com/admin/networking/gateways-and-relays/sdm-ami.md?ask=<question>
```

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.