Metadata Service

Overview

Virtual machine cloud services like AWS EC2 and Google GCE provide simple metadata services that allow a VM to obtain data about itself, such as its identity or network configuration.

The Metadata Service provides similar functionality, letting an Air SIM device obtain subscriber information about itself and perform basic management tasks directly from the device over HTTP. With Metadata Service, you can get basic information about an Air SIM, such as IMSI and subscription status, as well as modify its Speed Class or Tags, without using an SDK or implementing the Soracom API into your application. Since the Metadata Service is handled directly between the device and the Soracom platform, no additional authentication or encryption is required.

Internally, when an Air SIM device requests the Metadata Service using the /subscriber endpoint, Soracom will check the IMSI of the Air SIM and map the request endpoint to /subscribers/{IMSI}. This means that all APIs underneath /subscribers/{IMSI} are available to an Air SIM via Metadata Service. For the full list of available endpoint, refer to the Subscriber API in the API Reference.


Configuration

The Metadata Service option is found within Soracom Air for Cellular Group settings.

  1. Login to the User Console. From the Menu, open the Groups screen.

  2. From the list of groups, click the name of the group you want to configure to open its settings page.

    You can also open the group settings page directly from the SIM Management screen. Simply find a SIM that currently belongs to the group you want to configure, then click the group name.

  3. From the Basic Settings tab, click the SORACOM Air for Cellular panel to expand its settings.

    https://console.soracom.io

    Metadata Service

  4. Enable the Metadata Service option by switching the option to ON.

  5. Configure any of the Options below.

  6. Click the Save button at the bottom of the panel.

Once saved, the Metadata Service will be immediately available to any subscribers in the group.


Options


Basic Usage

Since Metadata Service is remapping requests from /subscriber to the /subscribers/{IMSI} API, we have access to all APIs underneath the Subscriber API. Typically, when using the Soracom API directly, we have to include an API key and token in the HTTPS request header in order to authorize the API call. However, since requests originating from an Air SIM device are already authenticated using cellular network SIM authentication, there is no need to obtain and include an access token.

Get the device IMSI

From your device, you can make the following HTTP request:

curl http://metadata.soracom.io/v1/subscriber

Metadata Service will return an HTTP response similar to the following:

{
  "imsi": "295050012345678",
  "msisdn": "423012345678",
  "ipAddress": "10.123.45.67",
  "operatorId": "OP0012345678",
  "apn": "soracom.io",
  "type": "s1.standard",
  "groupId": "abcdef00-0000-0000-0000-000012345678",
  "status": "active",
  "tags": {
    "name": "my-sim"
  },
  "sessionStatus": {
    "imei": "860000012345678",
    "cell": {
      "radioType": "lte",
      "mcc": 310,
      "mnc": 410,
      "lac": 42973,
      "sac": 14702,
      "rac": 255
    },
    "ueIpAddress": "10.123.45.67",
    "dnsServers": [
      "100.127.0.53",
      "100.127.1.53"
    ],
    "online": true
  },
  "speedClass": "s1.standard",
  "moduleType": "trio",
  "plan": 1,
  "iccid": "8942310000012345678",
  "subscription": "plan01s"
}

You can then parse the response to extract the IMSI. For example, if accessing the Metadata Service directly from a Linux shell environment with jq installed, you can pipe the output like this:

curl -s http://metadata.soracom.io/v1/subscriber | jq -r .imsi
>295000012345678

Change the Speed Class

With the regular Soracom API, we would normally make an API call to the updateSpeedClass API as follows:

curl -X POST \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "speedClass": "s1.standard"
>      }' \
>  https://api.soracom.io/v1/subscribers/295050012345678/update_speed_class

Since Metadata Service will remap the API call for us and doesn't require an API key and token, we can simplify the API call:

curl -X POST \
>  -H 'Content-Type: application/json' \
>  -d '{
>        "speedClass": "s1.standard"
>      }' \
>  http://metadata.soracom.io/v1/subscriber/update_speed_class

We should get an HTTP response similar to the response above, indicating our updated speed class. We can similarly pipe the output using | jq .speedClass to filter the response.

Notice that our HTTP request using the Metadata Service does not require us to specify the Air SIM IMSI in the request URL — Soracom gets that automatically from the network carrier! This means that we can implement the API request as a generalized call within our code. Then, when we deploy the code across multiple devices, the IMSI will automatically be filled in by Soracom.

We can use the same method for accessing other /subscribers/{IMSI} APIs.

Note that when accessing APIs that modify the properties of an Air SIM, the Metadata Service Readonly option must be unchecked.


Accessing User Data

​ In addition to accessing the /subscribers/{IMSI} APIs, Metadata Service allows us to enter user-defined content that an Air SIM device can access directly at http://metadata.soracom.io/v1/userdata.

For example, the following User data:

Hello, world!

Will return the following on the device:

curl -s http://metadata.soracom.io/v1/userdata
>Hello, world!

We can take advantage of the text being returned to our device's environment. For example, if our device has a Linux shell environment, we can change our User data to the following:

#!/bin/bash
echo Hello! My IMSI is $( curl -s http://metadata.soracom.io/v1/subscriber | jq -r .imsi )

Now when we run the same HTTP request, we can simply pipe the response to bash to execute:

curl -s http://metadata.soracom.io/v1/userdata | bash
>Hello! My IMSI is 295000012345678

This technique can be adapted for a variety of use cases, such as defining what firmware version a remote device should download or running an initialization script, all of which can be configured from the Soracom platform rather than being manually defined on the device.


Advanced Configuration

Metadata Service settings can also be configured through the Soracom API or CLI by using the SoracomAir namespace.

Configuration Structure

"SoracomAir": {
  "metadata": {
    "enabled": true|false,
    "readonly": true|false,
    "allowOrigin": ""
  },
  "userdata": "",
  // additional SoracomAir settings
}

Parameters

Configure Metadata Service settings:

Modify userdata parameter:

Example

The following configuration will set and enable Metadata Service:

[
  {
    "key": "metadata",
    "value": {
      "enabled": true,
      "readonly": true,
      "allowOrigin": "http://my.example.com"
    }
  },
  {
    "key": "userdata",
    "value": "my custom data"
  }
]

Programmatic Usage

You can use the advanced configuration structure to configure the Metadata Service option programmatically using the Soracom API and Soracom CLI.

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 putConfigurationParameters API with the SoracomAir namespace to set the Metadata Service option:

curl -X PUT \
>  -H 'X-Soracom-API-Key: <MY-API-KEY>' \
>  -H 'X-Soracom-Token: <MY-TOKEN>' \
>  -H 'Content-Type: application/json' \
>  -d '[
>        {
>          "key": "metadata",
>          "value": {
>            "enabled": true,
>            "readonly": true,
>            "allowOrigin": "http://my.example.com"
>          }
>        },
>        {
>          "key": "userdata",
>          "value": "my custom data"
>        }
>      ]' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>/configuration/SoracomAir

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 set the Metadata Service option:

soracom groups put-config --group-id "<GROUP-ID>" --namespace "SoracomAir" --body "<CONFIG>" --coverage-type g

Here, the JSON array from the API example above should be passed in to the --body parameter.