Using the HS Tunnel Tool

Overview

The HeadSpin tunnel tool allows network traffic to be routed from remote HeadSpin devices through your local network. This tool can also make intranet services and other local network resources available to your HeadSpin devices. Frequent scenarios in which users utilize the tunnel tool include testing intranet resources with an application, testing a non-public version of an app, or setting up ad-hoc regional routing to test a device within your network location.

Usage and Information

The main command for this tool is <code class="dcode">hs tunnel</code>, used via the HeadSpin CLI. Note that for best experience you’ll need to download the latest version of the CLI, which can be done from the User Settings page under ‘Downloads’.

This tool is intended for use with sessions capturing network data; in order to use the tunnel tool, you must start capture with network. Also note that this feature is tied to the tunnel_feature org permission; please check with your HeadSpin administrator to confirm your org permissions are correctly configured. For information on network configuration outside of a capture session, see our documentation on network shaping here.

The tunnel tool allows multiple upstream routes to be configured for both raw traffic and DNS resolution using the <code class="dcode">--proxy</code> and <code class="dcode">--dns</code> options respectively. These routes are chosen based on rules evaluated on the traffic or DNS query using the <code class="dcode">--proxy-rule</code> and <code class="dcode">--dns-rule</code> options respectively. Additionally, the <code class="dcode">--scope</code> option makes it possible to limit or expand access to your user, team or entire organization (default: <code class="dcode">user</code>). For more information on the <code class="dcode">hs tunnel</code> options can be found here under the hs tunnel [OPTIONS] section.

Your <code class="dcode">hs tunnel</code> routes, if properly configured, will be used automatically during network capture in descending order of preference: user-scoped tunnels, team-scoped tunnels, and org-scoped tunnels. (In other words, tunnels configured for use with a specific user will be given higher priority of usage for said user over tunnels configured for a team of users or an entire org.) Multiple tunnels may coexist at the same time to serve different portions of a network or for redundancy. Tunnels can be set up for teams or orgs so that individual customers within an org’s access can use the tunnel without configuring it themselves; this can be done using the -scope flag. You can learn more about this and other flags in the options documentation link provided above.

Some limitations currently apply to the tunnel tool. Specifically, there is only limited compatibility with browsers; while network traffic itself will be routed through a configured tunnel, DNS requests are now, so testing networking services via <code class="dcode">hs tunnel</code> on browsers can only be done with public DNS. Additionally, as with many networking configurations, if your network environment is using a proxy or a firewall, you may need to perform additional steps to ensure the tunnel tool works correctly within the security parameters of your network.

Steps for Usage

1. To use the tunnel tool, first make sure you have downloaded the CLI. (This is how you will execute commands.)

2. Next, select a device from your org’s device list and start a session on that device. Once your remote control session has begun, click the ‘Tools’ icon in the right-hand sidebar. Scroll down to the Local Environment Tunnel box in the tools page of the Remote Control window.

3. In the upper-right corner of the Remote Control window, click the second icon from the left that looks like a camera. A dropdown menu will appear with two options for recording your session. Select 'With Network'. This will activate your session's network capture, which is necessary for the tunnel tool to work. If you do not see an option for 'With Network', work with your org administrators and HeadSpin administrators to confirm your org's permissions are correct.

4. You can modify your tunnel’s configuration by setting options using the dropdown selections in the Local Environment Tunnel box of the UI or you can use API commands.

5. Check your device’s IP address, as well as your local machine’s address. This information will help you confirm when your tunnel’s configuration applies. You can check your IP address using online tools such as whatismyipaddress.com.

6. Copy and paste the hs tunnel command from the Local Environment Tunnel box into your CLI and run the command. When you check your device’s IP address, it should match your local machine’s IP instead of the IP of the device’s geographic location.