Guide for configuring SmartBridge connection parameters.


Overview


Net LineDancer supports two modes for the connection of SmartBridges to the core server: Bridge-to-Server and Server-to-Bridge.  All connections are via HTTPS, so wire traffic is encrypted end-to-end.


Bridge-to-Server

This is the new default connection mode.  In this mode, the SmartBridge will initiate contact with the core server; the core server will never initiate connections to the SmartBridge.  The SmartBridge is commonly running in a remote network, sometimes over public infrastructure, and often behind a firewall.  Corporate security groups are hesitant to open holes in the corporate firewall for in-bound connections, and rightfully so.

The Bridge-to-Server connection mode removes the necessity for the creation of a hole in the firewall in the SmartBridge network, as long as the firewall allows egress (out-bound) HTTPS traffic.  There is no involvement by firewall administrators required.

The following diagram shows various scenarios in which firewalls are present in one network, in both networks, or not present.



Server-to-Bridge

This connection mode is primarily useful for internal networks (LAN/WAN) in which there are no intervening firewalls between the core server and the SmartBridge.  In this mode, the core server will initiate contact with the SmartBridge; the SmartBridge will never initiate connections to the core server.

If the there is a firewall between the SmartBridge and the core server, then a hole must be punched in the firewall to allow ingress (in-bound) HTTPS connection initiation from the core server.

The following diagram shows various scenarios in which firewalls are present in one network, in both networks, or not present.


Connection Token

Net LineDancer v16 introduces the concept if a connection token.  A unique token is generated for a SmartBridge at the time that the SmartBridge is first configured on the core server.

If a SmartBridge is configured to use Bridge-to-Server mode, then the core server will not accept an in-bound connection from a SmartBridge unless it first presents its unique token.  This prevents random or malicious connections to the core server.

Similarly, if a SmartBridge is configured to use Server-to-Bridge mode, then the SmartBridge server will not accept an in-bound connection from the core server unless it first presents the bridge's unique token.  This prevents random or malicious connections to the SmartBridge.


SmartBridge Installation

Before installing a SmartBridge you must decide which of the connection modes will be employed, Bridge-to-Server or Server-to-Bridge.  The connection mode can be changed later, without the need to reinstall the SmartBridge, if you change your mind.

Before you install the SmartBridge, you should first obtain the Connection Token by provisioning the SmartBridge on the core server.  If you wish to install one or more SmartBridges before you know which connection mode will be used, skip to the SmartBridge Pre-Provisioning section below.

Bridge-to-Server

Step 1: Provision the SmartBridge
Login to the core server as an Administrator role user, and click on the Settings item at the top right of the window.  Select the Smart Bridges category on the left-hand side of the settings dialog.  Then click on the plus ➕ button to add a new Smart Bridge.


Enter the name for the bridge, then click the OK button.

Step 2: Obtain the Connection Token
The new Smart Bridge will appear in the table, and below the table you will find the Connection Token needed during the Smart Bridge installation, as shown here:



You can click on the little clipboard-with-arrow icon next to the token to copy the token value to the clipboard.

Step 3: Install the Smart Bridge
Execute the SmartBridge installer, and when you are prompted to choose the direction of connection initiation, choose the default (bridge ➔ server).  Enter the hostname or IP address of the remote core server, the listening port of the remote core server (default 443), and finally paste the Connection Token obtained during the provisioning process.
Linux Example:

Server-to-Bridge

Step 1: Provision the SmartBridge

Login to the core server as an Administrator role user, and click on the Settings item at the top right of the window.  Select the Smart Bridges category on the left-hand side of the settings dialog.  Then click on the plus ➕ button to add a new Smart Bridge.


Enter the name for the bridge, choose Server Bridge from the Connection drop-down, enter the hostname or IP address of the remote SmartBridge server, and the listen port (default 443), then press the OK button.

Step 2: Obtain the Connection Token

The new Smart Bridge will appear in the table, and below the table you will find the Connection Token needed during the Smart Bridge installation, as shown here:


You can click on the little clipboard-with-arrow icon next to the token to copy the token value to the clipboard.





Step 3: Install the Smart Bridge



Execute the SmartBridge installer, and when you are prompted to choose the direction of connection initiation, choose Server ➔ Bridge.   Enter the port that the SmartBridge should listen on for incoming connections (default 443), and finally paste the Connection Token obtained during the provisioning process.

Linux Example:

SmartBridge Pre-Provisioning

If you wish to pre-install a SmartBridge before you have provisioned it on the core server, etc. you can choose any connection mode, and enter any 32-character value for the token.  This will be changed later, when the SmartBridge is provisioned on the core server. 

If you plan to use bridge-initiated connection, you can specify an IP address from the self-assigned range (169.254.0.0/16) as the remote core server address (if the actual core server IP address has not be determined yet).

Finally, once the SmartBridge is provisioned on the core server, and the Connection Token obtained, follow the directions below for altering the SmartBridge connection information.


Modifying SmartBridge Connection Configuration

The SmartBridge connection information can be modified after installation at any time using the commands below.  Note that if you change the direction of connection initiation on the SmartBridge, you also need to make a similar change on the core server through the Settings dialog.

Execute these commands in the SmartBridge installation directory (/usr/share/netld on Linux), as Administrator on Windows or root on Linux.

Changing to Bridge ➔ Server mode:

Linux:

  ./dbutil prefset "netld.bridge:server.host" <core-server-host>

  ./dbutil prefset "netld.bridge:token" <connection-token>

  ./dbutil prefreset "org.ziptie.zap.web:web.start"

         After that, restart the bridge service.

 


Windows:

  perl dbutil prefset "netld.bridge:server.host" <core-server-host>

  perl dbutil prefset "netld.bridge:token" <connection-token>

  perl dbutil prefreset "org.ziptie.zap.web:web.start"

After that, restart the bridge service.


Optional (changing default port from HTTPS (443) to other):

  ./dbutil prefset "netld.bridge:server.port" <core-server-port>


            

i.e. 

  perl dbutil prefset "netld.bridge:server.host" 192.168.30.74

  perl dbutil prefset "netld.bridge:token" abcde12345

  perl dbutil prefreset "org.ziptie.zap.web:web.start"


Changing to Server ➔ Bridge mode:


Linux:

  ./dbutil prefreset "netld.bridge:server.host"

  ./dbutil prefset "org.ziptie.zap.web:web.start" "true"

  ./dbutil prefset "netld.bridge:token" <connection-token>

After that, restart the bridge service.


Windows:

  perl dbutil prefreset "netld.bridge:server.host"

  perl dbutil prefset "netld.bridge:token" <connection-token>

  perl dbutil prefset "org.ziptie.zap.web:web.start" "true"

 After that, restart the bridge service.



Optional (changing default port from HTTPS (443) to other):

  ./dbutil prefset "netld.bridge:server.port" <core-server-port>