Nomad Gateways

Last modified on October 4, 2023

This guide describes how to create and run a StrongDM gateway on HashiCorp Nomad.

To learn more about gateways in general, see Nodes.

Prerequisites

  • Before you begin, make sure you have the Administrator permission level in StrongDM.
  • Ensure that you have a running Nomad instance and are familiar with the Nomad CLI or Nomad Web UI.

Steps

Add a gateway in the Admin UI

  1. Log in to the StrongDM Admin UI.
  2. Go to Network > Gateways and click Add gateway.
  3. Create your gateway by setting the following:
    1. Name (Required): Enter a unique name for the gateway. This is the name that is displayed throughout StrongDM.
    2. Advertised Host (Required): Use the IP address or hostname of your Nomad server.
    3. Advertised Port (Required): Edit the port number if you want it to differ from the default 5000.
    4. Bind IP (Optional): Optionally set the IP address for the gateway to listen on. You can use 0.0.0.0 for all interfaces.
    5. Bind Port (Optional): Optionally set the port for the gateway to listen on (default: 5000).
  4. Click Create gateway to save.
  5. Copy the token that is generated. This token is used in later steps.

Create a gateway on Nomad

You can choose one of two ways to create a StrongDM gateway on Nomad. You can use either the Nomad CLI or Nomad Web UI.

Use the Nomad CLI

  1. Use SSH to log in to your Nomad server.

  2. Use a text editor to create a new file called sdm-gateway-nomad.

  3. Copy the following example code and paste it into your file:

    job "sdm" {
#Your datacenters should be updated to reflect your environment.
  datacenters = ["$datacenters"]  
  group "gateways" {
    count = 1
    task "server" {
      driver = "docker"      
      config {
        image = "quay.io/sdmrepo/relay"
      }
# Replace $SDM_RELAY_TOKEN with the token generated in the Admin UI.   
      env {
        SDM_RELAY_TOKEN = "$SDM_RELAY_TOKEN"
      }      
      resources {
        network {
          mbits = 10
# This port can be configured in the Admin UI. By default it is port 5000.
          port "relay" {
            static = 5000
          }
        }
      }
    }
  }
}

  4. In your file, replace the $datacenters and $SDM_RELAY_TOKEN placeholders with the actual values. If you changed the port when adding the gateway in the Admin UI, change the port here too.

  5. Save and close the file.

  6. Create a new job:

    nomad job init sdm-gateway

  7. Do a dry run to make sure there are no issues:

nomad job plan sdm-gateway
  1. Start the job:
nomad job run sdm-gateway

Use the Nomad Web UI

  1. Log in to the Nomad Web UI.

  2. Go to the Jobs tab.

  3. Click Run Job.

  4. Copy the following example code:

    job "sdm" {
#Your datacenters should be updated to reflect your environment.
  datacenters = ["$datacenters"]  
  group "gateways" {
    count = 1
    task "server" {
      driver = "docker"      
      config {
        image = "quay.io/sdmrepo/relay"
      }
# Replace $SDM_RELAY_TOKEN with the token generated in the Admin UI.   
      env {
        SDM_RELAY_TOKEN = "$SDM_RELAY_TOKEN"
      }      
      resources {
        network {
          mbits = 10
# This port can be configured in the Admin UI. By default it is port 5000.
          port "relay" {
            static = 5000
          }
        }
      }
    }
  }
}

  5. In the Job Definition section, paste that example code.

  6. Replace the $datacenters and $SDM_RELAY_TOKEN placeholders with the actual values. If you changed the port when adding the gateway in the Admin UI, change the port here too.

  7. Click Plan.

  8. Ensure no errors occurred.

  9. Click run.

Verify that your gateway is online

In the Admin UI, go to Network > Gateways to verify that the gateway you created is online.

If it does not appear online, perform a hard refresh of your web browser. Within a couple of minutes, if it is still not online, verify that the StrongDM daemon is running by running ps aux|grep sdm on the server and looking for sdm relay in the output.