# Configuration

Provision and configure Soracom Arc virtual SIMs.

> [!WARNING]
>
> Creating a Virtual SIM 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.

To configure a device to connect to Soracom using Arc, you must first create a Virtual SIM. You can create Virtual SIMs from the **User Console**, using the **Soracom API** or **CLI**, or using the [Soratun](https://docs.soracom.io/en/services/arc/soratun) command line tool provided by Soracom.

- The **User Console** will provide an easy, interactive way to create individual Virtual SIMs.
- For larger operations, you can use the **Soracom API** or **CLI** to perform the same Virtual SIM creation process programmatically.

Both of the methods above are generally intended to be performed on a computer, rather than on the devices that will connect to Soracom using Arc. This means you will need to separately copy or enter the Arc-provided WireGuard configuration to the device to complete the setup.

Unlike the User Console and Soracom API or CLI methods, the [Soratun](https://docs.soracom.io/en/services/arc/soratun) command line tool will allow you to create a Virtual SIM _directly from the device that will use the Arc connection_. This process is called **bootstrapping**, and can be used to allow a device to create its own Virtual SIM and configure its WireGuard settings automatically.

This section describes the process of creating a Virtual SIM using the User Console and Soracom API or CLI.

If you prefer to create a Virtual SIM directly from a device, refer to the [Soratun](https://docs.soracom.io/en/services/arc/soratun) section.

## Creating a Standalone Virtual SIM

> [!WARNING]
>
> Arc will automatically generate a set of client **private** and **public keys** that will allow your device to establish a secure connection to Soracom. However, you can also use your own set of private and public keys for additional security. For more information, refer to the [Credentials](https://docs.soracom.io/en/services/arc/credentials) section.

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **SIM Management** screen.

2. Click the **+ Register SIM** button.

   ![Register SIM](https://docs.soracom.io/_astro/register-sim.-NqHLB6z_ZeFpJe.webp)

3. Click the **Add Virtual SIM** tab, then click **Register** to create a new Virtual SIM.

   ![Create Standalone Virtual SIM](https://docs.soracom.io/_astro/standalone-sim-create.BRClw7rZ_ZHkR7s.webp)

Once your Virtual SIM has been created, its SIM ID and WireGuard configuration details will be displayed:

![Standalone Virtual SIM settings](https://docs.soracom.io/_astro/standalone-sim-created.28bnO4b2_12mBte.webp)

You can then copy the WireGuard configuration, and proceed to the [Connection](https://docs.soracom.io/en/services/arc/connection) instructions to configure the WireGuard client on your device.

> [!NOTE]
>
> The private key will be displayed only once, and you must make sure to copy the private key to your device.

> [!NOTE]
>
> When using the supplied settings for Wireguard it is highly recommended to add `PersistentKeepalive` settings to the Peer section, such as `PersistentKeepalive = 25`.
>
> While this is not required, it will be necessary in situations such as:
>
> - Accessing the device through a Network Address Translation (NAT) system.
> - Remotely accessing the device using Soracom Napter or Gate.
> - Accessing a server running on the device.

## Adding a Virtual SIM to an IoT SIM

1. Sign in to the **[User Console](https://console.soracom.io/?coverage_type=g)**. From the **☰ Menu**, open the **SIM Management** screen.

2. From the list of subscribers, click the **☑** for the SIM you want to manage.

3. Click the **Actions ▾** menu, then select **Add Virtual SIM...**.

4. Read the subscription delivery fee warning and usage charge, then click **Add Subscription**.

   ![Add Virtual SIM subscription to SIM](https://docs.soracom.io/_astro/add-subscription-to-sim.CjdSzTQq_Z2qowCH.webp)

Once your Virtual SIM has been added to the selected SIM, its WireGuard configuration details will be displayed:

![Subscription Container Virtual SIM settings](https://docs.soracom.io/_astro/container-sim-added.CITJt-oM_Z5ugYc.webp)

You can then copy the WireGuard configuration, and proceed to the [Connection](https://docs.soracom.io/en/services/arc/connection) instructions to configure the WireGuard client on your device.

> [!NOTE]
>
> When using the supplied settings for Wireguard it is highly recommended to add `PersistentKeepalive` settings to the Peer section, such as `PersistentKeepalive = 25`.
>
> While this is not required, it will be necessary in situations such as:
>
> - Accessing the device through a Network Address Translation (NAT) system.
> - Remotely accessing the device using Soracom Napter or Gate.
> - Accessing a server running on the device.

> [!NOTE]
>
> The private key will be displayed only once, and you must make sure to copy the private key to your device.

> [!WARNING]
>
> Arc will automatically generate a set of client **private** and **public keys** that will allow your device to establish a secure connection to Soracom. However, you can also use your own set of private and public keys for additional security. For more information, refer to the [Credentials](https://docs.soracom.io/en/services/arc/credentials) section.

## Programmatic Usage

In addition to creating Virtual SIMs from the User Console, you can also create them programmatically using the Soracom API or CLI.

### Soracom API

To access the Soracom API, first use the [**auth**](https://docs.soracom.io/en/api#!/Auth/auth) API to obtain an API Key and Token. Refer to the [**API Usage Guide**](https://docs.soracom.io/en/developers/soracom-api) for instructions on how to use the API Key and Token in API requests.

Then, to create a Standalone Virtual SIM, use the [createSim](https://docs.soracom.io/en/api#!/Sim/createSim) API to create a new Virtual SIM:

**Global**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "virtual",
        "subscription": "planArc01"
      }' \
  https://g.api.soracom.io/v1/sims
```

**Japan**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "virtual",
        "subscription": "planArc01"
      }' \
  https://jp.api.soracom.io/v1/sims
```

Alternatively, to create a Subscription Container Virtual SIM, use the [addSubscription](https://docs.soracom.io/en/api#!/Sim/addSubscription) API to add a Virtual SIM to an existing SIM:

**Global**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "virtual",
        "subscription": "planArc01"
      }' \
  https://g.api.soracom.io/v1/sims/<SIM-ID>/profiles/<ICCID>/add_subscription
```

**Japan**

```bash
curl -X POST \
  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
  -H 'X-Soracom-Token: <MY-TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
        "type": "virtual",
        "subscription": "planArc01"
      }' \
  https://jp.api.soracom.io/v1/sims/<SIM-ID>/profiles/<ICCID>/add_subscription
```

In either case, the API will return details about the Virtual SIM that was created, including the Virtual SIM IMSI for identification purposes, as well as the WireGuard configuration details. You can then use these details to configure the WireGuard client on your device and activate the WireGuard connection, as described in the [Connection](https://docs.soracom.io/en/services/arc/connection) section.

### 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 create a Standalone Virtual SIM:

**Global**

```bash
soracom sims create --type "virtual" --subscription "planArc01" --coverage-type g
```

**Japan**

```bash
soracom sims create --type "virtual" --subscription "planArc01" --coverage-type jp
```

Alternatively, run the following command to add a Virtual SIM to an existing SIM as a Subscription Container:

**Global**

```bash
soracom sims add-subscription --sim-id "<SIM-ID>" --iccid "<ICCID>" --type "virtual" --subscription "planArc01" --coverage-type g
```

**Japan**

```bash
soracom sims add-subscription --sim-id "<SIM-ID>" --iccid "<ICCID>" --type "virtual" --subscription "planArc01" --coverage-type jp
```

In either case, the CLI will return the same response as the API example above. You can then use these details to configure the WireGuard client on your device and activate the WireGuard connection, as described in the [Connection](https://docs.soracom.io/en/services/arc/connection) section.