Soracom Arc

Session Status

With Soracom Air for Cellular connectivity, the modem in your device must first send a request to a cellular network to register to the network and establish a data connection before it can start sending and receiving data. When Soracom receives this request, Soracom takes care of setting up a cellular data session for your device, so that your device can send and receive data.

When using Arc, the data connection is already provided by your device's Wi-Fi, ethernet, or other Internet connection. Accordingly, unlike a cellular connection, there is no need for your device to send a request to Soracom to enable the Arc connection.

Instead, when you create a Virtual SIM, Arc will also automatically start an Active session for the Virtual SIM. This session will remain active throughout the life of the Virtual SIM, and indicates that Arc is ready and waiting for your device's WireGuard client to connect. In this way, your device can freely connect to and disconnect from Soracom by simply enabling or disabling its WireGuard connection, without the need to send any special requests to start or end the session.

Resetting a Session

As the session will remain active even if your device is not connected, your device will resume the same Soracom network configuration each time it reconnects. If you change the network configuration for your Virtual SIM by attaching it to or removing it from a Virtual Private Gateway, or change from one VPG to another, you must reset the session in order for the new network configuration to take effect.

When resetting a session, Arc will continue to use the same client public key currently attached to the Virtual SIM. However, the client IP address, server endpoint, or server public key may change in order to apply a new network configuration if required. If any of these connection details change, you will need to change the configuration on your device accordingly.

To reset an Arc session:

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to manage, then click the Details button.

  3. From the SIM Details dialog, click the Virtual SIM tab.

  4. From the Session status section, click the Reset Virtual SIM session panel, then click Reset Virtual SIM session.

  5. Check if any of the connection details have changed. If any of the details are highlighted, you will need to update the Arc configuration on your device and reconnect.

    If any of the connection details have changed, your device will not be able to communicate with the Soracom platform using the Virtual SIM until the configuration has been updated.

    The steps for updating and reconnecting depend on your connection method:

    Connection Method How to update the Arc configuration and reconnect
    Connecting using Soratun Update the Soratun configuration file (e.g. /path/to/arc.json) or perform bootstrapping again, then reconnect using Soratun
    Other WireGuard client Update the WireGuard configuration file (e.g. /etc/wireguard/wg0.conf), then reconnect using your WireGuard client

    If you bootstrapped with Soratun, you can also update the Arc configuration and reconnect with the same bootstrap procedure as before. Refer to the following for further information.

Re-initializing a Virtual SIM

If you experience difficulty connecting to Soracom using the Arc connection, you can re-initialize your Virtual SIM to troubleshoot WireGuard connectivity issues. In addition to resetting a session, re-initializing the Virtual SIM will also reset the Arc server connection.

To re-initialize a Virtual SIM:

  1. Login to the User Console. From the Menu, open the SIM Management screen.

  2. From the list of subscribers, click the for the SIM you want to manage, then click the Details button.

  3. From the SIM Details dialog, click the Virtual SIM tab.

  4. From the Advanced section, click the Re-initialize Virtual SIM panel, then click Re-initialize Virtual SIM.

  5. Once the Virtual SIM has been re-initialized, connection details will be displayed. Update the Arc configuration on your device and reconnect.

    Your device will not be able to communicate with the Soracom platform using the Virtual SIM until the configuration has been updated.

    The steps for updating and reconnecting depend on your connection method:

    Connection Method How to update the Arc configuration and reconnect
    Connecting using Soratun Update the Soratun configuration file (e.g. /path/to/arc.json) or perform bootstrapping again, then reconnect using Soratun
    Other WireGuard client Update the WireGuard configuration file (e.g. /etc/wireguard/wg0.conf), then reconnect using your WireGuard client

    If you bootstrapped with Soratun, you can also update the Arc configuration and reconnect with the same bootstrap procedure as before. Refer to the following for further information.

Programmatic Usage

In addition to resetting a session or re-initializing a Virtual SIM from the User Console, you can also perform the same actions programmatically using the Soracom API or CLI.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the deleteSubscriberSession API to reset an Arc session:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/subscribers/<IMSI>/delete_session

Once the session has been deleted, Arc will automatically start a new session.

You can also use the deleteSimSession API, however when using this with a Subscription Container Virtual SIM, any cellular session will also be deleted. If your device has an active cellular connection, it will need to reconnect.

To re-initialize a Virtual SIM, use the createArcSession API:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  https://g.api.soracom.io/v1/sims/<SIM-ID>/sessions/arc

Soracom CLI

To use the Soracom CLI, you must first configure it to authenticate with your account information, authorization key, or SAM user credentials.

Then, run the following command to reset an Arc session:

soracom subscribers delete-session --imsi "<IMSI>" --coverage-type g

Similar to the API example above, once the session has been deleted, Arc will automatically start a new session.

You can also use the soracom sims delete-session command, however when using this with a Subscription Container Virtual SIM, any cellular session will also be deleted. If your device has an active cellular connection, it will need to reconnect.

You can also run the following command to re-initialize a Virtual SIM:

soracom sims create-arc-session --sim-id "<SIM-ID>" --coverage-type g