Hologram provides a service called Spacebridge that allows you to create secure, authenticated tunnels to send data to a device with a Hologram SIM card connected to the cellular network. With Spacebridge, you can send inbound traffic to any port on the device.

    Spacebridge Instructions

    Enabling Tunneling

    Before establishing the Spacebridge tunnel, you must first enable tunneling for your SIM.

    From the Hologram Dashboard’s device list, select the SIM that you wish to tunnel to.

    Enable/disable tunneling toggle

    Select the Cloud and messaging view and scroll down to the Device tunneling section. If tunneling isn’t already enabled, click the Enable tunneling button.

    You may also enable or disable tunneling on multiple devices from the device list page. Select which devices to configure, and select Manage->Enable tunneling (or Disable tunneling).

    Bulk device actions

    Note

    You must also configure your network interface to support inbound connections. Web-based configurations for some USB modems (e.g. E303's HiLink mode) do not support this. Configure the modem using PPP to expose full network functionality.

    Establishing the Tunnel With the Spacebridge Client

    Download the latest Spacebridge client from the Downloads page.

    Extract the downloaded package and run the extracted application. The application will prompt for your API key, which you can find in Account Settings.

    You can then configure the devices and ports you wish to tunnel to. Each row corresponds to a separate tunnel; for basic usage you’ll configure a single row.

    A tunnel forwards all connections from a port on your local computer to a port on the remote device. For example, if you wish to log into the remote device via SSH, you must forward a local port to the remote port 22 (the standard SSH port). To avoid ports already in use by your system’s network services, always use local ports above 1024. In this case we’ll use port 5000:

    Spacebridge tunnel configuration

    Then select Done to start the tunnel. A new dialog box will confirm that the tunnel is open:

    Open an SSH client and connect to port 5000 on localhost (127.0.0.1). It may take a few moments for the routing to get established, so be patient if the initial connection fails.

    Useful Command Line Arguments for Spacebridge Client

    • --text-mode – Display all prompts as text on the command line instead of in a GUI.
    • --apikey – Specify your Hologram API key on the command line.
    • --forward – Specify a forward in the format <linkid>:<device port>:<forwarded local port>. You can specify this option multiple times. Use this in combination with --text-mode to create a fully scripted tunneling setup.
    • --help – Display additional options

    Tunneling Without the Spacebridge Client

    The officially supported Spacebridge client is a convenient wrapper around Hologram API calls and an SSH client. In environments where a GUI application isn’t appropriate, you can use these standard protocols to open a tunnel directly.

    These instructions are for Linux with OpenSSH and assume that you’ve already enabled tunneling for your device in the dashboard (covered in the section above).

    Generate SSH Key and Upload to Hologram API

    You only need to complete this section the first time you’re setting up the tunnel on this computer. If you already have an SSH keypair that you’d like to use, skip to step 2.

    1. Use ssh-keygen to generate a SSH keypair:
      ssh-keygen -f spacebridge.key -b 4096
      
      You’ll see a prompt asking if you want to put a password on the key. We recommend this for enhanced security.
    2. Upload your public key to the Hologram API. In the code below, replace with your Hologram API key (Found on the Dashboard by clicking on the Account menu at the bottom-left and selecting API from the side menu). If you are using a key that you already generated, replace the filename in the export command.

      The filename ends in .pub, not .key. If you use the .key file this will upload your private key which you don’t want to do.

      PUBKEY=$(cat spacebridge.key.pub); curl -X POST -H "Content-Type: application/json" -d "{\"public_key\":\"$PUBKEY\"}" "https://dashboard.hologram.io/api/1/tunnelkeys?apikey=<APIKEY>"
      

      You should get a successful response back.

    Open the Tunnel by Running SSH With Port Forwarding

    1. Look up the link ID for the SIM you are trying to tunnel to. You can find this on the Dashboard by clicking on the plus sign next to the SIM number.
    2. The command below will open up the tunnel. You can see in this command where you would replace the link ID with your own ID. In this case, port 22 is the port on the device, and port 5000 is the local port being forwarded. Replace spacebridge.key with whatever private key you are using. This should be key file that goes with the .pub file that you uploaded to the Hologram API.
      ssh -p 999 -L 5000:link10311:22 -N -i spacebridge.key htunnel@tunnel.hologram.io
      
    3. You should now be able to connect to port 22 on your device from port 5000 on the local host