set surelink

Purpose

For Digi devices with cellular capability, configures Digi SureLink™ settings. Digi SureLink™ provides an “always-on” mobile network connection to ensure that a Digi Cellular Family device is in a state where it can connect to the network. It does this through hardware reset thresholds and periodic tests of the connection.

There are several groups of command options for set surelink:

Required permissions

For Digi products with two or more users, to use this command, permissions must be set to set permissions s‑ppp=read to display settings, and set permissions s‑ppp=rw to display and configure settings. See set permissions for details on setting user permissions for commands.

Syntax

Set hardware reset thresholds

set surelink index=1-2 (required on dual-SIM devices)
  [module_reset_connect_failures={1-255|0=off}]
  [system_reset_connect_failures={1-255|0=off}]

Configure link integrity monitoring tests:

Set general link test options

set surelink [state={on|off}]
  [test={ping|tcp|dns}]
  [trigger={interval|idle}]
  [max_consecutive_failures={1-255|0=off}] (probe failures before link reset)
  [interval=10-65535]

Set ICMP ping link test options

set surelink [pingaddr1={ipv4 address|fqdn}]
  [pingaddr2={ipv4 address|fqdn}]

Set DNS lookup link test parameters:

set surelink [dnsfqdn1=dns fqdn]
[dnsfqdn2=dns fqdn]

Set TCP connection link test parameters:

set surelink [ipaddr1={ipv4 address|fqdn}]
[ipaddr2={ipv4 address|fqdn}]
[ipport=1-65535]

Display current SureLink settings

set surelink

Options

Options for Hardware reset thresholds

index=1-2

The index number of the SIM to which the hardware reset threshold settings apply. This index number is required on dual-SIM devices.

module_reset_connect_failures={1-255|0=off}

The number of failed connection attempts that occur before the cellular modem module is reset. This value can be a number between 1 and 255, or 0, which turns off the cellular modem module-reset feature. The default is 3.

system_reset_connect_failures={1-255|0=off}

The number of failed connection attempts that occur before the Digi Cellular Family device is reset. This value can be a number between 1 and 255, or 0, which turns off the system-reset feature. The default is 0, or off.

Options for link integrity monitoring tests

General link test options

state={on|off}

Enables or disables link integrity monitoring tests. If set to on, the other link integrity monitoring settings may be configured and are used to verify the functional integrity of the mobile connection. The default is off.

test={ping|tcp|dns}

The link integrity monitoring test to be run.

Each test can be used to demonstrate that two-way communication is working over the mobile connection. This variety of tests is provided because different mobile networks or firewalls may allow or block Internet packets for various services. The appropriate test may be selected according to mobile network constraints and user preference.

The tests are performed only while the mobile connection is established. If the mobile connection is disconnected, the link integrity tests are suspended until the connection is established again.

For the tests to provide meaningful results, the remote or target hosts must be accessible over the mobile connection and not through the LAN interface of the device, if it has one. That is, the settings should be configured to guarantee that the mobile connection is actually being tested.

The link integrity monitoring test settings may be modified at any time. The changes are used at the start of the next test interval.

ping

Ping test. This test uses ping (ICMP) as a test to verify the integrity of the mobile connection. The test is successful if a valid ping reply is received in response to the ping request sent. The ping test actually sends up to three ping requests, at three second intervals, to test the link. When a valid reply is received, the test completes successfully and immediately. If a reply is received for the first request sent, there is no need to send the other two requests.

Two destination hosts may be configured for this test. If the first host fails to reply to all three ping requests, the same test is attempted to the second host. If neither host replies to any of the ping requests sent, the test fails. The primary and secondary addresses may be either IP addresses or fully qualified domain names.

tcp

TCP connection test. This test creates a new TCP connection as a test to verify the integrity of the mobile connection. The test is successful if a TCP connection is established to a specified remote host and port number. If the remote host actively refuses the connection request, the test is also considered to be successful, since that demonstrates successful two-way communication over the mobile connection. The TCP connection test waits up to 30 seconds for the connection to be established or refused. When the TCP connection is established, the test completes successfully, and the TCP connection is closed immediately.

Two destination hosts may be configured for this test. If the first host fails to establish (or refuse) the TCP connection, the same test is attempted to the second host. If neither host successfully establishes (or refuses) the TCP connection, the test fails. The primary and secondary addresses may be either IP addresses or fully qualified domain names.

dns

DNS lookup test. This test uses a Domain Name Server (DNS) lookup as a test to verify the integrity of the mobile connection. The test is successful if a valid reply is received from a DNS server. Typically, this means the hostname is successfully “resolved” to an IP address by a DNS server. But even a reply such as not found or name does not exist is acceptable as a successful test result, since that demonstrates successful two-way communication over the mobile connection. When a valid reply is received, the test completes successfully and immediately.

The DNS servers used in this test for the hostname lookup are the primary and secondary DNS servers obtained from the mobile network when the mobile PPP connection is first established. These addresses may be viewed in the web interface on the
Administration > System Information > Mobile page.

Note that this DNS lookup test is independent of the normal DNS client configuration and lookup cache, which is used for other hostname lookups. This test has been specifically designed to require communication over the mobile connection for each lookup, and to avoid being “short-circuited” by previously cached information. Also, this test does not interfere in any way with the normal DNS client configuration of this device.

Two hostnames may be configured for this test. If the first hostname fails to get a reply, the same test is attempted for the second hostname. If no reply is received for either hostname, the test fails. The primary and secondary DNS names should be fully qualified domain names. Note that the reverse lookup of an IP address is possible, but that is usually unlikely to succeed in returning a name. Still, such a reverse lookup can be used to demonstrate the integrity of the mobile connection.

trigger={interval|idle}

The conditions under which link integrity monitoring tests are performed.

interval

Link integrity monitoring tests are repeated at the interval specified by the interval option.

idle

Link integrity monitoring tests are performed only when idle; that is, if no data is received for the period of time specified by the interval option.

This value changes the behavior of the test, in that the test interval varies according to the presence of other data received from the mobile connection.

Although using trigger=idle may result in less data being exchanged over the mobile connection, it also prevents the link integrity tests from running as often to verify the true bi-directional state of that connection.

max_consecutive_failures={1-255, 0=off} (probe failures before link reset)]

The maximum number of consecutive Link Integrity Monitoring tests. After this number is reached, the mobile connection should be disconnected and reestablished.

This value must be between 1 and 255. The default is 3. A value of 0 turns off this feature. When the mobile connection is reestablished, the “consecutive failures” counter is reset to zero.

Note If the mobile connection is disconnected for any reason (including not as a result of a link integrity test failure), the consecutive failures count is reset to zero when the mobile connection is reestablished.

interval=10-65535

Specifies the interval, in seconds, at which the selected Link Integrity Monitoring test is initiated or repeated. A new test will be started every specified number of seconds while the mobile connection is established. This value must be between 10 and 65535. The default is 240.

If the configured interval is less time than it takes a test to complete, the next test will not be initiated until the previous (current) test has completed.

ICMP ping link test options

pingaddr1={ipv4 address|fqdn}

The first host to test.

pingaddr2={ipv4 address|fqdn}

The second host to test, if the first host fails.

TCP connection link test parameters:

ipaddr1={ipv4 address|fqdn}

The first host to test.

ipaddr2={ipv4 address|fqdn}

The second host to test, if the first host fails.

ipport=1-65535

The TCP port number to connect to on the remote host. The default is 80.

DNS lookup link test parameters

dnsfqdn1=dns fqdn

The first hostname to look up.

dnsfqdn2=dns fqdn

The second hostname to look up, if the first hostname fails.

Example

set surelink system_reset_connect_failures=30

See also