Custom DNS

The Custom DNS option allows you to specify which DNS resolvers to use. Soracom Air for Cellular subscribers that belong to a group with the Custom DNS option will automatically receive the Custom DNS resolver information when establishing a network connection. This allows you to control which servers your devices use to resolve domain names, in order to improve security and performance, or to specify DNS resolvers within your private network.

Your devices must be configured to automatically obtain DNS configuration. If your devices have manually configured DNS settings, they may override any Custom DNS settings below.

When setting or updating the Custom DNS option, your device must fully disconnect and reconnect in order to obtain the updated DNS settings. Any existing network connections will continue to use existing DNS settings.


Enabling the Custom DNS option may incur fees. Refer to the Pricing & Fee Schedule for more information.

The Custom DNS 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.

  4. Enable the Custom DNS option by switching the option to ON.

  5. Enter the DNS server IP address, click Add button to add a second DNS server if required.

  6. Click Save at the bottom of the panel.

    Custom DNS

Last, add any subscribers to the group so that they will receive the new Custom DNS settings.


Advanced Usage

When using Soracom Canal, Direct, or Door to connect your Air SIM devices to your private network environment, you can configure the Custom DNS option to use your private DNS servers. This will allow your Air SIM devices to access services within your private network environment through using custom DNS entries, and reduce any security vulnerabilities through using public DNS services.

In addition, when creating a Virtual Private Gateway (VPG) for use with Canal, Direct, or Door, you can disable the Enable internet gateway option. When disabled, Air SIM devices attached to the VPG will be unable to access the Internet, while still being able to access your private network resources using a Canal, Direct, or Door connection.

Advanced Configuration

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

Configuration Structure

"SoracomAir": {
  "useCustomDns": true|false,
  "dnsServers": [],
  // additional SoracomAir settings


Enable or disable Custom DNS:

Modify the DNS resolvers:


The following configuration will set and enable Custom DNS:

    "key": "useCustomDns",
    "value": true
    "key": "dnsServers",
    "value": [

Programmatic Usage

You can use the advanced configuration structure to configure the Custom DNS 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 Custom DNS 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": "useCustomDns",
>          "value": true
>        },
>        {
>          "key": "dnsServers",
>          "value": [
>            "",
>            ""
>          ]
>        }
>      ]' \

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 Custom DNS option:

soracom groups put-config --group-id '<GROUP-ID>' --namespace 'SoracomAir' \
>  --body '[ {"key":"dnsServers","value":["",""]}, {"key":"useCustomDns","value":true} ]' --coverage-type g

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