Virtual Private Gateway

IP Address Mapping

When using a Virtual Private Gateway to establish a private network environment for Soracom Air for Cellular SIMs, the VPG will dynamically assign an IP address to each SIM from the VPG's device subnet CIDR range configuration using DHCP.

IP Address Mapping

In general, a VPG will attempt to re-use the same IP address when a device reconnects to the network. For many applications, the default 10.128.0.0/9 device subnet CIDR range provides enough IP addresses so that Air for Cellular will typically receive the same IP address each time they connect.

However, when using a smaller device subnet range, or in applications where you require your SIM to always receive the same IP address, the IP Address Mapping option allows you to assign a specific IP address within the device subnet range to a specific SIM.

Configuration

You can configure an IP Address Mapping entry from the User Console.

  1. Login to the User Console. 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 IP address map panel, click the Add Entry button to add an entry.

    Add IP address mapping entry

  5. Enter the IMSI and IP Address, then click Add.

    Add entry

    Additional subscription container IMSIs cannot be mapped individually. The User Console will automatically suggest the associated primary IMSI for use if a additional IMSI is entered. Connections for this SIM that are created using a additional subscription will be assigned the same IP address as connections made using the primary subscription.

  6. Repeat steps 4. and 5. for any additional IP addresses you want to map.

    IP addresses will be assigned the next time a device connects. If your device is currently connected, you will need to disconnect and reconnect in order to receive the new IP address.

Filtering

Entries in the IP Address map list can be filtered by either IMSI or IP Address.

  1. Select IMSI or IP Address from the dropdown menu.

Filtering can only be performed with primary IMSIs.

  1. Enter the IMSI or IP Address to filter by.

    Filter by IMSI

Programmatic Usage

You can use the Soracom API and Soracom CLI to configure IP Address Mapping entries programmatically. Each entry should contain the following parameters:

For example, the following entry assigns the IP address 10.128.123.45 to the SIM with IMSI 295050012345678:

{
  "key": "295050012345678",
  "ipAddress": "10.128.123.45"
}

Then, simply pass in the IP address mapping entry to the Soracom API or Soracom CLI. For either method, you will need the VPG ID.

Soracom API

To access the Soracom API, first use the auth API to obtain an API Key and Token. Refer to the API Reference Guide for instructions on how to use the API Key and Token in API requests.

Then, use the putVirtualPrivateGatewayIpAddressMapEntry API to add or update the IP address mapping entry:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "key": "295050012345678",
>        "ipAddress": "10.128.123.45"
>      }' \
>  https://g.api.soracom.io/v1/virtual_private_gateways/<VPG-ID>/ip_address_map

To list or delete IP address mapping entries, use one of the following APIs:

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:

soracom vpg put-ip-address-map-entry --vpg-id '<VPG-ID>' --body '@path/to/ip-address-map.json' --coverage-type g

In this sample, we're using the @filename method for passing in the IP address mapping entry which is stored in a separate file, but you can of course pass the raw data into the --body parameter directly.

To list or delete IP address mapping entries, use one of the following CLI commands:

  • soracom vpg list-ip-address-map-entries
  • soracom vpg delete-ip-address-map-entry