Gateways and Relays in Docker Containers
Last modified on September 20, 2022
This guide describes how to do the following:
- Create a standard gateway or relay in your Docker container.
- Create a self-registering gateway or relay in your Docker container.
For general information about this topic, see section Containers and strongDM.
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.
sdmas root to allow gateways or relays to upgrade themselves automatically. If gateways or relays do not update automatically, this may cause incompatibilities between versions, which may result in access interruptions for your end users.
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.
Add your gateway/relay to the Admin UI and generate a token for it.
If you intend to create a relay instead of a gateway, click Add relay, fill in the name, and click Create.
- Log into the Admin UI and select Gateways in the left navigation.
- Click the Add gateway button in the upper right, and a box will pop up.
- 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.
- Click on create and the token appears onscreen.
- 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.
Execute the Docker command
docker pull quay.io/sdmrepo/relayto download the strongDM Docker Gateway Container image. Note that you may obtain the same link from the Admin UI’s Downloads & Install page.
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
net=hostoption 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.
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.
SDM_DOCKERIZEDin Environment Variables.
Generate the token
You can generate an admin token that has only one function: to create relay tokens. To do this, follow these steps:
In the Admin UI, go to section Access > API & Admin Tokens and click Add token.
On the Create Admin Token page, under Relays, select the checkbox for Create.
Click the Create button at the bottom.
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
#!/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
It is important to understand why each command is in this script:
- First, unset
SDM_DOCKERIZEDto turn off STDOUT logging, so when you run
$CMD relay createit is only outputting the token itself.
- Next, turn off admin authentication by removing the token in
SDM_ADMIN_TOKENand deleting the
.sdmdirectory. Otherwise, when you run the relay, it attempts to authenticate with the admin token.
- Finally, turn on
SDM_DOCKERIZEDand run the relay command. The
--daemonflag is needed to ensure the relay automatically restarts itself in case of upgrades or abnormal terminations.
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
docker run --restart=always [--net=host] --name sdm-relay -e SDM_ADMIN_TOKEN=<ADMIN_TOKEN> -d <ID>
--net=hostoption is only necessary if the destination database is known as localhost (running sdm-relay colocated with the DB). If you plan to use these instructions to generate arbitrary numbers of relays, be sure to account for this in the
--nameflag by removing it or generating a new name for each relay.
Verify your new relay
Log into the Admin UI. In that section, the relay you created should appear Online, with a heartbeat.
If any errors occur or if the gateway/relay does not report online status, please contact email@example.com for assistance.