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.

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).


You must also configure your network interface to support inbound
connections.

Establishing the Tunnel With the Spacebridge Client

Download the latest Spacebridge client from our 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:

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-modeto 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 key-pair that you'd
like to use, skip to step 2.

1) Use ssh-keygen to generate a SSH key-pair:  bash ssh-keygen -f spacebridge.key -b 4096You'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 ~APIKEY~ 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.
bash 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.
bash 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.

Did this answer your question?