Creating and Editing SSH Jumpbox Routes

See SSH Jumpbox Routes for an introduction.

Introduction

You can add jumpbox routes to Unix secrets when SSH proxying is enabled. A jumpbox route assigned to a target secret specifies a series of Unix servers called jumpboxes, jumpbox servers, or bastion hosts. The proxied connection is forwarded through the jumpbox route before reaching the server specified in the target secret.

Prerequisites

Using jumpbox routes requires these prerequisites:

  • Only use Unix servers and secrets: At this time, jumpbox routes are only supported by Unix secrets. The option to add a jumpbox route does not appear on any target secret that is not base on the Unix secret template. Similarly, a jumpbox route that attempts to connect to jumpbox servers that do not use a Unix secret template will also fail.
  • Enable SSH proxy on Secret Server: For more information on how to enable proxying on Secret Server, see SSH Proxy Configuration.
  • Enable the SSH Proxy setting for the target secret using a jumpbox route: To assign a jumpbox route to a target secret, the target secret itself must have SSH proxying enabled. The enable SSH Proxy check box appears in the secret’s Security tab if proxying is enabled on Secret Server itself.

Permissions

Using jumpbox routes requires these permissions:

  • Adding a jumpbox route to a target secret: A user must have owner permissions on a secret to assign, change, or remove that secret’s jump server route. Additionally, users are only able to pick from a list of routes where they have at least list permission on the first jump route server.
  • Editing Jumpbox Routes: Users must have the “Administer Jumpbox Route” permission to create, edit, or deactivate jump server routes. Users with the “View Jumpbox Route” permission can view the details of all jump server routes in the Admin Jumpbox Route page, but they cannot make any changes.

Creating, Editing, and Deactivating Jumpbox Routes

  1. Go to Admin > See All.

  2. Search for and select Jumpbox Routes. The Jumpbox Routes page appears:

    image-20211020092003207

    This page lists all existing jumpbox routes.

  3. Select an existing route to edit or create a new route by clicking the Create Jumpbox Route button.

  4. If you chose to create a new route, a popup appears. Type the name and description and click the Create Jumpbox Route button.

  5. In either case, the Jumpbox Routes page appears for the new or edited route:

    image-20211020093052558

  6. Note that routes can only be deactivated, not deleted, in the Jumpbox Route Status section.

  7. You can view or edit the the route's jump servers in the Jumpbox Route Levels section. Each row in the grid represents a level, each of which has these attributes:

    • Secret: Each level contains one secret that represents a jump server.

    • Port: The port used on the jump server for the route. Choose an available port on which the server listening for SSH connections. Typically, this is port 22, but we recommend changing it to deter basic script bots, see Best Practices for Jumpbox Routes for more information.

      This value overrides any port specified on the secret.

    • Order: The sequence of jumpboxes forwarding the proxied connection, starting with 1. You can hover over any level to present a handle for dragging it to reorder the list.

  8. Click the Add Level hyperlink to add a jumpbox to the route. An Add Level popup appears.

  9. Select or type your desired port in the Port list box.

  10. Click the No Secret Selected hyperlink to choose the secret for the new level (server).

  11. Click the Save button.

  12. Hover over any level to present a handle (on the left) for dragging the level to reorder the list.

  13. Hover over any level to present an ellipsis icon (on the right).

  14. Click the icon and choose Edit or Delete to change or remove the level. You can change the port or related secret. Deletion permanently removes the level from the jumpbox route. It is not deactivated as with the route itself.

Assigning a Jumpbox Route to a Secret

  1. Select or create a Unix secret for the route. Ensure that proxying and all other prerequisites described above are met.

  2. Navigate to the secret’s Settings tab and go to the Jumpbox Route section.

    image-20211020105742135

  3. Click the Edit hyperlink. The section becomes editable:

    image-20211020110157588

  4. Click to select the desired jumpbox route from the drop-down. Only active jump server routes to which you have access are visible. You can unassign the jumpbox route by selecting No Jumpbox Route in the dropdown list.

If the jumpbox route becomes deactivated, "Router Network (inactive)" appears in the Jumpbox Route dropdown list. You should select a new one.
You can also assign jumpbox routes though a secret policy. See Creating Secret Policies.

Global Jumpbox Settings

The Admin > Proxying page has these jumpbox settings that impact your jumpbox routes:

  • Tunnel Keep Alive: This setting is to stop intermediaries (such as firewalls or proxies) from deeming your connections inactive and timing them out and closing them. The default is 50 seconds (just shy of a common timeout setting). Adjust this to be just short of your network's timeout setting. Type 0 to disable the setting.

  • Available Port Range: This sets the port range for the SSH proxy endpoint for jumpbox forwarding. Type a range separated by a hyphen, such as 10000-15000. The ports are used for local port forwarding for jumps. You cannot use the ports for other processes, so we recommend using a high range (ports above 10000).