Page tree
Skip to end of metadata
Go to start of metadata

The Tunneling Client is a standalone program that when running, maintains a network tunnel between the developer machine and the Cloud.

The client is called network-tunnel on the Mac platform, and network-tunnel.exe on Windows.

Once a tunneling client is successfully connected to the Cloud Server, the invoking user (for a specific project, dictated by the Access Key) is considered to be in "Tunneling Mode". In this mode, all on-going device sessions will have tunneled networking, and the device can access network resources located on the developer's private network.

Tunneling is currently available for device sessions only.  Browser sessions will be supported in a future release.

Tunneling can provide access through a proxy server (see the description of command-line flags below).  However, secured communication (SSL) between the client to the proxy server is currently not supported.

System Requirements

The Windows client is compatible with Windows 7 and above (not Windows Vista).

The macOS client is compatible with macOS High Sierra and above.

Downloading the client

Open a session (Manual or Automation) on a device.

Click the "Network Tunnel" Button.

In the dialog that opens, follow the "Download" link.  The client executable will be downloaded to your machine.

01 Download the Tunneling Client

Operating the Client

Start the client in a shell (on Mac) or CMD window (on Windows), with --url and --access-key flags indicating which cloud and which user/project are connecting.

For your convenience, the full command line (using your current credentials on the Cloud you connected to) is displayed in the dialog, and you can simply copy/paste it into your terminal.

03-istpc-started-mac-Screen Shot 2018-09-04 at 11.02.45

Running on macOS

When running on macOS, please note:

  • Before the first run, make sure the downloaded file is executable (eg, run chmod +x network-tunnel)
  • In most shells, to start the client in the local folder, prepend ./ to the command (eg, ./network-tunnel ...)

A connected client is necessary but not sufficient for a tunnel to actually be created.    A session can be tunneled when the device is on a properly configured Agent with a connected Tunneling Server.  If your session is not tunneled, the Network Tunnel dialog may provide further information.  A typical case is when the device is on a WIFI network different from the one configured on the server for tunneling:

04-ssid-incorrect-Screen Shot 2018-09-04 at 11.57.19

For as long as your session is tunneled, the UI will display a tunneling icon on the left of the session window:

The client also provides optional flags to use a web proxy, and to display its own version or help text:

05-istpc-help-Screen Shot 2018-09-04 at 12.27.23

The access key that you provide when connecting a tunneling client identifies you (the user) and the project you are logged into.   If a new client connects with the same key while an old one is connected, the old client will disconnect after emitting an informative message to the console.

When the client is running, it may write diagnostic messages to the log file, located in the same folder from which it was run.  The log file is named per session, with the process ID as part of the file name (eg, network-tunnel_12718.log).

Using the Client with self-signed Certificate

If the Cloud server is configured for Secure mode and is using a self-signed certificate, you may need to add the following 2 arguments to the invocation of the client:

network-tunnel ....(other flags) ... --istp.config-srv-client-verify-cert path-to-cert.pem --tun.client-verify-cert  path-to-cert.pem

Where path-to-cert.pem is the file where your custom certificate can be found.

Using the Client with untrusted Cloud Certificate

In case you use a custom certificate for your cloud server, which is not trusted by the operating system on your Windows/macOS station, the tunneling client

will not connect to the cloud, and you will see a warning similar to this:

The simplest way to resolve this, is to add the flag --no-verify-server-ssl-cert to the tunneling client command line.  This causes the client to trust any certificate.

  • No labels