Nodes in Docker Containers

A node in your StrongDM network is either a gateway or a relay. You can find out more about them in the Nodes section of the documentation.

This guide describes how to do the following:

1. Create a standard gateway or relay in your Docker container.
2. Create a self-registering gateway or relay in your Docker container.

For general information about this topic, see the rest of the section about using StrongDM with Docker.

Prerequisites #

You can install your gateways or relays using either the StrongDM Docker Gateway Container or your existing Docker container; however, the configuration options in this guide assume you deployed, or will deploy, the StrongDM Docker Gateway Container.

Gateways and relays must be installed on “always up” Docker machines, as they form the connection to StrongDM for all users accessing the resources behind it. You may repurpose a preexisting machine (for example, bastion host), or in AWS parlance, any general purpose instance with 2 CPUs and 4 GBs memory. For example, the M3s or M4s are a good option.

Gateway and Relay Differences #

Because gateways are functionally different from relays, in that they listen for and accept incoming connections, it is important to note the following:

• If you configure a gateway, you must know the host address before you start because the relay token must be passed.
• If you create a relay token within StrongDM, you have to know the gateway address ahead of time. Once it is registered and you have the token, then you can pass the token into your Docker image.

Additionally, for self-registering gateways or relays, you must figure out which address a gateway or relay listens on. Once that is done, the gateway or relay registers itself with StrongDM, retrieves the token, and so forth.

Standard Gateways and Relays #

This section walks you through the process of setting up a gateway or relay using the StrongDM Docker Gateway Container. For general information, see section Containers and StrongDM.

1. Add your gateway/relay to the Admin UI and generate a token for it.

   1. Log into the Admin UI and select Gateways in the left navigation.
   2. Click the Add gateway button in the upper right, and a box will pop up.
   3. Name the gateway, set the advertised host, and set the port. The Advertised host should be the IP address or host that the gateway listens on. Select a TCP port (default 5000) for the service to listen on.
   4. Click on create and the token appears onscreen.
   5. Copy the token and put it aside, being careful to capture every character. You will need it again below. See sdm admin relay create-gateway if you want to generate a token via the CLI.
   If you intend to create a relay instead of a gateway, click Add relay, fill in the name, and click Create.

2. Execute the Docker command docker pull quay.io/sdmrepo/relay to download the StrongDM Docker Gateway Container image. Note that you may obtain the same link from the Admin UI’s Downloads & Install page.

3. To activate your gateway/relay, type the following Docker command replacing <YOUR_TOKEN> with the actual token you created:

    docker run --restart=always [--net=host] --name sdm-relay -e SDM_RELAY_TOKEN=<YOUR_TOKEN> -p 5000:5000 -d quay.io/sdmrepo/relay
   

   The net=host option is only necessary if the destination database is known as localhost (if you are running sdm-relay colocated with the resource), otherwise the Docker default works. If the destination database is already in a container, we can provide a separate pattern for configuring Docker container linking.

4. Log in to the Admin UI. In that section, the gateway/relay you created appears Online, with a heartbeat.

Self-Registering Gateways and Relays #

This section describes how to create a self-registering gateway or relay. The process involves modifying the default StrongDM Docker Gateway Container to take an admin token that generates its own relay token with the purpose of registering itself to your StrongDM organization. For more information, see Containers and StrongDM.

Generate the token #

You can generate an admin token that has only one function: to create relay tokens. To do this, follow these steps:

1. In the Admin UI, go to section Access > API & Admin Tokens and click Add token.

2. On the Create Admin Token page, under Relays, select the checkbox for Create.

3. Click the Create button at the bottom.

4. Copy the token that is generated, as you will need it later.

   For more detailed information on creating admin tokens, see Admin Tokens.

Create the new Dockerfile #

You can modify the default StrongDM relay binary, which is included in the StrongDM Docker Gateway Container, by creating and building a new Dockerfile. Use the following file to define your new Docker image. Save it as autoreg.dock in a directory on a system with Docker installed.

# Use the following command to build the Dockerfile.
# docker build -f autoreg.dock .

FROM quay.io/sdmrepo/relay:latest

ADD autoreg.sh /autoreg.sh
RUN chmod a+x /autoreg.sh

ENTRYPOINT /autoreg.sh

Note that this file references a shell script. Use the following file as autoreg.sh, which should be saved in the same directory as autoreg.dock.

#!/bin/bash

CMD=/sdm.linux

# necessary to suppress stdout during token create
unset SDM_DOCKERIZED

# generate fresh relay token (depends on inheriting SDM_ADMIN_TOKEN)
export SDM_RELAY_TOKEN=`$CMD relay create`

# temporary auth state is created by invoking `relay create` and must be cleared out prior to relay startup
rm /root/.sdm/*
unset SDM_ADMIN_TOKEN

# --daemon arg automatically respawns child relay process during version upgrades or abnormal termination
export SDM_DOCKERIZED=true # reinstate stdout logging
$CMD relay --daemon

With autoreg.dock and autoreg.sh in place, run the following command to generate the Dockerfile, taking note of the output image name.

$ docker build -f autoreg.dock .
Sending build context to Docker daemon  3.584kB
Step 1/4 : FROM quay.io/sdmrepo/relay:latest
 ---> 35bcea2d45b5
Step 2/4 : ADD autoreg.sh /autoreg.sh
 ---> 85b70821341d
Step 3/4 : RUN chmod a+x /autoreg.sh
 ---> Running in 89c456fd5f72
Removing intermediate container 89c456fd5f72
 ---> 2b934fda1d2d
Step 4/4 : ENTRYPOINT /autoreg.sh
 ---> Running in ec375c32487f
Removing intermediate container ec375c32487f
 ---> f734206ddaaa
Successfully built f734206ddaaa

In this case, the image f734206ddaaa is the resulting local Docker image.

Run the new Docker container #

Similarly to creating a normal Docker relay, you must invoke this Docker image with an environment variable. Replace <ADMIN_TOKEN> with the admin token you generated above, and with the ID of the Docker image you just generated.

docker run --restart=always [--net=host] --name sdm-relay -e SDM_ADMIN_TOKEN=<ADMIN_TOKEN> -d <ID>

Verify your new relay #

Log into the Admin UI. In that section, the relay you created should appear with the online status and a heartbeat.