Soracom Arc

Bootstrap using AuthKey

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 an AuthKey, Soratun will use a Soracom API AuthKey ID and AuthKey Secret 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 Standalone Virtual SIM.

Because authorization is provided through AuthKeys, there is no need for your device to have a Soracom Air for Cellular SIM or a cellular network interface. Bootstrapping can be performed over any Internet connection.

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.

Requirements

Your device should have:

Creating an AuthKey

  1. Refer to the Users & Roles documentation to create a new SAM user.

  2. Once you have created a user, click the name of the user. From the Permissions tab, modify its Inline permissions to allow access to the following APIs:

    {
  "statements": [
    {
      "api": ["Sim:createSim", "Sim:createArcSession"],
      "effect": "allow"
    }
  ]
}

    Then click the Save button to save the inline permissions.

  3. Finally, click the Authentication tab. From the AuthKeys panel, click the Generate an AuthKey button. An AuthKey ID and AuthKey Secret key pair will be automatically generated.

    When generating a new AuthKey, the AuthKey Secret will only be shown once. Ensure that you save the secret key in a secure location. If you lose the secret key, you will need to generate a new AuthKey.

Make sure to make a note of the AuthKey ID and AuthKey Secret, as you will need it to bootstrap your device.

Bootstrapping a Device

  1. Start the bootstrap process:

    soratun bootstrap authkey --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.

  2. When prompted, enter the following information:

    • SORACOM API auth key ID (starts with "keyId-") - The AuthKey ID of the SAM user created earlier.
    • SORACOM API auth key (starts with "secret-") - The AuthKey Secret of the SAM user created earlier.
    • Coverage to create a new virtual SIM - The coverage location, Global or Japan, where you want to create the Virtual SIM.

    If Soratun is able to successfully create a Virtual SIM, you will see a response indicating that the 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.

Non-Interactive Bootstrapping

If you want to perform bootstrapping without the interactive prompts, you can enter the same information using --auth-key-id, --auth-key, and --coverage-type flags to specify the AuthKey ID, AuthKey secret, and coverage type (g or jp), respectively:

soratun bootstrap authkey --config /path/to/arc.json --auth-key-id "<AUTHKEY-ID>" --auth-key "<AUTHKEY-SECRET>" --coverage-type g

Subsequent Bootstrapping

If you reset a Virtual SIM's session from the User Console or Soracom API/CLI, bootstrapping again allows your device to update its Arc connection information. By specifying the same configuration path (such as /path/to/arc.json), Soratun will skip creating a new Virtual SIM and will instead only update the session information (specified in the arcSessionStatus section of the Soratun configuration file).

As Soratun will also store the AuthKey information in the Soratun configuration file during the first bootstrap, there is no need to re-enter the AuthKey ID and AuthKey secret when bootstrapping additional times.

To bootstrap a new Virtual SIM, either specify a new configuration path, or delete the existing 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 begin 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.