Close
logodocs

Self-Registering Relay

This document will walk you through the process of modifying the default Docker image to result in an image that takes an admin token, which you can reuse, that generates its own relay token to register itself to your strongDM organization.

Note that STDOUT logging is on by default in the Docker container. For more information, see SDM_DOCKERIZED in Environment Variables.

Generate the Token

You can generate an admin token that has only one function: creating 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 Docker image 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

You'll note that this file references a shell scriptthat's where the real magic happens. 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

It is important to understand why each command is in this script. First you have to unset SDM_DOCKERIZED to turn off STDOUT logging, so when you run $CMD relay create it is only outputting the token itself. Next, you need to turn off admin authentication by removing the token in SDM_ADMIN_TOKEN and deleting the .sdm directory, because otherwise when you run the Relay, it will attempt to authenticate with the admin token. Finally, turn back on SDM_DOCKERIZED and run the Relay command. The --daemon flag is needed to ensure the Relay will automatically restart itself in case of upgrades or abnormal terminations.

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 XXX with the admin token you generated above, and YYY with the ID of the Docker image you just generated.

$ docker run --restart=always [--net=host] --name sdm-relay -e SDM_ADMIN_TOKEN=XXX -d YYY

The --net=host option 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 --name flag 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.

Relay Status in Admin UI
Relay Status in Admin UI

If any errors occur or if the Relay does not report online status, please contact support@strongdm.com for assistance.

Automation — Previous
strongDM Client Container
Next — Automation
Add strongDM to Docker Containers