Bootstrap using SIM Authentication

When bootstrapping, a Virtual SIM will be created which will incur an initial fee. In addition, the Virtual SIM will incur a monthly service fee until the Virtual SIM is terminated. Refer to the Pricing & Fee Schedule for more information.

When bootstrapping with SIM authentication, Soratun will use the Soracom Krypton Client to access authentication information embedded in a Soracom Air SIM card to authorize a request from the device to create a Virtual SIM.

You can use this method to streamline the process of creating a Virtual SIM by performing the following bootstrap steps when your device is initialized, without having to create Virtual SIMs one by one and using a separate process to install Soratun configuration files on each device.

This method will create a Subscription Container Virtual SIM which will be attached to the Air SIM.

Because authorization is provided through the SIM authentication credentials embedded in an Air SIM, there is no need to store additional credentials on your device.

Prerequisites

Your device should have:


Enabling Soracom Krypton

In addition to Virtual SIM initial and monthly fees, enabling Krypton in order to use the cellular bootstrapping method will incur Krypton fees. Refer to the Pricing & Fee Schedule for more information.

  1. Refer to the Groups: Basic Usage documentation to create a new Group.

  2. Once you have created a group, click the name of the group. From the Basic Settings tab, click the SORACOM Air for Cellular panel to expand its settings. Then enable the Metadata Service by switching the option to ON, and click the Save button.

  3. Next, click the SORACOM Krypton panel to expand its settings. Then enable Krypton by switching the option to ON, and click the Save button.

  4. Last, refer to the Groups: Basic Usage documentation to add your Air SIM to the group.

Installing Krypton Client

  1. Install the following dependencies to your device, and then reboot your device:

    sudo apt install -y libpcsclite-dev pcscd libpcsclite1 && sudo reboot
  2. Download the latest Krypton CLI release for your platform from the Krypton CLI Github repository:

    wget https://github.com/soracom/krypton-client-go/releases/download/v0.3.0/krypton-cli_0.3.0_linux_arm.tar.gz
  3. Extract the archive:

    tar xvf krypton-cli_0.3.0_linux_arm.tar.gz
  4. Copy the executable file krypton-cli to /usr/local/bin:

    sudo cp krypton-cli /usr/local/bin

    You should now be able to run the krypton-cli command. To check, you can run krypton-cli -version to verify that the command runs properly:

    krypton-cli -version
    >0.3.0
  5. If your modem or SIM card reader is not connected to your device, insert your Air SIM card into the modem or card reader, and then attach it to your device.

  6. If you are using a modem and have configured your device to automatically connect to a cellular network, disable it:

    • If using NetworkManager:

      sudo nmcli con down soracom
      sudo systemctl stop ModemManager.service
    • If using WvDial:

      sudo ifdown wwan0
  7. Check that krypton-cli is able to read the authentication information from the SIM card and access Metadata Service:

    krypton-cli -operation getSubscriberMetadata

    This command should return information about the Air SIM, even though your device is not connected to a cellular network:

    {
      "iccid": "8942310000012345678",
      "imsi": "295050012345678",
      "msisdn": "423012345678",
      "operatorId": "OP0012345678",
      "groupId": "abcdef00-0000-0000-0000-000012345678",
      "speedClass": "s1.standard",
      "status": "active",
      "subscription": "plan01s",
      "moduleType": "trio",
      // ...
    }

    If krypton-cli returns an error unexpected +CSIM response, the modem may be busy and preventing krypton-cli from reading the authentication information from the SIM. This may occur if the modem is scanning for networks or performing other actions even though NetworkManager or WvDial are stopped or disabled.

    You can connect to the modem's serial interface and send the command AT+CFUN=4 in order to disable modem functionality, while still leaving the AT+CSIM commands available so that krypton-cli is able to read the authentication information.

With the Krypton Client installed and able to read the SIM authentication information, you are now ready to bootstrap your device.


Bootstrapping a Device

  1. Start the bootstrap process:

    soratun bootstrap sim --config /path/to/arc.json

    The --config flag will allow you to specify where the Soratun configuration file will be saved on the device. If left unspecified, the configuration file will be saved in a file arc.json in the current directory.

    If Soratun is able to successfully create a Virtual SIM, you will see a response indicating that Soratun configuration file was successfully saved to the file path specified:

    >Virtual subscriber SIM ID: 8900000000012345678
    >Created/updated configuration file: /path/to/arc.json

Bootstrapping is now complete. With the Soratun configuration file successfully created, you can proceed to the Connecting to Soracom section below to activate the WireGuard connection and connect to Soracom.

If you prefer to use a different WireGuard client, refer to the Command Reference section for details about the Soratun configuration file.


Connecting to Soracom

To connect to Soracom, run soratun up while specifying the Soratun configuration file:

sudo soratun up --config /path/to/arc.json

Alternatively, if you have installed Soratun as a systemd service, you can start the Soratun daemon:

sudo systemctl start soratun

Then you can being accessing Soracom platform services:

curl -X POST \
  -d 'Hello world!' \
  http://harvest.soracom.io

When Soratun activates the WireGuard connection, Soratun will use the arcAllowedIPs and additionalAllowedIPs parameters in the Soratun configuration file to create network routes and route traffic via the Arc connection. By default:

  • arcAllowedIPs will contain 100.127.0.0/16, as returned from Arc to the device during bootstrapping.
  • additionalAllowedIPs will be empty, however you can specify additional IP address ranges in order to route additional traffic over the Arc connection.

Note that if a network route for the IP address range already exists, it will be overwritten.