# SIM-Based Routing

Route traffic to devices behind cellular routers without port forwarding or tunnels.

To access a device on the subnet beyond your cellular router, it used to be necessary to spend extra effort configuring network settings like port forwarding and tunnels for that router. With SIM-based routing, you can link the SIM card in that router and the router's Local Area Network (LAN) IP range. This allows the SIM itself to be set as the routing destination when using [Soracom Gate](https://docs.soracom.io/en/services/gate), reducing the time and cost of network maintenance for inter-site connection equipment and IoT gateways.

![SIM-Based Routing](https://docs.soracom.io/_astro/diagram.CzKyYY9x_Z7aiNV.webp)

> [!WARNING]
>
> SIM-Based Routing is a free feature that is included with the cost of your VPG.

## Configuration

> [!NOTE]
>
> SIM-based routing is not currently available for Type-F2 VPGs

Before enabling SIM-Based Routing, ensure that you have completed the following:

- Create a Type-F or Type-G [Virtual Private Gateway](https://docs.soracom.io/en/services/vpg).
- Enable [Soracom Gate](https://docs.soracom.io/en/services/gate/basic-configuration) for your VPG.
- Create a [Soracom Air for Cellular Group](https://docs.soracom.io/en/services/groups/usage).
- Configure your group's [Virtual Private Gateway option](https://docs.soracom.io/en/services/air/vpg) to use your VPG.
- [Add Air for Cellular subscribers](https://docs.soracom.io/en/services/groups/usage) that you wish to use SIM-Based Routing with to the group.
- Confirm you can access the router with Soracom Gate.

### Router Settings

To use SIM-based routing, the cellular router must be able to forward the packets received from Soracom to the devices connected to the router's Local Area Network (LAN). For our configuration guide, we will show how to enable the necessary settings on a Teltonika RUT240 cellular router. However, SIM-Based routing will work with any router capable of packet forwarding and receiving packets from the cellular network.

1. Log in to the RUT240's web interface. By default, this can be reached by navigating to `http://192.168.1.1`.

2. Click the **System** tab, then under the **Setup Wizard** header select **LAN**.

   Set the RUT240's LAN IP address to `192.168.100.1` and the DHCP IP address range to `192.168.100.100` to `192.168.100.249`.

   ![IP Configuration](https://docs.soracom.io/_astro/rut240-settings-01.CiZj33bR_Z8r9d.webp)

   These settings configure the router's LAN IP address and define the range of IP addresses assigned to devices connected to the router.

3. If the RUT240 is in **"Basic"** mode, click **Mode** to change it to **"Advanced"** mode.

   ![Mode](https://docs.soracom.io/_astro/rut240-settings-02.BeG0NSPe_11oiyO.webp)

4. Click the **Network** tab, then under the **Firewall** header select **General Settings**.

   ![General Settings](https://docs.soracom.io/_astro/rut240-settings-03.BgNknToP_Z1rPGNk.webp)

5. Change the **Forward** setting to **"Accept"**.

   ![Forward](https://docs.soracom.io/_astro/rut240-settings-04.Cq_CAA5H_Z2r1XOo.webp)

6. Click **Save and Apply**

7. Connect your device to the router's LAN.

> [!WARNING]
>
> Before proceeding, we recommend that you confirm that devices belonging to the router's LAN can access the Soracom network using Soracom's Ping response service.
>
> ```bash
> ping pong.soracom.io
> ```

### VPG Settings

You can configure a SIM-Based Routing from the User Console.

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

2. From the list of VPGs, click the **name** of the VPG you want to configure to open its settings page.

3. Click the **Device LAN** tab.

4. From the **SIM-Based Routing** panel, click the **+ Add** button to add an IP Range entry.

   ![Add IP SIM-Based Routing entry](https://docs.soracom.io/_astro/sim-based-routing.Dp4vyeFe_ZERki0.webp)

5. Enter the **IP Range** of your router's LAN in CIDR notation and the **SIM ID** of the SIM in that router. Multiple IP range and SIM ID associations can be defined at once.

   By default, you will only be able to associate IP ranges with SIM IDs that are currently registered to your account. If you would like to add entries for SIM cards that are not yet registered to your account, check the **Allow registration of non-owned SIMs** box.

   If a [Subscription Container](https://docs.soracom.io/en/services/air/subscription-containers) has been added to the SIM, the additional subscriptions on the SIM ID will also be displayed as suggestions. SIM-based routing differentiates SIMs by SIM ID, so selecting additional subscriptions will work identically to choosing the primary subscription.

   ![Add entry](https://docs.soracom.io/_astro/add-entry.DWpvOtiB_ZO8b5P.webp)

   > [!NOTE]
   >
   > Be aware of the following information when setting associations:
   >
   > - The same IP range cannot be assigned to multiple SIMs.
   > - If the IP ranges of multiple entries overlap, packets will be routed to the more precisely matched IP range that has the longest subnet mask. For example: if SIM A is associated with IP range `192.168.100.0/24` and SIM B is associated with IP range `192.168.100.240/28`, traffic for `192.168.100.241` will be routed to SIM B.
   > - Soracom Arc virtual SIMs cannot be mapped to IP ranges.

6. After you have completed your entries, click **Save Config Settings**.

7. Click the **Enable SIM-Based Routing** toggle to enable the feature.

   ![Enable SIM-Based Routing](https://docs.soracom.io/_astro/enable-sim-based-routing.BAo1C159_Z1YNsfE.webp)

> [!NOTE]
>
> When enabling and disabling SIM-Based routing, there will be a temporary interruption in all communications for the VPG. The new SIM-Based Routing configurations will be available to use once the respective SIMs re-establish their sessions.

### Gate Peer Configuration for SIM-Based Routing

To use **Gate Cloud-to-Device (C2D) + SIM-Based Routing**, you need to configure the Gate peer with the appropriate routing rules. This enables effective communication between cloud and device networks via the specified SIM-based routes.

#### Routing Configuration

> [!NOTE]
>
> Routes added using the `ip route` command are stored in the kernel's routing table, which is ephemeral and will be reset when the system reboots.

Use the following command to add the required route:

```bash
sudo ip route add 192.168.100.0/24 nexthop via xxx.xxx.xxx.xxx weight 1 nexthop via yyy.yyy.yyy.yyy weight 1 dev vxlan0
```

| Notation | Details |
| - | - |
| xxx.xxx.xxx.xxx | Replace with IP address for the first nexthop. |
| yyy.yyy.yyy.yyy | Replace with IP address for the second nexthop.**\*1** |
| vxlan0 | Device name for the routing interface. Rename as necessary per your network configuration. |

1. Additional nexthops can be added to the **ip route** command as long as the additional connections are supported by the system and network they are being configured for.

## Limitations

When using SIM-Based Routing, the following limitations apply:

- When using [Soracom Canal's](https://docs.soracom.io/en/services/canal) Amazon VPC peering connection, if the IP address range of Amazon VPC and the LAN IP address range of the SIM-based routing router overlap, SIM-based routing will be prioritized.
- In cases involving cloud to device communications with a [Gate Peer](https://docs.soracom.io/en/services/gate/gate-peer-configuration), [outbound filters](https://docs.soracom.io/en/services/vpg/outbound-filter) are ignored.

## Programmatic Usage

You can use the Soracom API and Soracom CLI to configure SIM-Based Routing entries programmatically.

For example, the following body assigns the IP range `192.168.2.0/24` to `SIM_ID_1`, and `192.168.2.128/25` to `SIM_ID_2`.

```json
{
  "SIM_ID_1": "192.168.2.0/24",
  "SIM_ID_2": "192.168.2.128/25"
}
```

Then, simply pass in the SIM-Based Routing entries to the Soracom API or Soracom CLI. For either method, you will need to specify the VPG ID.

### 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, use the [putSimBasedRoutingRoutes](https://docs.soracom.io/en/api#!/VirtualPrivateGateway/putSimBasedRoutingRoutes) API to add or update the SIM-Based Routing entry:

**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 '{
        "SIM_ID_1": "192.168.2.0/24",
        "SIM_ID_2": "192.168.2.128/25"
      }' \
  https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/gate/routing/static/sims/routes
```

**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 '{
        "SIM_ID_1": "192.168.2.0/24",
        "SIM_ID_2": "192.168.2.128/25"
      }' \
  https://jp.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/gate/routing/static/sims/routes
```

To enable or disable SIM-Based Routing, use one of the following APIs:

- [disableSimBasedRouting](https://docs.soracom.io/en/api#!/VirtualPrivateGateway/disableSimBasedRouting)
- [enableSimBasedRouting](https://docs.soracom.io/en/api#!/VirtualPrivateGateway/enableSimBasedRouting)

### 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 add or update the IP address mapping entry:

**Global**

```bash
soracom vpg put-sim-based-routing-routes --vpg-id '<VPG-ID>' --body '@path/to/sim-based-routing-entries.json' --coverage-type g
```

**Japan**

```bash
soracom vpg put-sim-based-routing-routes --vpg-id '<VPG-ID>' --body '@path/to/sim-based-routing-entries.json' --coverage-type jp
```

In this sample, we're using the `@filename` method for passing in the SIM-Based Routing entries which are stored in a separate file, but you can of course pass the raw data into the `--body` parameter directly.

To enable or disable SIM-Based Routing, use one of the following CLI commands:

- `soracom vpg enable-sim-based-routing --vpg-id '<VPG-ID>'`
- `soracom vpg disable-sim-based-routing --vpg-id '<VPG-ID>'`