Register an SSH Service for a Collection of SSH Servers

  • Updated on Apr 19, 2023

This article describes features that are only available in the Banyan Enterprise edition and Banyan Unlimited edition.


Though Banyan allows security policies to be applied at the granularity of a single SSH Server, organizations often manage multiple SSH servers, sometimes thousands, at a time. While some SSH servers require a unique set of access restrictions, many of them require identical access restrictions. Rather than configure each SSH server individually, you can group them and configure via a single service definition.

Banyan uses standards-compliant HTTP Connect Tunneling to enable connectivity to multiple services via a single SSH service definition.

In the Banyan desktop app, the end user selects Connect, which adds an entry to the SSH config file with an SSH ProxyCommand to direct traffic to banyanproxy.

  1. When the user runs ssh user@host, traffic is automatically sent by the SSH client to banyanproxy running in HTTP Connect mode.

  2. banyanproxy initiates an MTLS connection with the Banyan service on the Netagent side at Netagent checks the device posture and identity and, if successful, establishes the MTLS session. banyanproxy then uses HTTP Connect to specify the actual destination of the SSH request.

  3. Netagent checks the Service Backend configurations for the httpconnect and allow_pattern settings. If the connection request matches, Netagent makes the connection to the backend.

Once the connection is established, communication from the SSH client is as if it were directly connected to SSH server.


  • A registered Access Tier or Connector, behind which your SSH server exists
  • A registered domain that resolves to this Access Tier


In this doc, we lay out how to secure access to a collection of SSH servers, using the following steps:

Step 1: Create a Role and a Policy
Step 2. Register a Service
Step 3. Connect to the service through Banyan’s desktop app

1.1 Follow the steps to create a Role and a Policy, as outlined here.

2.1 Navigate from Manage Services > Infrastructure, and then select + Register Service. Select the option SSH Service.

2.2 Under Service Details, enter a Service Name. Optionally, enter a Description and a Link.

2.3 Select a Cluster. Ensure that you select the Cluster (a logical grouping of Access Tiers, managed together) that contains the Access Tier or the Connector your SSH server sits behind.

2.4 Optional: Display the Service in the Banyan app by toggling on Show Service in Service Catalog within the Banyan App. This means that end users will be able to view the service in the Banyan desktop app.

2.5 Optional: Toggle on Autorun if you want your SHH service to automatically connect when end users in your org log into their Banyan desktop app.

Note: Autorun settings are only evaluated during device registration. End users can manually adjust Autorun settings from their desktop app after registration, and these changes will not be reflected in the Command Center UI.

2.6 Under Service Attributes, select an Access Tier. Ensure that this is the Access Tier that your SSH server sits behind.

2.7 Assign a Service Domain Name for this service. Optionally, leave the port as 8443.

Note: the Service Domain Name must be a registered domain or a sub-domain of a registered domain that contains a wildcard (e.g.,, which is a sub-domain of *

2.8 To secure access to an collection of SSH servers, select Client specifies using HTTP Connect.

2.9 Specify which Hostnames and CIDR ranges this SSH service is allowed to connect to.

2.10 Optional: enter a Backend DNS Override.

2.11 Optional: In the SSH Desktop App Settings section, enter an SSH Host Directive. This is a short-cut name that can be used in SSH commands.

2.12 Select Only use the TrustCert (Banyan’s Trust certificate) or select Use both the TrustCert and the SSHCert, if your SSH server already requires certificate authentication.

2.13 Select whether the desktop app should update the SSH config file on the device.

Admins should select Yes, unless they prefer to update the SSH config file themselves. Note that independent management of the SSH config file may create difficulty in using the Banyan desktop app, which is configured to update the SSH config file. Contact Banyan for further support.

2.14 Optional: Attach the policy created in Step 2, and then choose an Enforcement Mode (i.e., Permissive or Enforcing).

3.1 Ensure your end users install the latest Banyan desktop app and register their device.

3.2 Once the service is registered (i.e., Step 3 is completed), your end users will see it in their Banyan desktop app. End users must then select Connect, and the desktop app will add an entry to the SSH config file (typically located in ~/.ssh/config).

Note: If Autorun was enabled (by the admin) during service registration, then end users will not have to manually connect; they will automatically connect when they log into the desktop app.

3.3 End users can now access any SSH server in the collection based on the SSH Hostname or IP address of the specific server you want to connect to, using the following command:

ssh username@hostdirective -o ""


ssh username@hostdirective -o ""

Enter the specific host name (or IP address) that you want to reach in the suffix of the command.

The SSH client will use banyanproxy to automatically tunnel the SSH session over a Mutual-Auth TLS channel using HTTP Connect Tunneling.


Role-based Authorization

To enable role-based authorization for your SSH servers, review our SSH Certificate Authentication capability, which leverages SSH’s native AuthorizedPrincipals capability.

Include & Exclude Backends in your Collection

Advanced Use Cases with Complex Patterns

For advanced use cases that require complex patterns, you can create a custom Hosted Service JSON to specify CIDRs and IP Ranges in an “allow list” in the service spec. This lets you manage allow lists that include and exclude specific backends in your collection.

For example, you can define the pattern for the allowed backends using hostnames (via allow_patterns). In the example below, connections are allowed only the service destination is in the CIDR range

"backend": {
  "target": {},
  "allow_patterns": [
      "cidrs": [

Can’t find what you’re looking for?

We’re happy to help. Contact our team .