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.

Configuration

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.

Login to the User Console. From the Menu, open the Groups screen.
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.
From the Basic settings tab, click the SORACOM Air for Cellular panel to expand its settings.
Enable the Custom DNS option by switching the option to ON.
Enter the DNS server IP address, click Add button to add a second DNS server if required.
Click Save at the bottom of the panel.

https://console.soracom.io

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

Options

DNS servers - Define up to 2 DNS servers to use.

Advanced Usage

When using Soracom Canal, Direct, or Door to connect your IoT SIM devices to your private network environment, you can configure the Custom DNS option to use your private DNS servers. This will allow your IoT 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, IoT 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
}

Parameters

Enable or disable Custom DNS:

key - useCustomDns
value (boolean, default: false) - Enables or disables the Custom DNS option.

Modify the DNS resolvers:

key - dnsServers
value (array of strings, default: []) - Array of IP addresses to use when Custom DNS is enabled. Maximum of two can be specified. Example: ["8.8.8.8", "8.8.4.4"].

Example

The following configuration will set and enable Custom DNS:

[
  {
    "key": "useCustomDns",
    "value": true
  },
  {
    "key": "dnsServers",
    "value": [
      "8.8.8.8",
      "8.8.4.4"
    ]
  }
]

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:

Global
Japan

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": [
>            "8.8.8.8",
>            "8.8.4.4"
>          ]
>        }
>      ]' \
>  https://g.api.soracom.io/v1/groups/<GROUP-ID>/configuration/SoracomAir

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": [
>            "8.8.8.8",
>            "8.8.4.4"
>          ]
>        }
>      ]' \
>  https://jp.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 Custom DNS option:

Global
Japan

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

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

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