# Gateways and Relays ### Overview Gateways serve as the primary entry point to a StrongDM network. Gateways have an assigned IP address and optional DNS entry. Relays, much like gateways, are how the StrongDM network connects with resources such as databases and servers. Unlike a gateway, the relay does not listen for client connections. When might this be helpful? For a secure network where you are not able to expose ports, the StrongDM relay is the answer. The relay dials out to connect to your gateways, preserving the egress-only nature of your firewall, but allowing your StrongDM clients to reach any configured resources in the network via those connections. {% hint style="info" %} We recommend the following best practices when configuring gateways and relays: * Deploy gateways and relays in pairs for redundancy. * Offset gateway and relay [maintenance windows](https://docs.strongdm.com/admin/networking/maintenance-windows) within any pair for redundancy. * Deploy gateways in regions that are closest to the largest amount of users. * Deploy relays in regions as close as possible to the resources to which they send traffic. * Do not place gateways and relays behind a load balancer. If you must do so (such as with a cluster) there must be a 1:1 relationship between the port and the container. Deploying new gateways and relays via autoscaling is all right, but failover and routing are handled by StrongDM. * The hierarchy of gateways and relays is usually best with a limited number of gateways. Aim for 20 gateways maximum and have as many relays as necessary to enable the desired data flow or segregation. For more flexibility in network segmentation or for larger amounts of deployed resources and proxies, consider using [proxy-clusters](https://docs.strongdm.com/admin/networking/proxy-clusters "mention"). {% endhint %} ### Gateways Gateways serve as the primary entry point to a StrongDM network. Therefore, each gateway must be assigned an address that is accessible to your users. They can be deployed with a Domain Name System (DNS) entry or sit privately on the corporate network behind a Virtual Private Network (VPN). You can also assign an IP address directly if you prefer not to use DNS or a VPN. You need at least one gateway to connect to resources, but we recommend running them in pairs. {% hint style="info" %} If your host is set up so that the IP address changes upon reboot, this change also causes the gateway to lose connection to StrongDM. There is no way to change the IP address of the gateway in StrongDM manually after the gateway has been created. If this is an issue, one solution is to use a fully qualified domain name instead of an IP address for the gateway or relay hostname in StrongDM. Another is to use the [self-registering StrongDM Gateway AMI](https://docs.strongdm.com/admin/networking/gateways-and-relays/sdm-ami). {% endhint %} StrongDM gateways are usually exposed directly to the internet. In the case of a flat network, the gateway talks to the target systems on the corporate network. On a segmented network with no ingress, however, resources such as databases and servers may not be publicly accessible. If you wish to extend your StrongDM network into a more secure network or subnet, you may deploy a relay behind your firewall to route traffic and allow egress-only connections to secured resources. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-3fafee55e8bc0f280be65b53dc6f6f2f79619643%2Fnetwork-diagram.png?alt=media) Gateways are essentially relays with an assigned IP address and optional DNS entry. Both gateways and relays also decrypt end-user credentials and deconstruct requests for auditing purposes. When clients connect to the StrongDM network, they request a list of available gateways. StrongDM determines the most suitable route and sends all connections through one or more of these gateways. From the point of view of a resource, such as a database or server, all traffic originates from any relay or gateway with access to the resource. {% hint style="info" %} Certificates for gateways automatically regenerate 14 days before they expire. During this process, the gateway will restart, typically without a noticeable impact on services. {% endhint %} Gateways can be deployed as a native [Linux service](https://docs.strongdm.com/admin/networking/gateways-and-relays/ecs-nodes), [Docker container](https://docs.strongdm.com/admin/networking/gateways-and-relays/docker-nodes), or [Kubernetes container](https://docs.strongdm.com/admin/networking/gateways-and-relays/kubernetes-nodes). For more, check the **Download & Install** page in the Admin UI. Gateway settings and configurations can be managed in the Admin UI from **Networking** > **Gateways**. On the **Gateways** page, you can add new gateways and view the [status](#view-status) and details of existing gateways. #### Add a gateway 1. Log in to the Admin UI. 2. Go to **Networking** > **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. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-b93a7be0b5f05568d24930ce4ab83536662e4ace%2Fadd-gateway.png?alt=media) 4. Click **Advanced** to add a **Bind IP** or a **Bind Port**. 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. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-cf0384b4ac90245936035fc69551e6e4a9b7127f%2Fgateway-token.png?alt=media) 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](https://docs.strongdm.com/admin/networking/selinux) to install the gateway. {% hint style="info" %} If you are familiar with Terraform, and choose to set up a gateway in AWS, you can [automate gateway setup](https://github.com/strongdm/terraform-aws-sdm-gateway)! {% endhint %} 7. Log in to the gateway instance. Then download the StrongDM binary: {% tabs %} {% tab title="US" %} ```sh curl -J -O -L https://app.strongdm.com/releases/cli/linux ``` {% endtab %} {% tab title="UK" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh curl -J -O -L https://app.uk.strongdm.com/releases/cli/linux ``` {% endtab %} {% tab title="EU" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh curl -J -O -L https://app.eu.strongdm.com/releases/cli/linux ``` {% endtab %} {% endtabs %} 1. Unzip the binary: ```sh unzip sdmcli_VERSION_NUMBER_linux_amd64.zip ``` 2. Run the installer: {% tabs %} {% tab title="US" %} ```sh sudo ./sdm install --node ``` {% endtab %} {% tab title="UK" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh sudo ./sdm install --app-domain app.uk.strongdm.com --node ``` {% endtab %} {% tab title="EU" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh sudo ./sdm install --app-domain app.eu.strongdm.com --node ``` {% endtab %} {% endtabs %} The installer must be run by a user that exists in the `/etc/passwd` file. Any users remotely authenticated, such as with LDAP or an SSO service, will fail to complete the installation. {% hint style="info" %} The `--node` flag indicates to the software that you are installing a gateway or relay rather than a client. The flags `--gateway` and `--relay` alias to `--node` as well. The token that you paste in the next step, not the install flag used here, will dictate whether the software installs in "relay mode" or as a gateway. {% endhint %} 1. When you are prompted for the gateway token you created, paste it into the terminal. Press enter. For security purposes, the token does not display in the terminal. 2. Log in to the Admin UI and go to **Networking** > **Gateways**. The gateway you created appears online and healthy. You may need to hard refresh the page. 3. Confirm your gateway creation was successful by verifying that the LISTENADDR is accessible from the appropriate end user network, as in the following example. ```bash telnet 10.0.50.17 5000 Trying 10.0.50.17... Connected to 10.0.50.17 Escape character is '^]' ``` 4. Repeat this process to create a second gateway if you wish. {% hint style="info" %} We recommend deploying gateways and relays in pairs for high availability. {% endhint %} ### Relays As with gateways, StrongDM uses relays to connect with network resources such as databases and servers. However, relays do not listen for client connections. They can be deployed behind your firewall when internal subnets do not allow ingress, and you are not able to expose ports publicly. Relays create a reverse tunnel to form connections to the gateway. With this action, they preserve the egress-only nature of your firewall and allow your users to reach any configured resources in the network via their StrongDM [client](https://app.gitbook.com/s/HaY8OFbXUreWEF61MhKm/client). ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-3fafee55e8bc0f280be65b53dc6f6f2f79619643%2Fnetwork-diagram.png?alt=media) When clients connect to the StrongDM network, they request a list of available gateways. StrongDM determines the most suitable route and sends all connections through one or more of these gateways. From the point of view of a resource, such as a database or server, all traffic originates from any relay or gateway with access to the resource. The relay component can be deployed as a native [Linux service](https://docs.strongdm.com/admin/networking/gateways-and-relays/ecs-nodes), [Docker container](https://docs.strongdm.com/admin/networking/gateways-and-relays/docker-nodes), or [Kubernetes container](https://docs.strongdm.com/admin/networking/gateways-and-relays/kubernetes-nodes). For more, check the **Download & Install** page in the Admin UI. Relay settings and configurations can be managed in the Admin UI from **Networking** > **Relays**. On the **Relays** page, you can add new relays and view the [status](#view-status) and details of existing relays. #### Relay use cases How do you know when to deploy a relay instead of a gateway? You may wish to use a relay if your organization has sensitive resources or if you want to isolate certain parts of the network in order to further protect them. Relays are typically used if the organization has any of the following: * Sensitive internal website resources (data science tools, CI/CD, internal repositories, and so forth) * Sensitive databases with network compliance requirements * Sensitive servers with network compliance requirements * Segmented networks for Protected Health Information (PHI), Personally Identifiable Information (PII), or other sensitive data, with separate VPCs with additional compliance requirements #### Add a relay Add a relay to generate a relay token. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-53ceb89388fb295f7288966a0e5f97fe81974cac%2Fadd-relay.png?alt=media) 1. Log into the Admin UI. 2. Go to **Networking** > **Relays**. 3. Click the **Add relay** button. 4. In the modal that appears, you can rename the relay, or you can do it later. 5. Click **Create relay** and the relay token appears. ![](https://4180056444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FF7eka9SH5TT8nJm2ZfWj%2Fuploads%2Fgit-blob-2d44f564397f82b8b5fdcb84a87b0752ff6299a4%2Frelay-token.png?alt=media) 6. Copy the relay token and save it for use in a later step. 7. Set up a **64-bit** Linux instance to run the relay. Machines should have at least 2 CPUs and 4 GB of memory. If the instance is using SELinux you need to [disable SELinux](https://docs.strongdm.com/admin/networking/selinux) to install the relay. 8. Log in to the relay instance and download the StrongDM binary: {% tabs %} {% tab title="US" %} ```sh curl -J -O -L https://app.strongdm.com/releases/cli/linux ``` {% endtab %} {% tab title="UK" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh curl -J -O -L https://app.uk.strongdm.com/releases/cli/linux ``` {% endtab %} {% tab title="EU" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh curl -J -O -L https://app.eu.strongdm.com/releases/cli/linux ``` {% endtab %} {% endtabs %} 9. Unzip it: ```sh unzip sdmcli_*_linux_amd64.zip ``` 10. Run the installer: {% tabs %} {% tab title="US" %} ```sh sudo ./sdm install --node ``` {% endtab %} {% tab title="UK" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh sudo ./sdm install --app-domain app.uk.strongdm.com --node ``` {% endtab %} {% tab title="EU" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* ```sh sudo ./sdm install --app-domain app.eu.strongdm.com --node ``` {% endtab %} {% endtabs %} {% hint style="info" %} The installer must be run by a user that exists in the `/etc/passwd` file. Any users remotely authenticated, such as with LDAP or an SSO service, will fail to complete the installation. {% endhint %} 12. When prompted for the relay token you created, paste it into the terminal and press enter. For security purposes you will not see the token on the screen. 13. Log in to the Admin UI and the relay you created should now appear as online, with a heartbeat. You may need to hard refresh the page. 14. Repeat this process to create a second relay if you wish. We recommend running them in pairs for high availability. 15. To allow access to and from resources and StrongDM, make sure that [relay egress requirements](#egress-requirements) are met. {% hint style="info" %} We recommend deploying gateways and relays in pairs for redundancy. {% endhint %} ### Egress Requirements Although relays do not allow ingress, both gateways and relays do have some egress requirements. Gateways and relays must be able to successfully send traffic to several destinations in order to function correctly. Specifically, they must meet the following minimal egress requirements: {% tabs %} {% tab title="US" %} * `app.strongdm.com:443` (which resolves to multiple IP addresses) * `downloads.strongdm.com:443` (which resolves to multiple IP addresses) for downloading updates * Gateway(s) in your StrongDM organization {% endtab %} {% tab title="UK" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* * `app.uk.strongdm.com:443` (which resolves to multiple IP addresses) * `downloads.uk.strongdm.com:443` (which resolves to multiple IP addresses) for downloading updates * Gateway(s) in your StrongDM organization {% endtab %} {% tab title="EU" %} *Follow instructions in the tab for the region of your organization's StrongDM control plane, not your own location. The default control plane region is US.* * `app.eu.strongdm.com:443` (which resolves to multiple IP addresses) * `downloads.eu.strongdm.com:443` (which resolves to multiple IP addresses) for downloading updates * Gateway(s) in your StrongDM organization {% endtab %} {% endtabs %} For more information, please see the [Ports Guide](https://docs.strongdm.com/admin/networking/ports-guide). Additionally, if your organization requires outbound traffic from your infrastructure to pass through your own corporate proxy, you must set either or both of the `HTTP_PROXY`/`HTTPS_PROXY` environment variables (or the StrongDM-specific version). Please see the [Enviroment Variables](https://docs.strongdm.com/admin/deployment/environment-variables) for a list of available environment variables for use with StrongDM. ### Gateway and Relay Management in the Admin UI The **Gateways** and **Relays** pages of the Admin UI list the gateways and relays that have been configured for your organization. On these pages, you may search and filter on gateways and relays, view status, view the last heartbeat, and get more details about each node. {% hint style="info" %} Gateways and relays without a heartbeat for 30 days are automatically removed. {% endhint %} A list (in table format) of existing gateways or relays is displayed on the **Gateways** and **Relays** pages in the Admin UI. You can sort the table of gateways or relays in your organization by clicking on column headers. Clicking a column header sorts the table by the values in that column, in ascending order. Clicking again on the same header reverses the sorting direction. #### Search filters You can use search filters to search for specific gateways and relays and display them according to their name, status, listen address, or bind address. To use filters, type or copy/paste the following filters into the **Search** field, with or without other text. Do not use quotes or tick marks. | Filter | Description | Example search | | --------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | | `bindaddr:` | Shows gateways or relays with the specified bind address | `bindaddr:0.0.0.0:5000` finds gateways or relays that have a bind address of `0.0.0.0:5000`. | | `listenaddr:` | Shows gateways or relays with the specified listen address | `listenaddr:10.0.0.021:5000` finds gateways or relays that have a listen address of `10.0.0.021:5000`. | | `name:` or any free-form text | Shows gateways or relays with names that match the entered string; partial string OK | `name:keen-coffee` or `coffee` finds all gateways or relays whose names contain those characters. | | `status:` | Shows gateways or relays that are online (`true`) or offline (`false`) | `status:false` finds all offline gateways or relays. | #### View status In addition to the gateway or relay name and heartbeat, you can see its current status (for example, "online"). The possible statuses for gateways and relays are shown in the following table. | Status | Description | Node type | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | | **awaiting restart** | Gateway or relay is waiting to enter a restart window to execute a planned restart | Gateway, relay | | **dead** | Gateway or relay is offline or not able to reach the StrongDM API | Gateway, relay | | **isolated** | Relay cannot dial or successfully handshake an authentication with any gateways; isolated relays may successfully healthcheck resources, but their routes will be unavailable for use by users, as there is no way for the user to hop from a gateway to an isolated relay | Relay | | **new gateway** | Gateway has been created but has not been started or has never accessed the StrongDM API | Gateway | | **new relay** | Relay has been created but has not been started or has never accessed the StrongDM API | Relay | | **online** | Gateway or relay is able to reach out to both the StrongDM API and at least one gateway and can serve client connections | Gateway, relay | | **restarting** | Gateway or relay has shut down for a planned restart | Gateway, relay | | **verifying restart** | Gateway or relay has come online once and is awaiting coming back online after an initial restart | Gateway, relay | ### Maintenance and Monitoring There are several features that enable administrators to maintain and monitor the status of the gateways and relays in their organization. #### Maintenance Windows See the [Maintenance Windows](https://docs.strongdm.com/admin/networking/maintenance-windows) for information about how to schedule a maintenance window for gateways and relays. If a gateway or relay has been active (had a heartbeat at least once) and then remains completely inactive (no heartbeat) for 30 days, it is automatically removed from the StrongDM organization due to its inactivity. #### Liveness Check The StrongDM binary includes a configurable 'liveness' URL that you can use to verify that the relay/gateway is alive and functioning properly. To enable this URL: * **Docker:** Add `-e SDM_ORCHESTRATOR_PROBES=:9090` to the invocation. **9090** is the default port; you can replace it with any port. * **Kubernetes:** Liveness check is already enabled in the Kubernetes configuration. * **Direct configuration:** Add the `SDM_ORCHESTRATOR_PROBES` environment variable when starting the relay/gateway process, setting it to `:9090` or whichever port you prefer. Once configured, you can check `http://ip-of-relay:9090/liveness`, replacing `9090` with the port you configured in the environment variable. If it returns HTTP status 200, then the relay/gateway is in good health. #### Relay/Gateway Capacity The StrongDM binary is carefully designed to use a relatively constant amount of RAM, so its memory utilization should not change significantly through the process lifecycle. Because of this, StrongDM recommends watching the CPU load of the underlying machine to assess the need for additional capacity. {% hint style="info" %} When increasing gateway/relay capacity, you can either add a new gateway or relay or, if you are running in a virtual environment, simply add additional CPUs to the system. {% endhint %} **Load Average** The StrongDM binary will use all available CPUs. If you note that more than 50% of your CPU cores are constantly saturated, then this is a good measure that it is time to scale up. **CPU Time of sdm Process** If you notice that the CPU time of the `sdm` process is increasing faster than real time (for instance, if it uses 30 hours of CPU time in 15 hours of real time) then this is another indication that it is time to scale up capacity. **Throughput** If a lower tier node instance is between clients and high traffic resources, it is possible that the limited transfer speeds or caps of the node will affect the speed of interactions, compared to direct connections from the client to the resource. If this is happening, it may be an indication that node infrastructure with greater throughput is necessary for your organization's nodes. ### Install Your Gateway or Relay The first step to deploy StrongDM is to decide where to host your StrongDM gateways and relays. This is not a final decision; you can change them, or add additional gateways and relays at any time. Check out the following guides to learn how to install a node on various tech stacks: {% content-ref url="gateways-and-relays/docker-nodes" %} [docker-nodes](https://docs.strongdm.com/admin/networking/gateways-and-relays/docker-nodes) {% endcontent-ref %} {% content-ref url="gateways-and-relays/gcp-nodes" %} [gcp-nodes](https://docs.strongdm.com/admin/networking/gateways-and-relays/gcp-nodes) {% endcontent-ref %} {% content-ref url="maintenance-windows" %} [maintenance-windows](https://docs.strongdm.com/admin/networking/maintenance-windows) {% endcontent-ref %} {% content-ref url="gateways-and-relays/nomad-nodes" %} [nomad-nodes](https://docs.strongdm.com/admin/networking/gateways-and-relays/nomad-nodes) {% endcontent-ref %} {% content-ref url="gateways-and-relays/uninstall-nodes" %} [uninstall-nodes](https://docs.strongdm.com/admin/networking/gateways-and-relays/uninstall-nodes) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.strongdm.com/admin/networking/gateways-and-relays.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.