StrongDM Gateway AMI Installation Guide

Last modified on October 13, 2023

The StrongDM Gateway Amazon Machine Image (AMI) makes it easy to deploy gateways and relays when launching Amazon EC2 instances. The AMI comes with the StrongDM gateway pre-installed, so you don’t have to create a gateway manually in the StrongDM Admin UI—all you have to do is launch an EC2 instance 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.


Ensure that you are an Account 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). Likewise, if installing a relay, you need a relay token (SDM_RELAY_TOKEN).


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

  1. In a new browser tab or window, log in to the StrongDM Admin UI at
  2. If you are setting up a self-registering gateway:
    1. Go to Access > API & Admin Tokens, and click add token.
    2. On the Create Admin Token page:
      1. Enter a descriptive name (e.g., “Gateway AMI Creator"), so you can remember what this token is for later.
      2. Select the checkbox for Relays, and underneath that, select List and Create.
      3. Click Create to generate the SDM_ADMIN_TOKEN value.
      4. Copy the admin token value and save it somewhere safe.
  3. If setting up a relay:
    1. Go to Network > Relays and click add relay.
    2. Fill out the name of the relay and click create to generate the SDM_RELAY_TOKEN value.
    3. 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:

    1. Click Community AMIs.
    2. Search for “StrongDM” and then choose the latest AMI available.
    3. Click Select to attach the StrongDM Gateway AMI to your EC2 instance root device volume.
  3. Choose your instance type and click Next.

    The StrongDM gateway is based on Ubuntu and works on any instance type with two CPUs and 4 GB of memory. We recommend a t3.medium.

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

    1. 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

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

      # 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, <YOUR_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 <YOUR_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
  5. Set up the instance the way you want on the Add Storage and Add Tags pages.

  6. On the Configure Security Group page, click Add Rule and set:

    1. Type: Custom TCP
    2. Port Range: 5000
    3. Source: Anywhere
  7. At the bottom of the page, click Review and Launch.

  8. On the Review Instance Launch page that opens, check that everything looks OK, and click Launch.

  9. 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.


  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 on the Network > 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. The new gateway may have a less than obvious name, like “stinky-fruit-123,” so 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 (e.g., “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 Network > 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!