Gateways

Last modified on November 21, 2022

Overview

Gateways are the initial entry point into the StrongDM network. Therefore, each gateway must be assigned an address that is accessible to your users. You need at least one gateway to connect to resources, but we recommend running them in pairs.

StrongDM gateways are usually exposed directly to the internet. If you wish to extend your StrongDM network into a more secure network or subnet, you may deploy a relay that allows egress-only connections to secured resources. To learn more, see the Gateways and Relays pages.

Add a Gateway

  1. Log in to the Admin UI.

  2. Go to Network > Gateways.

  3. Click Add gateway. You can rename the gateway here or modify it later. Advertised host is the IP address or host that the gateway listens on. The Advertised port (default 5000) is the port that the service listens on.

    Add a New Gateway
    Add a New Gateway
  4. Click Advanced to add a Bind IP or a Bind Port.

    Add Advanced Bind Settings
    Add Advanced Bind Settings
  5. Click Create gateway and the gateway token appears in a modal. Copy the gateway token and save it for use in a later step.

    Gateway Token
    Gateway Token
  6. Set up a 64-bit Linux instance to run the gateway. Machines should have at least 2 CPUs and 4 GB of memory. If the instance is using SELinux, you need to disable SELinux to install the gateway.

  7. Log in to the gateway instance. Then download the StrongDM binary:

    curl -J -O -L https://app.strongdm.com/releases/cli/linux
    
  8. Unzip the binary:

    unzip sdmcli_VERSION_NUMBER_linux_amd64.zip
    
  9. Run the installer:

    sudo ./sdm install --relay
    
  10. When you are prompted for the gateway token you created in Step 5, paste it into the terminal. Press enter. For security purposes, the token does not display in the terminal.

  11. Log in to the Admin UI and go to Network > Gateways. The gateway you created appears online and healthy. You may need to hard refresh the page.

  12. Confirm your gateway creation was successful by verifying that the LISTENADDR is accessible from the appropriate end user network, as in the following example.

    telnet 10.0.50.17 5000
    Trying 10.0.50.17...
    Connected to 10.0.50.17
    Escape character is '^]'
    
  13. Repeat this process to create a second gateway if you wish. We recommend running them in pairs for high availability.

Gateway Search Filters

Gateway search filters display gateways according to their name, status, listen address, or bind address. Once you have added at least one gateway, you can use filters to search for specific gateways.

On the Gateways page, type or copy/paste the following filters into the Search field, with or without other text. Do not use quotes or tick marks.

FilterDescriptionExample search
bindaddr:<IP_ADDRESS>Shows gateways with the specified bind addressbindaddr:0.0.0.0:5000 finds gateways that have a bind address of 0.0.0.0:5000.
listenaddr:<IP_ADDRESS>Shows gateways with the specified listen addresslistenaddr:10.0.0.021:5000 finds gateways that have a listen address of 10.0.0.021:5000.
name:<PARTIAL_STRING> or any free-form textShows gateways with names that match the entered string; partial string OKname:keen-coffee or coffee finds all gateways whose names contain those characters.
status:<BOOLEAN>Shows gateways that are online (true) or offline (false)status:false finds all offline gateways.

Gateway Maintenance Windows

This section describes how to set a maintenance window for gateways. Scheduling a maintenance window allows you to have some control over the hour of the day when gateway upgrades happen. If a custom maintenance window is not specified, the default window of 7 Coordinated Universal Time (UTC) applies.

All gateways have a maintenance window and follow a standard process for upgrades:

When a gateway is notified of a new version and it has no client connections, it updates itself immediately. This is true whether a custom maintenance window is set or not.

If a gateway does have client connections, however, it enters the state Awaiting Restart and updates as soon as client connections drop to zero. If that doesn’t happen before the maintenance window is reached, the gateway terminates all connections, updates, and restarts with the new version.

There are several ways to schedule maintenance windows. The method you choose depends on your setup and what is easiest for you:

General considerations

Please consider the following when scheduling maintenance windows:

  • The maintenance window start value is an integer representing the hour of the day, 0 to 23 UTC, when the gateway can terminate connections and restart.
  • The default value is 7.
  • To ensure high availability for your StrongDM network, we recommend that you set unique maintenance window values for your gateways. At minimum, if your gateways are deployed in pairs, the members of each pair should have different windows. This enables each gateway to restart at a different hour, maintaining availability for users to continue to connect to your resources.

Install a gateway on a Linux host

If your gateway is installed on a Linux host, we recommend that you use the environment variable method to set a maintenance window:

  1. Install your gateway using our default Linux gateway instructions. Doing so installs a systemd .service unit file and an environment file.

  2. Open the environment file for editing. The default location is /etc/sysconfig/sdm-proxy.

  3. Add a new line with the SDM_MAINTENANCE_WINDOW_START variable and desired UTC time, like so:

    SDM_RELAY_TOKEN=[redacted]
    SDM_MAINTENANCE_WINDOW_START=15
    
  1. Save the file.

  2. Run the following to pick up the update:

    systemctl daemon-reload
    
  3. Restart the Gateway service:

    systemctl restart sdm-proxy.service
    

Use YAML to deploy the StrongDM Gateway Container

If you are using YAML to deploy the StrongDM Gateway image in a container, you can use the SDM_MAINTENANCE_WINDOW_START environment variable as follows:

spec: null
containers:
  - name: sdm-relay
image: 'quay.io/sdmrepo/relay:latest'
imagePullPolicy: Always
environment:
  - SDM_RELAY_TOKEN=[redacted]
  - "SDM_ORCHESTRATOR_PROBES=:9090"
  - SDM_MAINTENANCE_WINDOW_START=15

In the example shown, the environment variable sets a maintenance window at 15 UTC.

Build a container and pass CLI parameters to the StrongDM binary

If you are building a container and want to pass CLI parameters to the StrongDM binary, you can set a maintenance window by running the following command, where <VALUE> is an integer representing the UTC hour:

sdm relay --maintenance-window-start <VALUE>

For example:

sdm relay --maintenance-window-start 15

In the example shown, we set the value to 15. If the gateway is under load when a new version is released, the maintenance window starts at 15 UTC. At that time, the gateway starts terminating client connections, restarts, and updates.

If any errors occur, please copy them into an email and send them to support@strongdm.com.

Top