# Bootstrapping with SIM

Bootstrap Soracom Arc virtual SIMs using SIM authentication.

## Bootstrapping with SIM

> [!WARNING]
>
> 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](https://docs.soracom.io/en/pricing) for more information.

When bootstrapping with SIM authentication, Soratun will use the Soracom Krypton Client to access authentication information embedded in a Soracom IoT 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 IoT SIM.

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

## Prerequisites

Your device should have:

- Soratun installed (refer to the [Installation](https://docs.soracom.io/en/services/arc/soratun/installation) section for instructions)

- An Internet connection

- A plan01s, plan01s - LDV, plan-US, planX3, or planX3-EU IoT SIM

- A compatible modem or SIM card reader. As reference, Soracom has tested the following devices:

  - Huawei MS2131i-8 3G USB modem
  - Gemalto USB-TR HWP119316 card reader
  - Soracom Onyx LTE™ USB Modem

> [!NOTE]
>
> When using other modems, ensure that the modem supports the `AT+CSIM` command.

## Enabling Soracom Krypton

> [!WARNING]
>
> 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](https://docs.soracom.io/en/pricing) for more information.

1. Refer to the [Groups: Basic Usage](https://docs.soracom.io/en/services/groups/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](https://docs.soracom.io/en/services/groups/usage) documentation to add your IoT SIM to the group.

## Installing Krypton Client

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

   ```bash
   sudo apt install -y libpcsclite-dev pcscd libpcsclite1 && sudo reboot
   ```

2. Download the latest Krypton CLI [release](https://github.com/soracom/krypton-client-go/releases) for your platform from the [Krypton CLI Github repository](https://github.com/soracom/krypton-client-go):

   ```bash
   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:

   ```bash
   tar xvf krypton-cli_0.3.0_linux_arm.tar.gz
   ```

4. Copy the executable file `krypton-cli` to `/usr/local/bin`:

   ```bash
   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:

   ```bash
   krypton-cli -version

   0.3.0
   ```

5. If your modem or SIM card reader is not connected to your device, insert your IoT 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**:

     ```bash
     sudo nmcli con down soracom
     sudo systemctl stop ModemManager.service
     ```

   - If using **WvDial**:

     ```bash
     sudo ifdown wwan0
     ```

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

   ```bash
   krypton-cli -operation getSubscriberMetadata
   ```

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

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

> [!NOTE]
>
> 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:

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

   > [!WARNING]
   >
   > 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:

   ```bash
   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.

> [!WARNING]
>
> If you prefer to use a different WireGuard client, refer to the [Command Reference](https://docs.soracom.io/en/services/arc/soratun/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:

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

Alternatively, if you have [installed Soratun as a systemd service](https://docs.soracom.io/en/services/arc/soratun/installation), you can start the Soratun daemon:

```bash
sudo systemctl start soratun
```

Then you can being accessing Soracom platform services:

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

> [!NOTE]
>
> 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.