Self registering relay

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

Generating the token

You can generate an admin token that has only one function: creating relay tokens. Do this in the Admin UI under Settings / Admin Tokens. Select Create under Relays then click the Create button. Copy the token that is printed to screen as you will need it later.

For more detailed information on creating admin tokens, check out the admin token guide.

Creating 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 .
RUN chmod a+x /

You'll note that this file references a shell script---that's where the real magic happens. Use the following file as, which should be saved in the same directory as autoreg.dock.

# necessary to suppress stdout during token create
# 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/*
# --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 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
---> 35bcea2d45b5
Step 2/4 : ADD /
---> 85b70821341d
Step 3/4 : RUN chmod a+x /
---> Running in 89c456fd5f72
Removing intermediate container 89c456fd5f72
---> 2b934fda1d2d
Step 4/4 : ENTRYPOINT /
---> 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 this recipe 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 for assistance.

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