Soratun Tool

When using Soracom Arc to connect to the Soracom platform, the configuration and connection process involves the following steps:

Creating a Virtual SIM and receiving WireGuard configuration details
Configuring a WireGuard connection on the device
Activating the WireGuard connection on the device

While the first step can easily be done directly on the Soracom User Console or through the Soracom API or CLI, there may be situations where you want a device to create its own Virtual SIM during a part of the device's initialization process.

soratun (sora-com tun-nel) is a command line tool that helps you create Virtual SIMs and connect to Soracom.

In addition to providing several bootstrapping methods for creating Virtual SIMs directly from a device, Soratun also includes a WireGuard client implementation that allows you to configure and activate a WireGuard connection to Soracom, without the need to install WireGuard separately.

While Soratun helps streamline the configuration and connection process, using Soratun to connect to Soracom is not mandatory.

Functionality

Soratun provides the following functions:

Virtual SIM bootstrapping (see Bootstrapping Methods below)
WireGuard connection configuration and activation
OS network routing configuration
Periodic reporting of WireGuard connection status to systemd
Configurable logging

For more information on configuration parameters, refer to the Command Reference documentation.

Comparison

Depending on your requirements, you may prefer to use a different WireGuard client implementation. Here is a basic overview of the major differences between Soratun and the WireGuard implementation provided in the Linux kernel:

	Soratun	WireGuard
Performance	User process (comparatively slow)	Kernel space (fast)
Stability	Uses the official wireguard-go library, however the kernel implementation is considered to have better test coverage	Highly stable
Security	Uses the official wireguard-go library and is considered to be as secure as the kernel implementation	Highly secure
Installation	Install by copying a binary file to the device	Install through OS package manager
Virtual SIM Bootstrapping	Supported	Not Supported

If you prefer to use the kernel implementation of WireGuard, you can still create a Virtual SIM separate from the device through the Soracom User Console, or with the Soracom API or CLI. Alternatively, you can use Soratun simply to bootstrap the device, and then use the WireGuard configuration details directly with the kernel implementation of WireGuard.

Bootstrapping Methods

Bootstrapping is the process of creating a new Virtual SIM directly from the device that will use the Virtual SIM when connecting to Soracom. Soratun supports three bootstrapping methods based on different authentication types:

AuthKey authentication - Creates a Standalone Virtual SIM directly from a device, without the need to use an actual Soracom Air for Cellular SIM or for the device to have a cellular network interface. This method will use Soracom API authentication to authorize the Virtual SIM creation request. Therefore, a Soracom API AuthKey must be stored on the device, and you will need to implement a method to securely install the AuthKey on your devices.

Because an AuthKey will be stored on the device, there is a risk that an unauthorized individual that gains access to your device may be able to retrieve the key and subsequently create additional Virtual SIMs without permission.
Cellular authentication - Creates a Subscription Container Virtual SIM directly from a device using a Soracom Air cellular connection, and automatically associates the Virtual SIM with the IoT SIM. This method uses the Soracom Air cellular connection to authorize the Virtual SIM creation request and identify which IoT SIM the Virtual SIM should be associated with, and does not require any additional credentials to be stored on the device. However, the device must be configured with a cellular network connection beforehand.
SIM authentication - Creates a Subscription Container Virtual SIM directly from a device using SIM authentication, and automatically associates the Virtual SIM with the IoT SIM. This method uses SIM authentication credentials stored inside a plan01s, plan01s - LDV, plan-NA1, plan-US, planX3, or planX3-EU IoT SIM to authorize the Virtual SIM creation request and identify which IoT SIM the Virtual SIM should be associated with, and does not require any additional credentials to be stored on the device. Additionally, this method does not require the device to be configured with a cellular network connection beforehand, however you must use a compatible modem or SIM card reader that allows the device to read the SIM contents.

Bootstrap Method	Virtual SIM Type	Requirements	Tested Platforms
AuthKey authentication	Standalone	SAM User with AuthKey Internet connection	Linux, macOS
Cellular authentication	Subscription Container	Soracom Air for Cellular SIM (any) Soracom Krypton enabled Modem and cellular connection	Linux, macOS
SIM authentication	Subscription Container	Soracom Air plan01s, plan01s - LDV, plan-NA1, plan-US, planX3, or planX3-EU SIM Soracom Krypton enabled with Krypton CLI installed Compatible modem or SIM reader Internet connection	Linux

Supported Platforms

The following devices and platforms are supported:

Linux amd64
- Ubuntu 20.04.2 LTS
Linux arm (Raspberry Pi 32-bit)
- Raspberry Pi OS 2021-05-07
- Ubuntu 20.04.2 LTS

Soratun can also be used on the following platforms for testing and development, however support is not provided:

macOS Big Sur or later