Secure Tunnel

Last modified on September 02, 2021

Why tunnels?

Tunnels are helpful when you need to test a mobile application that is a client for some web service. When a team are developing such an application, they often host the interim work-in-progress server versions in the local environments. Typically, these environments are restricted from the global network to prevent unwanted external access. For this reason, the tested app running on a mobile device in the BitBar farms need a secure connection to local resources — a tunnel.

How does it work?

To set up a tunnel, use the lightweight SecureTunnel utility that you can download from the BitBar website.

Run the utility on a computer with access to both the global Web and the tested web service. The test device working in the BitBar farm connects to your local resources through this tunnel:

How SmartBear Tunnel works

The entire procedure of setting up and using a tunnel includes the following steps:

  1. Install the SecureTunnel app on your computer (needed only once).

  2. Start the tunnel.

  3. Run your tests.

  4. Close the tunnel.

For details, see information below.

SecureTunnel utility

  • The SecureTunnel utility is available in form of a desktop application and a command-line utility for Windows, Linux, and Mac OS operating systems.

    You can download both forms from the BitBar website.

    Utility form Can be used on
    Desktop app Windows, Mac OS
    Command-line package Windows, Linux, Mac OS

    The desktop app is a wrapper on the command-line functionality. It provides a visual interface to the tunnel settings. The command-line utility is helpful when you need to automate the tunnel start and stop.

  • The utility works with HTTP and HTTPS traffic.

  • It connects to the geo.tunnel.smartbear.com server through the port 443.

    Proxies and firewalls running in your network should allow connection to these URL and port.

  • The utility is resource friendly. It doesn’t have any specific requirements and can run on almost any machine, even on a “weak” one.

1. Install the tunnel app

Option 1 — Desktop app

  1. Log in to BitBar and click Secure Tunnel in the toolbar.

  2. In the subsequent dialog box, click the link on the Desktop tab page to download the SecureTunnel desktop installer:

    Download the desktop Tunnel application

    Click the image to enlarge it.

    Note: BitBar automatically provides the package that matches your operating system: Windows or MacOS.

That’s all. You can now run the downloaded file.

Option 2 — Command-line utility

  1. Log in to BitBar and click Secure Tunnel in the toolbar.

  2. In the subsequent dialog box, switch to the Command Line tab and click the link to download the Secure Tunnel executable (SBSecureTunnel.exe):

    Download the command-line Tunnel application

    Click the image to enlarge it.

    Note: BitBar automatically provides the package that matches your operating system: Windows, Linux, or MacOS.

That’s all. You can run the downloaded executable as it is. Depending on the security settings, the operating system may ask your permission to run it. Grant the permission.

2. Start the tunnel

You can start the tunnel from the BitBar website or your computer (see information below). Either way works fine. Select the mode that suits your needs best.

Go to the BitBar website:

  1. On the BitBar website, click Secure Tunnel at the top.

  2. On the Desktop App tab, select the connection type and options (see information below) and then click Connect:

    Start the tunnel from the website

    Click the image to enlarge it.

  3. The browser will ask you for permission to run the SecureTunnel app installed on your computer. Grant the permission.

From your computer

Option 1 — Desktop app
  1. Run the downloaded SecureTunnel application.

  2. Type in your BitBar account and specify the API key, then click Login:

    Starting the SecureTunnel desktop app
  3. Specify the connection type and options (see information below), then click Connect:

    The SecureTunnel desktop app - Settings screen
Options 2 — Command-line utility

To run the SBSecureTunnel executable, use a command line like this:

SBSecureTunnel.exe --username "john.smith@example.com" --authkey aaabbbXXXXXNNNNccc

Here, username is your BitBar account, and authkey is your authentication key (also called API key). For detailed information on supported command-line parameters, see SecureTunnel Command Line.

You can get the needed command line at any time on the BitBar website: open the Secure Tunnel dialog box and select the needed options on the Command Line tab. The dialog will update the sample command line respectively:

Configure command line

Click the image to enlarge it.

3. Run your tests

After the tunnel is up and running, you can create or run your tests as you regularly do. For details, see the following links:

Important notes:

  • If you need to refer to a resource on your computer, use local or 127.0.0.1 in the URL rather than localhost. The reason for this is that some test devices don’t recognize localhost.

  • It’s important to check if the tunnel is on before you start testing. For details on how to preoseed, see information below.

4. Close the tunnel

Regardless of the way you started the tunnel, you can close it on the BitBar website: open the Secure Tunnel dialog box and click Disconnect.

Close the tunnel

Click the image to enlarge it.

You can also close the tunnel from the command line by using the --kill parameter. See SecureTunnel Command Line.

Tunnel settings

The SmartBear Secure Tunnel supports the following connection types:

Internal Websites

Most basic type of tunnel that works in most cases. It creates an encrypted tunnel that allows traffic and requests to be routed through the local network of your computer. This allows you to test sites that are only accessible through your local network or behind your firewall.

Proxy Server

Select this mode if the tested local server is behind a “non-transparent” proxy on your side. This mode is useful for corporate environments that require proxies for HTTP/HTTPS traffic.

If you select this mode, you will need to specify the following settings:

Proxy IP

The IP address of the proxy server in your network.

Proxy Port

The proxy port number.

Local HTML files

Currently, BitBar doesn’t use them. You can see it in the SecureTunnel desktop app or the command-line utility. These are shared applications with other SmartBear products.

Additional options include:

Bypass tunnel for public URLs

When the tunnel is up and running, it routes requests from the test device to the tested server app. Select this check box if you want to skip using the tunnel for requests that the tested client app sends to publicly available websites. This will generally speed up tests since many applications call publicly available resources.

If the tunnel is unable to resolve a URL publicly, it resolves it through the user computer.

Accept all SSL certificates

Select this check box so that the tunnel considers all security certificates as valid. This is useful for testing interim versions of websites and services which may have self-signed or invalid certificates.

Tips

Check the tunnel status

It’s important the tunnel is on before you create or run your tests. You can check the tunnel status at any time on the BitBar website. Regardless of the way you started the tunnel, the following label on the toolbar will be “On” if the tunnel is up and running. If the tunnel is inactive, the label is “Off”:

Check tunnel status

Click the image to enlarge it.

How to get the API key

  1. Log in to BitBar, click the user icon in the top-right corner, and select My Account.

  2. Go to [My Integrations] API Access > API tab and copy the API key value:

    Get the API key

    Click the image to enlarge it.

Logging the tunnel work

By default, the tunnel posts message about its work to the <your user folder>/.sb-tunnel/tunnel.log file.

If you start the tunnel from the command line, you can add the --verbose command-line argument to log messages to the command-line window.

Notes

  • For the SecureTunnel utility to be able to function properly, the proxies and firewalls working in your local network should allow connection to geo.tunnel.smartbear.com on port 443.

  • It’s important for you to start the tunnel before /?>running or creating your tests.

  • A new tunnel you start with your credentials closes other tunnels you started earlier.

  • Since the tunnel is working on your computer, all DNS resolutions occur on your machine (its hosts file is used).

  • For information on using the tunnels in automated tests, see Using Tunnels in Automated Tests.

See Also

SecureTunnel Command Line
Using Tunnels in Automated Tests

Highlight search results