Port Bridge

UNIFY Port Bridge is a point-to-point tunneling utility that allows mapping TCP listener ports and named pipes from some machine on network A to UNIFY’s cloud servers, and make it appear as if the listener were local to the cloud servers.

UNIFY Port Bridge is similar to what can generally be achieved via SSH tunneling, but transmits traffic over a relay so that both parties can reside safely behind Firewalls, leverage the Service Bus authorization integration, and have all communication run over the Firewall-friendly WebSocket protocol.

How it works

UNIFY Port Bridge consists of two components, the “Port Bridge Service” and the “Port Bridge Agent”.

The Agent listens for and accepts TCP or Named Pipe connections on a configurable port or local pipe name. The Service accepts incoming connections from the Agent, establishes a connection with the Agent, using a Service Bus to transmit TCP traffic. The Agent initiates contact with the service bus relay, meaning there is no changes required to your firewalls.

To increase the responsiveness and throughput for protocols that are happy to kill and reestablish connections frequently such as HTTP, “Port Bridge” always multiplexes concurrent socket connections between two parties over the same relayed connection.

When using Port Bridge to bridge to a remote HTTP proxy that the Service machine can see, but the Agent machine cannot see, there are very many and very short-lived connections tunneled through the channel. Creating a new Hybrid Connection channel for each of these connections is feasible – but not very efficient.

How do I use it?

UNIFY will work with you to determine a base configuration that is required for our Cloud Services to operate. This is likely to be a single port mapping to either your Active Directory or HR system.

You will need to install the UNIFY Port Bridge Service on one of your services, and will be in complete control of which ports maps to which services on your end.

The service is a single executable file. It is installed as a Windows service using the installutil.exe command in Windows.

The file will be shared with you, along with the configuration once we are ready to connect.

Service

The Service is your side of the connection.

The Service’s executable file is Unify.PortBridge.Server.exe and is both a console app and a Windows Service. If the Windows Service isn’t registered, the app will always start as a console app. If the Windows Service is registered, you can force console-mode with the -c command line option. See the Service Install Instructions for more details on configuring the executable as a service.

The server.config.json file on the Service specifies what ports or named pipes you want to project into Service Bus:

{
  "PortBridge": {
    "ServiceBusNamespace": "**.servicebus.windows.net",
    "ServiceBusAccessRuleName": "*****",
    "ServiceBusAccessRuleKey": "*****",
    "HostMappings": [
      {
        "targetHost": "****",
        "allowedPorts": "33392",
        "tcpHost": "127.0.0.1"
      }
    ]
  }
}

The serviceBusNamespace attribute takes the Service Bus namespace name you will be provided, and the serviceBusAccessRuleName and serviceBusAccessRuleKey attributes are set to the SAS rules we set up specific to your solution.

The hostMappings section contains a list of hosts and rules for what you want to project out to Service Bus. Each added entry can have the following attributes:

• targetHost (required): The targetHost value identifies the host to which the connection shall be forwarded. This name must be resolvable on the network on which the server agent runs.
• allowedPorts : This value defines which ports may be accessed on the target host through this bridge. The permitted values are a list of command separated numbers. The value ‘*’ permits use of all ports.

Agent

The Agent is our side of the service. This information is only supplied so you can see how we operate our side of the connection.

The server.config file on the Agent side specifies which ports or pipes you want to project into the Agent machine and whether and how you want to firewall these ports. The firewall rules here are not interacting with your local firewall. This is an additional layer of protection.

The ports mapped in the Agent configuration only work if they are also preconfigured on the Server. This prevents the Agent from accessing ports are not required for the solution.

  <portBridgeAgent serviceBusNamespace="mynamespace.servicebus.windows.net" 
                   serviceBusAccessRuleName="RootManageSharedAccessKey" 
                   serviceBusAccessRuleKey="xxxxxxxx">
    <portMappings>
      <port localTcpPort="13389" targetHost="mybox" remoteTcpPort="3389">
        <firewallRules>
          <rule source="127.0.0.1" />
          <rule sourceRangeBegin="10.0.0.0" sourceRangeEnd="10.255.255.255" />
        </firewallRules>
      </port>
    </portMappings>
  </portBridgeAgent>

Again, the serviceBusNamespace attribute takes our Service Bus namespace name, and serviceBusAccessRuleName plus serviceBusAccessRuleKey the SAS rule information.

The portMappings collection holds the individual ports or pipes you want to bring onto the local machine.

The firewallRules collection allows (un-)constraining the TCP clients that may connect to the projected port. By default, only connections from the same machine are permitted.

For named pipes, the configuration is similar, even though there are no firewall rules and named pipes are always constrained to local connectivity by a set of ACLs that are applied to the pipe. Pipe names must be relative. Here’s how a named pipe projection of a default SQL Server instance could look like:

     <port localPipe="sql/remote" targetHost="mymachine" remotePipe="sql/query"/>

Can I install it as a service?

Your side of the connection (Unify.PortBridge.Server.exe) can be installed as a Windows Service to run as per your requirements.

The service must be registered with the service name as PortBridgeService to execute correctly. The following two commands can be used to register the service on your machine, depending on whether you prefer command line or PowerShell. These commands will need to be run with administrator privileges to successfully register the service.

Console

     sc create PortBridgeService BinPath=C:\Path\To\Unify.PortBridge.Server.exe displayname=Unify.PortBridge

PowerShell

     New-Service -Name "PortBridgeService" -BinaryPathName "C:\Path\To\Unify.PortBridge.Server.exe" -DisplayName "Unify.PortBridge"

This will create a service with the Service Name of PortBridgeService and a display name of Unify.PortBridge for visibility. You can tweak these commands to your liking (adding service account authentication or startup type), as long as the Service Name of PortBridgeService stays the same.

As mentioned in the Service section, if you have installed the service and subsequently wish to use the command line to run the executable, you will have to pass the -c command line flag to force console mode. Without a service install, the command line runner will default to console mode if it can’t locate the service. However since the same executable is used for both console and service execution, the command line flag is required to use the console after the service is installed.

More questions?

Let us know; we’re always happy to answer any questions you may have.